Messaging - Callback service

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

This page describes any parameters in callback notifications from the Messaging product that are different from the general callback notification schema explained on Transaction Callback Service. It also includes examples of notifications for this API.

This API returns both Delivery Status notifications and Read notifications.

Delivery Status notifications

The Delivery Status notification schema includes both the parameters below and those described in the general schema.

Schema

Property	Type	Description	Example
status.last_channel	string	The last channel that the service tried. This is an additional property added to the `status` object described in the general schema.	sms
channel_status	array (of objects)	Contains an object with properties related to the status of the send for each attempted channel.
channel_status.{}.{channel_name}	object	Contains properties related to the status of the send on the channel specified by the property name ( {channel_name} ).
channel_status.{}.{channel_name}.code	integer	A numeric code indicating the delivery status of the send on this channel.	3000
channel_status.{}.{channel_name}.description	string	Text describing the delivery status of the send on this channel.	Delivered
channel_status.{}.{channel_name}.reference_id	string	A 32-digit hex value used to identify the send on this channel. The value is unique to each send and is randomly-generated by TeleSign.	65C77D4A6C5C09085694EFB6C554D2BF
channel_status.{}.{channel_name}.updated_on	string	An RFC 3339 timestamp indicating when the delivery status was last updated.	2020-05-04 22:07:01:226
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`.	7c8832a1-ab0c-4f12-89f3-0bfbfb7f9645

Example

POST /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{
  "reference_id": "35C8B5D509BC10689196FED2AD551B8A",
  "external_id": null,
  "status": {
    "code": 3000,
    "description": "Delivered",
    "last_channel": "sms",
    "updated_on": "2020-05-04 22:07:01:226"
  },
  "channel_status": [
    {
      "rcs": {
        "code": 3056,
        "description": "Message failed to deliver in specified fallback time",
        "reference_id": "65C77D4A6C5C09085694EFB6C554D2BF",
        "updated_on": "2020-05-04 22:05:00.325"
      }
    },
    {
      "sms": {
        "code": 3000,
        "description": "Delivered",
        "reference_id": "65C77D4A6C5C09085694EFB6C558B4C7",
        "updated_on": "2020-05-04 22:07:01:226"
      }
    }
  ]
}

Read Notifications

Read notifications are supported for WhatsApp, Viber, and RCS channels.

Schema

No additional properties

Example

{
  "reference_id": "35C8B5D509BC10689196FED2AD551B8A",
  "status": {
    "code": 3005,
    "description": "Message is read",
    "reference_id": "65C77D4A6C5C09085694EFB6C558B4C7",
    "updated_on": "2021-11-26T15:01:39.000000Z"
  }
}

Status codes

Status Code	Text String	Description
3000	Delivered	The message was delivered to the end-user. (Final if the last channel used doesn't support Read status. Intermediate otherwise)
3001	Message in progress	Telesign successfully received this message request and is processing it. (Intermediate)
3002	Delivered to Gateway	The message is in the process of delivery. Once all delivery options are exhausted, the status will be updated again. (Intermediate)
3003	Delivery error	The message could not be delivered to the end-user. (Final)
3005	Message is read	The message has been read by the end-user. (Final)
3006	None of the channels is enabled for the customer	The channels specified in this request are all either not enabled for this customer or are invalid values. (Final)
3011		Provider Account registration error
3012		Provider Account migration error
3030	Temporary phone error	The message 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)
3031	Permanent phone error	The message 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)
3032	Gateway/network cannot route message	The network cannot route the message to the handset. (Final)
3033	Message expired before delivery	The message was queued by the mobile provider and timed out before it could be delivered to the handset. (Final)
3034	SMS not supported	SMS is not supported by this phone, carrier, plan, or user.
3035	Invalid/unsupported	The content of the message is not supported.
3036	Price threshold exceeded	Message not sent due to the price exceeding your set maximum price.
3037	Message blocked in requested country	You requested that messages in a specific country be blocked, and the message was being sent to this country.
3038	Destination blocked by prefix	You requested that phone numbers with a particular prefix be blocked.
3039	Final status unknown	The final status of the SMS cannot be determined.
3040	Queued by gateway	The SMS gateway has queued the message.
3041	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.
3042	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.
3043	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.
3044	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.
3045	Parameters problem	One or more parameters used in the request is not supported.
3046	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.
3047	Subscriber low on credit	The end user exceeded their spending limits and cannot receive SMS.
3048	Roaming error	End user cannot receive SMS because their device that receives the messages is roaming.
3049	Mobile number portability error	SMS failed because ported combinations are unreachable.
3050	Subscriber absent	The operator/carrier is temporarily unable to reach the end user's device.
3051	Suspected spam	This message is considered to be spam by carrier or operator.
3052	Message blocked by your request	This code can happen because you requested a block or because Telesign blocked on your behalf. The block is custom, meaning it applies to you and not others.
3053	Message blocked by TeleSign	Telesign blocks a message if it is being sent to a phone number that is on a global blocklist.
3054	Delivery channel not supported by the end user's device	The end user's device does not support the channel used for delivery. (Final)
3055	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.
3056	Message failed to deliver in specified fallback time	Delivery could not be confirmed on this channel within the fallback window; triggers the next channel (if any) to send. (Intermediate)
3057	Invalid source address	The message requires a source address. Verify that one is provided and correct.
3058		The requested API host is not allowed for this `customer_id`
3059		Exceeded number of elements for rich card
3061		Media size exceeds the limit
3062		MMS not supported
3071		Unverified phone_number requested for trial account.
3073		Insufficient funds in prepaid wallet
3100	Unknown channel specified: {channel}	This channel specified in the request is not one of the supported values; triggers the next channel (if any) to send. (Intermediate)
3101	Invalid value for parameter phone_number: {phone_number}	Phone number is too long, too short, or contains non-digit values. (Intermediate)
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)
3107		Invalid country code for parameter `phone_number`
3108		Invalid value for parameter `message`
3109		Invalid value for parameter `sender_id`
3110	Invalid request	The API request or its JSON payload is improperly formatted. (Final)
3112		Specified template does not exist for selected channel
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)
3114		Specified message type not allowed outside of conversation window
3115		Destination phone number not in coverage
3117	Invalid value for parameter fbmessager_id: { fbmessager_id}	fbmessager_id value is too long, too short, or not valid. (Intermediate)
3118	Invalid value for parameter instagram_id: { instagram_id}	instagram_id value is too long, too short, or not valid. (Intermediate)
3200	{channel} channel is not enabled for customer	This channel is not enabled for this customer. (Intermediate)
3202	Fallback is not enabled for Customer ID	Multiple channels are specified in the request, but fallback is not enabled for this customer. (Intermediate)
3205		Rate Limit Exceeded
3207		Messaging exceeded transaction hard cap. Request denied.
3208		Provider Account ID not found
3209		Phone number not registered for testing
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)
3305		Missing template specific parameters
3306	Missing message parameters for specified channel	Message object doesn't contain required info for sending message through selected channel. (Intermediate)
3400	Not authorized	No permissions for this resource or authorization failed. (Final)
3405		Missing required `Authorization` header
3406		CustomerID Account Suspended
3408		CustomerID Account Not Found
3409		Invalid source IP address
3410		Invalid Customer ID
3411		Invalid API Key
3412		Required `Authorization` header is not in the correct format
3413		Not Allowed IP Address
3500	System Unavailable	The system is currently unavailable. The request should be resubmitted. (Final)
3601		CustomerID Account Not Found

📘NOTE:

Delivery Status notifications

Schema

Example

Read Notifications

Schema

Example

Status codes

📘
NOTE: