Messaging - Send suggested replies with RCS

📘

NOTE:

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

This page walks you step-by-step through how to use the Messaging to send an RCS message to an end-user that includes a question and multiple buttons, each of which suggests a reply for them to choose from.

Before you begin

Make sure you have the following before you start:

  • Transaction Callback Service: You need to have this set up so Telesign can send you delivery status updates for your Messaging requests. See Messaging - Callback service for more details.
  • RCS account details: Before sending a message using RCS, you first need to work with our Customer Support Team to set up an RCS account for you. See Set up RCS for your account for more details.

🚧

CAUTION:

Currently RCS is not supported by iOS devices. We recommend either ensuring your end users have supported devices or including a fallback channel for iOS users.

Steps

  1. Send a POST /v1/omnichannel request. Include the following param values:
ParameterValueDescriptionRequired?
channelsarray of channel objectsAdd channel objects to the array in the order you want the service to try the channels.yes
channels[0]{"channel":"rcs"}Include rcs as the first channel.yes
channels[0].fallback_timeA time in seconds.Specify the time to wait before cascading to the next channel.no
channels[1]{"channel":"sms"}Include sms as the backup channel.yes (if SMS is used for backup)
message.rcs.template2_suggested_replies or 3_suggested_repliesSpecify one of the predefined templates that includes buttons with suggested answers to a question.yes
message.rcs.parameters.button_text_1Some text.Text you want to appear inside the first suggested reply button. Typically this is an answer to your question.yes
message.rcs.parameters.button_payload_1A unique identifier.An ID identifying this button.yes
message.rcs.parameters.button_text_2Some text.Text you want to appear inside the second suggested reply button. Typically this is an answer to your question.yes
message.rcs.parameters.button_payload_2A unique identifier.An ID identifying this button.yes
message.rcs.parameters.button_text_3Some text.Text you want to appear inside the third suggested reply button. Typically this is an answer to your question.no (required only for the 3_suggested_replies template)
message.rcs.parameters.button_payload_3A unique identifier.An ID identifying this button.no (required only for the 3_suggested_replies template)
message.rcs.parameters.textSome text.Text to display above the buttons. Typically this is a question that you want the end-user to answer.yes
message.rcs.parameters.urlA fully-qualified URL.The URL where you are hosting your media file.yes
message.sms.templatetextSpecify SMS as your preferred backup channel, using the text template. You can use a different backup channel and template if you prefer.no

Request example

POST /v1/omnichannel HTTP/1.1
Content-Type: application/json
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Host: rest-ww.telesign.com
{
  "channels": [
    {
      "channel": "rcs",
      "fallback_time": 600
    },
    {
      "channel": "sms"
    }
  ],
  "phone_number": "15558675309",
  "message": {
    "rcs": {
      "template": "2_suggested_replies",
      "parameters": {
        "button_text_1": "Yes",
        "button_payload_1": "r1id",
        "button_text_2": "No",
        "button_payload_2": "r2id",     
        "text": "Someone is trying to access your Viatu account on a new device. Is this an authorized login?"      
      },
      "sms": {
        "template": "text",
        "parameters": {
          "text": "Someone is trying to access your Viatu account on a new device. Is this an authorized login? Reply with YES or NO."
        }
      }
    },
  "message_type": "MKT"
}
  1. If the request is processed successfully, you should see a response with a 3001 status code.

Response example

HTTP/1.1 200 OK
Server: nginx/1.17.7
Date: Wed, 14 Oct 2020 21:25:54 GMT
Content-Type: application/json
Content-Length: 137
Connection: keep-alive
Allow: GET,POST,HEAD
{
  "status": {
    "code": 3001,
    "description": "Message in progress"
  },
  "reference_id": "35C8B5D509BC10689196FED2AD551B8A",
  "external_id": null
}
  1. If the send in RCS format is successful, your end-user receives a message on their device based on the text in message.rcs.parameters.text. For example, a RCS message could be sent to your end-user stating that someone is attempting to access their account on a new device and ask them to confirm (Yes/No) whether it is an authorized sign in.
  2. If the send in RCS format fails, the service tries to send to the next specified backup channel (if any).
A screenshot of a message sent using the next specified backup channel if the send in RCS format is unsuccessful.

SMS Backup

  1. Updates on the status of this message are sent to the callback URL for your Transaction Callback Service. The general callback schema common to both this and other products is described on Transaction Callback Service. Modifications to the callback schema for this product are described on Messaging - Callback service. Search for these callbacks based on the reference ID in the response to your original Messaging request. Each callback payload includes an object with the status of the send for each channel that is tried.

Callback example

GET /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"
    }}
  ]
}

📘

NOTE:

In addition to the reference ID for the Messaging transaction itself, the delivery status payload also includes a reference ID for the message-send on each channel. These can be useful for troubleshooting purposes.

  1. When the end-user who received your RCS message selects one of the reply buttons, an inbound message event is sent to your Transaction Callback Service. Search for these events based on the reference ID in the response to your original Messaging request. The reference ID you are searching for here is found in the suggestionResponse.original_reference_id property of the inbound message event's payload.

📘

NOTE:

The inbound message event also has its own reference ID, which isn't relevant to your search.

Inbound Message example

GET /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{
  "phone_number": "15558675309",
  "reference_id": "9876543210ABCDEF0123456789ABCDEF",
  "submit_timestamp": "2020-05-04 22:06:00.325",
  "suggestionResponse": {
    "original_reference_id": "35C8B5D509BC10689196FED2AD551B8A",
    "text": "Maybe"
  }
}
  1. Match the value of the suggestionResponse.text property in the inbound message event's payload against the button_text_1, button_text_2, and button_text_3 text from your original request. If the value matches any of those text strings, you know that the end user selected that answer to your question.