Send an SMS message

post https://rest-ww.telesign.com/v1/messaging

Send an SMS message. Use request parameters to specify the type of message, what phase of the account lifecycle the message is being sent in, and additional details about the transaction.

General requirements

Authentication: Basic (easiest to implement) or Digest
Encoding: Accepts only UTF-8 unicode characters as inputs.
Accepts: application/x-www-form-urlencoded
Required headers: Content-Type - application/x-www-form-urlencoded
Rate limit: Default rate limits by product

Form Data

phone_number

string

required

The end user's phone number with country code included. Avoid use of special characters and spaces.

message

string

required

Text of the message to be sent to the end user. You are limited to 1600 characters. If you send a very long message, Telesign splits your message into separate parts. Telesign recommends against sending messages that require multiple SMSes when possible.

message_type

string

required

This parameter specifies the traffic type being sent in the message. You can provide one of the following values -

OTP (One time passwords)
ARN (Alerts, reminders, and notifications)
MKT (Marketing traffic)

account_lifecycle_event

string

This parameter allows you to indicate what phase of the lifecycle you are in when you send a transaction. The options for this parameter are -

create - For the creation of a new account)
sign-in For when an end user signs in to their account.
transact - For when an end user completes a transaction within their account
update - For when an update is performed, such as an update of account information or similar.
delete - For when an account is deleted.

sender_id

string

length ≤ 20

This parameter allows you to set a specific sender ID to be used on an SMS message sent to the end user. In order to use a specific sender ID, Telesign must whitelist your selected sender ID values. Be aware that 100% preservation of a sender ID value is not guaranteed. Telesign may override the sender ID value that your end user will receive in order to improve delivery quality or follow SMS regulations in particular countries. In order to use this feature, you must contact Telesign Support and have them enable it for you. We recommend limiting values to 0-9 and A-Z, as support for other ASCII characters varies by carrier.

external_id

string

A customer-generated ID for this transaction. The response simply echoes the value provided for this parameter.

originating_ip

string

Your end user's IP address (do not send your own IP address). This is used to help Telesign improve our services. IPv4 and IPv6 are supported. For IPv4, the value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Internet Protocol. For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled IP Version 6 Addressing Architecture.

callback_url

string

A URL where you want delivery reports to be sent related to your request. This overrides any default callback URL that you’ve previously set. The override only lasts for this request.

is_primary

string

Defaults to true

Whether you are using this service as your primary provider to send this message (”true”) or as a backup after your primary provider failed (”false”). We use this data to optimize message routing.

dlt_template_id

string

length ≤ 40

(India-local traffic only). The ID of the DLT template used for this message. See India DLT Update for more details on the relevant regulations.

dlt_entity_id

string

length ≤ 40

(India-local traffic only). The ID of the entity sending this message. See India DLT Update for more details on the relevant regulations.

Responses

Status code	Associated text string	Description
290	Message in progress	The message is being sent to the SMS gateway.

Response body

object

reference_id

string

required

A unique, randomly generated hex value that identifies your web service request.

status

object

required

code

integer

required

A numeric code that indicates the status of your transaction.

description

string

required

Text describing the status of your transaction.

phone_number_modified

string

Indicates whether the end user's phone number provided in the request was modified before processing by Telesign to increase message deliverability.
Contact our Customer Support Team to enable this feature. Possible values are "True" and "False".

external_id

string

The customer-generated ID for this transaction that was provided in the request. If the external_id parameter was not included in the request, the value here is null.

cleansed_phone_number

string

The corrected version of the submitted phone number returned in the response after common formatting issues are fixed to improve deliverability. If there are no changes, the original phone number from the request is returned. Contact our Customer Support Team to enable this feature.

Status code	Associated text string
11000	Invalid value for parameter phone_number.
11001	Invalid country code for parameter phone_number.
11003	Invalid value for parameter account_lifecycle_event
11004	Invalid value for parameter callback_url
11009	Invalid value for parameter message.
11010	Invalid value for parameter originating_ip.
11013	Invalid value for parameter sender_id.
11016	Invalid value for parameter external_id
11017	Invalid value for parameter message_type.
11027	Invalid value for parameter integration_name.
11034	Invalid value for parameter dlt_template_id
11035	Invalid value for parameter dlt_entity_id
12000	Missing Required Parameter phone_number
12009	Missing Required Parameter message
12017	Missing Required Parameter message_type

Status code	Associated Text String
10002	'x-ts-nonce' header value has been used recently
10003	'x-ts-nonce' header value is either too long or too short
10004	'Date' or 'x-ts-date' header is not within tolerable range
10005	'Date' or 'x-ts-date' header is not RFC822 compliant
10006	Invalid 'x-ts-auth-method' header.
10007	Missing required 'Date' or 'x-ts-date' header
10008	Invalid Signature.
10009	Missing required 'Authorization' header
10010	CustomerID Account Suspended
10011	This product is not enabled for this CustomerID.
10014	Invalid source IP address.
10015	Invalid Customer ID.
10022	Invalid API Key.
10028	Required 'Authorization' header is not in the correct format
10031	Not Allowed Host
10033	{phone_number} has not been verified for this trial account.
10035	The requested API host is not allowed for this CustomerID.

Status code	Associated text string
10019	Rate Limit Exceeded
10020	Generic messaging exceeded transaction hard cap. Request denied.

`status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.

Status code Associated text string
10000 System Unavailable, Please try again later.

Status code	Associated text string
10000	System Unavailable, Please try again later.

xxxxxxxxxx
curl --request POST \
     --url https://rest-ww.telesign.com/v1/messaging \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data is_primary=true