Bulk Send SMS

This API is to send Bulk SMS messages using the Cellcast API. The API detects any invalid contact numbers and return which numbers are invalid or unsubscribed on the response body, ensuring that messages are sent only to valid and subscribed numbers.

Parameters for Send SMS API

Headers Parameters

Parameters	Description
Authorization	Please add provided Bearer token - linked to your Cellcast account. Check here

Request Body Parameters

Name	Example	Description
sender	#SharedNum# or Sender ID (Custom ID)	Sender ID (Custom ID): Valid characters: A-Z a-z 0-9, space, and Dash (-). A numeric sender ID can be a maximum length of 16 digits. An alpha-numeric Sender ID can be a maximum length of 11 characters. If 'sender' is left blank, the system will default to '#SharedNum#'. *Note: Price increases to 1.3 credits per SMS for Custom ID and dedicated numbers.
message	SMS Text goes here	String - Required field. To add a new line to the message, use "\r\n" in the message string with only double quotes.
contacts	["+61400000000"]	JSON encoded Array - Required field. To send multiple SMS messages, provide the recipient numbers in a JSON-encoded array, such as ["+61400000000", "+61400000001"]. You can include up to 1,000 numbers in a single API call. Supported number formats include : "+61400000000", "61400000000", "0400000000", "400000000"
countryCode	61	Allowed values: 61
scheduleAt	2024-08-14T14:58:00.981Z	Leave blank for immediate delivery. Your schedule time should be in Y-m-d H:i:s format UTC+0 Time
delay	60000	Leave blank for immediate delivery. Your delay time should be in miliseconds. Allowed max 86400000 miliseconds (24 Hours)

Code Samples

Post https://api.cellcast.com/api/v1/gateway

cURL

curl --location 'https://api.cellcast.com/api/v1/gateway' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{API_KEY}}' \
--data '{
  "message": "Test API Bulk SMS",
  "contacts": [
    "+61400000001",
    "+61400000002",
    "+61400000003",
    "+61400000004"
  ],
  "sender": "+61400000001"
}'

node.js

const axios = require("axios");

const sendSMS = async () => {
  try {
    const response = await axios.post(
      "https://api.cellcast.com/api/v1/gateway",
      {
        message: "Test API Bulk SMS",
        contacts: ["+61400000000","+61400000001","+61400000002"],
        sender: "+61400000001"
      },
      {
        headers: {
          "Content-Type": "application/json",
          Accept: "application/json",
          Authorization: "Bearer {{API_KEY}}",
        },
      }
    );
    console.log(response.data);
  } catch (error) {
    console.error(error.response.data);
  }
};

Replace with the actual API key that you own.

Responses

Response Body

Name	Example	Description
messageId	675161d8a000000000000000	A unique identifier for the message, automatically generated by the system.

200 Success

{
    "app_type": "web",
    "app_version": "1.0",
    "maintainence": 0,
    "new_version": 0,
    "force_update": 0,
    "invalid_token": 0,
    "refresh_token": "",
    "show_message": 0,
    "is_enc": false,
    "status": true,
    "message": "Request is being processed",
    "message_type": "toast",
    "data": {
        "queueResponse": [
            {
                "Contact": "400000000",
                "MessageId": "675161d8a000000000000000",
                "Result": "Message added to queue."
            },
            {
                "Contact": "400000001",
                "MessageId": "675161d8a000000000000000",
                "Result": "Message added to queue."
            },
            {
                "Contact": "400000002",
                "MessageId": "675161d8a000000000000000",
                "Result": "Message added to queue."
            }
        ],
        "message": "success register all valid contacts to queue",
        "invalidContacts": [
            {
                "Contact": "+6140000",
                "Error": "Number is less than 9 digit",
                "ErrorType": "less_nine_digit"
            },
            {
                "Contact": "+61400000003123132",
                "Error": "Number is not valid",
                "ErrorType": "number_not_valid"
            },
            {
                "Contact": "+65400000000",
                "Error": "Number is not valid",
                "ErrorType": "number_not_valid"
            },
            {
                "Contact": "1400000006",
                "Error": "Number is not valid",
                "ErrorType": "number_not_valid"
            }
        ],
        "unsubscribeContacts": [
            "400000003"
        ],
        "totalValidContact": 3,
        "totalInvalidContact": 4,
        "totalUnsubscribeContact": 1
    },
    "error": {}
}

400 Bad Request contact not exist

{
    "code": 400,
    "message": "Contacts must either start with 61 or +61 and be exactly 11 digits long (e.g., 614xxxxxxxx or +614xxxxxxxx), or be 9 digits without the area code (e.g., 4xxxxxxxx)",
    "stack": "APIError: Contacts are required."
}

422 Unprocessable Entity (Credit is too Low)

{
    "app_type": "web",
    "app_version": "1.0",
    "maintainence": 0,
    "new_version": 0,
    "force_update": 0,
    "invalid_token": 0,
    "refresh_token": "",
    "show_message": 0,
    "is_enc": false,
    "status": false,
    "message_type": "toast",
    "message": "Your balance is too low for this request, please recharge.",
    "data": {},
    "error": {
        "errorMessage": "Your balance is too low for this request, please recharge."
    }
}

401 Unauthorized

{
  "code": 401,
  "message": "Token expired",
  "stack": "APIError: Token expired ...."
}