Home » API » IM Gateway REST API » Request Body

Request Body

The request is encoded in JSON, and is split into 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[]

An array of DESTINATION_INFO (see DESTINATION_INFO). Minimum of 1 item in this array. Maximum of 50,000 items in this array.

job_id

String

A unique identifier provided by yourself for reference. Maximum 255 characters

message

UBIQUITY_CONTENT

Defines a request making use of the ubiquity functionality. When using the ubiquity functionality AMP will attempt to deliver the message at the lowest possible cost via all available channels configured in the API Token being used.

When using the ubiquity functionality delivery channel routing is handled internally by AMP and thus all *_content (e.g. sms_content and im_content) sections MUST be omitted.

see UBIQUITY_CONTENT

sms_content

SMS_CONTENT

Defines the content of your message if sent via SMS.

This section MUST be populated if you wish to include SMS as a possible delivery channel for this request.

NOTE: if you are making use of the ubiquity functionality (i.e. ‘message’ section mentioned above) this section MUST be omitted.

see SMS_CONTENT

im_content

IM_CONTENT[]

Defines the content of your message if sent via IM.

This section MUST be populated if you wish to include IM as a possible delivery channel for this request.

NOTE: if you are making use of the ubiquity functionality (i.e. ‘message’ section mentioned above) this section MUST be omitted.

see IM_CONTENT

message_plan

Enum

Used only when im_content field has 1 or more records (optionally). Allowed values are:

Enum	Description
FEATURE_RICH	Will attempt to deliver via IM first
LOW_COST	Will attempt the cheapest mode of delivery per destination first

Defaults to FEATURE_RICH if not specified.

callback_url

String

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.

reply_url

String

If set, any replies sent by the recipient of this message will generate a message-reply callback that will be delivered to the URL given by this field. Note that for this feature to be used, 2-way messaging must be enabled on the Sender ID specified
in this message. To enable 2-way messaging on a sender ID, please login to the control panel on the Fortytwo website, or ask for assistance. Must be a valid URL starting with http:// or https://. If https is used a valid signed certificate must be
used.

promotional

Boolean

If set to true, the message will be flagged as containing promotional content. When not present, it is defaulted to false. A promotional Message is a Message which contains any information that promotes the User’s business agenda,
the User’s business offer or commercial information. The first Message sent to a recipient cannot be promotional, but must be personal, informative and a targeted Message. The user must ensure that all promotional Messages are tagged “Promotional”
in the REST API request.

DESTINATION_INFO

Key	Type	Optional	Description
number	String	N	MSISDN to deliver the message to. Number must be in international format and can only be between 7-20 digits long. First digit cannot be a 0. All numbers must be unique within the “destinations” array.
custom_id	String	Y	Your reference for each individual 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 or IM_CONTENT tables below. For an example on how to use this feature, see Samples.

UBIQUITY_CONTENT

Key	Type	Optional	Description
texts	TEXT[]	C	Contains a list of text objects. For the time being only one item is allowed in this array. See TEXT. This is required only if all the other fields in this block are not defined.
images	IM_IMAGE[][]	C	*See note on allowed media content combinations below this table. Array of objects containing the images of the IM message to send, if message includes images. See IM_IMAGE for full description. For the time being, the maximum size of the array is 1, as only one image is supported per message on the current providers. This is required only if all the other fields in this block are not defined.
actions	IM_ACTION[]	C	*See note on allowed media content combinations below this table. Array of objects describing the action buttons of the IM message to send, if message includes action buttons. See IM_ACTION for full description. For the time being, the maximum size of the array is 1, as only one button is supported per message on the current channels. Action buttons may be rendered differently depending on the destination IM platform. This is required only if all the other fields in this block are not defined.

Key

Type

Optional

Description

texts

TEXT[]

Contains a list of text objects. For the time being only one item is allowed in this array. See TEXT. This is required only if all the other fields in this block are not defined.

images

IM_IMAGE[][]

*See note on allowed media content combinations below this table.

Array of objects containing the images of the IM message to send, if message includes images. See IM_IMAGE for full description.

For the time being, the maximum size of the array is 1, as only one image is supported per message on the current providers.

This is required only if all the other fields in this block are not defined.

actions

IM_ACTION[]

*See note on allowed media content combinations below this table.

Array of objects describing the action buttons of the IM message to send, if message includes action buttons. See IM_ACTION for full description.

For the time being, the maximum size of the array is 1, as only one button is supported per message on the current channels. Action buttons may be rendered differently depending on the destination IM platform.

This is required only if all the other fields in this block are not defined.

When using the ubiquity functionality, AMP will attempt to deliver the message to all destinations at the lowest possible cost via all available channels configured in the API Token being used.

For an API Token to support SMS when using the ubiquity functionality, the following parameters need to be set-up when configuring the API Token.

SMS sender ID
SMS route

For an API Token to support IM messages when using the ubiquity functionality, the following parameter needs to be set-up when configuring the API Token.

IM Sender ID

SMS messages only support messages of type TEXT[], a request containing either an IM_IMAGE[] or an IM_ACTION[] block will automatically exclude the SMS channel from the available channels, such messages will only attempt delivery via IM.

SMS_CONTENT

Key

Type

Optional

Description

message

String

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

Specifies how the message will be encoded when forwarding it to the destination device. If unspecified, it will 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

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

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

User Data Header. Value is in binary, encoded using base64. This is required if encoding is set to binary.

pid

int

Known as “TP-Protocol-Identifier” (TP-PID). Minimum value: 0 Maximum value: 255 Default: 0 See http://www.3gpp.org/ftp/specs/archive/23_series/23.040/ for further
information regarding this field.

ttl

int

If supplied, this sets the length of time, in seconds, for which Fortytwo will attempt to send the message on the SMS channel. Note that SMS messages may still be delivered beyond this timeframe, as not all network operators will honour this time value.

Value type: 32-bit integer (number of seconds)

Default: (when not supplied, or when set to 0): Up to route or network defaults.

Min value: 0 (same as default).

Max value: 172800 (2 days). Setting a value greater than the maximum value will result in an error.

IM_CONTENT

Key	Type	Optional	Description
channel	Enum	Y	Specifies the IM provider to use. Currently, only VIBER is supported, therefore this field is provided only for future compatibility. Possible values: VIBER
sender_id	String	Y	The sender ID (a.k.a. from) for the IM delivery. Sender IDs must be requested via the Fortytwo Control Panel (https://controlpanel.fortytwo.com/usercontrol/ Message_services/IM/Sender_IDs/) and be pre-approved by your Fortytwo account manager. If unspecified, the sender ID linked to your authorization token will be used.
content	String	C	See note on allowed media content combinations below this table. String containing the text of the IM message to send, if message includes text. 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.Minimum length: 1 character Maximum length:* 1000 characters When parameter names are used, the maximum length of a message pertains to the resultant message after the parameters have been evaluated.
images	IM_IMAGE[]	C	*See note on allowed media content combinations below this table. Array of objects containing the images of the IM message to send, if message includes images. See IM_IMAGE for full description. For Viber, the maximum size of the array is 1, as only one image is supported per message.
actions	IM_ACTION[]	C	*See note on allowed media content combinations below this table. Array of objects describing the action buttons of the IM message to send, if message includes images. See IM_ACTION for full description. For Viber, the maximum size of the array is 1, as only one button is supported per message. Action buttons may be rendered differently depending on the destination IM platform.
ttl	Int	Y	If supplied, this sets the length of time, in seconds, for which Fortytwo will attempt to send the message on this channel. Value type: 32-bit integer (number of seconds) Valid values for VIBER channel Default: (when not supplied): 86400 (24 hours) Min value: 15 (seconds) Max value: 86400 (24 hours). Additional values accepted: 0 is accepted and means “same as default” Exception: Beyond the maximum value above, the special value of 432000 (5 days) is also accepted and honoured. Setting a value outside the min-max range, except if value is 0 or 432000, will result in an error.
expiry_text	String	Y	If specified and the recipient’s device platform supports it, the message is replaced with this text content if it exceeds the TTL before being delivered. Default if unspecified: ‘This message has expired.’ Currently supported on iOS devices only.

*Note on Media content combinations
Different IM channels may support different combinations of text, images and actions. Currently IM messages may only be sent via Viber. The following message combinations are allowed on Viber. Any other combination will be rejected with an error.

Text only
Image only
Text + Image + Action
Text + Action

TEXT

Key	Type	Optional	Description
text	String	N	String containing the actual message text to send.

IM_IMAGE

Key	Type	Optional	Description
url	String	Y	The HTTP URL of the image to send with the IM message. Images must be hosted on a server accessible from the Internet. One may optionally specify keys within the image URL to replace later with values given by the params field in the DESTINATION_INFO object. That way, one can display a different image to each message recipient. 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.

IM_ACTION

Key	Type	Optional	Description
title	String	N	The caption text to display on the button.
target_url	String	N	The HTTP URL that will be called on the click event for this action. The destination URL must be accessible from the Internet. One may optionally specify keys within the URL to replace later with values given by the params field in the DESTINATION_INFO object. That way, one could customise the URL depending on the message recipient opening it. 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.