post

/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
Endpoint: https://rest-ww.telesign.com/v1/messaging
Encoding: Accepts only UTF-8 unicode characters as inputs.
Accepts: application/x-www-form-urlencoded
Required Headers: Content-Type - application/x-www-form-urlencoded

Request Body

Form data (application/x-www-form-urlencoded)

phone_number

string

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

required

message

string

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.

required

message_type

string

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)

required

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

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.

maxLength: 20

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 value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Textual Representation of IPv4 and IPv6 Addresses.

max_price

number

If this value is lower than the price provided by an operator for an outbound message you have submitted, the message will be rejected. To use this feature, ask our Customer Support Team to turn on “Enable price threshold”.

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

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.

default: true

dlt_template_id

string

(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.

maxLength: 40

dlt_entity_id

string

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

maxLength: 40

Responses

Success. Your request was fulfilled and resulted in a new resource being created. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.

Status Code	Associated Text String	Description
200	Delivered to handset	The SMS was delivered to the end user’s phone. (Final)
203	Delivered to gateway	The SMS was delivered to the gateway. If the gateway responds with further information (including successful delivery to handset or delivery failure), the status is updated. (Intermediate)
207	Error delivering SMS to handset (reason unknown)	The SMS could not be delivered to the end user’s handset for an unknown reason. (Final)
210	Temporary phone error	The SMS could not be delivered to the handset due to a temporary error with the phone. Examples - phone is turned off, not enough memory to store the message. (Final)
211	Permanent phone error	The SMS could not be delivered to the handset due to a permanent error with the phone. For example, the phone is incompatible with SMS, or illegally registered on the network. This can happen when a phone number is blacklisted, or is incorrectly provisioned. (Final)
220	Gateway/network cannot route message	The network cannot route the message to the handset. (Final)
221	Message expired before delivery	The message was queued by the mobile provider and timed out before it could be delivered tothe handset. (Final)
222	SMS not supported	SMS is not supported by this phone, carrier, plan, or user.
229	Message blocked by your request	TeleSign blocked the SMS before it was sent. This is due to your prior submitted request to blocklist this phone number.
230	Message blocked by TeleSign	TeleSign blocks a message if it is being sent to a phone number that is on a global blocklist.
231	Invalid/unsupported	The content of the message is not supported.
234	Price threshold exceeded	Message not sent due to the price exceeding your set maximum price.
237	Message blocked in requested country	You requested that messages in a specific country be blocked, and the message was being sent to this country.
238	Destination blocked by prefix	You requested that phone numbers with a particular prefix be blocked.
250	Final status unknown	The final status of the SMS cannot be determined.
251	Message successfully sent out for delivery, however final confirmation of delivery to handset was not received.
286	Transaction not attempted	The SMS is blocked from being sent due to the phone type not being one of the following - mobile, prepaid, personal, or pager.
290	Message in progress	The message is being sent to the SMS gateway.
292	Queued by gateway	The SMS gateway has queued the message.
295	Status delayed	The status of the SMS is temporarily unavailable.
500	Transaction not attempted	No SMS request was attempted.
502	Campaign error	This error can be generated if there is a problem with the short code used.
503	Carrier rejected - temporary problem	This error is generated if there is an error on the carrier or operator side that is temporary and the message can be retried.
504	Carrier rejected - permanent error	This error is generated if there is an error on the carrier or operator side that is permanent and the message should not be retried.
505	Error on gateway - temporary error	This error is generated if there is an error on TeleSign’s partner side that is considered temporary and the message can be retried.
506	Error on gateway - permanent error	This error is generated if there is an error on TeleSign’s partner side that is considered permanent and the message should not be retried.
507	Invalid destination address	There is a problem with the destination address used. Either the format is not valid, or the number is not associated with any carrier, or if MSC is used it does not know about this MSISDN.
508	Invalid source address	The message requires a source address. Verify that one is provided and correct.
509	Parameters problem
510	Message blocked by subscriber action or request	The end user has blocked receiving SMS with their carrier plan or by request or from the particular short code used.
511	Subscriber low on credit	The end user exceeded their spending limits and cannot receive SMS.
512	Roaming error	End user cannot receive SMS because their device that receives the messages is roaming.
513	Mobile number portability error	SMS failed because ported combinations are unreachable.
514	Subscriber absent	The operator/carrier is temporarily unable to reach the end user.
515	Suspected spam	This message is considered to be spam by carrier or operator.
517	Selected DLT details for India not supported	The DLT template ID or entity ID in the request cannot be found by the end operator.
599	Status not available	The system is unable to provide status at this time.

Schema

object

reference_id

string

A 32-digit hex value used to identify the web service request. The value is unique to each web service request, is randomly generated by TeleSign, and is returned in the response message immediately following the web service request.

phone_number_modified

string

(Optional) Indicates whether the end user’s phone number provided in the request was modified before processing by TeleSign to increase message deliverability. Contact Customer Success to enable this feature. Possible values are "True" and "False".

status

object

external_id

string or null

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.

1 validation

Send a Test Request

Send requests directly from the browser (CORS must be enabled)

$$.env

1 variable not set

host