Send an SMS with Cellcast RESTful API

With our SMS messaging API you can:

  1. Send SMS messages.
  2. Receive real time delivery reports (DLR) for all messages sent.
  3. Receive replies and inbound SMS messages.


Our simple REST API allows you to get up and running in minutes, just follow the helpful Quick Start guide. For advanced users, dig deeper into our technology and check our reference guides for more detailed functions and calls. We have a wide range of calls to mirror useful functionality on the site at both user and reseller level. We also offer code samples in order to make your experience using the API suite as clean as possible.


So let's now look at how to use and get the best out of the REST API.


Security

To ensure security & privacy the API only works over HTTPS protocol for all requests. Also, for your own security, If you have a website with a form which sends SMS be sure to send the request from your server and not directly from the browser otherwise you will be giving away your API secret and opening the floodgates to unwanted charges.


Authentication

All API requests require your API credentials, We will provide you APPKEY. For Security API credentials must be passed as HTTP Basic Authentication headers not as CGI parameters.


Throttling

To provide the best service to all our customers we limit the number of API calls which can be made by each account to 15 calls per sec. For heavy users we can increase your throttling speed, but please contact us to discuss your requirements. If you exceed this limit we will return two indicators which you can use in your code to detect that you have been throttled. The first is the HTTP status code 429 "Too Many Requests", the second is the error code "OVER_LIMIT" in the error block of the response body.


Pagination

Some responses are too large to be returned in one go so we paginate. To identify which calls use pagination look for the "page" parameters in the parameter descriptions for each API call. These calls include a "page" block in the response with two values, "count" and "number". Count tells you how many pages are available and number indicates the page number you are on. The page parameter is used to request a certain page, it defaults to 1. 25 responses will be returned per page.


Error Reporting

Always check if your API call was successful or resulted in error. You may check the following

  1. 200 OK response header. It will be 4xx if an error occurred.
  2. error->code structure should equal to 'SUCCESS'Note that some API functions can return custom errors of their own (listed in appropriate document sections). Check the error->description for details, e.g. which field caused an error or which resource you don’t have access to.

We can't wait to see what you build!


Send SMS

Base URL:

https://cellcast.com.au/api/v3/send-sms
Method: POST

Parameters

Header Parameters Description
APPKEY Please add provided APPKEY - linked to your Cellcast account.
Content-Type application/json

SMS Data Parameters

Name Example Description
sms_text 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 quote
numbers ["+61400000000"] JSON encoded Array - Required field For multiple SMS send: ["+61400000000","+61400000001"] You can pass 1000 numbers to send an SMS in one API call
from 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 'from' is left blank system will default to 'Regular ID' *note price increases to 1.3 credits per sms for Custom ID and dedicated numbers
source Allow any text in source. eg. ZOHO, Zappier Allowed characters: letters, numbers, and dashes in the source
custom_string Allow any text in Custom string. eg. ZOHO, Zappier Allowed characters: letters, numbers, and dashes in Custom string
schedule_time (Optional) Y-m-d H:i:s format. eg. 2020-02-14 20:00:05 Leave blank for immediate delivery. Your schedule time in Y-m-d H:i:s format.
delay (Optional) Valid value : 1 to 1440 minutes Leave blank for immediate delivery. Allowed max 1440 Delay minutes (24 Hours)

Successful Responses

Code Status Description
200 SUCCESS You will get SMS scheduled count and credit deduction count.

Successful Responses look like:

 {
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "Queued",
    "data": {
        "messages": [
            {
                "message_id": "6EF87246-52D3-74FB-C319-NNNNNNNNNN",
                "from": "SENDER_ID",
                "to": "+614NNNNNNN",
                "body": "SMS body here",
                "date": "2019-06-15 14:02:29",
                "custom_string": "lead",
                "direction": "out"
            }
        ],
        "total_numbers": 1,
        "success_number": 1,
        "credits_used": 1
    },
    "low_sms_alert": "Your account credits are low, you have 36.80 credits remaining, please top-up via the platform"
}

Error Response

Status Code Description
AUTH_FAILED_NO_DATA 401 You have not provided APPKEY
AUTH_FAILED 401 - APPKEY you have provided is invalid - You are not a registered user
FIELD_EMPTY 400 Required field is empty
RECIPIENTS_ERROR 400 No valid recipients left after validation or recipient in unsubscribed list.(You can send an SMS to any Australian Mobile number.)
FIELD_INVALID 400 - You can pass 10000 numbers to send an SMS in one API call - You can send the maximum message length of 918 characters, or send a message length of 402 characters for the Unicode character set. - You do not have enough credit to send SMS
BAD_REQUEST 400 Please provide proper data

Error Responses look like:

 {
    "meta": {
        "code": 400,
        "status": "FIELD_INVALID"
    },
    "msg": "You can send the maximum message length of 918 characters, or send a message length of 402 characters for the Unicode character set.",
    "data": []
}

PHP Code Example

You can call following function to send SMS.

Need to pass "SMS text" and "Mobile number array" parameters for this function

 function sendSms($text, $phone_number) {
    try {
        $url = 'https://cellcast.com.au/api/v3/send-sms'; //API URL
        $fields = array(
            'sms_text' => $text, //here goes your SMS text
            'numbers' => $phone_number // Your numbers array goes here
        );
        $headers = array(
            'APPKEY: < >',
            'Accept: application/json',
            'Content-Type: application/json',
        );
        $ch = curl_init(); //open connection
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, count($fields));
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($fields));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        if (!$result = curl_exec($ch)) {
            $response_error = json_decode(curl_error($ch));
            return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again", "result" => $response_error));
        }
        curl_close($ch);
        return json_encode(array("status" => 200, "msg" => "SMS sent successfully", "result" => json_decode($result)));
    } catch (\Exception $e) {
        return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again.", "result" => array()));
    }
}

Call Function

 //Set text and mobile numbers
$text = "Hi User, This is my first SMS Test!";
$phone_number = array("< >","< >","< >");
//Call function to send SMS
sendSms($text, $phone_number);

Get SMS

Base URL:

 https://cellcast.com.au/api/v3/get-sms?message_id=<<message_id>>
Method: GET

Parameters

Header Parameters Description
APPKEY Please add provided APPKEY - linked to your Cellcast account.
Content-Type application/json

API Parameters

Name Example Description
message_id Response of Message ID The Message ID of the sent sms message.

Successful Responses

Code Status Description
200 Success Record founded

Successful Responses look like:

 {
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "Record founded",
    "data": [
        {
            "to": "+61NNNNNNNNN",
            "body": "Here is sent message content",
            "sent_time": "2019-06-15 14:04:46",
            "message_id": "6EF87246-52D3-74FB-C319-NNNNNNN",
            "status": "Delivered",
            "subaccount_id": ""
        }
    ]
}

Error Response

Status Code Description
AUTH_FAILED 400 You are not a registered user

Error Responses look like:

 {
    "meta": {
        "code": 401,
        "status": "AUTH_FAILED"
    },
    "msg": "APPKEY you have provided is invalid",
    "data": []
}

PHP Code Example

You can call following function to get SMS details.

 function getSms($message_id) {
    try {
        $url = 'https://cellcast.com.au/api/v3/get-sms?message_id=$message_id'; //API URL
        $headers = array(
            'APPKEY: < >',
            'Accept: application/json',
            'Content-Type: application/json',
        );
        $ch = curl_init(); //open connection
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 4);
        if (!$result = curl_exec($ch)) {
            $response_error = json_decode(curl_error($ch));
            return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again", "result" => $response_error));
        }
        curl_close($ch);
        return json_encode(array("status" => 200, "msg" => "Successfully received", "result" => json_decode($result)));
    } catch (\Exception $e) {
        return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again.", "result" => array()));
    }
}

Call Function

 //Call function to get sms details
$response_status = getSms(< >);

Get Responses

Base URL:

 https://cellcast.com.au/api/v3/get-responses?page=<<page_number>>&type=sms
Method: GET

Parameters

Header Parameters Description
APPKEY Please add provided APPKEY - linked to your Cellcast account.
Content-Type application/json

API Parameters

Name Example Description
page Page number Pass page number.Default value is 1
type Response of SMS pass 'sms' value to get only responses of sent SMS

Successful Responses

Code Status Description
200 Success You have <<Total Responses>> response(s)
Response Description
from Recipient Mobile Number that sent the reply message.
body Inbound message body.
received_at Received date and time.
original_body Original outgoing SMS message body.
original_message_id Original SMS message ID. Returned when originally sending the message.
message_id The Message ID for the inbound message.

Successful Responses look like:

 {
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "You have 1 response(s)",
    "data": {
        "page": {
            "count": 1,
            "number": 1
        },
        "total": "1",
        "responses": [
            {
                "from": "+614NNNNNNNN",
                "body": "Received ",
                "received_at": "2024-09-18 07:15:36",
                "custom_string": "",
                "original_body": "Hello Sent outbound",
                "original_message_id": "9ECD7AEC-C92B-B5F4-8EC8-278F028FEB8B",
                "message_id": "5000000001"
            }
        ]
    }
}

Error Response

Status Code Description
AUTH_FAILED 400 You are not a registered user
NOT_FOUND 400 No Response are available!

Error Responses look like:

 {
    "meta": {
        "code": 401,
        "status": "AUTH_FAILED"
    },
    "msg": "APPKEY you have provided is invalid",
    "data": []
}

PHP Code Example

You can call following function to get SMS responses.

 function getSmsResponses($page = 1) {
    try {
        $url = 'https://cellcast.com.au/api/v3/get-responses?page=' .$page.'&type=sms'; //API URL
        $headers = array(
            'APPKEY: < >',
            'Accept: application/json',
            'Content-Type: application/json',
        );
        $ch = curl_init(); //open connection
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 4);
        if (!$result = curl_exec($ch)) {
            $response_error = json_decode(curl_error($ch));
            return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again", "result" => $response_error));
        }
        curl_close($ch);
        return json_encode(array("status" => 200, "msg" => "Successfully received", "result" => json_decode($result)));
    } catch (\Exception $e) {
        return json_encode(array("status" => 400, "msg" => "Something went to wrong, please try again.", "result" => array()));
    }
}

Call Function

 //Call function to get sms status function
$response_status = getSmsResponses(< >);

Inbound Read

Base URL:

https://cellcast.com.au/api/v3/inbound-read
Method: POST

Parameters

Header Parameters Description
APPKEY Please add provided APPKEY - linked to your Cellcast account.
Content-Type application/json

API Parameters

Name Example Description
message_id Response of Message ID The Message ID for the inbound message. We are consider first "message_id" parameter.
date_before Date timestamp An optional timestamp - mark all as read before this timestamp. If not given, all messages will be marked as read.

You can use one parameter at a time. If you want to change status using message_id then you just need to pass message_id. If you want to mark all as read before given timestamp then you can pass only "date_before" parameter.



You can set the status of inbound messages of your account.