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[] | N | 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 | Y | A unique identifier provided by yourself for reference. Maximum 255 characters | ||||||
| message | UBIQUITY_CONTENT | C | 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 | C | 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[] | C | 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 | Y | Used only when im_content field has 1 or more records (optionally). Allowed values are:
Defaults to FEATURE_RICH if not specified. |
||||||
| 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. | ||||||
| reply_url | String | C | 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 | Y | 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-15 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. |
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 | 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 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 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 | Y | 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) 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. |
Get Started