Profiles

Basic guide on requesting an RCS profile with the Channels API.

Preface

RCS is an OTT Channel. This guide describes the RCS specific endpoints you use to create an RCS profile and provide the information it needs. It assumes you already have a Channel request for RCS. Creating a Channel request is part of the generic OTT Channel onboarding flow and is not covered here.

All RCS specific endpoints follow the pattern:

/channels/v1/accounts/{accountId}/rcs/{channelRequestId}/...

Before you start

You need:

• Your account ID and product token. See Authentication to find them. Every request in this guide must include your product token in the X-CM-PRODUCTTOKEN header.
• The Channel type identifier (channelTypeId) of RCS. Get all Channel types and use the GUID of the RCS Channel type.
• The Channel type category identifier (channelTypeCategoryId) of the RCS Profile category. A Channel type is divided into categories, and the request form is retrieved per category. Get the Channel type categories of the RCS Channel type and use the GUID of the Profile category.
• The Channel request identifier (channelRequestId) of your existing RCS Channel request.

📘

The Channel type and category identifiers are constant

channelTypeId and channelTypeCategoryId do not change. Retrieve them at least once as described above, after which you can store them and reuse them for all later requests.

📘

Note

All examples use the base URL https://api.cm.com. Replace the placeholders in curly braces with your own values.

How the request form works

The information required to request an RCS profile is described by the request form of the Channel type. The request form:

• returns the fields that are required,
• indicates when all required fields have been provided.

The set of fields is dynamic. Fields can be added or removed based on the input you have already provided. For this reason, the request form is both where the process starts and where it ends:

1. Call the request form to see which fields are required.
2. Save data (create the profile, add form input).
3. Call the request form again after every save to get the updated set of required fields.
4. Repeat steps 2 and 3 until the request form indicates that all required fields are provided.

🚧

Call the request form after every save

Do not rely on a field list you retrieved earlier. Providing a value can change which fields are required, so always read the request form again after saving.

To retrieve the request form of the RCS profile you always provide the channelTypeCategoryId of the Profile category. In addition, because the required fields depend on what you have already provided, the request form needs to know which input to look at. You do this by passing the channelCategoryRequestId. For RCS this is the identifier of the profile you create in step 2.

🚧

Always pass the channelCategoryRequestId once you have a profile

Without it the request form cannot refer to your previous input, so it will never be returned as completed. The only call without it is the first one, made before the profile exists.

Request an RCS profile

Step 1: Get the request form

Retrieve the request form for the RCS Channel type.

GET https://api.cm.com/channels/v1/accounts/{accountId}/channels/types/{channelTypeId}/requestform

Path parameters

Query parameters

Example request

The first call, before the profile exists:

curl --request GET \
  --url 'https://api.cm.com/channels/v1/accounts/{accountId}/channels/types/{channelTypeId}/requestform?channelTypeCategoryId={channelTypeCategoryId}' \
  --header 'X-CM-PRODUCTTOKEN: {productToken}' \
  --header 'accept: application/json'

Every call after the profile has been created:

curl --request GET \
  --url 'https://api.cm.com/channels/v1/accounts/{accountId}/channels/types/{channelTypeId}/requestform?channelTypeCategoryId={channelTypeCategoryId}&channelCategoryRequestId={profileId}' \
  --header 'X-CM-PRODUCTTOKEN: {productToken}' \
  --header 'accept: application/json'

Response

The response lists the fields that are required and indicates whether all required fields have been provided. Without a channelCategoryRequestId the form is never returned as completed.

For the full response body, see the Get the request form API reference.

Step 2: Create the profile

Create a new RCS profile for your Channel request.

POST https://api.cm.com/channels/v1/accounts/{accountId}/rcs/{channelRequestId}/profiles

Path parameters

This endpoint does not require a request body.

Example request

curl --request POST \
  --url 'https://api.cm.com/channels/v1/accounts/{accountId}/rcs/{channelRequestId}/profiles' \
  --header 'X-CM-PRODUCTTOKEN: {productToken}' \
  --header 'accept: application/json'

Response

A successful request returns 201 Created.

For the full response body, see the Create an RCS profile API reference.

Keep the identifier of the created profile. You pass it as the channelCategoryRequestId on every request form call from now on, and you need it as profileId in the next step.

Now get the request form again, this time also with the profile's identifier as channelCategoryRequestId, to see which fields are required.

Step 3: Add the form input

Add the form input that belongs to the profile you just created. Provide values for the fields the request form returned as required.

PUT https://api.cm.com/channels/v1/accounts/{accountId}/rcs/{channelRequestId}/profiles/{profileId}/forminput

Path parameters

Request body

The body contains the form input. The endpoint accepts application/json (default), text/json, text/xml, multipart/form-data and application/x-www-form-urlencoded.

Example request

curl --request PUT \
  --url 'https://api.cm.com/channels/v1/accounts/{accountId}/rcs/{channelRequestId}/profiles/{profileId}/forminput' \
  --header 'X-CM-PRODUCTTOKEN: {productToken}' \
  --header 'content-type: application/json' \
  --header 'accept: application/json' \
  --data '{
    "<input key>": "<value>"
  }'

Response

A successful request returns 202 Accepted. See the Adds the profile form input API reference.

Step 4: Check the request form again

After every save, call the request form from step 1 again, with the channelTypeCategoryId and the profile's identifier as channelCategoryRequestId.

• If the response lists required fields that are not provided yet, return to step 3 and add them. Fields can appear or disappear as you save, so provide whatever the latest response lists.
• If the response indicates that all required fields are provided, the form is complete and your RCS profile request has everything it needs.

Review your request

You can read back what you submitted:

• Get the profile
• Get the profile form input
• Get the Channel request

Summary

What's Next

• Get the request form - API reference
• Create an RCS profile - API reference
• Add the profile form input - API reference