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": "+614NNNNNNNN",
                "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
    }
}

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: <<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("<<Number1>>","<<Number2>>","<<Number3>>");

//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: <<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(<<message_id>>);
                                

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": "2019-04-08 17:37:49",
                "message_id": "dba864ec-e486-4647-82c4-d0b94771080b", // Response Message ID(inbound_id)
            }
        ]
    }
}

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: <<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(<<page_number>>);
                                

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.


Successful Responses

Code Status Description
200 SUCCESS You have <<Total Responses>> response(s)

Successful Responses look like:

{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "Inbound messages have been marked as read.",
    "data": []
}

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 responses.

function setSmsInboundStatus($timestamp) {
    try {
        $url = 'https://cellcast.com.au/api/v3/inbound-read'; //API URL
        $fields = array(
            'message_id' => $message_id, //here goes your inbound message ID
        );

        // If you want to mark all inbound message as read optionally before a certain date.
        //$fields = array(
        //    'date_before' => $date_before, //here goes your date timestamp
        //);

        $headers = array(
            'APPKEY: <<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" => "Successfully set status", "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 = setSmsInboundStatus(<<message_id>>);
                                

Inbound Read Bulk

Base URL:

https://cellcast.com.au/api/v3/inbound-read-bulk
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 ["<<message_id>>","<<message_id>>"]Response of Message ID The Message ID for the inbound message. We are consider first "message_id" parameter.

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.


Successful Responses

Code Status Description
200 SUCCESS You have <<Total Responses>> response(s)

Successful Responses look like:

{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "Inbound messages have been marked as read.",
    "data": []
}

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 responses.

function setSmsInboundStatus($timestamp) {
    try {
        $url = 'https://cellcast.com.au/api/v3/inbound-read'; //API URL
        $fields = array(
            'message_id' => $message_id, //here goes your inbound message ID
        );

        // If you want to mark all inbound message as read optionally before a certain date.
        //$fields = array(
        //    'date_before' => $date_before, //here goes your date timestamp
        //);

        $headers = array(
            'APPKEY: <<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" => "Successfully set status", "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
$message_id = array("<>","<>","<>");
$response_status = setSmsInboundStatus($message_id);
                                

Inbound Webhook

To receive SMS messages in real-time, please log in to your Cellcast account to set up the URL where the messages will be forwarded to. Cellcast recommends using a HTTPS URL.

When receiving SMS messages in real-time, Cellcast’s server will send a HTTP POST to the URL you have specified, as soon as a message is received.

Parameters

Header Parameters Description
APPKEY Please add provided APPKEY - linked to your Cellcast account.
Content-Type application/json
Parameters Description
from This is the mobile number of the handset which sent in the message
body This is the text message content that was received
received_at This is the date the message was received
message_id Inbound Message ID
custom_string Custom String Value
type Message Type: SMS or MMS
original_message_id Original SMS message ID
original_body Original outgoing SMS message body.

PHP Code to retrieve POST data:

$json = file_get_contents('php://input');
$data = json_decode($json, true);

Get Optout

Base URL:

https://cellcast.com.au/api/v3/get-optout
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
DATESTART 2015-08-25 00:00:00 Datetime - Optional - To specify a day and time for how far back you wish to retrieve the opt out list, please specify this day and time in datetime format.
DATEEND 2015-08-25 23:59:59 Datetime - Optional - To specify a day and time for an end period for which you wish to retrieve the opt out list, please specify this day and time in datetime format.

How do I activate the opt-out list via API?

- Select 'Settings' on the left menu, then select 'Inbound sms settings'.

- Select 'Active' from 'Opt-out for API' dropdown.



Successful Responses

Code Status Description
200 SUCCESS You have <<Total>> optout contact(s)

Successful Responses look like:

{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "You have 1 optout contact(s)",
    "data": {
        "page": {
            "count": 1,
            "number": 1
        },
        "total": "3",
        "responses": [
            {
                "number": "+61NNNNNNNNN",
                "first_name": "Peter",
                "last_name": "berg",
                "gender": "Male",
                "post_code": "6688",
                "dob": "2010-11-12",
                "created_at": null
            }
        ]
    }
}

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 responses.

function getOptoutList() {
    try {
        $url = 'https://cellcast.com.au/api/v3/get-optout'; //API URL

        $headers = array(
            'APPKEY: <<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 set status", "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 opt out list function
$response_status = getOptoutList();
                                

Delivery Reports

The status field describes which state a particular message is in. Please note that statuses of type Intermediate will only be reported if you request a status per recipient (Retrieve a recipient delivery report), no callback will be made to report them.

POST callback-url
[
    {
        "message_id":"0061DF26-B015-D7F6-7B31-C446BA4FDE8B",
        "status":"Delivered",
        "recipient":"61NNNNNNNNN",
        "custom_string":"Custom string",
        "source":"Source"
    }
]

Please contact us to setup Callback URL

NOTE:The security cert must match the domain name being used, self signed certs will not verify and will generate errors.

The following statuses are available when using the REST API:

Status Type Description
Queued Intermediate Message is queued within REST API system and will be dispatched according to the rate of the account.
Dispatched Intermediate Message has been dispatched and accepted for delivery by the SMSC.
Aborted Final Message was aborted before reaching the SMSC.
Rejected Final Message was rejected by the SMSC.
Delivered Final Message has been delivered.
Failed Final Message failed to be delivered.
Expired Final Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.
Unknown Final Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that could not be interpreted was received.

Balance

Base URL:

https://cellcast.com.au/api/v3/account
Method: GET

Parameters

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

Successful Responses

Code Status Description
200 SUCCESS Here's your account

Successful Responses look like:

{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "Here's your account",
    "data": {
        "account_name": "John",
        "account_email": "[email protected]",
        "sms_balance": "5831.43",
        "mms_balance": "1006.00"
    }
}

Get SMS Template

Base URL:

https://cellcast.com.au/api/v3/get-template
Method: GET

Parameters

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

Successful Responses

Code Status Description
200 SUCCESS Here's your account

Successful Responses look like:

{
    {
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "You have 2 Template(s)",
    "data": {
        "page": {
            "count": 1,
            "number": 1
        },
        "total": "2",
        "per_page": 15,
        "responses": [
            {
                "template_id": "5e6786ade15ac71272e139b9f393e345",
                "message_title": "New template u",
                "Message": "Hello {fname},\r\n\r\nTest from Cellcast",
                "created_at": "2023-07-13 01:25:49"
            },
            {
                "template_id": "21b7acea52c12f59517e491fbecee169",
                "message_title": "Test Template",
                "Message": "Hello {fname}\r\n\r\nTest ",
                "created_at": "2023-07-13 01:33:21"
            }
        ]
    }
}
}

Send SMS with template

Base URL:

https://cellcast.com.au/api/v3/send-sms-template
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
template_id for template_id Please use get-template API string - Required field
- To use Message template Please provide template_id from get-template api
numbers
[{"number":"61413XXXXXX",
"fname":"First name",
"lname":"Last name",
"gender":"Gender",
"post_code":"Post Code",
"dob":"Date of Birth",
"custom_value_1":"Custom Value 1",
"custom_value_2":"Custom Value 2",
"custom_value_3":"Custom Value 3",
"special":"Special"}]
JSON encoded Array - Required field
For multiple SMS send: [ { "number":"61413XXXXXX", "fname":"First name" },{ "number":"61413XXXXXX", "fname":"first name" }
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": "+614NNNNNNNN",
                "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
    }
}

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-template'; //API URL
        $fields = array(
            'sms_text' => $text, //here goes your SMS text
            'numbers' => $phone_number // Your numbers array goes here
        );
        $headers = array(
            'APPKEY: <<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()));
    }
}
                                

Send bulk SMS

Base URL:

https://cellcast.com.au/api/v3/bulk-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

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": "+614NNNNNNNN",
                "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
    }
},
{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "Queued",
    "data": {
        "messages": [
            {
                "message_id": "6EF87246-52D3-74FB-C319-NNNNNNNNNN",
                "from" : "SENDER_ID",
                "to": "+614NNNNNNNN",
                "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
    }
}

]

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": []
},
{
    "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($fields) {
    try {
        $url = 'https://cellcast.com.au/api/v3/bulk-send-sms'; //API URL

        $headers = array(
            'APPKEY: <<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
$message = array(
        array(
            'sms_text' => "Hi User Test one message", //here goes your SMS text
            'numbers' => "<<Number1>>" // Your numbers array goes here
        ),
        array(
            'sms_text' => "Hi User Test two message", //here goes your SMS text
            'numbers' => "<<Number2>>" // Your numbers array goes here
        )
        );
//Call function to send SMS
sendSms($message);
                                

Register Custom ID

Base URL:

https://www.cellcast.com.au/api/v3/register-alpha-id
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
custom_id Custom ID goes here string - Required field
- To Register Custom ID

Successful Responses

Code Status Description
200 SUCCESS Alpha ID is successfully registered! Please check portal for Alpha ID status

Successful Responses look like:

[{
    "meta": {
        "code": 200,
        "status": "SUCCESS"
    },
    "msg": "Alpha ID is successfully registered! Please check portal for Alpha ID status",
    "data": []
}]

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": "ALREADY_EXISTS"
    },
    "msg": "The Alpha ID is already registered",
    "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 registerID($fields) {
    try {
        $url = 'https://www.cellcast.com.au/api/v3/register-alpha-id'; //API URL

        $headers = array(
            'APPKEY: <<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" => "Alpha ID is successfully registered! Please check portal for Alpha ID status", "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
$customIDArr = array(
            'custom_id' => "TestCustomID", //here goes your Custom ID
        );
//Call function to Register Custom ID
registerID($customIDArr);
                                

Create App Token & Webhook URL Configuration

For any help, shoot us an email [email protected]

How to get App Token:

App tokens are necessary for each action that requires authentication. To generate your App Token follow below steps:

#NOTE: DO NOT SHARE YOUR APP TOKEN WITH ANYONE

You can copy this token with handy option on right side corner of the text box.

This token is a Bearer authentication token which will be used in APIs as show in examples.

About WebHooks:

Cellcast provides you with three types of WebHooks for integrating your application.

You can find these here - https://app.cellcast.com/accounts/api-keys

receive URL: On this URL you will receive any responses submitted by your users when replylink checkbox is checked.

Request from Cellcast will contain following parameters in request's body:

  • _id - message Id
  • status - current status of message e.g. delivered
  • type - type of request i.e. receive
  • message - response from your customer

status URL: On this URL you will receive status of messages sent via Cellcast's Single API.

Request from Cellcast will contain following parameters in request's body:

  • _id - message Id
  • status - current status of message e.g. delivered
  • type - type of request i.e. send
  • reason - description of error or failure, if there is any

bulk status URL: On this URL you will receive status of messages sent via Cellcast's Bulk API.

Request from Cellcast will contain following parameters in request's body:

  • _id - message Id
  • status - current status of message e.g. delivered
  • type - type of request i.e. send
  • reason - description of error or failure, if there is any.
  • bulkId - bulk Id to track all the messages sent in a Bulk API request (response from Bulk API will contain bulkId too)

Verify App Token:

https://api.cellcast.com/api/v1/user/token/verify
Method: GET

Parameters

Header Parameters Description
Authorization Please add provided Baerer token - linked to your Cellcast account.

Successful Responses look like:

        {
        "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": "Token verified successfully!",
        "message_type": "toast",
        "data": {
        "token":
        "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
        "error": {}
        }

Custom Business Name (Alpha ID)

Base URL:

https://api.cellcast.com/api/v1/business/add
Method: POST

Parameters

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

Validation Pointers

  • Business Name is required.
  • Business name must be between 3 and 11 characters.
  • Content Type - JSON

API Data Parameters

Name Example Description
businessname Business Name ['Pizza Business'] String - Rquired Field
customerContact "485632144" To add a new line to the message, use "\r\n" in the message string with only double quote

Successful Responses

Code Status Description
200 SUCCESS Request added successfully for business name!

Successful Responses look like:

                                {
                                    "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 added successfully for business name!",
                                    "message_type": "toast",
                                    "data": {
                                        "isDeleted": false,
                                        "isDefault": false,
                                        "_id": "65f02d52ce1d3b572497f8b9",
                                        "businessname": "Pizza Business",
                                        "user": "6596aa5bfcdf91b3d7ccffe7",
                                        "requestedAt": "2024-03-12T10:24:18.859Z",
                                        "status": "REQUESTED",
                                        "createdBy": "6596aa5bfcdf91b3d7ccffe7",
                                        "createdAt": "2024-03-12T10:24:18.861Z",
                                        "updatedAt": "2024-03-12T10:24:18.861Z",
                                        "__v": 0
                                    },
                                    "error": {}
                                }

Error Response

Status Code Description
AUTH_FAILED_NO_DATA 401 You have not provided APPKEY
AUTH_FAILED 401 - Token you have provided is invalid or expired
- You are not a registered user
FIELD_EMPTY 400 Required field is empty
BAD_REQUEST 400 Please provide proper data

Error Responses look like:

{
                        "meta": {
                            "code": 400,
                            "status": "FIELD_INVALID"
                        },
                        "msg": "Business Name is required.",
                        "data": []
                    }

Custom Number

#NOTE: For register custom number you will get OTP. You need to verify the OTP first after that you can use that number

Base URL:

https://api.cellcast.com/api/v1/customNumber/add
Method: POST

Parameters

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

Validation Pointers

  • Name is required.
  • Number is required.
  • Standart SMS charges apply for get verification code.
  • Content Type - JSON

API Data Parameters

Name Example Description
name Name : 'JOHN' String - Rquired Field
number "485632144" From this number receiver will get a message
- Number should be in format '+614XXXXXXXX , 470XXXXXX' ,

Successful Responses

Code Status Description
200 SUCCESS OTP sent to your number successfully!

Successful Responses look like:

                                    {
                                        "app_type": "web",
                                        "app_version": "1.0",
                                        "maintainence": 0,
                                        "new_version": 0,
                                        "force_update": 0,
                                        "invalid_token": 0,
                                        "refresh_token": "",
                                        "show_message": 1,
                                        "is_enc": false,
                                        "status": true,
                                        "message": "OTP sent to your number successfully",
                                        "message_type": "toast",
                                        "data": {
                                            "success": true,
                                            "message": "OTP sent to your number successfully"
                                        },
                                        "error": {}
                                    }

Error Response

Status Code Description
AUTH_FAILED_NO_DATA 401 You have not provided APPKEY
AUTH_FAILED 401 - Token you have provided is invalid or expired
- You are not a registered user
FIELD_EMPTY 400 Required field is empty
BAD_REQUEST 400 Please provide proper data
NUMBER_EXIST 400 Number already exist in system

Error Responses look like:

                                        {
                                            "meta": {
                                                "code": 400,
                                                "status": "FIELD_INVALID"
                                            },
                                            "msg": "Number is required.",
                                            "data": []
                                        }
                                        

Custom Number Verification

Base URL:

https://api.cellcast.com/api/v1/customNumber/verifyCustomNumber
Method: POST

Parameters

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

Validation Pointers

  • Verification Code is required.
  • Content Type - JSON

API Data Parameters

Name Example Description
name Name : 'JOHN' String - Rquired Field
number "485632144" From this number receiver will get a message
- Number should be in format '+614XXXXXXXX , 470XXXXXX' ,
otp "12345" For Verification

Successful Responses

Code Status Description
200 SUCCESS OTP Verified Successfully!!

Successful Responses look like:

                                {
                                        "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": "OTP Verified Successfully!",
                                        "message_type": "toast",
                                        "data": {},
                                        "error": {}
                                    }
                                

Error Response

Status Code Description
AUTH_FAILED_NO_DATA 401 You have not provided APPKEY
AUTH_FAILED 401 - Token you have provided is invalid or expired
- You are not a registered user
FIELD_EMPTY 400 Required field is empty
BAD_REQUEST 400 Please provide proper data

Error Responses look like:

                                        {
                                            "meta": {
                                                "code": 500,
                                                "status": "VERIFICATION_FAILED"
                                            },
                                            "otp": "OTP verification failed.",
                                            "data": []
                                        }
                                        

Send SMS

Base URL:

https://api.cellcast.com/api/v1/gateway
Method: POST

Parameters

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

Validation Pointers

  • Sender can be max 11 characters.
  • Message in English characters can be max 1600 digits and other languages can be max 800 characters.
  • Contacts should start with 61 and must be 11 digits, e.g. 614xxxxxxxx
  • Max 25 contacts per request.
  • Include Bearer Token in request header.
  • For sending SMS need sufficient credit.
  • Content Type - JSON

SMS Data 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 '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
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 quote
contacts ["+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
senderType ['customNumber', 'businessName', 'dedicatedNumber', '#SharedNum#'], customNumber - Your Own Number
businessName - Alpha ID
dedicatedNumber - For using Dedicated Number
'#SharedNum#' -Starndard shared number is a set of local numbers
countryCode 61 Allowed values: 61

Successful Responses

Code Status Description
200 SUCCESS Request is being processed

Successful Responses look like:

                                {
                                    "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": "4XXXXXXXX",
                                                "MessageId": "6524fa0ce5a39b4f231312dc",
                                                "Result": "Message added to queue."
                                            }
                                        ]
                                    },
                                    "error": {}
                                }

Error Response

Status Code Description
AUTH_FAILED_NO_DATA 401 You have not provided APPKEY
AUTH_FAILED 401 - Token you have provided is invalid or expired
- 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.)
BAD_REQUEST 400 Please provide proper data
LOW_CREDIT 203 Your balance is too low for this request, please recharge.

Error Responses look like:

{
                        "meta": {
                            "code": 400,
                            "status": "FIELD_INVALID"
                        },
                        "msg": "Contacts are required. They should start with 61 and must be 11 digits, e.g. 614xxxxxxxx",
                        "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

                            $curl = curl_init();

                            curl_setopt_array($curl, array(
                                CURLOPT_URL => 'https://api.cellcast.com/api/v1/gateway',
                                CURLOPT_RETURNTRANSFER => true,
                                CURLOPT_ENCODING => '',
                                CURLOPT_MAXREDIRS => 10,
                                CURLOPT_TIMEOUT => 0,
                                CURLOPT_FOLLOWLOCATION => true,
                                CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
                                CURLOPT_CUSTOMREQUEST => 'POST',
                                CURLOPT_POSTFIELDS =>'{
                                    "sender":"XXXXXXXXXX",
                                    "message":"Text SMS Content",
                                    "contacts":["4XXXXXXXX1", "4XXXXXXXX2"],
                                    "countryCode":"61"
                                }',
                                CURLOPT_HTTPHEADER => array(
                                    'Authorization: Bearer TOKEN',
                                    'Content-Type: application/json'
                                ),
                            ));

                            $response = curl_exec($curl);

                            curl_close($curl);
                            echo $response;
                            

Send MMS

Base URL:

https://api.cellcast.com/api/v1/gatewaymms
Method: POST

Parameters

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

Validation Pointers

  • Sender can be max 11 characters.
  • Message in English characters can be max 1600 digits and other languages can be max 800 characters.
  • Contacts should start with 61 and must be 11 digits, e.g. 614xxxxxxxx
  • Max 10 contacts per request.
  • Include Bearer Token in request header.
  • Content Type - JSON

MMS Data Parameters

Name Example Description
sender 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
media media.png | media.jpg Media: A valid media file. Allowed extension: jpg,jpeg,png,gif (Max. file size is 230 KB)
message MMS 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
contacts ["+61400000000"] JSON encoded Array - Required field
For multiple MMS send: ["+61400000000","+61400000001"]
You can pass 1000 numbers to send an MMS in one API call
countryCode 61 Allowed values: 61

Successful Responses

Code Status Description
200 SUCCESS Request is being processed

Successful Responses look like:

                                {
                                    "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": "4XXXXXXX",
                                                "MessageId": "6525038ed5b35855f77baf0c",
                                                "Result": "Message added to queue."
                                            }
                                        ]
                                    },
                                    "error": {}
                                }
                                

Error Response

Status Code Description
AUTH_FAILED_NO_DATA 401 You have not provided Token
AUTH_FAILED 401 - Token you have provided is invalid or expired
- 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 MMS to any Australian Mobile number.)
BAD_REQUEST 400 Please provide proper data

Error Responses look like:

{
                        "meta": {
                            "code": 400,
                            "status": "FIELD_INVALID"
                        },
                        "msg": "Contacts are required. They should start with 61 and must be 11 digits, e.g. 614xxxxxxxx",
                        "data": []
                    }

PHP Code Example

You can call following function to send MMS.

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

                            $curl = curl_init();

                            curl_setopt_array($curl, array(
                                CURLOPT_URL => 'https://api.cellcast.com/api/v1/gatewaymms',
                                CURLOPT_RETURNTRANSFER => true,
                                CURLOPT_ENCODING => '',
                                CURLOPT_MAXREDIRS => 10,
                                CURLOPT_TIMEOUT => 0,
                                CURLOPT_FOLLOWLOCATION => true,
                                CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
                                CURLOPT_CUSTOMREQUEST => 'POST',
                                CURLOPT_POSTFIELDS => array('media'=> new CURLFILE('/{LocalFilePath}'),'message' => 'MMS Text data','sender' => 'XXXXXX','contacts' => '["4XXXXXXXXX"]'),
                                CURLOPT_HTTPHEADER => array(
                                    'Authorization: Bearer TOKEN'
                                ),
                            ));

                            $response = curl_exec($curl);

                            curl_close($curl);
                            echo $response;
                            

Webhook - Delivery reports and Status

Configure webhook to get real-time delivery reports and status directly to your application

A webhook (or callback) lets our platform send real-time information to your application. This happens in real-time, allowing you to leverage the platform to create your logic and workflows.

Events that you will get on Webhook:

  • SMS -> Receive SMS
  • MMS > Received MMS
  • Delivery Reports -> Message is delivered
  • Delivery Reports -> Message has expired
  • Delivery Reports -> Message has Failed
  • Delivery Reports -> Message has unknown

Go to integration > Webhooks

  • Enter your webhook endpoint for Receive SMS/MMS - Click update
  • Enter your webhook endpoint for Receive Delivery reports - Click update

 

Go to your application and check JSON data:

SMS Status: Sent

{
"_id": "6461d2d65a9c394e1899db35",
"status": "sent",
"type": "send",
"sender": "614XXXXXXXX",
"receiver": "4XXXXXXXX",
"number": "+614XXXXXXXX"
}

SMS Status: Delivered

{
"_id": "6461d2d65a9c394e1899db35",
"status": "delivered",
"type": "send",
"sender": "614XXXXXXXX",
"receiver": "4XXXXXXXX",
"number": "+61481071500"
}

 

SMS : Received 

{
"_id": "6461d3af5a9c394e1899dc56",
"status": "delivered",
"type": "receive",
"message": "Test sms",
"sender": "4XXXXXXXX",
"receiver": "614XXXXXXXX"
}


MMS : Received

{
"_id": "6461d3af5a9c394e1899dc56",
"status": "delivered",
"type": "receive",
"message": "{\"message\":\"\",\"media\":[{\"url\":\"https://my.mmsmsg.com/mmsmo/NeaBrcjQ/9C6WHckBw.jpeg\"},{\"url\":\"https://my.mmsmsg.com/mmsmo/NeaBrcjQ/Za2DCcdOv.smil\"}]}",
"sender": "614XXXXXXXX",
"receiver": "614XXXXXXXX",
"media": [
{
"url": "https://url/NeaBrcjQ/9C6WHckBw.jpeg"
},
{
"url": "https://url/NeaBrcjQ/Za2DCcdOv.smil"
}
],
"mms": true
}

RMS: Send Bulk Message

Base URL:

https://api.cellcast.com/api/v1/chat/
Method: POST

Parameters

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

SMS Data 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 '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
number ["4XXXXXXX1", "4XXXXXXX2", "4XXXXXXX3"] JSON encoded Array - Required field
For multiple SMS send: ["4XXXXXXX1", "4XXXXXXX2", "4XXXXXXX3"]
You can pass 1000 numbers to send an SMS in one API call
smsTemplateId SMS Template Id Please add SMS template ID
rmsTemplateId RMS Template Id Please add RMS template ID
countryCode #countrycode# Please add country code e.g. 61

Successful Responses

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

Successful Responses look like:

{
    "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": "Success",
    "message_type": "toast",
    "data": [
        {
            "number": "4XXXXXXXX",
            "message": "Added in queue successfully!"
        },
        {
            "number": "4XXXXXXXX",
            "message": "Added in queue successfully!"
        },
        {
            "number": "5XXXXXXXX",
            "message": "Invalid mobile number, it should start with 61 e.g. 614xxxxxxxx"
        }
    ],
    "error": {}
}

Error Response

Status Code Description
AUTH_FAILED_NO_DATA 401 You have not provided Token
AUTH_FAILED 401 - Token you have provided is invalid
- You are not a registered user
BAD_REQUEST 400 Please provide proper data

Error Responses look like:

{
    "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": "Something went wrong",
    "data": {},
    "error": {
        "error": "Cannot read properties of undefined (reading 'map')"
    }
}

PHP Code Example

You can call following function to send SMS.

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

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cellcast.com/api/v1/chat/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "sender" : "#SharedNum#",
    "number" : ["4XXXXXXX1", "4XXXXXXX2", "4XXXXXXX3"],
    "smsTemplateId" : "11df1111edfe11136de8905a",
    "rmsTemplateId" : "11f111115294cee0f623ff1a",
    "countryCode":"61"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWJqZWN0IjoiNjNhNDFhZGZlZTgwNGNkMjFhNjQ4YWI5Iiwicm9sZSI6Im93bmVyIiwidXNlcklkIjoiNjNhNDFhZGZlZTgwNGNkMjFhNjQ4YWI5IiwidHlwZSI6ImFjY2Vzc1Rva2VuIiwiaWF0IjoxNjk2ODQ3NTk4LCJleHAiOjE2OTk0Mzk1OTh9.4qJXLD1fODBi-h3C9iFVFbFKcT13iRcoDVCM7SOZm2I'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
                                

RMS: Get Full Conversation by Number

Base URL:

https://api.cellcast.com/api/v1/chat/<<4XXXXXXXX>>
Method: GET

Parameters

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

API Parameters

Name Example Description
number conversation of number The covnversation number of the sent message.

Successful Responses

Code Status Description
200 SUCCESS Record founded

Successful Responses look like:

{
    "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": "Success",
    "message_type": "toast",
    "data": [
        {
            "_id": "6502adb0ffe8078ed27ec63c",
            "rmsThreadKey": "757947743541466d6e4f4d4656663267:be6ea713ce11705f1dbcd0896a42f264",
            "user": "63a41adfee804cd21a648ab9",
            "subscriberNumber": 4XXXXXXXX,
            "templateId": "11df1111edfe11136de8905a",
            "rmsShortCode": "ULdbuJ",
            "rmsChat": [
                {
                    "isDeleted": false,
                    "_id": "#_id#",
                    "rmsContent": "text message",
                    "type": "sent",
                    "createdAt": "2023-09-14T06:52:32.572Z"
                },
                {
                    "isDeleted": false,
                    "_id": "#_id#",
                    "type": "received",
                    "rmsContent": "text message",
                    "createdAt": "2023-09-15T23:08:37.543Z"
                },

            ],
            "createdAt": "2023-09-14T06:52:32.574Z",
            "updatedAt": "2023-10-09T11:52:19.802Z",
            "__v": 0,
            "lastSeen": "2023-10-08T16:55:13.464Z"
        }
    ],
    "error": {}
}

Error Response

Status Code Description
AUTH_FAILED 400 You are not a registered user

Error Responses look like:

{
    "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": "Something went wrong",
    "data": {},
    "error": {
        "error": "Cannot read properties of undefined (reading 'map')"
    }
}

PHP Code Example

You can call following function to send SMS.

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

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cellcast.com/api/v1/chat/4XXXXXXXX',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWJqZWN0IjoiNjNhNDFhZGZlZTgwNGNkMjFhNjQ4YWI5Iiwicm9sZSI6Im93bmVyIiwidXNlcklkIjoiNjNhNDFhZGZlZTgwNGNkMjFhNjQ4YWI5IiwidHlwZSI6ImFjY2Vzc1Rva2VuIiwiaWF0IjoxNjk2ODQ3NTk4LCJleHAiOjE2OTk0Mzk1OTh9.4qJXLD1fODBi-h3C9iFVFbFKcT13iRcoDVCM7SOZm2I'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;                 

Upload Subscribers Data

Base URL:

https://api.cellcast.com/api/v1/group
Method: POST

Parameters

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

Validation Pointers

  • Only CSV or Xlsx file type is allowed
  • At least "Mobile Number" field is required to upload subscribers
  • Number should start with 61 and must be 11 digits, e.g. 614xxxxxxxx
  • Max 5000 contacts per account.
  • Include Bearer Token in request header.
  • Content Type - JSON

Upload Subscribers Parameters

Name Example Description
name VIP list A name of contacts list
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 quote
contacts ["+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
countryCode 61 Allowed values: 61

Successful Responses

Code Status Description
200 SUCCESS Request is being processed

Successful Responses look like:

                                                    {
                                                        "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": "4XXXXXXXX",
                                                                    "MessageId": "6524fa0ce5a39b4f231312dc",
                                                                    "Result": "Message added to queue."
                                                                }
                                                            ]
                                                        },
                                                        "error": {}
                                                    }

Error Response

Status Code Description
AUTH_FAILED_NO_DATA 401 You have not provided Token
AUTH_FAILED 401 - Token you have provided is invalid or expired
- 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.)
BAD_REQUEST 400 Please provide proper data

Error Responses look like:

{
                                            "meta": {
                                                "code": 400,
                                                "status": "FIELD_INVALID"
                                            },
                                            "msg": "Contacts are required. They should start with 61 and must be 11 digits, e.g. 614xxxxxxxx",
                                            "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

                                                $curl = curl_init();

                                                curl_setopt_array($curl, array(
                                                    CURLOPT_URL => 'https://api.cellcast.com/api/v1/gateway',
                                                    CURLOPT_RETURNTRANSFER => true,
                                                    CURLOPT_ENCODING => '',
                                                    CURLOPT_MAXREDIRS => 10,
                                                    CURLOPT_TIMEOUT => 0,
                                                    CURLOPT_FOLLOWLOCATION => true,
                                                    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
                                                    CURLOPT_CUSTOMREQUEST => 'POST',
                                                    CURLOPT_POSTFIELDS =>'{
                                                        "sender":"XXXXXXXXXX",
                                                        "message":"Text SMS Content",
                                                        "contacts":["4XXXXXXXX1", "4XXXXXXXX2"],
                                                        "countryCode":"61"
                                                    }',
                                                    CURLOPT_HTTPHEADER => array(
                                                        'Authorization: Bearer TOKEN',
                                                        'Content-Type: application/json'
                                                    ),
                                                ));

                                                $response = curl_exec($curl);

                                                curl_close($curl);
                                                echo $response;
                                                

SMS Pricing Structure

Regular ID:

For pricing relating to general SMS & MMS messaging using Cellcast Regular ID, please refer to pricing listed online - www.cellcast.com.au

Custom ID:

Messaging containing custom 'numbers' or 'names' are subject to Regular ID pricing plus an additional 33% per message.

SMS character count

Can I send messages in excess of 160 characters?

You have the capability of sending messages in excess of 160 characters through our services.

When sending a message in excess of 160 characters, the message is broken up in to message parts of 153 characters, and sent to the handset. The handset then reassembles the message, displaying the message as one extended-length, concatenated message. When sending an extended-length message you are charged for each 153 character part that is sent. This charging process is dictated by the network operators.

You can send the maximum message length of 918 characters, or send a message length of 402 characters for the Unicode character set.


What characters are part of the Unicode charset?

The Unicode character list contains symbols from the Cyrillic, Chinese, Arabic, Korean and Hangul alphabets. It also contains several special symbols (such as emoticons, emoji and kanji).

Unicode character list: here


GSM Charset: The GSM 03.38 charset is the standard character set for text messaging on GSM-based cell phones. All GSM handsets and network elements support the GSM 7-bit alphabet. The basic GSM charset contains the letters A to Z (uppercase and lowercase), numbers, special symbols and several symbols from the Greek alphabet.

@ Δ   SP  0   ¡   P   ¿   p
£   _   !   1   A   Q   a   q
$   Φ   "   2   B   R   b   r
¥   Γ   #   3   C   S   c   s
è   Λ   ¤   4   D   T   d   t
é   Ω   %   5   E   U   e   u
ù   Π   &   6   F   V   f   v
ì   Ψ   '   7   G   W   g   w
ò   Σ   (   8   H   X   h   x
Ç   Θ   )   9   I   Y   i   y
LF  Ξ   *   :   J   Z   j   z
Ø   ESC +   ;   K   Ä   k   ä
ø   Æ   ,   <    L   Ö   l   ö

Escape Characters: Some characters in the GSM 03.38 extension table can only be used at the cost of two characters. The GSM charset uses 7-bit alphabet encoding, but the escape characters require 14 bits to encode, thus taking up two characters. These symbols are:  |, ^, {, }, €, [, ~, ] and \.

Unicode Symbols: Unicode is a standard for encoding, handling and representing the text expressed in many of the world’s writing systems. The latest list of Unicode symbols contains over 120,000 characters from multiple symbol sets and 129 historic and modern scripts.

Unicode Encoding: Compared to the GSM charset, Unicode encoding supports a huge range of languages and symbols. However, if your text message contains a symbol that isn’t in the 7-bit alphabet, UCS-2 encoding must be used. This type of encoding takes up a lot of space, thus reducing the number of characters allowed in a message to 70.

Mobile format

Australian Mobile format

You can send an SMS to any Australian Mobile number.

Allocation for numbers in the range 04xy z00 000 – 04xy z99 999


Valid Mobile Numbers format:

  1. +614NNNNNNNN
  2. 04NNNNNNNN

Master List of Emojis

Master List of Emojis

Simply highlight and copy the emoji of your choice from any emoji column below. Then paste it where you want it to appear. This will work well in messages, chats, and social media posts.


"If you cannot see some emojis from the list below, we recommend using the latest version of Chrome since some emojis are part of the new release and may not be viable in your browser just yet. They will still work however if you copy and paste just like any other emoji."


*** Reminder: Unicode characters are larger in bytes and will decrease your SMS character limit from 160 to 70 ***

Master List of Emojis

Postman Collection

Importing data into Postman

You can import Cellcast collection specifications directly into Postman

To import your data into Postman:
1. Select Import in the left navigation menu.
2. Select Cellcast Collection JSON file.
3. Select Import to bring your data into Postman

Cellcast V3 Collection: Download

Help

Contact us

Email: [email protected]
Melbourne Office:
Level 2, 40 Porter St, Prahran, VIC 3181, Australia
Australia & NZ: +61 (03) 8560 7025


Get in touch, send us a message to arrange a coffee catch-up