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

PropertyTypeDescriptionExample
status.last_channelstringThe last channel that the service tried. This is an additional property added to the status object described in the general schema.sms
channel_statusarray (of objects)Contains an object with properties related to the status of the send for each attempted channel.
channel_status.{}.{channel_name}objectContains properties related to the status of the send on the channel specified by the property name ( {channel_name} ).
channel_status.{}.{channel_name}.codeintegerA numeric code indicating the delivery status of the send on this channel.3000
channel_status.{}.{channel_name}.descriptionstringText describing the delivery status of the send on this channel.Delivered
channel_status.{}.{channel_name}.reference_idstringA 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_onstringAn RFC 3339 timestamp indicating when the delivery status was last updated.2020-05-04 22:07:01:226
external_idstring or nullThe 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 CodeText StringDescription
3000DeliveredThe message was delivered to the end-user. (Final if the last channel used doesn't support Read status. Intermediate otherwise)
3001Message in progressTelesign successfully received this message request and is processing it. (Intermediate)
3002Delivered to GatewayThe message is in the process of delivery. Once all delivery options are exhausted, the status will be updated again. (Intermediate)
3003Delivery errorThe message could not be delivered to the end-user. (Final)
3005Message is readThe message has been read by the end-user. (Final)
3006None of the channels is enabled for the customerThe channels specified in this request are all either not enabled for this customer or are invalid values. (Final)
3011Provider Account registration error
3012Provider Account migration error
3030Temporary phone errorThe 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)
3031Permanent phone errorThe 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)
3032Gateway/network cannot route messageThe network cannot route the message to the handset. (Final)
3033Message expired before deliveryThe message was queued by the mobile provider and timed out before it could be delivered to the handset. (Final)
3034SMS not supportedSMS is not supported by this phone, carrier, plan, or user.
3035Invalid/unsupportedThe content of the message is not supported.
3036Price threshold exceededMessage not sent due to the price exceeding your set maximum price.
3037Message blocked in requested countryYou requested that messages in a specific country be blocked, and the message was being sent to this country.
3038Destination blocked by prefixYou requested that phone numbers with a particular prefix be blocked.
3039Final status unknownThe final status of the SMS cannot be determined.
3040Queued by gatewayThe SMS gateway has queued the message.
3041Carrier rejected - temporary problemThis error is generated if there is an error on the carrier or operator side that is temporary and the message can be retried.
3042Carrier rejected - permanent errorThis error is generated if there is an error on the carrier or operator side that is permanent and the message should not be retried.
3043Error on gateway - temporary errorThis error is generated if there is an error on Telesign's partner side that is considered temporary and the message can be retried.
3044Error on gateway - permanent errorThis error is generated if there is an error on Telesign's partner side that is considered permanent and the message should not be retried.
3045Parameters problemOne or more parameters used in the request is not supported.
3046Message blocked by subscriber action or requestThe end user has blocked receiving SMS with their carrier plan or by request or from the particular short code used.
3047Subscriber low on creditThe end user exceeded their spending limits and cannot receive SMS.
3048Roaming errorEnd user cannot receive SMS because their device that receives the messages is roaming.
3049Mobile number portability errorSMS failed because ported combinations are unreachable.
3050Subscriber absentThe operator/carrier is temporarily unable to reach the end user's device.
3051Suspected spamThis message is considered to be spam by carrier or operator.
3052Message blocked by your requestThis 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.
3053Message blocked by TeleSignTelesign blocks a message if it is being sent to a phone number that is on a global blocklist.
3054Delivery channel not supported by the end user's deviceThe end user's device does not support the channel used for delivery. (Final)
3055Error on gateway - temporary errorThis error is generated if there is an error on Telesign's partner side that is considered temporary and the message can be retried.
3056Message failed to deliver in specified fallback timeDelivery could not be confirmed on this channel within the fallback window; triggers the next channel (if any) to send. (Intermediate)
3057Invalid source addressThe message requires a source address. Verify that one is provided and correct.
3058The requested API host is not allowed for this customer_id
3059Exceeded number of elements for rich card
3061Media size exceeds the limit
3062MMS not supported
3071Unverified phone_number requested for trial account.
3073Insufficient funds in prepaid wallet
3100Unknown 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)
3101Invalid value for parameter phone_number: {phone_number}Phone number is too long, too short, or contains non-digit values. (Intermediate)
3102Invalid value for parameter message_type: {message_type}The value of parameter message_type is not one of the supported values: ARN, MKT, OTP. (Final)
3103Unsupported value for parameter external_id: {external_id}The value of parameter external_id is longer than 100 or contains non-ASCII characters. (Final)
3104Invalid 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)
3105Invalid value for parameter originating_ip: {originating_ip}Parameter originating_ip is improperly formatted. (Final)
3106Invalid value for parameter callback_url: {callback_url}The value of parameter callback_url is empty. (Final)
3107Invalid country code for parameter phone_number
3108Invalid value for parameter message
3109Invalid value for parameter sender_id
3110Invalid requestThe API request or its JSON payload is improperly formatted. (Final)
3112Specified template does not exist for selected channel
3113Invalid value for parameter channel: {channels}The value of the parameter channels contains the same channel more than once or is improperly formatted. (Final)
3114Specified message type not allowed outside of conversation window
3115Destination phone number not in coverage
3117Invalid value for parameter fbmessager_id: { fbmessager_id}fbmessager_id value is too long, too short, or not valid. (Intermediate)
3118Invalid 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 customerThis channel is not enabled for this customer. (Intermediate)
3202Fallback is not enabled for Customer IDMultiple channels are specified in the request, but fallback is not enabled for this customer. (Intermediate)
3205Rate Limit Exceeded
3207Messaging exceeded transaction hard cap. Request denied.
3208Provider Account ID not found
3209Phone number not registered for testing
3302Missing parameter phone_numberThe API request does not contain the mandatory parameter phone_number. (Final)
3303Missing parameter messageThe API request does not contain the mandatory parameter message. (Final)
3304Missing parameter message_typeThe API request does not contain the mandatory parameter message_type. (Final)
3305Missing template specific parameters
3306Missing message parameters for specified channelMessage object doesn't contain required info for sending message through selected channel. (Intermediate)
3400Not authorizedNo permissions for this resource or authorization failed. (Final)
3405Missing required Authorization header
3406CustomerID Account Suspended
3408CustomerID Account Not Found
3409Invalid source IP address
3410Invalid Customer ID
3411Invalid API Key
3412Required Authorization header is not in the correct format
3413Not Allowed IP Address
3500System UnavailableThe system is currently unavailable. The request should be resubmitted. (Final)
3601CustomerID Account Not Found