Docs
BetaSDKsGet startedTalk to salesSign inSupportStatusPricing

Messaging - Receive inbound messages

📘

NOTE:

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

This page explains how to set up inbound messaging to receive messages and notifications from your end users.

All Mobile Originated (MO) messages received through Telesign Messaging will be delivered on a MO callback URL. This is done using a web service (Messaging Callbacks) that you created to receive notifications from Telesign Messaging about Mobile Originated (MO) messages from end users sent using its email, MMS, RCS, SMS, Viber, or WhatsApp channels. While you can receive notifications from multiple Telesign services at the same endpoint, we recommend that you use a different callback URL for each channel to help with channel identification. Our Customer Support Team can help you set this up for each channel that you use.

A callback is triggered by a user-defined event at the originating site (which varies depending on the channel used). The purpose of a callback is to manage MO messages from end users, including text, location, and media such as photos and documents. You can use a different MO callback URL for each channel.

Before you begin

  • Integration with Messaging: You will only receive these callbacks if you've made a Telesign Messaging request. See Messaging - Overview to learn how to code its integration.

Basic usage

  1. Enable channels: Confirm with our Customer Support Team that the channels you want to use for receiving inbound messages from end users have been enabled. You can select between six different Messaging channels: SMS, MMS, RCS, Viber, WhatsApp, and email.

  2. Set up MO callback for channels: Ask our Customer Support Team to enable the MO Callback feature in your account and set the MO Callback URL. Setting up a different MO Callback URL for each channel will allow you to determine which channel was used for a MO message.

  3. Set up handling of MO message notifications: The schema for MO message notifications is not the same as the notification schema shown on Transaction Callback Service. Instead, you will need to use the schema section details from the reference page of the channel(s) you are using (see the schema links for each channel listed in Examples).

    📘

    NOTE:

    Messaging also returns Delivery Status notifications and Read notifications so this service has a different schema than the general Transaction Callback Service. Also see Messaging - Callback Service for more about Delivery Status Notifications and Read Notifications for Messaging.

  4. Check your callback service: After you have sent a request to the API, check your callback service to see if you have received a notification of an inbound message indicating that the end user has responded to the message. (The documentation listed in Messaging - Overview will help you send a request for your specific channel and use case.)

Examples

Email: Unsubscribe request

{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "status": {
    "updated_on": "2023-10-31T14:47:10.490130Z",
    "description": "Delivered to customer",
    "code": 1500
  },
  "email": "[email protected]",
  "content": {
    "end_user_action": {
      "template": "text",
      "event": "unsubscribe"
    }
  },
  "sub_resource": "mo_email"
}

The full schema for email callbacks can be found on the Receive email callbacks reference page.

MMS: Image and text message

{
  "content": {
    "text_1": "Thank you",
    "url_image_1": "https://messaging-qa.telesign.com/mms/C62CA36E4D4001288A6329E831BA0005image_1?Expires=1697283961&Signature=WoxkS138d6wscGAX4KskPEcuBEMUaPkvBOTlhEvyH~L7S5NhVYVqOUojui0OmIgxZ7QEHJ6aAmvBFTWZV-bjJNPOtzDOszXCWG1guWrg3U91C3QLhKZackd3XTUECwuxvBUV5VXKaWG0CVKC9mHGf~sfBOXipBKeGr5M49DH5WjDlYGNz47wkqSSE9u6E2~MA7booqPmJWAAOvm35QuuaDbx9HpCABCW6RnFTnmFbG0HPOztOS~s6VxRKXsRScndJwhuzYZ8GjDu4WVtVFtB5jWvipsdb6vzltQ0TNklqLL2HjQPNjmBTOcf8GWLeu8UwNMFOhhJ8e1WYNpIk91dwg__&Key-Pair-Id=K132WY3DLO2U37",
    "subject": ""
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "phone_number": "11234567890",
  "sub_resource": "mo_mms",
  "status": {
    "updated_on": "2023-10-13T11:46:00.347975Z",
    "description": "Delivered to customer",
    "code": 1500
  }
}

The full schema for MMS callbacks can be found on the Receive MMS callbacks reference page.

RCS: Image message

{
  "rcs_sender_id": "rcs_sender_example",
  "phone_number": "11234567890",
  "status": {
    "description": "Delivered to customer",
    "updated_on": "2023-10-03T09:08:07.000000Z",
    "code": 1500
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "content": {
    "file": {
      "payload": {
        "name": "61999.jpg",
        "mime_type": "image/jpeg",
        "uri": "https://rcs-user-content-eu.storage.googleapis.com/c71c5cb4-5c1d-402d-938c-0137b1b90764/26abd8a692ecc5be69072dfff456515b22504b56851adc4952d6b3d5abc4",
        "size_bytes": 335861
      }
    }
  },
  "sub_resource": "mo_rcs"
}

The full schema for RCS callbacks can be found on the Receive RCS callbacks reference page.

Inbound SMS callbacks: Text message with keyword

(If you are using keywords set up for the Inbound SMS feature).

{
  "status": {
    "code": 1500,
    "description": "Delivered to customer",
    "updated_on": "2023-10-31T14:47:10.490130Z"
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "user_response": {
    "sender_id": "4442",
    "iso_country_code": "RS",
    "action": "start",
    "keyword": "start",
    "phone_number": "11234567890",
    "mo_message": "Start"
  },
  "sub_resource": "mo_sms",
  "errors": [],
  "submit_timestamp": "2023-10-31T14:47:10.154000Z"
}

The full schema for inbound SMS callbacks can be found on the Receive inbound SMS callbacks reference page.

Viber: Text message with emoticon

{
  "content": {
    "text": "Thank you! 😎"
  },
  "phone_number": "11234567890",
  "status": {
    "updated_on": "2023-09-25T14:04:51.000000Z",
    "code": 1500,
    "description": "Delivered to customer"
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

The full schema for Viber callbacks can be found on the Receive Viber callbacks reference page.

WhatsApp: Text message

{
  "status": {
    "description": "Delivered to customer",
    "code": 1500,
    "updated_on": "2023-10-02T07:54:41.000000Z"
  },
  "content": {
    "content": {
      "body": "Thank you"
    },
    "type": "text"
  },
  "phone_number": "11234567890",
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "waba_phone_number": "11234567891"
}

The full schema for WhatsApp callbacks can be found on the Receive WhatsApp callbacks reference page.

Keyword handling

Keyword handling is available for RCS and WhatsApp channels. This feature allows you to send your pre-defined replies in response to certain keywords within messages from end users for compliance purposes. Please contact our Customer Support Team to enable this feature for you.

Keyword handling means that a specific action is triggered when an end user's message contains specific keywords. When Telesign detects a specific keyword from an end user that maps to an action ("stop", "help", "start"), we in turn notify you (so you can update your information or any opt-out list that you manage). Telesign then notifies the end user using a response template (success or failure) once you direct us to do so. You can set up a separate response message for each keyword associated with a specific action so that each keyword can use a response message that is suitable for that keyword (such as different languages). For more information, refer to the Receive RCS callbacks and Receive WhatsApp callbacks reference pages.

The SMS channel has similar keyword handling but the actions are different. When using SMS channel, refer to Inbound SMS - Overview and the Receive inbound SMS callbacks reference page. Inbound SMS - Action-to-keyword mapping has a complete list of actions and the associated keywords. See Inbound SMS - Get started for an example.

Keyword handling actions for RCS and WhatsApp

"stop"

  • Keywords: "arrêt", "arret", "cancel", "end", "quit", "stop", "unsubscribe"
  • Description: Allows you to send a response notifying the end user that their phone number was removed from a list controlled and managed by you.
  • Automatic response available? Yes

"help"

  • Keywords: "aide", "contact", "help", "info"
  • Description: Sends a custom response that you created to end users that are seeking assistance or information. A default response is sent if you have not created your own custom response.
  • Automatic response available? Yes

"start"

  • Keywords: "start"
  • Description: Allows you to send a response notifying the end user that their phone number was added to a list controlled and managed by you.
  • Automatic response available? Yes

"generic"

  • Keywords: n/a
  • Description: No keywords found in the inbound message.
  • Automatic response available? Yes

Examples - Keyword handling

RCS: "stop" action

{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "phone_number": "11234567890",
  "status": {
    "description": "Delivered to customer",
    "code": 1500,
    "updated_on": "2023-12-13T09:36:10.000000Z"
  },
  "rcs_sender_id": "",
  "content": {
    "end_user_action": {
      "action": "stop",
      "iso_country_code": "US",
      "keyword": "stop",
      "text": "Stop"
    }
  },
  "sub_resource": "mo_rcs"
}

WhatsApp: "stop" action

{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "content": {
    "end_user_action": {
      "keyword": "end",
      "action": "stop",
      "text": "end",
      "iso_country_code": "US"
    }
  },
  "phone_number": "11234567890",
  "status": {
    "code": 1500,
    "description": "Delivered to customer",
    "updated_on": "2023-12-05T13:33:01.000000Z"
  },
  "waba_phone_number": "11234567891"
}

Updated 6 months ago

© 2024 Telesign / Terms & Conditions / Privacy Notice / Privacy Hub