Send an RCS Message

To send an RCS message you'll send a request to our Invoke API. Within the request you can customize the information you send to your end users. In addition, you can specify whether to fall back to SMS if we determine that the device for a destination phone number does not support RCS.

See Invoke API Parameters for the information you need to build your own RCS message.

Note: If you have media files that you want to store in OpenMarket's Content Management System (CMS), use our Media Upload API to upload your files to our CMS.

Quick facts

Method

POST

Returns

Rejected response only: JSON

Available

All regions

Prerequisites

You must have RCS messaging provisioned with OpenMarket, and the following role set in your user account:

  • Invoke API

Request URL Definition

POST https://message.openmarket.com/service/v1/invokeService/<serviceId>

URL example 

https://message.openmarket.com/service/v1/invokeService/F9E8D7C6B5A4

Query parameters

Parameters must be URL encoded.

Parameter

Description

serviceId

The unique identifier identifying the RCS service. Your account manager can provide a serviceId once the RCS service is provisioned in OpenMarket.

Type: string

Required: Yes

Header fields

You must provide your authentication details using Basic authentication in the header. You should also specify that the content-type is JSON. For example:

POST /service/v1/invokeService/F9E8D7C6B5A4 HTTP/1.1
Host: message.openmarket.com
Content-Type: application/json
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Field

Description

Authorization

Your account ID and password, separated by a colon, and then base64 encoded. Your account ID and password are case-sensitive. For help with Basic authentication see Authenticate with OpenMarket.

Content-Type

Specify application/json for these requests.

RCS schema

The RCS schema is composed of an endUser parameter and a variables object. The endUser parameter sets the recipient phone number. Under variables you'll define the request object of your RCS message. These will be the values for one or more types of RCS message you're sending to an end user: text, media, and/or richCard. Lastly, you can include an optional sms element. In the event that the recipient's handset does not support RCS, the sms element will instead send a standard SMS to the end user. For more details about formatting the request using Invoke API, see Invoke API Parameters.

Here is the basic RCS schema, including the optional sms element:

Basic RCS schema

{
  "endUser": {
    "phoneNumber": "<number>"
  },
  "variables": {
    "request": {
      "rcs": {
        "text": "<value>",
        "media": "<value>",
        "richCard": "<value>"
      },
      "sms": {
        "messageContent": "<value>"
      }
    }
  }
}

Accepted requests

OpenMarket responds to a successful request with a status code of 202.

Note: The API will accept requests with any correctly formatted service ID (and request header/body).

The response header contains an X-Request-Id. This uniquely identifies the request with our support team. Please include this ID in any request to OpenMarket Support where referencing an issue with a specific invoke request.

HTTP/1.1 202 OK
Date: Tue, 15 Feb 2018 16:14:43 GMT
X-Request-Id: 012-W010K-123AB-456CD-789EF-PSI