Messaging API - Callback Service

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


Did this page help you?