Send a message with advanced features

post

https://rest-ww.telesign.com/v1/omnichannel

Use this action to send a message with advanced features through your specified channel (optionally with cascading backup channels) to a recipient phone number or email address.

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

General requirements

Authentication: Basic (easiest to implement) or Digest
Encoding: Accepts only UTF-8 unicode characters as inputs.
Accepts: application/json
Responds with: application/json
Rate limit: Default rate limits by product

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

channels

array of objects

required

All the potential channels you want the service to be able to try and details on how to use those channels. If the first channel attempted fails, you have specified a fallback channel, and the fallback timeout has elapsed, the service looks to the next channel object here for details on what to do.

channels*

recipient

object

Contains properties specifying the contact information needed to communicate with a recipient for a particular channel. At least one sub-property must be included. If the phone_number parameter is not included in this request, this parameter is required.

message

object

required

Contains properties specifying to the service how to construct the message for each channel. There should be one object in here for each channel, plus a default object with configuration to be applied if none of the specified channels can be used.

message_type

string

enum

required

The purpose for which the message is being sent. Choose from OTP - one-time passwords, ARN - alerts, reminders, and notifications, or MKT - marketing messages.

Allowed:

external_id

string

length ≤ 100

Your own identifier, used to refer to this transaction.

callback_url

string

Your URL that you want Telesign to send callbacks to for this transaction. Overrides any previously set callback URL for your account.

account_lifecycle_event

string

enum

The phase of the customer life-cycle the end user is in when this transaction is sent. Choices include:

create - Create a new account.
sign-in - End user signs-in to their account.
transact - End user completes a transaction.
update - End user updates contact details or other info related to their account.
delete - Delete an account.

Allowed:

sender_id

string

Specifies the sender ID to be displayed to the end user on the generated message. Before using this, give any sender IDs you might want to use to our Customer Support Team, so we can add them to our allow list. If the sender ID in this field is not on this list, it is not used. We do not guarantee that the sender ID you specify will be used; Telesign may override this value to improve delivery quality or to follow the regulations of particular countries.

originating_ip

string

The IP address of the end user the message is sent to. Must be in the format defined by the Internet Engineering Task Force (IETF).

phone_number

string

deprecated

The end user's phone number you want to send this message to, as digits without spaces or special characters, beginning with the country dialing code. If the recipient parameter is not included in this request, this parameter is required.

Headers

Content-Type - application/json

string

Responses

Status Code	Text String	Description
3001	Message in progress	Telesign successfully received this message request and is processing it. (Intermediate)

Status Code	Text String	Description
3102	Invalid value for parameter message_type: {message_type}	The value of parameter `message_type` is not one of the supported values: `ARN`, `MKT`, `OTP`. (Final)
3103	Unsupported value for parameter external_id: {external_id}	The value of parameter `external_id` is longer than 100 or contains non-ASCII characters. (Final)
3104	Invalid value for parameter account_lifecycle_event: {account_lifecycle_event}	The value of parameter `account_lifecycle_event` is not one of the supported values: `create`, `sign-in`, `transact`, `update`, `delete`. (Final)
3105	Invalid value for parameter originating_ip: {originating_ip}	Parameter originating_ip is improperly formatted. (Final)
3106	Invalid value for parameter callback_url: {callback_url}	The value of parameter `callback_url` is empty. (Final)
3110	Invalid request	The API request or its JSON payload is improperly formatted. (Final)
3113	Invalid value for parameter channel: {channels}	The value of the parameter `channels` contains the same `channel` more than once or is improperly formatted. (Final)
3116	Payload limit size exceeded	Allowed payload size is limited to 10KB
3300	Missing parameter channels	The API request does not contain mandatory parameter `channels`. (Final)
3301	Missing parameter channel	The value of the parameter `channels` does not contain any instances of the mandatory sub-property `channel`. (Final)
3302	Missing parameter phone_number	The API request does not contain the mandatory parameter `phone_number`. (Final)
3303	Missing parameter message	The API request does not contain the mandatory parameter `message`. (Final)
3304	Missing parameter message_type	The API request does not contain the mandatory parameter `message_type`. (Final)

Status Code	Text String	Description
3400	Not authorized	No permissions for this resource or authorization failed. (Final)

413

Request entity too large. Allowed payload size is limited to 10KB.

Status code	Text string	Description
3203	Callback URL parameter not enabled for Customer ID	Using `callback_url` in the API request is not allowed for this customer. (Final)
3204	Rate limit exceeded	Allowed number of requests per second to the Telesign Messaging API has been exceeded. (Final)
3206	Omnichnnel Product not enabled for Customer ID	Telesign Messaging is not enabled for this customer. (Final)