Send Call Button with RCS

This page walks you step-by-step through how to use the Messaging API to send a message to an end-user that includes a button they can select to initiate a voice call.

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 the message you send through the Messaging API. See 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:
Parameter Value Description Required?
channels array of channel objects Add 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_time A time in milliseconds. Specify the time to wait before cascading to the next channel. no
message.rcs.template dial_action Specify the predefined RCS template that includes a click-to-call button in the message. yes
message.rcs.parameters.dial_id An identifier. A unique ID for this click-to-call phone number. yes
message.rcs.parameters.dial_text Some text. Text to display inside the click-to-call button. yes
message.rcs.parameters.phone_number_to_dial A complete phone number (including country code). The number that the end-user’s device dials after they select the click-to-call button. yes
message.rcs.parameters.text Some text. Text to display above the click-to-call button. yes
message.sms.template text Specify SMS as your preferred backup channel, using the text template. You can use a different backup channel and template if you prefer. no
NOTE:

By using the dial_id parameter, you can change out the phone number used over time without changing data collection that is keyed to the dial ID.

Request Example
HTTPS
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": "dial_action",
      "parameters": {
      	"dial_text": "Call us",
        "phone_number_to_dial": "18003334444",
        "dial_id": "dialid1",
        "text": "We received your refund request for order #45390 from viatushop.com. Please call our customer support team so we can finish servicing this request."
      }
    },
    "sms": {
      "template": "text",
      "parameters": {
        "text": "We received your refund request for order #45390 from viatushop.com. Please call our customer support team at 1.800.333.4444 so we can finish servicing this request."
      }
    }
  },
  "message_type": "MKT"
}
  1. If the request is processed successfully, you should see a response with a 3001 status code.
Response Example
HTTP
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 that looks like this.
  1. If the send in RCS format fails, the service tries to send the next specified backup channel (if any).
SMS Backup
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 Callback Service. Search for these callbacks based on the reference ID in the response to your original Messaging API request. Each callback payload includes an object with the status of the send for each channel that is tried.
Callback Example
HTTP
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 API 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.