Messaging - Send link button in rich card 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 displays a rich card, including both an image and a link button to a URL of your choice.

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

Depending on whether you want a vertical rich card (image stacked above button) or a horizontal rich card (image to the side of button), skip to the appropriate section:

Vertical rich card

Steps

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 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.template`	`rc_url_action_vertical`	Specify the predefined RCS template for a vertically stacked rich card with a link button in the message.	yes
`message.rcs.parameters.media_url`	Some text.	The URL where you are hosting your image file for the rich card.	yes
`message.rcs.parameters.url`	A fully-qualified URL.	The URL that the link button takes the end-user to after it is clicked.	yes
`message.rcs.parameters.url_payload`	An identifier.	A unique ID for this link.	yes
`message.rcs.parameters.url_text`	Some text.	Text to display inside the link 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
`message.sms.parameters.text`	Some text.	Text to display in the message.	yes (if text template is used for backup)

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": "rc_url_action_vertical",
      "parameters": {
      	"url_text": "Go to shop",
        "url_payload": "urlid1",
        "url":"https://viatushop.com/products?id=62384&code=BOGO",
        "media_url":"https://s3.amazonaws.com/viatu-mktg/bogo_coupon_52360.jpg"
      }
    },
    "sms": {
      "template": "text",
      "parameters": {
        "text": "Buy one get one free! Use code 'BOGO' at checkout on viatushop.com."
      }
    }
  },
  "message_type": "MKT"
}

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
}

If the send in RCS format is successful, your end-user receives a message on their device that looks like this.

A screenshot of a message received by an end user if the send in RCS format is successful.

If the send in RCS format fails, the service tries to send 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.

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.

Horizontal rich card

Steps

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
`channels[1]`	`{"channel":"sms"}`	Include `sms` as the backup channel.	yes (if SMS is used for backup)
`message.rcs.template`	`rc_url_action_vertical`	Specify the predefined RCS template for a horizontally arranged rich card with a link button in the message.	yes
`message.rcs.parameters.media_url`	Some text.	The URL where you are hosting your image file for the rich card	yes
`message.rcs.parameters.url`	A fully-qualified URL.	The URL that the link button takes the end-user to after it is clicked.	yes
`message.rcs.parameters.url_payload`	An identifier.	A unique ID for this link.	yes
`message.rcs.parameters.url_text`	Some text.	Text to display inside the link 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
`message.sms.parameters.text`	Some text.	Text to display in the message.	yes (if text template is used for backup)

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": "rc_url_action_horizontal",
      "parameters": {
      	"url_text": "Go to shop",
        "url_payload": "urlid1",
        "url":"https://viatushop.com/products?id=62384&code=BOGO",
        "media_url":"https://s3.amazonaws.com/viatu-mktg/bogo_coupon_52361.jpg"
      }
    },
    "sms": {
      "template": "text",
      "parameters": {
        "text": "Buy one get one free! Use code 'BOGO' at checkout on viatushop.com."
      }
    }
  },
  "message_type": "MKT"
}

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
}

If the send in RCS format is successful, your end-user receives a message on their device that looks like this.

A screenshot of a message received by an end user if the send in RCS format is successful. — RCS Message

If the send in RCS format fails, the service tries to send 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

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.

Messaging - Send link button in rich card with RCS

📘
NOTE:

Before you begin

🚧
CAUTION:

Steps

Vertical rich card

Steps

📘
NOTE:

Horizontal rich card

Steps

📘
NOTE:

📘NOTE:

Before you begin

🚧CAUTION:

Steps

Vertical rich card

Steps

📘NOTE:

Horizontal rich card

Steps

📘NOTE:

📘
NOTE:

🚧
CAUTION:

📘
NOTE:

📘
NOTE: