SMS Gateway REST API
Request Body
Request Body
The request is encoded in JSON, and is split in several levels.
Each table below will represent a level, starting with the outermost one.
Legend for “Optional” column:
N → No;
Y → Yes;
C → Conditional (see description)
Outer Level
| Key | Type | Optional | Description |
|---|---|---|---|
| destinations | DESTINATION_INFO[] | N | An array of DESTINATION_INFO (see DESTINATION_INFO). Minimum of 1 item in this array. |
| job_id | String | Y | A unique identifier provided by yourself for reference. Maximum length of 255 characters. |
| sms_content | SMS_CONTENT | C | Defines the content of your message (see SMS_CONTENT). |
| callback_url | String | Y | If set, the callback (delivery / status report) will be delivered to this URL, otherwise no callback will take place. Must be a valid URL starting with http:// or https://. If https is used a valid signed certificate must be used. |
| ttl | int | Y | If supplied, this sets the length of time, in seconds, for which Fortytwo will attempt to send the message. Note that this does not guarantee a message will be delivered within the specified time, as not all network operators will honour this value.
Value type: 32-bit integer (number of seconds) Default (when not supplied, or when set to 0): Up to route or network defaults. |
DESTINATION_INFO
| Key | Type | Optional | Description |
|---|---|---|---|
| number | String | N | Mobile number (MSISDN) to deliver the message to. Number is in international format and is only digits between 7-15 digits long. First digit cannot be a 0. All numbers must be unique within the “destinations” array. |
| custom_id | String | Y | If set, this custom_id will be echoed back in the callback along with delivery status for the message to this particular destination. |
| params | Key-Values | C | If your message content contains placeholders for personalised messages per destination, this field is required to populate the value for each recipient. For further details, see the SMS_CONTENT table below. For an example on how to use this feature, see Samples. |
SMS_CONTENT
| Key | Type | Optional | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| message | String | N | String containing the body of the SMS message to be delivered to the destination device. One can optionally specify keys within the message body to replace later with values given by the params field in the DESTINATION_INFO object. See ‘params’ in the DESTINATION_INFO section for more information on supplying the value for these keys. Each placeholder must be specified as {#KEY}, where KEY is a key name in the params list. For this feature to be used, GSM7 or UCS2 encoding must be used.
In case of binary (see “encoding” below), this field’s value should be base64 encoded. Minimum length of 1 character. Maximum length is of 5 pages in GSM7 encoding equivalent. When parameter names are used, the maximum length of a message pertains to the resultant message after the parameters have been evaluated. In case of binary message, maximum length is 140 bytes, including the field (see below). |
||||||||
| encoding | Enum | Y | Specifies how the message will be encoded when forwarding it to the destination device. If unspecified, it will default to default to GSM7.
|
||||||||
| route | String | Y | The SMS route to deliver on. If unspecified, it will use the route configured with the authorization token you use (default: G1 -standard global coverage). The only valid values are those routes available for your account. | ||||||||
| sender_id | String | Y | The sender ID (a.k.a. from) for the SMS delivery. If unspecified, the sender ID tied to your authorization token will be used. If numeric, minimum length is 1, maximum length is 15 digits. If alphanumeric, minimum length is 1, maximum length is 11 characters. |
||||||||
| udh | String | C | User Data Header. Value is in binary, encoded using base64. This is required if encoding is set to binary. | ||||||||
| pid | int | Y | Known as “TP-Protocol-Identifier (TP-PID)”.
Minimum value: 0 |
Get Started