Skip to main content
Version: Next

Send SMS via the Comms API: Request & Response

The Pahappa Comms API provides a single JSON endpoint for sending SMS messages. This page covers the request structure, authentication, and response format for the SendSms method.

Endpoint​

Send a POST request to the following URL with Content-Type: application/json:

POST https://comms.egosms.co/api/v1/json/
Content-Type: application/json

Quick example​

Replace YOUR_USERNAME and YOUR_PASSWORD with your credentials and run this to send a single message:

curl -X POST https://comms.egosms.co/api/v1/json/ \
  -H "Content-Type: application/json" \
  -d '{
    "method": "SendSms",
    "userdata": {
      "username": "YOUR_USERNAME",
      "password": "YOUR_PASSWORD"
    },
    "msgdata": [
      {
        "number": "256700111222",
        "message": "Hello World!",
        "senderid": "MyCompany",
        "priority": 1
      }
    ]
  }'

Authentication​

Include your API credentials inside the userdata object in every request. You can find your API username and API password in the Comms platform under Settings > API Settings.

Request fields​

methodstringrequired

Must be "SendSms".

userdataobjectrequired

Authentication credentials object.

userdata.usernamestringrequired

Your API username, copied from the platform under Settings > API Settings.

userdata.passwordstringrequired

Your API password, copied from the platform under Settings > API Settings.

msgdataarrayrequired

List of message objects to send. A single request may contain at most 1000 message objects — split larger batches across multiple requests.

msgdata[].numberstringrequired

Recipient phone number in international format, without a leading + or 00, for example "256700111222".

msgdata[].messagestringrequired

SMS message content.

msgdata[].senderidstringdefault: EgoSMS

Sender ID as configured in your Comms account.

msgdata[].priorityintegerdefault: 1

Optional message priority, from 0 (most urgent) to 4 (send later). Lower value = higher priority. See MessagePriority.

Request examples​

Send one message​

{
   "method": "SendSms",
   "userdata": {
      "username": "api_username",
      "password": "api_key"
   },
   "msgdata": [
      {
         "number": "256700111222",
         "message": "Hello World!",
         "senderid": "MyCompany",
         "priority": 1
      }
   ]
}

Send many messages​

{
   "method": "SendSms",
   "userdata": {
      "username": "api_username",
      "password": "api_key"
   },
   "msgdata": [
      {
         "number": "256700111222",
         "message": "Hello World!",
         "senderid": "MyCompany"
      },
      {
         "number": "256700333444",
         "message": "Hello World 2!",
         "senderid": "MyCompany"
      }
   ]
}

Each object in msgdata is independent, so you can vary the message, sender ID, and priority per recipient. priority is omitted here, so both messages default to 1.

Response fields​

Statusstring

"OK" on success, or "Failed" on error.

Messagestring

Human-readable status message. This field only exists when the Status is "Failed"

Costnumber

Credit cost of the sent messages. Not always a whole number. This field only exists when the Status is "OK"

MsgFollowUpUniqueCodestring

Unique tracking code, for example 8efd86fb78a56a5145ed7739dcb00c78581c5375. Use this to query delivery status later. This field only exists when the Status is "OK"

Response examples​

Status=OK​

{
  "Status": "OK",
  "Cost": 35,
  "MsgFollowUpUniqueCode": "8efd86fb78a56a5145ed7739dcb00c78581c5375"
}

Cost isn't always a whole number — sending to a different network or country can produce a fractional cost, for example "Cost": 0.09.

Status=Failed​

{
  "Status": "Failed",
  "Message": "Wrong Username or Password."
}

Error handling​

Failures still return HTTP 200

The API returns HTTP 200 OK even when a request fails. Do not rely on the HTTP status code — always check the Status field in the response body, and treat "Failed" as an error.

If Status is "Failed", the Message field contains the reason for the failure. For a full list of error codes and troubleshooting guidance, see the Error Handling page.

Next steps​