RCS HTTP REST

The CLX Communications RCS REST API provides Universal Profile 2.0 RCS messaging with granular controls to allow fallback to SMS when a handset is not RCS enabled.

SMS Fallback and SMS status reporting are facilitated using the SMS HTTP REST API that allows for the use of existing tools to receive and collect delivery reports and mobile originated messages which should be familiar to existing users.

It will be possible to setup the RCS REST API to use an existing SMS account for all fallback SMS traffic.

When SMS Fallback is desired, fine grained control is provided by configuring fallback conditions.

Getting started

Authentication

Request with token

$ curl -H "Authorization: Bearer {token}" \
"https://api.clxcommunications.com/rcs/v1/{endpoint}"

The token is required for all requests made to the REST API.

The token is sent in the Authorization header preceded by Bearer.

RCS Universal Profile primer

RCS is the logical evolution of SMS enabling enterprises and individuals to exchange rich media, deep linking features and interactive content with the same ease as SMS.

The RCS REST API exposes a large portion of the chatbot enabled messaging formats described in the GSMA Universal Profile 2.0 specification.

The following types and concept are available:

  • Two-way text messaging
  • Two-way file transfer (including rich media messages such as videos and GIFs)
  • Rich cards (with suggestion chips)
  • Rich card carousels (NOTE: We are aware of stability issues associated with this feature)
  • Suggestion chips (actions and replies)
  • Delivery, display and composing indications
  • Message revocation

Sending the first message

Example of sending a simple text message.

curl https://api.clxcommunications.com/rcs/v1/my-agent-id/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zIMEJGfwD4oJ4qObPPjwZxwiP5cKARXRJpt9Kf6GSv7uOesvRV" \
  -d '{
    "message_id": "59a75b73-0669-4075-aeff-2a13f9967ebb",
    "to": "46555123456",
    "message": {
      "type": "text",
      "text": "Madam Im Adam"
    }
  }'

Sending messages is described in detail in Send a message.

Formats

This section will take a brief look at some of the formats used in the REST API.

JSON

JSON (application/json) is the content type of both requests and responses if not otherwise specified.

Requests with invalid JSON will be rejected.

Null values can be omitted in requests and will be omitted in responses. In some cases explicitly setting null will overwrite a previously set value with null. See Update a group for an example.

MSISDN

Only MSISDNs in international format are accepted by the API.

MSISDNs can be sent in with or without a leading “+” (i.e. +123456789 or 123456789) or with a leading “00”. Any spaces, dashes or brackets, will also be ignored by the API.

All MSISDNs returned by the REST API will be without a “+” or “00” prefix, even if they were sent in with one.

Timestamp

Timestamps are represented using ISO-8601 standard (see http://en.wikipedia.org/wiki/ISO_8601).

All timestamps returned by the batch will be in UTC with millisecond precision.

The time zone can be specified in accordance with ISO-8601. If no time zone offset is specified (local time in ISO-8601) then UTC will be used.

HTTP Status Codes

The REST API returns an HTTP status and code each time a request is made.

HTTP Statuses

The following HTTP status codes are used by the API. Additional codes might be added in the future and if you encounter a code not in this list please consult the HTTP specification for a definition.

Status Description
200 OK The request was successful.
400 Bad Request The request does not conform to the API. The request body should provide more information.
401 Unauthorized The authentication token is invalid for this service plan.
404 Not Found The path is invalid, or no resource exists with the given ID.
409 Conflict Duplicate message-id provided or trying to revoke an irrevocable message
405 Method Not Allowed The path is valid but not for this method.
415 Unsupported Media Type The request Content-Type is missing or unsupported. Most operations expect application/json.
500 Internal Server Error An unexpected internal error occurred, and the request was not processed.
503 Service Unavailable The service is unable to perform the request at this point. Most likely due to a required subsystem being unavailable.

HTTP Errors

Responses with status 400 Bad Request and 409 Forbidden the body is a JSON object explaining the error. It has the following parameters:

Error

JSON Representation
{
  "error": string,
  "field_errors": [
    object(FieldError), ...
  ]
}
Fields
Field Type Description Default Constraints Required
error string Descriptive message of the error No N/A Yes
field_errors arrayOf(FieldError) List of field errors, each element describes a specific field No N/A No

FieldError

JSON Representation
{
  "field": string,
  "errors": [
    string, ...
  ]
}
Fields
Field Type Description Default Constraints Required
field string The field for which this error is relevant No N/A Yes
errors arrayOf(string) List of errors for the field No N/A Yes

SMS Fallback

The RCS REST API enables robust support for SMS fallback based on a range of configurable conditions.

When fallback occurs, the message is handed over to CLX SMS HTTP REST API and further status update are available in accordance with Retrieve a delivery report and SMS REST API Callback.

Fallback is indicated by receiving a StatusReportFallbackDispatched on the agent’s webhook endpoint as described in Receiving updates and callbacks. The status report includes the external_ref field referencing a batch_id provided by the SMS REST API Send a batch message.

Fallback SMS service plan is configured during provisioning of the RCS REST API.

Fallback and condition configuration is controlled in detail by providing FallbackInfo in Send a message.

Fallback conditions

rcs_unavailable

(Default: enabled)

Fallback to SMS when the targeted MSISDN is not reachable by RCS. This will happen immediately after the user agent’s capabilities have been established.

capability_unsupported

(Default: disabled)

NOTE: Not currently enabled. Fallback to SMS if the specific capability needed to deliver the provided message payload is not supported by the receiving MSISDN, e.g., the device does not support media messages.

expire

(Default: enabled)

Fallback to SMS if the per message provided (See ExpireInfo) or RCS REST API system wide (48h) message expiry happens.

This means that a delivered notification was not received before the message expired. The RCS message will be revoked before sending the fallback SMS. Revocation is also configurable in the FallbackInfo object.

agent_error

(Default: disabled)

Fallback to SMS if a fatal agent error occurs with a RCS supplier or within the RCS REST API platform.

Enabling SMS fallback on agent error guarantees that an SMS is sent instead of potentially delaying a message because of unexpected issues in the RCS delivery pipeline.

Agent errors should not occur as RCS matures, but is useful if delivery using any channel is the priority.

Receiving updates and callbacks

Message status updates, events and messages from the RCS REST API and user agents, are delivered to the API client using webhook callbacks.

All types of callbacks are sent to the same HTTP(S) endpoint registered in the RCS REST API. See Registering Webhook URI for details on how to register a webhook URI.

Callbacks are categorized as:

  • Status reports, sent every time the status of a sent message changes
  • User Agent Events, sent for events generated by the user agent, e.g., composing notifications
  • User Agent Messages, sent whenever the user agent manually sends a message (text/image/location/etc.) or interacts with sent suggestion chips.

A callback is a HTTP POST request with a notification made by the RCS REST API to a URI of your choosing. The RCS REST API expects the receiving server to respond with a response code within the 2xx Success range. If no successful response is received then the RCS REST API will either schedule a retry if the error is expected to be temporary or discard the callback if the error seems to be permanent.

Callback Request

Callbacks are sent as a JSON encoded HTTP POST requests to the agent-specific webhook URI (See Registering Webhook URI):

POST {agent_callback_uri}

Callback Payload

The callback payload format is

JSON Representation

{
  "type": enum(
    "status_report_rcs",
    "user_agent_event_rcs",
    "user_agent_message_rcs"
  ),
  ... // type specific fields
}

Fields

Depending on the type of callback the payload will be one of (as indicated by type field):

Examples

Successfully delivered message
{
  "type": "status_report_rcs",
  "message_id": "bc6776ee-7bde-4d6e-9c1e-102e87f92520",
  "at": "2017-10-31T13:06:30Z",
  "status_report": {
    "type": "delivered"
  }
}
Message dispatched as SMS fallback

An SMS fallback was delivered since the RCS message was not delivered before it expired.

{
  "type": "status_report_rcs",
  "message_id": "9cd91120-5e54-4d42-af22-1a042502ad97",
  "at": "2017-10-31T13:06:30Z",
  "status_report": {
    "type": "fallback_dispatched",
    "external_ref": "23esaaf9912s",
    "revoked": true,
    "reason": {
      "type": "expired"
    }
  }
}
User agent taps a suggested reply chip
{
  "type": "user_agent_message_rcs",
  "message_id": "9lkj32asd712jkasdjkasdkhsadasd",
  "from": "4655123456",
  "message": {
    "type": "suggestion_response",
    "postback_data": "ef425f90-a27b-4956-9ba0-37cdd2d6e160_YES_CHIP",
    "text": "Yes"
  }
}

Status reports

Message status reports are sent whenever a message performs a state transition in the diagram below:

Message state diagram

Message state transitions and flow diagram. Rectangles represent states communicated using StatusReport callback payloads. The logic in the flow diagram is controlled by various options passed to the FallbackInfo when sending a message, combined with events such as message expiry (see ExpireInfo), supplier errors, etc.

Status descriptions

Status Description
queued Message is queued within RCS REST API system and will be dispatched.
capability_lookup_dispatched Message is awaiting capability lookup request dispatched with the RCS supplier.
dispatched Message is dispatched in the selected RCS supplier / operator platform.
fallback_dispatched Message was not sent as RCS message, and a fallback SMS has been dispatched. See SMS Fallback.
aborted Message was not sent, and no fallback SMS was dispatched.
failed Message failed to be dispatched as RCS or fallback SMS.
delivered Message was Successfully delivered.
displayed Message was displayed in user agent.

JSON Models

Detailed description of all available status report payloads

StatusReport
JSON Representation
{
  "type": "status_report_rcs",
  "message_id": string,
  "at": timestamp,
  "status_report": {
    "type": enum(
      "queued",
      "capability_lookup_dispatched",
      "dispatched",
      "fallback_dispatched",
      "aborted",
      "failed",
      "delivered",
      "displayed"
    ),
    ... // type specific fields
  }
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘status_report_rcs’ N/A N/A Yes
message_id string Message id for which this status report is relevant No ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ Yes
at string Timestamp of then the status report was created in the CLX service No A timestamp in RFC3339 UTC “Zulu” format Yes
status_report
oneOf:
Object describing the status report. The type of report is identified by the type property. No N/A Yes
StatusReportQueued
JSON Representation
{
  "type": "queued"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘queued’ N/A N/A Yes
StatusReportCapabilityLookupDispatched
JSON Representation
{
  "type": "capability_lookup_dispatched"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘capability_lookup_dispatched’ N/A N/A Yes
StatusReportDispatched
JSON Representation
{
  "type": "dispatched"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘dispatched’ N/A N/A Yes
StatusReportFallbackDispatched
JSON Representation
{
  "type": "fallback_dispatched",
  "external_ref": string,
  "revoked": boolean,
  "reason": {
    enum(
      "rcs_unavailable",
      "capability_unsupported",
      "expired",
      "agent_error",
    ),
    ... // type specific fields
  }
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘fallback_dispatched’ N/A N/A Yes
external_ref string SMS HTTP REST API batch id after fallback No N/A Yes
revoked boolean Has the RCS message been revoked? No N/A Yes
reason
oneOf:
The reason why the fallback occurred, always based on one of the provided fallback conditions No N/A Yes
FallbackReasonRcsUnavailable
JSON Representation
{
  "type": "rcs_unavailable"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘rcs_unavailable’ N/A N/A Yes
FallbackReasonCapabilityUnsupported
JSON Representation
{
  "type": "capability_unsupported"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘capability_unsupported’ N/A N/A Yes
FallbackReasonExpired
JSON Representation
{
  "type": "expired"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘expired’ N/A N/A Yes
FallbackReasonAgentError
JSON Representation
{
  "type": "agent_error",
  "code": integer,
  "reason": string
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘agent_error’ N/A N/A Yes
code integer Error code of agent error causing the fallback N/A N/A Yes
reason string Descriptive message of why the message failed N/A N/A Yes
StatusReportAborted
JSON Representation
{
  "type": "aborted",
  "revoked": boolean,
  "expired": boolean
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘aborted’ N/A N/A Yes
revoked boolean Has the RCS message been revoked? No N/A Yes
expired boolean Has the RCS message expired? No N/A Yes
StatusReportFailed
JSON Representation
{
  "type": "failed",
  "revoked": boolean,
  "expired": boolean,
  "code": integer,
  "reason": string
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘failed’ N/A N/A Yes
revoked boolean Has the RCS message been revoked? No N/A Yes
expired boolean Has the RCS message been expired? No N/A Yes
code integer Error code of agent error causing the fallback No N/A Yes
reason string Descriptive message of why the message failed No N/A Yes
StatusReportDelivered
JSON Representation
{
  "type": "delivered"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘delivered’ N/A N/A Yes
StatusReportDisplayed
JSON Representation
{
  "type": "displayed"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘displayed’ N/A N/A Yes

User Agent Events

Detailed descriptions of all available user agent event payloads

JSON Models

UserAgentEvent
JSON Representation
{
  "type": "user_agent_event_rcs",
  "from": MSIDSN,
  "event": {
    "type": enum("composing"),
    ... // type specific fields
  }
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘user_agent_event_rcs’ N/A N/A Yes
from string MSISDN of the device that sent the event No No Yes
event
oneOf:
Object describing the event No N/A Yes
UserAgentEventComposing
JSON Representation
{
  "type": "composing"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘composing’. This type notifies the agent that the user is typing N/A N/A Yes

User Agent Messages

Detailed descriptions of all available user agent message payloads

JSON Models

UserAgentMessage
JSON Representation
{
  "type": "user_agent_message_rcs",
  "message_id": string,
  "from": MSISDN,
  "message": {
    "type": enum(
      "text",
      "file",
      "suggestion_response"
    ),
    ... // type specific fields
  }
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘user_agent_message_rcs’ N/A N/A Yes
message_id string Unique message id for this user message No No Yes
from string MSISDN of the device that sent the message No No Yes
message
oneOf:
The message content No N/A Yes
SuggestionResponse
JSON Representation
{
  "type": "suggestion_response",
  "postback_data": string,
  "text": string
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘suggestion_response’ N/A N/A Yes
postback_data string The postback data that was supplied in the object(SuggestedReply) or object(SuggestedAction) No No No
text string The text that was supplied in the object(SuggestedReply) or object(SuggestedAction) No No No

At least one of postback_data and text will be set

Registering Webhook URI

Please contact CLX Communications to update the webhook URL.

Messages endpoint

The messages endpoint provides operations for sending and revoking messages.

Send a message

Send an RCS message, optionally falling back to SMS depending on provided conditions. A fallback SMS can be delivered if:

  • The targeted device does not support RCS (controlled by the rcs_unavailable condition)
  • The targeted device does not support the specific RCS capability needed to deliver the message provided in the message body (controlled by the capability_unsupported condition)
  • The RCS platform does not receive a delivery confirmation before the provided expiration time. It is possible to configure if the original RCS message should be revoked when a message expires (controlled by the expired condition)
  • The RCS message cannot reliably be delivered because of an error within the RCS platform or the downstream suppliers. (controlled by the agent_error condition)

Status reports will be continuously delivered to the agent’s webhook endpoint described in Receiving updates and callbacks.

HTTP Request

POST /rcs/v1/{agent_id}/messsages

Path parameters

Field Type Description Default Constraints Required
agent_id string ID of the agent to be used No No Yes

Request Body

The request body contains an instance of AgentMessage.

Response

200 OK

The message was successfully accepted by the system. The response body contains an instance of StatusReport.

400 Bad Request

This error is returned when either the JSON is malformed or one or more parameters in the JSON failed validation. The body contains an Error object further describing the error.

409 Conflict

Duplicate message id, make sure message_id in AgentMessage is unique. The body contains an Error object further describing the error.

Examples
Send text message
curl https://api.clxcommunications.com/rcs/v1/my-agent-id/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zIMEJGfwD4oJ4qObPPjwZxwiP5cKARXRJpt9Kf6GSv7uOesvRV" \
  -d '{
      "message_id": "5f6ec22b-f03a-4961-9c57-6c4e464edae0",
      "to": "46555123456",
      "message": {
          "type": "text",
          "text": "Test message!"
      }
  }'
Send text message with fallback
curl https://api.clxcommunications.com/rcs/v1/my-agent-id/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zIMEJGfwD4oJ4qObPPjwZxwiP5cKARXRJpt9Kf6GSv7uOesvRV" \
  -d '{
      "message_id": "5bb77a04-78b7-41ff-abd3-a1006f8d6979",
      "to": "46555123456",
      "message": {
          "type": "text",
          "text": "Test message!"
      },
      "fallback": {
          "message": {
              "type": "mt_text",
              "from": "MyOriginator",
              "text": "Test message!"
          }
      }
  }'
Send text message with (non-default) expire
curl https://api.clxcommunications.com/rcs/v1/my-agent-id/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zIMEJGfwD4oJ4qObPPjwZxwiP5cKARXRJpt9Kf6GSv7uOesvRV" \
  -d '{
      "message_id": "66c4eeea-259b-4ba0-9dcd-cd0545cd9344",
      "to": "46555123456",
      "message": {
          "type": "text",
          "text": "This is a time-sensitive message!"
      },
      "expire": {
          "timeout": 3000,
          "revoke": true
      }
  }'
Send file message
curl https://api.clxcommunications.com/rcs/v1/my-agent-id/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zIMEJGfwD4oJ4qObPPjwZxwiP5cKARXRJpt9Kf6GSv7uOesvRV" \
  -d '{
      "message_id": "41a54db6-6abf-48dd-8a2b-63890981d80d",
      "to": "46555123456",
      "message": {
          "type": "file",
          "thumbnail": {
              "mime_type": "image/png",
              "file_size": 1234,
              "file_uri": "http://example.com/my_image_thumbnail.png"
          },
          "file": {
              "mime_type": "image/png",
              "file_name": "funny.png",
              "file_size": 123456,
              "file_uri": "http://example.com/my_image.png"
          }
      }
  }'
Send text message and suggestions
curl https://api.clxcommunications.com/rcs/v1/my-agent-id/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zIMEJGfwD4oJ4qObPPjwZxwiP5cKARXRJpt9Kf6GSv7uOesvRV" \
  -d '{
      "message_id": "feed1169-8500-4b66-a65c-5986b8ae59f7",
      "to": "46555123456",
      "message": {
          "type": "text",
          "text": "Test message!"
      },
      "suggestions": [
          {
              "type": "reply",
              "display_text": "Like",
              "postback": {
                  "data": "feed1169-8500-4b66-a65c-5986b8ae59f7_LIKE"
              }
          },
          {
              "type": "reply",
              "display_text": "Stop please",
              "postback": {
                  "data": "feed1169-8500-4b66-a65c-5986b8ae59f7_STOP"
              }
          },
          {
              "type": "action",
              "display_text": "Call us",
              "postback": {
                  "data": "feed1169-8500-4b66-a65c-5986b8ae59f7_CALL"
              },
              "action": {
                  "type": "dial_phone_number",
                  "phone_number": "+46555123456"
              }
          }
      ]
  }'
Send standalone rich card message with suggestions on card
curl https://api.clxcommunications.com/rcs/v1/my-agent-id/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zIMEJGfwD4oJ4qObPPjwZxwiP5cKARXRJpt9Kf6GSv7uOesvRV" \
  -d '{
      "message_id": "ea099bc3-541a-4967-bbe3-5598e8209c75",
      "to": "46555123456",
      "message": {
          "type": "standalone_rich_card",
          "orientation": "VERTICAL",
          "thumbnail_alignment": "RIGHT",
          "content": {
              "title": "Hello1",
              "description": "Hello There",
              "media": {
                "height": "TALL",
                "thumbnail": {
                    "mime_type": "image/png",
                    "size": 1234,
                    "file_uri": "http://example.com/my_image_thumbnail.png"
                },
                "file": {
                    "mime_type": "image/png",
                    "name": "funny.png",
                    "file_size": 12345,
                    "file_uri": "http://example.com/my_image.png"
                }
              },
              "suggestions": [
                  {
                      "type": "reply",
                      "display_text": "Like",
                      "postback": {
                          "data": "feed1169-8500-4b66-a65c-5986b8ae59f7_LIKE"
                      }
                  },
                  {
                      "type": "reply",
                      "display_text": "Stop please",
                      "postback": {
                          "data": "feed1169-8500-4b66-a65c-5986b8ae59f7_STOP"
                      }
                  },
                  {
                      "type": "action",
                      "display_text": "Call us",
                      "postback": {
                          "data": "feed1169-8500-4b66-a65c-5986b8ae59f7_CALL"
                      },
                      "action": {
                        "type": "dial_phone_number",
                        "phone_number": "+46555123456"
                      }
                  }
              ]
          }
      }
  }'

JSON Model

AgentMessage
JSON Representation
{
  "message_id": string,
  "to": string,
  "message": {
    "type": enum(
      "text",
      "file",
      "standalone_rich_card",
      "carousel_rich_card"
    ),
    ... // type specific fields
  },
  "suggestions": [
    {
      "type": enum(
        "action",
        "reply"
      )
      ... // type specific fields
    }
  ],
  "expire": object(ExpireInfo),
  "fallback": object(FallbackInfo)
}
Fields
Field Type Description Default Constraints Required
message_id string Provide a globally unique id for this message No ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ Yes
to string MSISDN of the recipient No ^(?:00|+|)[1-9][0-9]{8,16}$ Yes
message
oneOf:
The content of the message No No Yes
suggestions
arrayOf:
A list of suggestions comprised of suggested replies and suggested actions. No MaxLength: 11 No
expire object(ExpireInfo) Object describing how the message should expire No No No
fallback object(FallbackInfo) Object describing fallback message and under which conditions it should be triggered No No No
TextMessage
JSON Representation
{
  "type": "text",
  "text": string
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘text’ N/A N/A Yes
text string The message body content No MaxLength: 2000 Yes
FileMessage
JSON Representation
{
  "type": "file",
  "file": object(FileInfo),
  "thumbnail": object(FileInfo)
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘file’ N/A N/A Yes
file object(FileInfo) Object describing the file No N/A Yes
thumbnail object(FileInfo) Thumbnail of the media, only required for images and videos No N/A No
FileInfo
JSON Representation
{
  "mime_type": string,
  "file_size": integer,
  "file_name": string,
  "file_uri": string
}
Fields
Field Type Description Default Constraints Required
mime_type string Mime type of the media No   Yes
file_size integer File size in bytes No   Yes
file_name string Only set for payload (not thumbnail) No   No
file_uri string HTTP(S) URL for the actual resource No URL - As defined by RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax, amended by RFC 2732: Format for Literal IPv6 Addresses in URLs. Yes
StandaloneRichCardMessage
JSON Representation
{
  "type": "standalone_rich_card",
  "orientation": enum(
    "HORIZONTAL",
    "VERTICAL"
  ),
  "thumbnail_alignment": enum(
    "LEFT",
    "RIGHT"
  ),
  "content": object(RichCardContent)
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘standalone_rich_card’ N/A N/A Yes
orientation string Orientation of the card No
Valid values:
  • HORIZONTAL
  • VERTICAL
Yes
thumbnail_alignment string Image preview alignment for cards with horizontal layout No
Valid values:
  • LEFT
  • RIGHT
Yes
content object(RichCardContent) Object describing the content of the rich card. No N/A Yes
CarouselRichCardMessage
JSON Representation
{
  "type": "carousel_rich_card",
  "width": enum(
    "SMALL",
    "MEDIUM"
  ),
  "contents": [
    object(RichCardContent), ...
  ]
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘carousel_rich_card’ N/A N/A Yes
width string The width of the cards in the carousel No
Valid values:
  • SMALL
  • MEDIUM
Yes
contents arrayOf(RichCardContent) The list of contents for each card in the carousel. There must be at least 2 and at most 10 cards in a carousel No MinLength: 2
MaxLength: 10
Yes
RichCardContent
JSON Representation
{
  // At least one of title, description and media must be specified
  "title": string,
  "description": string,
  "media": object(RichCardMedia),
  "suggestions": [
    {
      "type": enum(
        "reply",
        "action"
      )
      ... // type specific fields
    }
  ]
}
Fields
Field Type Description Default Constraints Required
title string Title of the card No MaxLength: 200 No
description string Description of the card No MaxLength: 2000 No
media object(RichCardMedia) Object describing the media to be included in the card No N/A No
suggestions
arrayOf:
List of suggestions to be included within the rich card No MaxLength: 4 No
RichCardMedia
JSON Representation
{
  "file": object(FileInfo),
  "thumbnail": object(FileInfo),
  "height": enum(
    "SHORT",
    "MEDIUM",
    "TALL"
  )
}
Fields
Field Type Description Default Constraints Required
file object(FileInfo) Object describing the media to be included in the card No N/A Yes
thumbnail object(FileInfo) Object describing the thumbnail of the media in the card. No N/A No
height string The height of the media within a vertically oriented rich card No
Valid values:
  • SHORT
  • MEDIUM
  • TALL
Yes
SuggestedReply
JSON Representation
{
  "type": "reply",
  "display_text": string,
  "postback": object(Postback)
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘reply’ N/A N/A Yes
display_text string The text that will be shown in the suggested reply No MinLength: 1
MaxLength: 25
Yes
postback object(Postback) Optional data that will be sent back to the agent when the user taps the reply No N/A No
SuggestedAction
JSON Representation
{
  "type": "action",
  "display_text": string,
  "postback": object(Postback),
  "action": {
    "type": enum(
      "dial_phone_number",
      "show_location",
      "request_location_push",
      "open_url",
      "create_calendar_event"
    )
    ... // type specific fields
  }
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘action’ N/A N/A Yes
display_text string The text that will be shown in the suggested action No MinLength: 1
MaxLength: 25
Yes
postback object(Postback) Optional data that will be sent back to the agent when the user taps the action No N/A No
action
oneOf:
Object defining the action No N/A Yes
DialPhoneNumber
JSON Representation
{
  "type": "dial_phone_number",
  "phone_number": string
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘dial_phone_number’ N/A N/A Yes
phone_number string The phone number to call No ^(?:00|+|)[1-9][0-9]{8,16}$ Yes
ShowLocation
JSON Representation
{
  "type": "show_location",
  "latitude": number,
  "longitude": number,
  "label": string
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘show_location’ N/A N/A Yes
latitude number Latitude No MinValue: -90
MaxValue: 90
Yes
longitude number Longitude No MinValue: -180
MaxValue: 180
Yes
label string Optional label to be shown on the map at the given lat/long No MaxLength: 1000 No
RequestLocationPush
JSON Representation
{
  "type": "request_location_push"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘request_location_push’ N/A N/A Yes
OpenUrl
JSON Representation
{
  "type": "open_url",
  "url": string
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘open_url’ N/A N/A Yes
url string The URL to open No URL - As defined by RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax, amended by RFC 2732: Format for Literal IPv6 Addresses in URLs. Yes
CreateCalendarEvent
JSON Representation
{
  "type": "create_calendar_event",
  "start_time": timestamp,
  "end_time": timestamp,
  "title": string,
  "description": string
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘create_calendar_event’ N/A N/A Yes
start_time string Start time of the event No A timestamp in RFC3339 UTC “Zulu” format Yes
end_time string End time of the event No A timestamp in RFC3339 UTC “Zulu” format Yes
title string The title of the event No MinLength: 1
MaxLength: 1024
Yes
description string Description of the event No MinLength: 1
MaxLength: 1024
Yes
Postback
JSON Representation
{
  "data": string
}
Fields
Field Type Description Default Constraints Required
data string Payload (base64 encoded) that will be sent back to the agent when the user taps the suggestion No MinLength: 1
MaxLength: 1024
Yes
ExpireInfo
JSON Representation
{
  "timeout": integer,
  "revoke": boolean
}
Fields
Field Type Description Default Constraints Required
timeout integer Expire the message after this many milliseconds. If fallback is configured for expiry, then the fallback message will be sent after this timeout. 172800000 (48h) Minimum: 1 No
revoke boolean Should the message be revoked when the timeout happens. If not, the message might still be delivered to the handset after the configured timeout. However, no further status updates will be sent by the system. true No No
FallbackInfo
JSON Representation
{
  "message": object(XmsBatchMessage)
  "conditions": object(FallbackConditions)
}
Fields
Field Type Description Default Constraints Required
message object(XmsBatchMessage) Object describing the SMS fallback message No No Yes
conditions object(FallbackConditions) Object describing when to use the fallback message No No No
FallbackConditions
JSON Representation
{
  "rcs_unavailable": {
    "enabled": boolean
  },
  "capability_unsupported": {
    "enabled": boolean
  },
  "expired": {
    "enabled": boolean
  },
  "agent_error": {
    "enabled": boolean
  }
}
Fields
Field Type Description Default Constraints Required
rcs_unavailable Object   No No No
rcs_unavailable.enabled boolean Trigger fallback if recipient does not have RCS support true No Yes
capability_unsupported Object   No No No
capability_unsupported.enabled boolean Trigger fallback if capability needed for sent message is not supported by the recipient true No Yes
expired Object   No No No
expired.enabled boolean Trigger fallback if the RCS message is not delivered in a timely manner - see expire in object(AgentMessage) object. true No Yes
agent_error Object   No No No
agent_error.enabled boolean Trigger fallback for any errors encountered, e.g., error from south bound service provider false No Yes
XmsBatchMessage
JSON Representation
{
  "type": enum(
    "mt_text",
    "mt_binary"
  )
  "from": string,
  "text": string,
  "udh": string
  "campaign_id": string,
  "delivery_report": enum(
    "none",
    "summary",
    "full",
    "per_recipient"
  ),
  "expire_at": timestamp,
  "callback_url": string
}
Fields
Field Type Description Default Constraints Required
from string Sender number No MinLength: 1
MaxLength: 128
Yes
type string Identifies the type of the message No
Valid types are:
  • mt_text
  • mt_binary
Yes
text string The message content. Normal text string for mt_text and Base64 encoded for mt_binary No MaxLength: 2000 Yes
udh string The UDH header of a binary message No ^[0-9a-fA-F]*$ No
campaign_id string The campaign/service ID this message belongs to. (Only applicable for the USA.) No MaxLength: 2000 No
delivery_report string Request delivery report callback. Note that delivery reports can be fetched from the SMS HTTP REST API regardless of this setting none
Valid types are:
  • none
  • summary
  • full
  • per_recipient
No
expire_at string If set the system will stop trying to deliver the message at this point 3 days A timestamp in RFC3339 UTC “Zulu” format No
callback_url string Override the default callback URL for this message No
  • MaxLength: 2048
  • URL - As defined by RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax, amended by RFC 2732: Format for Literal IPv6 Addresses in URLs.
No

Revoking a sent message

Revoke a previously sent message, not yet delivered to the user agent. If a message is delivered to the user agent shortly after a revoke request is initiated there is a possibility of receiving a delivered status report after sending the revoke request.

HTTP Request

DELETE /rcs/v1/{agent_id}/messsages/{message_id}

Path parameters

Field Type Description Default Constraints Required
agent_id string ID of the agent to be used No No Yes
message_id string ID of a previously sent message to be revoked No No Yes

Request Body

The request body is empty.

Response

200 OK

The message was successfully revoked.

The response body is empty.

404 Not found

Unable to revoke, the message_id provided is not known by the system

The reason for this can be:

  • The message has already been delivered
  • The message_id provided is not known by the system

The response body will contain an Error object further describing the error.

409 Conflict

Unable to revoke, the message is in a state where is cannot be revoked.

The response body will contain an Error object further describing the error.

Examples
Revoking a message
curl https://api.clxcommunications.com/rcs/v1/my-agent-id/messages/2bf270e4-08a4-409b-8e0f-85293f6d1709 \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zIMEJGfwD4oJ4qObPPjwZxwiP5cKARXRJpt9Kf6GSv7uOesvRV" \

Agent event endpoint

The agent event endpoint provides operations for sending events from the agent to the user.

Sending agent events to user

Send events to a user from the agent. This enables the agent to emulate real user behavior by sending displayed notifications and composing events.

HTTP Request

POST /rcs/v1/{agent_id}/events

Path parameters

Field Type Description Default Constraints Required
agent_id string ID of the agent to be used No No Yes

Request Body

The request body contains an instance of AgentEvent.

Response

200 OK

The event was successfully sent.

502 Bad gateway

Unable to send event due to issue with service provider / operator, please retry.

Examples
Sending a composing event
curl https://api.clxcommunications.com/rcs/v1/my-agent-id/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zIMEJGfwD4oJ4qObPPjwZxwiP5cKARXRJpt9Kf6GSv7uOesvRV" \
  -d '{
    "to": "46555123456",
    "event_id": "ce5f9373-8a77-45fa-a78b-84a931005dc9",
    "event": {
      "type": "agent_composing"
    }
  }'
Sending a read event
curl https://api.clxcommunications.com/rcs/v1/my-agent-id/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zIMEJGfwD4oJ4qObPPjwZxwiP5cKARXRJpt9Kf6GSv7uOesvRV" \
  -d '{
    "to": "46555123456",
    "event_id": "ce5f9373-8a77-45fa-a78b-84a931005dc9",
    "event": {
      "type": "agent_read",
      "message_id": "Jsiuh76sJKAhdsiufg86823"
    }
  }'

JSON Model

AgentEvent
JSON Representation
{
  "to": string,
  "event_id": string,
  "event": {
    "type": enum(
      "agent_composing"
      "agent_read"
    )
    ... // type specific fields
  }
}
Fields
Field Type Description Default Constraints Required
to string MSISDN of the recipient No ^(?:00|+|)[1-9][0-9]{8,16}$ Yes
event_id string Globally unique event ID No ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ Yes
event
oneOf:
Object describing the event to send to the user No N/A Yes
AgentComposingEvent
JSON Representation
{
  "type": "agent_composing"
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘agent_composing’. This type notifies the recipient that the agent is typing N/A N/A Yes
AgentReadEvent
JSON Representation
{
  "type": "agent_read",
  "message_id": string
}
Fields
Field Type Description Default Constraints Required
type string Static string ‘agent_read’. This type notifies the recipient that the message sent by the user has been read by the agent N/A N/A Yes
message_id string The message id that the agent has read. This is the message id the agent received in object(UserAgentMessage) N/A N/A Yes