Introduction

The SMS Cellular API is presented as a collection of JSON services. These services are simple to use and can be easily accessed with most programming languages in various computing environments. Endpoints that you interact with directly (used for sending SMS, MMS, or the tracking of messages) are accessible through the HTTPS protocol and secured with basic authentication. To receive feedback information and mobile responses in a push fashion, you need to create and share similar endpoints. We will then use these endpoints to provide you with feedback. More information is available in the smsfeedback section.

Authentication

Service Authentication

We secure our services (used for sending SMS, MMS, or the tracking of messages) with basic authentication.

Basic Athentication within the header of the HTTPS request.

using System;
using System.Net;
using System.Text;

public void AddAuthorizationHeader(HttpWebRequest httpWebRequest, string username, string password)
    {
        string encodedCredentials = Convert.ToBase64String(
            Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password)
            );
        httpWebRequest.Headers.Add("Authorization", "Basic " + encodedCredentials);
    }

The above code will add a header to the HTTPS request that looks like this:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Feedback Authentication

The feedback endpoints you share can use either basic authentication or bearer token authentication. You can configure these authentication methods, along with the URLs and required credentials, using the dashboard.

SMS

sendsmsV1

To send a SMS, you simply need to send a JSON message using the sendsmsV1 URL that we gave you during your sign-up. We offer three endpoints for each service to support development, testing, and production environments, making it easier for you to manage different stages of your work.

sendsmsV1 HTTPS Request

To invoke this service, you need to POST a JSON request, with a content type of application/json, to the sendsmsV1 URL we provided during your sign-up.

POST to sendsmsV1:

HttpWebRequest httpWebRequest = (HttpWebRequest)WebRequest.Create("https://***.cellsysapps.com/api/dev/sendsmsV1");

httpWebRequest.Method = "POST";
httpWebRequest.ContentType = "application/json";
httpWebRequest.Headers.Add("CountryCode", "ZA");
httpWebRequest.Headers.Add("LanguageCode", "en");

AddAuthorizationHeader(httpWebRequest, "username", "password");

using (StreamWriter streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{                 
    streamWriter.Write(jsonRequestBody);
}

using (HttpWebResponse httpResponse = (HttpWebResponse)httpWebRequest.GetResponse())
{
    //Do what you need with the response
}

The request must have a JSON body structured like this:

{
  "correlationId": 1,
  "msisdn": "27831231234",
  "message": "Hello",
  "simulate": true
}

• POST https://***.cellsysapps.com/api/dev/sendsmsV1 (development environment)
• POST https://***.cellsysapps.com/api/test/sendsmsV1 (testing environment)
• POST https://***.cellsysapps.com/api/prod/sendsmsV1 (production environment)

sendsmsV1 Request Fields

sendsmsV1 HTTPS Response

You will receive a response indicating the submission status of the SMS. It's important to note that this status doesn't confirm whether the SMS was sent; it only indicates if the SMS was successfully queued for processing or not. To check if the SMS was indeed sent, you can use the tracksmsV1 service or set up a smsfeedback service to receive feedback in a push fashion.

The above request will respond with a JSON body of:

{
  "correlationId": 1,
  "statusCode": 0,
  "statusMsg": "Submitted for processing"
}

HTTP 200 OK

sendsmsV1 Response Fields

tracksmsV1

Tracking enables you to get status updates for a previously sent SMS by using its corresponding correlation ID. The returned information includes status messages from the mobile network operators (MNOs) and any replies associated with that specific SMS. Additionally, feedback messages and mobile replies can be sent (pushed) to the endpoint you specified in the dashboard - see smsfeedback for more information. Please note that tracking information is available for 45 days by default from the time the original SMS was sent.

tracksmsV1 HTTPS Request

To invoke this service, you need to POST a JSON request, with a content type of application/json, to the tracksmsV1 URL we provided during your sign-up.

POST to tracksmsV1:

The request must have a JSON body structured like this:

{
  "correlationId": 1
}

POST https://***.cellsysapps.com/api/tracksmsV1 (used across all three environments)

tracksmsV1 Request Fields

tracksmsV1 HTTPS Response

You will receive a response containing all information available for a particular SMS.

The above request will respond with a JSON body of:

{
  "correlationId": "1",
  "status": {
    "source": "102.32.82.192",
    "msisdn": "27831231234",
    "message": "Hello",
    "submissionDate": "2024-01-09T12:14:40.000Z",
    "submissionCode": 0,
    "submissionMsg": "Submitted for processing",
    "firstStatusDate": "2024-01-09T12:14:40.000Z",
    "firstStatusCode": 0,
    "firstStatusMsg": "Message accepted by the SMSC. (ID=0026659401 SEQ=M04493590) (27831231234)",
    "secondStatusDate": "2024-01-09T12:14:52.000Z",
    "secondStatusCode": 0,
    "secondStatusMsg": "Status: DELIVRD Result: Successful (ID=0026659401) (21/06/09 14:14)"
  },
  "replies": [
    {
      "source": "MNO",
      "msisdn": "27831231234",
      "message": "Test reply",
      "replyDate": "2024-01-09T12:15:12.000Z",
      "replyCode": 0,
      "replyMsg": "Reply received from recipient"
    }
  ]
}

HTTP 200 OK

tracksmsV1 Response Fields

tracksmsV1 Status Fields

tracksmsV1 Reply Fields

smsfeedback

For every SMS sent, you'll receive feedback from the mobile network operator (MNO). The initial message (First status) usually indicates the "accepted" or "rejected" status. After a message is accepted for processing, a second message (Second status) will convey the delivery status. To receive these status messages in a push manner, you need to set up a JSON service for us to call. It's advisable for the endpoint's path to conclude with /smsfeedback. We will send POST requests containing the feedback messages to the URL you specified in the dashboard. Each environment (development, testing, and production) can have its own smsfeedback endpoint. Eg.

• https://yourdomain.co.za/dev/smsfeedback (development environment)
• https://yourdomain.co.za/test/smsfeedback (testing environment)
• https://yourdomain.co.za/prod/smsfeedback (production environment)

smsfeedback HTTPS Request

First Status Message

{
    "correlationId": 1,
    "feedbackType": 1,
    "statusCode": 0,
    "statusMsg": "Message accepted by the SMSC. (ID=0026659401 SEQ=M04493590) (27831231234)"
}

Second Status Message

{
    "correlationId": 1,
    "feedbackType": 2,
    "statusCode": 0,
    "statusMsg": "Status: DELIVRD Result: Successful (ID=0026659401) (21/06/09 14:14)"
}

smsfeedback Request Fields

smsfeedback HTTPS Response

It is expected that your service responds to this POST with a HTTPS response that is similar to the HTTPS response of the sendsmsV1 service.

Your service should respond with a JSON body of:

{
  "correlationId": 1,
  "statusCode": 0,
  "statusMsg": "OK"
}

HTTP 200 OK

smsfeedback Response Fields

smsreply

To receive SMS replies, you need to set up a second endpoint for each environment, similar to smsfeedback. It's advised to conclude the path of this endpoint with /smsreply. We will send the reply SMS to the URL configured in the dashboard using POST requests. Eg.

• https://yourdomain.co.za/dev/smsreply (development environment)
• https://yourdomain.co.za/test/smsreply (testing environment)
• https://yourdomain.co.za/prod/smsreply (production environment)

smsreply HTTPS Request

Reply Message

{
  "correlationId": 1,
  "msisdn": "27831231234",
  "message": "Reply message from mobile"
}

smsreply Request Fields

smsreply HTTPS Response

It is expected that your service responds to this POST with a HTTPS response that is similar to the HTTPS response of the sendsmsV1 service.

Your service should respond with a JSON body of:

{
  "correlationId": 1,
  "statusCode": 0,
  "statusMsg": "OK"
}

HTTP 200 OK

smsreply Response Fields

simulator

The simulator is designed for testing purposes, mimicking the responses anticipated from the live system. Under regular conditions, the simulator will provide both a first status and a second status message. To dispatch a message to the simulator, set the simulate field to true in the sendsmsV1 request.

Example sendsmsV1 request body for the simulator

{
  "correlationId": 1,
  "msisdn": "27831231234",
  "message": "zz-Hello?",
  "simulate": true
}

Other simulator functions

Simulate Replies

If the SMS ends with a ?, a reply will also be simulated for this message.

Simulate Failed Status Messages

Failed first and second status messages can also be simulated by simply starting the SMS with one of these flags.

MMS

This MMS section is still under construction

sendmmsV1

To send a MMS, you simply need to send a JSON message using the sendmmsV1 URL that we gave you during your sign-up. We offer three endpoints for each service to support development, testing, and production environments, making it easier for you to manage different stages of your work.

sendmmsV1 HTTPS Request

To invoke this service, you need to POST a JSON request, with a content type of application/json, to the sendmmsV1 URL we provided during your sign-up.

POST to sendmmsV1:

HttpWebRequest httpWebRequest = (HttpWebRequest)WebRequest.Create("https://***.cellsysapps.com/api/dev/sendmmsV1");

httpWebRequest.Method = "POST";
httpWebRequest.ContentType = "application/json";
httpWebRequest.Headers.Add("CountryCode", "ZA");
httpWebRequest.Headers.Add("LanguageCode", "en");

AddAuthorizationHeader(httpWebRequest, "username", "password");

using (StreamWriter streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{                 
    streamWriter.Write(jsonRequestBody);
}

using (HttpWebResponse httpResponse = (HttpWebResponse)httpWebRequest.GetResponse())
{
    //Do what you need with the response
}

The request must have a JSON body structured like this:

{
  "correlationId": 1,
  "msisdn": "27831231234",
  "subject": "my subject",
  "text": [
    {
      "id": "some_id",
      "data": "some text..."
    }
  ],
  "png": [
    {
      "id": "some_id",
      "dataB64": "some base64 png data..."
    }
  ],
  "vcard": [
    {
      "id": "some_id",
      "data": "some vcard data..."
    }
  ]
  "smil": "<smil>...some smil layout data...</smil>",
  "simulate": true
}

• POST https://***.cellsysapps.com/api/dev/sendmmsV1 (development environment)
• POST https://***.cellsysapps.com/api/test/sendmmsV1 (testing environment)
• POST https://***.cellsysapps.com/api/prod/sendmmsV1 (production environment)

sendmmsV1 Request Fields

sendmmsV1 HTTPS Response

You will receive a response indicating the submission status of the MMS. It's important to note that this status doesn't confirm whether the MMS was sent; it only indicates if the MMS was successfully queued for processing or not. To check if the MMS was indeed sent, you can use the trackmmsV1 service or set up a mmsfeedback service to receive feedback in a push fashion.

The above request will respond with a JSON body of:

{
  "correlationId": 1,
  "statusCode": 0,
  "statusMsg": "Submitted for processing"
}

HTTP 200 OK

sendmmsV1 Response Fields

trackmmsV1

Tracking enables you to get status updates for a previously sent MMS by using its corresponding correlation ID. The returned information includes status messages from the mobile network operators (MNOs) and any replies associated with that specific MMS. Additionally, feedback messages and mobile replies can be sent (pushed) to the endpoint you specified in the dashboard - see mmsfeedback for more information. Please note that tracking information is available for 45 days by default from the time the original MMS was sent.

trackmmsV1 HTTPS Request

To invoke this service, you need to POST a JSON request, with a content type of application/json, to the trackmmsV1 URL we provided during your sign-up.

POST to trackmmsV1:

The request must have a JSON body structured like this:

{
  "correlationId": 1
}

POST https://***.cellsysapps.com/api/trackmmsV1 (used across all three environments)

trackmmsV1 Request Fields

trackmmsV1 HTTPS Response

You will receive a response containing all information available for a particular MMS.

The above request will respond with a JSON body of:

{
  "correlationId": "1",
  "status": {
    "source": "102.32.82.192",
    "msisdn": "27831231234",
    "subject": "my subject",
    "submissionDate": "2024-01-09T12:14:40.000Z",
    "submissionCode": 0,
    "submissionMsg": "Submitted for processing",
    "firstStatusDate": "2024-01-09T12:14:40.000Z",
    "firstStatusCode": 0,
    "firstStatusMsg": "Sending succeeded",
    "secondStatusDate": "2024-01-09T12:14:52.000Z",
    "secondStatusCode": 0,
    "secondStatusMsg": "Message delivered"
  },
  "replies": []
}

HTTP 200 OK

trackmmsV1 Response Fields

trackmmsV1 Status Fields

mmsfeedback

For every MMS sent, you'll receive feedback from the mobile network operator (MNO). The initial message (First status) usually indicates the "accepted" or "rejected" status. After a message is accepted for processing, a second message (Second status) will convey the delivery status. To receive these status messages in a push manner, you need to set up a JSON service for us to call. It's advisable for the endpoint's path to conclude with /mmsfeedback. We will send POST requests containing the feedback messages to the URL you specified in the dashboard. Each environment (development, testing, and production) can have its own mmsfeedback endpoint. Eg.

• https://yourdomain.co.za/dev/mmsfeedback (development environment)
• https://yourdomain.co.za/test/mmsfeedback (testing environment)
• https://yourdomain.co.za/prod/mmsfeedback (production environment)

mmsfeedback HTTPS Request

First Status Message

{
    "correlationId": 1,
    "feedbackType": 1,
    "statusCode": 0,
    "statusMsg": "Message accepted by the SMSC. (ID=0026659401 SEQ=M04493590) (27831231234)"
}

Second Status Message

{
    "correlationId": 1,
    "feedbackType": 2,
    "statusCode": 0,
    "statusMsg": "Status: DELIVRD Result: Successful (ID=0026659401) (21/06/09 14:14)"
}

mmsfeedback Request Fields

mmsfeedback HTTPS Response

It is expected that your service responds to this POST with a HTTPS response that is similar to the HTTPS response of the sendmmsV1 service.

Your service should respond with a JSON body of:

{
  "correlationId": 1,
  "statusCode": 0,
  "statusMsg": "OK"
}

HTTP 200 OK

mmsfeedback Response Fields

simulator

The simulator is not fully functional at present.

The simulator is designed for testing purposes, mimicking the responses anticipated from the live system. Under regular conditions, the simulator will provide both a first status and a second status message. To dispatch a message to the simulator, set the simulate field to true in the sendmmsV1 request.

Example sendmmsV1 request body for the simulator

{
  "correlationId": 1,
  "msisdn": "27831231234",
  "message": "zz-Hello?",
  "simulate": true
}

Other simulator functions

Simulate Replies

If the MMS subject ends with a ?, a reply will also be simulated for this message.

Simulate Failed Status Messages

Failed first and second status messages can also be simulated by simply starting the MMS subject with one of these flags.

EMAIL

This EMAIL section is still under construction

send sms

Send an SMS using email

Example 1 (text body)

 `To: 27831231234@cellsysapps.com`
 `Subject: message to Joe`
 `Body Text: Hi Joe,`
 `           How are you doing?`
 `           Jane`

SMS: Hi Joe, How are you doing? Jane

Example 2 (no text body, but subject present)

 `To: 27831231234@cellsysapps.com`
 `Subject: Hi Joe, How are you doing? Jane`

SMS: Hi Joe, How are you doing? Jane

Example 3 (no text body, no subject, but HTML content present)

 `To: 27831231234@cellsysapps.com`
 `Body HTML: <h1>Hi Joe,</h1><div>How are you doing?</div><div>Jane</div>`

SMS: Hi Joe, How are you doing? Jane

Example 4 (send subject rather than text body)

 `To: 27831231234@cellsysapps.com`
 `Subject: message to Joe`
 `Body Text: Hi Joe,`
 `           How are you doing?`
 `           Jane`
 `           !--!`

SMS: message to Joe

Example 5 (no text body, send HTML content rather than the subject)

 `To: 27831231234@cellsysapps.com`
 `Subject: message to Joe !--!`
 `Body HTML: <h1>Hi Joe,</h1><div>How are you doing?</div><div>Jane</div>`

SMS: Hi Joe, How are you doing? Jane

Example 6 (no text body, send selected HTML content rather than the subject)

 `To: 27831231234@cellsysapps.com`
 `Subject: message to Joe !--!`
 `Body HTML: <h1>Hi Joe, !++!</h1><div>How are you doing?</div><div>Jane !++!</div>`

SMS: Hi Joe, Jane

Sending an SMS via email is a breeze! Just follow these simple steps:

1. Compose an email to xxx@cellsysapps.com (replace xxx with the destination cellphone number).
2. Place your SMS message in the body of the email as plain text content.
3. Hit send!

If the email body contains plain text content, that content will be used as the SMS message. In case there's no plain text content in the email body, our service will check the email subject and utilize it as the SMS message. If there's no email subject, we'll look for HTML content in the email body. However, please note that using HTML content doesn't always produce optimal results. If HTML content is present, we'll remove all the HTML tags and use the resulting text as the SMS message. If there's no HTML content in the email body either, the message will be rejected, and nothing will be sent. For the smoothest experience, we recommend including your SMS message directly in the email body as plain text content.

Using the magic tokens

Integrate the special token !--! anywhere within the email content or subject, and watch the magic unfold! This unique token instructs the service to exclude the specified content when determining the SMS message value. It's a handy feature if you wish to selectively bypass certain parts of the email, ensuring they won't be incorporated into the SMS message.

Simply use !--! strategically to tailor your SMS content exactly the way you want it. This gives you the flexibility to control which portions of the email contribute to the final SMS, allowing for a customized and precise messaging experience.

For even better control over the final SMS, use the !++! special token within the HTML content. This unique token instructs the service to include only the specified content when determining the SMS message value.

send mms