SMS8 API Documentation

Last modified: March 15, 2024

  • Getting Started
  • Endpoint: Send SMS
  • Endpoint: Get Message Status
  • SMS8 Webhook
  • Contact information

Getting Started

The SMS8 API allows you to send SMS messages through your Android device as a gateway. To use this API, you must:

  1. Create an account on SMS8.
  2. Install the Android App to connect your device.
  3. Authenticate using your API key.

Installation

API Authentication

  • The API requires authentication via an API key.
  • Obtain your API key from your SMS8 account dashboard.
  • Authentication URL: https://app.sms8.io/api.php

Endpoint: Send SMS

  • URL: https://app.sms8.io/services/send.php
  • Method: GET

Request Parameters

  • key: Your unique API key (required).
  • number: The phone number to send the SMS (required).
  • message: The SMS content (URL-encoded; required).
  • devices: JSON-encoded array of devices and SIM slots. Format: ["deviceID|simSlot"] (required).
  • type: Type of message. Set to sms (required).
  • prioritize: 0 or 1 (optional, default 0). Prioritize device for sending if multiple devices are available.
  • Example Request
https://app.sms8.io/services/send.php?key=YOUR_API_KEY&number=0608918217&message=This+message&devices=%5B%22182%7C0%22%2C%22182%7C1%22%5D&type=sms&prioritize=0

API Usage Examples

JavaScript (Fetch)
fetch('https://app.sms8.io/services/send.php?key=YOUR_API_KEY&number=0608918217&message=This%20message&devices=%5B%22182%7C0%22%2C%22182%7C1%22%5D&type=sms&prioritize=0')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
cURL
 
curl -X GET "https://app.sms8.io/services/send.php?key=YOUR_API_KEY&number=0608918217&message=This+message&devices=%5B%22182%7C0%22%2C%22182%7C1%22%5D&type=sms&prioritize=0"
PHP
 
<?php
$response = file_get_contents("https://app.sms8.io/services/send.php?key=YOUR_API_KEY&number=0608918217&message=This+message&devices=%5B%22182%7C0%22%2C%22182%7C1%22%5D&type=sms&prioritize=0");
$data = json_decode($response, true);
print_r($data);
?>
React
import React, { useEffect, useState } from 'react';

function App() {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch('https://app.sms8.io/services/send.php?key=YOUR_API_KEY&number=0608918217&message=This%20message&devices=%5B%22182%7C0%22%2C%22182%7C1%22%5D&type=sms&prioritize=0')
      .then(response => response.json())
      .then(data => setData(data))
      .catch(error => console.error('Error:', error));
  }, []);

  return <div>{data && JSON.stringify(data)}</div>;
}

export default App;
C#
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        using HttpClient client = new HttpClient();
        string url = "https://app.sms8.io/services/send.php?key=YOUR_API_KEY&number=0608918217&message=This+message&devices=%5B%22182%7C0%22%2C%22182%7C1%22%5D&type=sms&prioritize=0";
        HttpResponseMessage response = await client.GetAsync(url);
        string result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}
Python
import requests

url = "https://app.sms8.io/services/send.php"
params = {
    "key": "YOUR_API_KEY",
    "number": "0608918217",
    "message": "This message",
    "devices": '["182|0","182|1"]',
    "type": "sms",
    "prioritize": 0
}

response = requests.get(url, params=params)
print(response.json())
Java
import java.io.*;
import java.net.*;

public class Sms8Api {
    public static void main(String[] args) throws Exception {
        String urlStr = "https://app.sms8.io/services/send.php?key=YOUR_API_KEY&number=0608918217&message=This+message&devices=%5B%22182%7C0%22%2C%22182%7C1%22%5D&type=sms&prioritize=0";
        URL url = new URL(urlStr);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("GET");

        BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
        String inputLine;
        StringBuffer content = new StringBuffer();
        while ((inputLine = in.readLine()) != null) {
            content.append(inputLine);
        }
        in.close();
        System.out.println(content.toString());
    }
}

Response Format

Success Response

A successful request returns a JSON object with detailed message information:

 
{
  "success": true,
  "data": {
    "messages": [
      {
        "ID": 296180,
        "number": "0608918217",
        "message": "This message",
        "deviceID": 182,
        "simSlot": 0,
        "schedule": null,
        "userID": 1,
        "groupID": "DEGxMhxJiQUpU9F6nY671d682d63d9e2.96844762",
        "status": "Pending",
        "resultCode": null,
        "errorCode": null,
        "type": "sms",
        "attachments": null,
        "prioritize": false,
        "retries": null,
        "sentDate": "2024-10-26T23:07:41+0100",
        "deliveredDate": null,
        "expiryDate": null
      }
    ]
  },
  "error": null
}

Error Response

In case of an error, the API returns a JSON object with an error code and message:

 
{
  "success": false,
  "data": null,
  "error": {
    "code": 401,
    "message": "This API key is invalid."
  }
}

Balance Query Response

If querying for credits, the response may look like this:

 
{
  "success": true,
  "data": {
    "credits": null
  },
  "error": null
}

Status Codes

  • 200: Request was successful.
  • 400: Bad request (missing parameters, invalid format).
  • 401: Unauthorized (invalid API key).
  • 500: Internal server error.
 

Endpoint: Get Message Status

  • URL: https://app.sms8.io/services/get-msgs.php
  • Method: GET

Request Parameters

  • key: Your unique API key (required).
  • status: Filter messages by status. Options include:
    • Received
    • Pending
    • Sent
    • Failed
    • Queued
    • Delivered
    • Scheduled

Example Request:

 
 
GET https://app.sms8.io/services/get-msgs.php?key=dcf65ee699fe13eec2baaf06d1cfb6826e150a0d&status=Received

Example Code Snippets:

  • cURL:

 
 
curlA "https://app.sms8.io/services/get-msgs.php?key=dcf65ee699fe13eec2baaf06d1cfb6826e150a0d&status=Received"

  • PHP:

 
 
$url = "https://app.sms8.io/services/get-msgs.php?key=dcf65ee699fe13eec2baaf06d1cfb6826e150a0d&status=Received";
$response = file_get_contents($url);
echo $response;

  • JavaScript (Fetch):

 
 
fetch("https://app.sms8.io/services/get-msgs.php?key=dcf65ee699fe13eec2baaf06d1cfb6826e150a0d&status=Received")
  .then(response => response.json())
  .then(data => console.log(data));
  • Python:
 
 
import requests

url = "https://app.sms8.io/services/get-msgs.php"
params = {
    "key": "dcf65ee699fe13eec2baaf06d1cfb6826e150a0d",
    "status": "Received"
}
response = requests.get(url, params=params)
print(response.json())
  • C# :
 
 
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var url = "https://app.sms8.io/services/get-msgs.php?key=dcf65ee699fe13eec2baaf06d1cfb6826e150a0d&status=Received";
        using var client = new HttpClient();
        var response = await client.GetStringAsync(url);
        Console.WriteLine(response);
    }
}
  • Java:
 
 
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class GetMessageStatus {
    public static void main(String[] args) throws Exception {
        String url = "https://app.sms8.io/services/get-msgs.php?key=dcf65ee699fe13eec2baaf06d1cfb6826e150a0d&status=Received";
        URL obj = new URL(url);
        HttpURLConnection con = (HttpURLConnection) obj.openConnection();
        con.setRequestMethod("GET");
        BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
        String inputLine;
        StringBuffer content = new StringBuffer();
        while ((inputLine = in.readLine()) != null) {
            content.append(inputLine);
        }
        in.close();
        System.out.println(content.toString());
    }
}

Possible Responses

  • Success Response: Message status details.

{
  "success": true,
  "data": {
    "messages": [
      {
        "ID": 296180,
        "number": "0608918217",
        "message": "This message",
        "deviceID": 182,
        "status": "Delivered",
        // Additional fields...
      }
    ]
  },
  "error": null
}

Error Response: Example of an invalid API key error.

{
  "success": false,
  "data": null,
  "error": {
    "code": 401,
    "message": "This API key is invalid."
  }
}

SMS8 Webhook

This documentation provides an overview of setting up and handling webhooks for SMS8, allowing developers to receive and respond to events like incoming messages or USSD requests. Webhooks can be configured and managed in the SMS8 Webhook Management.

Introduction

Webhooks in SMS8 let you automatically trigger specific actions when events occur, like receiving an SMS message or a USSD request on your connected Android device. You can set up a URL endpoint on your server that SMS8 can call, delivering event data in real-time. This integration makes it easy to automate responses or trigger workflows based on the incoming data.

Prerequisites

  1. Webhook URL: You’ll need an endpoint on your server to receive SMS8 webhook requests.
  2. API Key: Define your unique API_KEY for hashing signatures. This key will authenticate incoming requests to ensure security.

Security Overview

Each webhook request contains a signature in the HTTP_X_SG_SIGNATURE header to verify the request authenticity. Use your API_KEY to hash the message content and compare it against this signature.

Example Code

Here is a PHP example to help developers get started with SMS8 Webhooks. This script listens for incoming SMS messages and USSD requests, verifies the signature, and processes the data.

<?php
// Replace with your API Key
define("API_KEY", "dcf65ee699fe13eec2baaf06d1cfb6826e150a0d");

try {
    if (isset($_SERVER["HTTP_X_SG_SIGNATURE"])) {
        // Handling incoming SMS messages
        if (isset($_POST["messages"])) {
            $hash = base64_encode(hash_hmac('sha256', $_POST["messages"], API_KEY, true));
            if ($hash === $_SERVER["HTTP_X_SG_SIGNATURE"]) {
                $messages = json_decode($_POST["messages"], true);

                foreach ($messages as $message) {
                    // Check if message content is "hi" and respond
                    if (strtolower($message["message"]) === "hi") {
                        // You can respond using an API call here, for example:
                        // sendReply($message["number"], "Hello! How can I help you?");
                    }
                }
            } else {
                throw new Exception("Signature doesn't match!");
            }
        }
        // Handling USSD requests
        else if (isset($_POST["ussdRequest"])) {
            $hash = base64_encode(hash_hmac('sha256', $_POST["ussdRequest"], API_KEY, true));
            if ($hash === $_SERVER["HTTP_X_SG_SIGNATURE"]) {
                $ussdRequest = json_decode($_POST["ussdRequest"]);
                $deviceID = $ussdRequest->deviceID;
                $simSlot = $ussdRequest->simSlot;
                $request = $ussdRequest->request;
                $response = $ussdRequest->response;

                // Perform actions based on USSD data
            } else {
                throw new Exception("Signature doesn't match!");
            }
        }
    } else {
        http_response_code(400);
        error_log("Signature not found!");
    }
} catch (Exception $e) {
    http_response_code(401);
    error_log($e->getMessage());
}
?>

Explanation of Fields

Incoming SMS Messages

The webhook receives SMS messages in the messages array, where each message has the following structure:

  • ID: Unique identifier of the message.
  • number: The sender’s phone number.
  • message: The content of the SMS.
  • deviceID: The ID of the device that received the message.
  • simSlot: The SIM slot that received the message.
  • userID: User ID associated with the message.
  • status: Current status of the message (e.g., “Received”).
  • sentDate: Date and time the message was received on the device.
  • deliveredDate: Date and time the message was received by the server.
  • groupID: If the message is part of a group, it contains the group ID; otherwise, it’s null.

Incoming USSD Requests

USSD requests have the following fields:

  • deviceID: The ID of the device that received the USSD request.
  • simSlot: The SIM slot from which the request was received.
  • request: The USSD code entered.
  • response: Response text associated with the USSD request.

Setting Up Webhooks on SMS8

  1. Log in to the SMS8 Webhook Management.
  2. Enter your webhook URL, where SMS8 will send requests.
  3. Select the types of events (e.g., SMS, USSD) you want to receive at this endpoint.
  4. Save your settings.

This concludes the SMS8 Webhook documentation, providing developers with the necessary information to set up and handle SMS8 webhooks.

Contact information

For any additional questions, technical support, or feature requests, please don’t hesitate to reach out. We’re here to assist you in making the most of your SMS8 experience!

Contact Information

Thank you for choosing SMS8 for your SMS solutions!