RCS Channel

Conversation API provides support for RCS channel through Sinch RCS API.

Note:

If you are unfamiliar with RCS, we encourage you to visit the RCS Knowledge Base on the Sinch Community site. There, you'll find articles that answer common questions and provide context for the information detailed below.

To start using RCS through Conversation API you need to first have a Sinch RCS bot - read more.

Warning

Both Conversation API and Sinch RCS API are regional. Your Conversation API App must be created in the same region that your RCS bot is provisioned. If your Conversation API App is created in a different region than the RCS bot is provisioned, the RCS channel will report errors and you won't receive your delivery reports.

Sending Configuration

Sending a RCS message requires a Conversation API app with channel_credentials for RCS channel (You can create an app either in the portal or through API call - read more). Example, app is given in the following snippet:

Copy

Copied

{
  "channel_credentials": [
    {
      "channel": "RCS",
      "static_bearer": {
        "claimed_identity": "{{RCS_BOT_ID}}",
        "token": "{{RCS_BEARER_TOKEN}}"
      }
    }
  ]
}

You need to replace:

{{RCS_BOT_ID}} with your Sinch RCS bot ID
{{RCS_BEARER_TOKEN}} with the bot's access token.

Receiving Configuration

Receiving contact messages (replies) and delivery receipts from RCS requires setting the Callback URL of the RCS bot to point to your Conversation API app. The URL is the following:

Copy

Copied

https://rcs-adapter.{{REGION}}.conversation-api.int.prod.sinch.com/adapter/v1/{{CONV_API_APP_ID}}/callback

Where:

{{REGION}} is one of eu1 or us1 and must match the region of your app.
{{CONV_API_APP_ID}} is your app id.

You also need to configure at least one Conversation API webhook which will trigger POST callbacks to the given URL (You can create a webhook either in the portal or through API call - read more).

Sending Messages

Some rich messages are natively supported by RCS channel while others must be transcoded. The following sections demonstrate the mapping between the Conversation API generic message format and the way RCS renders the messages on mobile devices.

Text Messages

RCS channel natively supports Text Messages. The following image gives an example of a text message.

Text Message

The code to send a text message for this channel doesn't differ from the generic message and can be viewed here.

Media Messages

RCS channel natively supports Media Messages. Send a media message by specifying the URL to the media. Conversation API will automatically detect what type of RCS message to use - image or video.

The following image gives an example of a media message.

Image Media Message

The code to send a media message for this channel doesn't differ from the generic message and can be viewed here.

Choice Messages

RCS channel natively supports Choice Messages. You can configure a choice message from the following four choice types:

Text Choice
URL Choice
Call Choice
Location Choice

You can send a maximum of 3 choices in one message.

The following image gives an example of a choice message.

Choice Message

The code to send a choice message for this channel doesn't differ from the generic message and can be viewed here.

Card Messages

RCS natively supports Card Messages with a maximum of 3 choices. The media message in the Card should point to an image or a video. The following image gives an example of a card message.

Card Message With URL Choice

The code to send a card message for this channel doesn't differ from the generic message and can be viewed here.

Carousel Messages

RCS natively supports Carousel Messages. You can put from 1 to 10 cards in one message. Each card can consist of the elements described in the "Card Messages" section. If you send only one card, the message will be rendered as a normal Card Message. Additionally, RCS channel supports a maximum of 3 outer choices. You can put outer choices into the carousel_message.choices array field, and these choices will be rendered right after the displayed cards.

The following image gives an example of a carousel message.

Carousel Message

The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed here.

Location Messages

RCS channel doesn't natively support Location Messages. You can simply put your coordinates in a message body and Conversation API transcodes it into a text message with one Location Choice.

The following image gives an example of a location message.

Location Message

The code to send a location message for this channel doesn't differ from the generic message and can be viewed here.

Receiving Messages

RCS channel supports various kinds of receiving messages - text, media, location as well as quick replies. All of these are delivered by Conversation API with POST to MESSAGE_INBOUND webhook:

Example text reply message:

Copy

Copied

{
  "app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
  "accepted_time": "2020-10-01T19:52:11.495283Z",
  "event_time": "2020-10-01T19:52:11.390725Z",
  "project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
  "message": {
    "id": "01EKJVHPW7M6E50FAN02B91CW3",
    "direction": "TO_APP",
    "contact_message": {
      "text_message": {
        "text": "test"
      }
    },
    "channel_identity": {
      "channel": "RCS",
      "identity": "14700000000",
      "app_id": ""
    },
    "conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
    "contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
    "metadata": "",
    "accept_time": "2020-10-01T19:52:11.483787Z"
  }
}

Example media reply message:

Copy

Copied

{
  "app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
  "accepted_time": "2020-10-01T20:05:15.031962Z",
  "event_time": "2020-10-01T20:05:14.983131Z",
  "project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
  "message": {
    "id": "01EKJW9M3B7X131JKXM3W6025H",
    "direction": "TO_APP",
    "contact_message": {
      "media_message": {
        "url": "https://rcs-cnt.s3.amazonaws.com/9bcef194-02c6-4765-992e-d55ec16b474d/NTkyMzAyZjNkZTUyMTNlNjdkMGM1NWQx.png"
      }
    },
    "channel_identity": {
      "channel": "RCS",
      "identity": "14700000000",
      "app_id": ""
    },
    "conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
    "contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
    "metadata": "",
    "accept_time": "2020-10-01T20:05:15.019657Z"
  }
}

Example location reply message:

Copy

Copied

{
  "app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
  "accepted_time": "2020-10-01T19:57:46.142424Z",
  "event_time": "2020-10-01T19:57:46.087756Z",
  "project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
  "message": {
    "id": "01EKJVVXQEKQ4Y12ZJSC8M0SP7",
    "direction": "TO_APP",
    "contact_message": {
      "location_message": {
        "title": "Location",
        "coordinates": {
          "latitude": 55.61018,
          "longitude": 13.00106
        },
        "label": ""
      }
    },
    "channel_identity": {
      "channel": "RCS",
      "identity": "14700000000",
      "app_id": ""
    },
    "conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
    "contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
    "metadata": "",
    "accept_time": "2020-10-01T19:57:46.125490Z"
  }
}

Example quick reply message:

Copy

Copied

{
  "app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
  "accepted_time": "2020-10-01T20:09:28.535558Z",
  "event_time": "2020-10-01T20:09:28.490771Z",
  "project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
  "message": {
    "id": "01EKJWHBNH9AHD0QQ5Z8B715MF",
    "direction": "TO_APP",
    "contact_message": {
      "choice_response_message": {
        "message_id": "01EKJWGGMA53D91CS7GTDW0BAE",
        "postback_data": "01EKJWGGMA53D91CS7GTDW0BAE_Suggested Reply Text"
      }
    },
    "channel_identity": {
      "channel": "RCS",
      "identity": "14700000000",
      "app_id": ""
    },
    "conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
    "contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
    "metadata": "",
    "accept_time": "2020-10-01T20:09:28.518771Z"
  }
}

Receiving Delivery Receipts

Messages sent through RCS channel can have three statuses: DELIVERED, READ and FAILED.

In case of FAILED status you can find more information about the failure in a reason field. Below you can see examples of all status messages.

Conversation API delivers all receipts by a POST to MESSAGE_DELIVERY webhook:

Example of DELIVERED receipt:

Copy

Copied

{
  "app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
  "accepted_time": "2020-10-01T20:09:00.810Z",
  "event_time": "2020-10-01T20:09:06Z",
  "project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
  "message_delivery_report": {
    "message_id": "01EKJWGGMA53D91CS7GTDW0BAE",
    "conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
    "status": "DELIVERED",
    "channel_identity": {
      "channel": "RCS",
      "identity": "14700000000",
      "app_id": ""
    },
    "contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
    "metadata": ""
  }
}

Example of READ receipt:

Copy

Copied

{
  "app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
  "accepted_time": "2020-10-01T20:09:00.810Z",
  "event_time": "2020-10-01T20:09:07Z",
  "project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
  "message_delivery_report": {
    "message_id": "01EKJWGGMA53D91CS7GTDW0BAE",
    "conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
    "status": "READ",
    "channel_identity": {
      "channel": "RCS",
      "identity": "14700000000",
      "app_id": ""
    },
    "contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
    "metadata": ""
  }
}

Example of FAILED receipt:

Copy

Copied

{
  "app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
  "accepted_time": "2020-10-02T13:19:13.737Z",
  "event_time": "2020-10-02T13:19:16Z",
  "project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
  "message_delivery_report": {
    "message_id": "01EKMQEWT985EB0QNFA4CY17F9",
    "conversation_id": "01EKMQEWVF07XH0849C05B1XK2",
    "status": "FAILED",
    "channel_identity": {
      "channel": "RCS",
      "identity": "14700000000",
      "app_id": ""
    },
    "contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
    "reason": {
      "code": "RECIPIENT_NOT_REACHABLE",
      "description": "The underlying channel reported: Unable to find rcs support for the given recipient"
    },
    "metadata": ""
  }
}