Send a Plain Text Message with ChipList

POST Method

The Send a Plain Text Message with ChipList API request allows you to send a plain text message accompanied by a chiplist—a set of interactive buttons that can either trigger a reply or open a URL. This format is ideal for enhancing user interaction by offering quick responses or actionable links directly within the message.

Prerequisites

After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in kaleyra.io.
Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
Before sending the RCS, you must configure the RCS channel in the Kaleyra platform. To configure the RCS channel in your account, please contact your local Kaleyra representative.

You must have an approved AgentID or a specific number to be used as AgentID.

Base URL

https://rcs-api.<pod>.kaleyra.ai - For North America (NA).

https://rcs-api.<pod>.kaleyra.io - For rest of the world.

API Domain and Value

api_domain	Value
IN pod	https://rcs-api.in.kaleyra.io
NA pod	https://rcs-api.na.kaleyra.ai

API request to send a Plain Text Message with ChipList

To send a plain text message with cliplist, use the https://rcs-api.<pod>.kaleyra.ai/v1/<sid>/rcs/messages endpoint with the following request method:

Request Format

The following is the request format to send a plain text message with cliplist:

curl --location --request POST 'https://<api_domain>/v1/<sid>/rcs/messages'\
--header 'Content-Type:<Content-Type>' \
--header 'api-key: <api-key>' \
--data { 
  "from": "<from>", 
  "to": [ 
    "<to>" 
  ], 
  "text": "<text>", 
  "suggestions": [ 
    { 
      "reply": { 
        "text": "<text>", 
        "postbackData": "<postbackData>", 
        "buttonId": "<buttonId>" 
      } 
    }, 
    { 
      "action": { 
        "text": "<text>", 
        "postbackData": "<postbackData>", 
        "openUrlAction": { 
          "url": "<url>"  
        } 
      } 
    } 
  ] 
}

Sample Request Format

The following is the sample request format to send a plain text message with cliplist:

curl --location --request POST 'https://rcs-api.na.kaleyra.ai/v1/xxxxx6913850xxxx/rcs/messages’ \
--header 'Content-Type: application/json' \ 
--header 'api-key: xxxxx3b8497f58a94e84b671aca43xxxx' \ 
--data {
  "from": "rcs-test",
  "to": ["9191588XXXXX"],
  "text": "Welcome to Tata Communications.",
  "suggestions": [
    {
      "reply": {
        "text": "Thank you!",
        "postbackData": "more_info",
        "buttonId": "01"
      }
    },
    {
      "action": {
        "text": "Visit Website",
        "postbackData": "tata_comm_website",
        "openUrlAction": {
          "url": "https://www.tatacommunications.com/"
        }
      }
    }
  ]
}

URL Parameters and Headers

The following is the list of parameters and headers to send the outgoing message request:

Parameter/Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	xxxxx6913850xxxx	Yes
`Content-Type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/JSON	Yes
`api-key`	String	API key generated from kaleyra.io account.	xxxxx3b8497f58a94e84b671aca43xxxx	Yes

Following is the list of attributes to be used in the payload to send the messages:

Parameter	Data Type	Description	Example	Mandatory?
`from`	String	The service code unique to the RCS agent, specified when the RCS agent is created or onboarded. You can contact the RCS Provisioning Team for more details on unique service code.	rcs-test	Yes
`to`	Array of String	List of recipients’ device addresses (up to 100 allowed), a phone number in E.164 format prefixed with the country code without a plus sign used to contact the user.	["9191588XXXXX"]	Yes
`text`	String	Text message content, encoded in UTF-8 (2000 Unicode characters max.)	Welcome to Tata Communications. Visit https://...	Yes
`suggestions`	JSON Object	List of suggestions comprised of suggested reply and suggested action chips the users can click on (11 chips max.).	See the specific table for details.	No

The following table describes the different attributes used for the suggestions JSON object:

Parameter	Data Type	Description	Example	Mandatory?
`reply`	JSON Object	Contains the details of the reply chip.	See the specific table for details.	No
`action`	JSON Object	Contains the details of the action chip.	See the specific table for details.	No

The following table describes the different attributes used for the reply JSON object:

Parameter	Data Type	Description	Example	Mandatory?
`text`	String	Text displayed on the reply chip.	Thank you!	Yes (if reply)
`postbackData`	String	Data sent back to your system when the reply chip is clicked.	more_info	Yes (if reply)
`buttonId`	String	Identifier for the reply button.	01	No

The following table describes the different attributes used for the action JSON object:

Parameter	Data Type	Description	Example	Mandatory?
`text`	String	Text displayed on the action chip.	Visit Website	Yes (if action)
`postbackData`	String	Data sent back to your system when the action chip is clicked.	tata_comm_website	Yes (if action)
`openUrlAction`	JSON Object	Contains the URL to be opened when the action chip is clicked.	See the specific table for details.	Yes (if action)

The following table describes the different attributes used for the openUrlAction JSON object:

Parameter	Data Type	Description	Example	Mandatory?
`url`	String	A URL, as defined by RFC 2396 (4000 Unicode characters max.)	https://www.tatacommunications.com/	Yes (if action)

Sample Success Response

The following success message appears:

{
  "recipientDetails": [
    {
      "to": "9191588XXXXX",
      "messageId": "dc4cxxxx-xxxx-xxxx-xxxx-xxxx349a5e3d "
    }
  ]
}

Sample Failure Response

The following failure message appears:

{
    "status": "ERROR",
    "errorText": "Error Message"
}

Updated about 8 hours ago