Send an SMS

In order to send an SMS, make a POST request to the /sms endpoint.

Request

URL https://api.apitel.co/sms
Method POST
Content type application/x-www-form-urlencoded or application/json

Parameters

to
required
The phone number you are sending the message to. It must be provided in the format: [+][country code][number] For example: +66812345678.
from
The sender the message is from. Either 'ATSMS', or an approved sender name is valid. This parameter is optional. If omitted, your configured default sender name will be used.
ttl
Message Time to live. A value in seconds, between 1 and 21600 (6 hours). If not provided, this value defaults to 21600.
statusCallback
The URL used to deliver status information for the sent message. If provided, it will override the configured status URL for your account.
apiKey
required
Your api key.
apiSecret
required
Your api secret.
text
required

The text of the message encoded as UTF-8.

Messages which contain only ISO-Latin-1 characters can be up to 160 characters in length before being split into messages with a maximum length of 153 characters.

If other characters are used, the text can be up to 70 characters in length before being split into messages with a maximum length of 67 characters.

Each of the resulting messages will be recomposed and displayed as a single message on the recipient's device.

Examples

A url encoded request using curl

curl -X POST https://api.apitel.co/sms \ --data-urlencode "to=+661234567890" \ -d "from=ATSMS" \ -d "text=A text message" \ -d "apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \ -d "apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

A JSON encoded request using curl

curl -i -X POST https://api.apitel.co/sms \ -H "Content-Type:application/json" \ -d \ '{ "to": "+661234567890", "from": "ATSMS", "text": "A text message", "apiKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "apiSecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }'

Response

Request responses are formatted as JSON. When a request is successful an HTTP 200 response will be returned. If there is an error with the request an HTTP 400 response will be returned.

Keys

id
The message ID.
to
The phone number the message was sent to.
from
The sender ID the message is from.
text
The text of the message.
status
The status of the message.
errors
Request errors grouped by parameter.
segments
If the length of the message text resulted in multiple messages being sent the message id, and text of each message will be available as an array of objects with id and text keys.

Examples

A successful response

{ "id": 13, "from": "ATSMS", "to": "+661234567890", "text": "Good evening.", "status": "ACCEPTED" }

A successful response when sending a long message. While two messages are sent, only one message will be displayed on the recipeint's device.

{ "id": 91, "from": "ATSMS", "to": "+661234567890", "text": "Good evening. There is a lot to say in this message. I suspect it may be too long to fit in a single sms. Unfortunately, they're limited in length to only 140 bytes.", "status": "ACCEPTED", "segments":[ { "id": 91, "text": "Good evening. There is a lot to say in this message. I suspect it may be too long to fit in a single sms. Unfortunately, they're limited in length to onl" }, { "id": 92, "text": "y 140 bytes." } ] }

A response to an unparseable request. This may happen if the incorrect content type is specified, or there is a syntax error in the parameter encoding.

{ "errors": { "request": [ "Unable to parse request" ] } }

A response to a request with missing parameters. In this example the from parameter was not provided.

{ "errors": { "from": [ "can't be empty" ] } }

SMS status

In order to recieve status details about sent messages you'll need to implement a status webhook. You will then need to configure your account to send status notifications to this URL. For example: http://yourdomain.com/sms-status.

An example webhook implementation using nodejs.

const express = require('express') const app = express() app.route('/sms-status').get(function(request, response) { handleStatus(request.query, response) }); function handleStatus(query, response) { console.log('message id', query.id); console.log('message status', query.status); response.sendStatus(200) } app.listen(8080);

The status webhook request will contain the message id in the 'id' parameter, and the message status in the 'status' parameter. For example: http://yourdomain.com/sms-status?id=1&status=DELIVERED.

Status parameters

ACCEPTED
The message is valid, and will be sent.
SENT
The message has been sent. Waiting for delivery receipt.
DELIVERED
The message has been delivered.
SEND_ERROR
An error occured while sending the message.

Sender names

The sender names API supports requesting, and deleting a sender name, as well as listing your sender names.

Request sender name

In order to request a sender name, make a POST request to the /sender_names endpoint.

Request

URL https://api.apitel.co/sender_names
Method POST
Content type application/x-www-form-urlencoded or application/json

Parameters

name
required
The name you are requesting. It must be no longer than 11 characters, and only contain letters and numbers.
apiKey
required
Your api key.
apiSecret
required
Your api secret.

Examples

A url encoded request using curl

curl -X POST https://api.apitel.co/sender_names \ --data-urlencode \ -d "name=goodco" \ -d "apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \ -d "apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

A JSON encoded request using curl

curl -i -X POST https://api.apitel.co/sender_names \ -H "Content-Type:application/json" \ -d \ '{ "name": "goodco", "apiKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "apiSecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }'

Response

Request responses are formatted as JSON. When a request is successful an HTTP 200 response will be returned. If there is an error with the request an HTTP 400 response will be returned.

Keys

name
The sender name requested.
pending
Either true of false. Reflects if the sender name is pending approval. Once approved, pending will be false. Rejected sender names will be removed.
reliable
Either true of false. Reflects if the sender name is reliable, or not. Messages sent from an unreliable sender name will more often be blocked as spam.
default
Either true of false. Reflects if the sender name is the default sender name for your account.

Examples

A successful response

{ "name": "goodco", "pending": true, "reliable": false, "default": false }

List sender names

In order to list your sender names, make a GET request to the /sender_names endpoint.

Request

URL https://api.apitel.co/sender_names
Method GET

Parameters

apiKey
required
Your api key.
apiSecret
required
Your api secret.

Examples

A request using curl

curl -X GET 'https://apitel.co/sender_names?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Response

Request responses are formatted as JSON. The body will be an array of sender name objects. Each of the objects will have the following keys.

Keys

name
The sender name.
pending
Either true of false. Reflects if the sender name is pending approval.
reliable
Either true of false. Reflects if the sender name is reliable, or not. Messages sent from an unreliable sender name will more often be blocked as spam.
default
Either true of false. Reflects if the sender name is the default sender name for your account.

Examples

A successful response

{ sender_names: [ { "name": "goodco", "pending": true, "reliable": false, "default": false }, { "name": "verygoodco", "pending": false, "reliable": true, "default": true } ] }

Delete sender name

In order to delete a sender name, make a DELTE request to the /sender_names/{name} endpoint.

Request

URL https://api.apitel.co/sender_names/{name}
Method DELETE

Parameters

apiKey
required
Your api key.
apiSecret
required
Your api secret.

Examples

A request using curl

curl -X DELETE 'https://apitel.co/sender_names/goodco?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Response

Request responses are formatted as JSON. The body will be the deleted sender name.

Keys

name
The sender name.
pending
Either true of false. Reflects if the sender name is pending approval.
reliable
Either true of false. Reflects if the sender name is reliable, or not. Messages sent from an unreliable sender name will more often be blocked as spam.
default
Either true of false. Reflects if the sender name is the default sender name for your account.

Examples

A successful response.

{ "name": "goodco", "pending": false, "reliable": false, "default": false }