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.

Enum Description
GSM7 Value of “message” will be converted from UTF-8 (as per HTTP request) to GSM7 prior to forwarding to destination.
UCS2 Value of “message” will be converted from UTF-8 (as per HTTP request) to UCS2 prior to forwarding to destination.
BINARY Value of “message” must contain the binary being sent, encoded using base64.
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
Maximum value: 255
Default: 0
See: http://www.3gpp.org/dynareport/23040.htm  for information regarding this field.

 

Get Started