Send SMS
Introduction
Standard SMS length is 160 charchters which are 140 octates encoded in GSM-7 bit coding.
To easily calculate how many charchters are allowed for a single SMS use the following formula:
140(Octates)*8(8 bit for each ocate)/7(7 bit per GSM-7 bit encoding) = 1120/7 = 160 characters into an SMS.
Our gateway enables message concatenation by default (see message concatenation section), this limits the maximum amount of characters per SMS to 153 for all GSM-7 bit coded messages and to 63 charchters for Unicode non GSM-7 bit encoding messages due to SMS protocols.
Supported request parameters
| Name | Mandatory | Max length | Description | Default value | Dashboard location |
|---|---|---|---|---|---|
| token | Yes | 70-80 | Access token | settings/api-access-tokens | |
| from | Yes | 20 | Sender of message, Check supported sender ids by region | ||
| to | Yes | 20 | Receiver of message, international number format 44544444444 (no + symbol) | ||
| text | Yes | 160 | 160 charachters for 7 bit (plain text) 70 for unicode | ||
| coding | No | 1 | coding=0: 7 bit "GSM", coding=1: 8 Bits (binary), coding=2: Unicode (UTF-16BE) | 0 | |
| dlr-mask | No | 2 | Set level of messages status reporting. (see Dlr mask section) | ||
| dlr-url | No | 150 | URL to be fetched if a dlr-mask CGI parameter is present. (callback URI) |
Dlr mask
You can request the receipt of one or more message status updates.
| dlr-mask | Aggregated value | Description | dlr-url hits | Comments |
|---|---|---|---|---|
| 1 | 1 | Notify upon: delivery | 1 | Notify only upon successful delivery |
| 3 | 1 + 2 | Notify upon: delivery,failed | 1 | Notify upon delivery or permanent failure |
| 7 | 1 + 2 + 4 | Notify upon: buffered,delivery,failed | 1 or 2 | Notify upon delivery or permanent failure and/or buffered state |
| 15 | 1 + 2 + 4 + 8 | Notify upon: buffered,processing,delivery,failed | 2 or 3 | Notify upon delivery or permanent failure and/or buffered state and/or processing state |
| 31 | 1 + 2 + 4 + 8 + 16 | Notify upon: buffered,processing,delivery,failed,rejected | 2 or 3 | Notify upon delivery or permanent failure and/or buffered state and/or processing state and/or rejected state |
Dlr status values
| value | description |
|---|---|
| 1 | Delivered |
| 2 | Failed |
| 4 | Buffered |
| 8 | Processing |
| 16 | Rejected |
Sending messages
Plain text
To send a plain text message set coding to 0.
Maximum length of a plain text message is 153 characters a single non concatenated message (instead of 160, see introduction section).
For concatenated messages please see concatenated messages section for more details
GET /v2/sms/send
curl -X GET -G API_URL \
-d token=TOKEN \
-d from=123 \
-d to=445555555555 \
--data-urlencode text='my plain text message' \
-d coding=0 \
-d dlr-mask=31 \
--data-urlencode dlr-url='http[s]://mydomain.com/deliveryReports?&msgid=123123&status=%d&to=%p&from=%P&ts=%T&price=%price'
Unicode
To send a unicode (GSM-7) message set coding to 2 and encode your text to HEX UTF8 encoding.
Maximum allowed length of a unicode (GSM-7) message is 67 characters for a single non concatenated message (instead of 70, see introduction section).
For concatenated messages please see concatenated messages section for more details
Examples:
For the following arabic plain text ابت your encoded message should like so: %D8%A7%D8%A8%D8%AA
For the following hebrew plain text אבג your encoded message should like so: %D7%90%D7%91%D7%92
For the following greek plain text αβγ your encoded message should like so: %CE%B1%CE%B2%CE%B3
GET /v2/sms/send (Send arabic unicode message ابت encoding %D8%A7%D8%A8%D8%AA)
curl -X GET -G API_URL \
-d token=TOKEN \
-d from=123 \
-d to=445555555555 \
-d text='%D7%90%D7%91%D7%92' \
-d coding=2 \
-d dlr-mask=31 \
--data-urlencode dlr-url='http[s]://mydomain.com/deliveryReports?&msgid=123123&status=%d&to=%p&from=%P&ts=%T&price=%price'
Concatenated messages
Introduction
A concatenated message is a message that is longer than the allowed length for a single message given its coding value.
By default our gateway allows for concatenated messages to be sent.
For example: a message that contains 175 characters would normally be sent it two parts.
The first part would be 160 characters long and the second 15 characters long.
Our gateway will send the message as a single message automatically. internally it will be viewed as a two part message. first part is 153 characters long (instead of 160, see introduction section) and second part is 22 characters long.
Unicode non GSM-7 coded messages vs GSM-7 encoded messages
Any message that contains one or more non GSM-7 characters is a unicode non GSM-7 coded message.
Concatinated message length
A message part is the total number of characters allowed in a message given is coding value.
By default we allow for 5 parts per message.
GSM-7 non unicode messages
A massage part for GSM-7 coded messages is 153 characters long, we allow a total of 5 such parts to be sent is a single message for a total message length of 765.
Unicode non GSM-7 messages
A massage part for unicode non GSM-7 coded messages is 63 characters long, we allow a total of 5 such parts to be sent is a single message for a total message length of 315.