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) |
3004 | Message successfully sent out for delivery, however final confirmation of delivery to handset was not received. | Telesign successfully delivered the message through our gateway and it passed downstream. However, Telesign did not receive a delivery receipt within 12 hours of transmission. We cannot confirm delivery to the handset. |
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 | Message cannot be sent to RBM provider - parsing error | Telesign’s RBM (Rich Business Messaging) partner encountered a temporary problem while sending this message. Please try again. |
3055 | Delivery channel not supported by the end user's device | The end user's device does not support the channel used for delivery. (Final) |
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 | Product exceeded transaction hard cap. Request denied. | Product exceeded transaction hard cap limit. 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 |
Updated 29 days ago