Launch an Agent

POST Method

The Launch Agent API allows you to submit RCS agents automatically for official launch across one or more carrier networks.

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.
To send any RCS messages, you must configure the RCS channel in the Kaleyra platform. To configure the RCS channel in your account, please contact your local Kaleyra representative.

Base URL

https://rcs-api.<pod>.kaleyra.io/v1/<sid>

API Domain and Value

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

API request to Launch an Agent

To launch an agent, use the https://rcs-api.<pod>.kaleyra.io/v1/<sid>/rcs/agent/launch endpoint with the following request method:

Request Format

The following is the request format to launch an agent.

curl --location --request POST 'https://<api_domain>/v1/<sid>/rcs/agent/launch'\
--header 'Content-Type: <content_type>' \
--header 'api-key: <api-key>' \
--data '{
    "launch": {
        "optin_description": "<optin_description>",
        "trigger_description": "<trigger_description>",
        "interactions_description": "<interaction_description>",
        "optout_description": "<optout_description>",
        "agent_access_instructions": "<agent_access_instructions>",
        "provider_launch_id": "<provider_launch_id>",
        "launch_name": "<launch_name>",
        "launch_type": "<launch_type>",
        "video_uris": [
            "<video_uris>"
        ],
        "screenshot_uris": [
            "<screenshot_uris>"
        ],
        "agent_no": "<agent_no>"
    },
    "regions": [
        {
            "region_id": "<region_id>",
            "region": "<region>"
        }
    ]
}'

Sample Request Format

The following is the sample request format to launch an agent.

curl --location --request POST 'https://rcs-api.na.kaleyra.io/v1/xxxxx6913850xxxx/rcs/agent/launch' \
--header 'Content-Type: application/json' \
--header 'api-key: xxxxx3b8497f58a94e84b671aca43xxxx ' \
--data '{
    "launch": {
        "optin_description": "Bigbasket Optin",
        "trigger_description": "START",
        "interactions_description": "Demo Messages",
        "optout_description": "Stop",
        "agent_access_instructions": "This is a demo account",
        "provider_launch_id": "launch_001_google_rcs",
        "launch_name": "launch_48900",
        "launch_type": "1",
        "video_uris": [
            "https://www.example.com/videos"
        ],
        "screenshot_uris": [
            "https://www.example.com/uris"
        ],
        "agent_no": "48900"
    },
    "regions": [
        {
            "region_id": "8346a250-d7a9-47dc-8202-a8XXXXXXXXe8",
            "region": "4f4bf2b0-5110-44e1-9aa1-43XXXXXXXX39"
        }
    ]
}'

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

The following is the list of attributes to be used in the payload to launch an agent:

Parameter	Data Type	Description	Example	Mandatory?
`launch`	JSON object	Object encapsulates all necessary details for launching an RCS Business Messaging agent.	See the specific table for details.	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`optin_description`	String	A short explanation on how end users give consent to interact with your agent.	Bigbasket Opt in	Yes
`trigger_description`	String	Explain when or how the conversation is initiated.	START	Yes
`interactions_description`	String	A description of what type of interaction the agent supports.	Demo Messages	Yes
`optout_description`	String	Instructions on how you can stop receiving messages.	Stop	Yes
`agent_access_instructions`	String	Detail on how reviewers or carriers can access or test your agent during verification.	This is a demo account	Yes
`provider_launch_id`	String	A unique identifier assigned by the carrier or Google when the agent is submitted for launch used for tracking.	launch_001_google_rcs	Optional
`launch_name`	String	The unique name for the launch instance.	launch_48900	Optional
`launch_type`	String	Defines the type of launch. Determines who approves and controls the rollout. Default is set to 1.	1	Yes
`video_uris`	JSON Object	The Video link (a unique identifier) that tells a system where a video is located so it can be accessed, streamed, or downloaded.	See the specific table for details.	Optional
`screenshot_uris`	JSON Object	The screenshot link (a unique identifier) that tells a system where a screenshot is located so it can be accessed, streamed, or downloaded.	See the specific table for details.	Optional
`agent_no`	String	Internal agent identifier or sequence number.	48900	Yes
`regions`	JSON Object	List of carrier regions where the agent will be launched.	See the specific table for details.	Optional

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

Parameter	Data Type	Description	Example	Mandatory?
`uris`	String	URLs pointing to demo videos that showcase how the agent works. Used during review.	`https://www.example.com/video`	Optional

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

Parameter	Data Type	Description	Example	Mandatory?
`uris`	String	URLs pointing to the screenshots of the agent's user experience. Required for verification and carrier approval.	`https://www.example.com/uri`	Optional

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

Parameter	Data Type	Description	Example	Mandatory?
`region_id`	UUID	A unique identifier that represents specific launch region. Note: You can launch 5 agents at a time during launch.	8346a250-d7a9-47dc-8202-a8XXXXXXXXe8	Optional
`region`	String	List of carrier regions where the agent will be launched.	4f4bf2b0-5110-44e1-9aa1-43xxxxxxxx39	Yes

Sample Success Response

The following is the sample success response:

{
  "code": "RCS902",
  "message": "Agent launch request created successfully",
	{
    "launch": {
        "provider_launch_id": "launch_001_google_rcs",
        "launch_name": "launch__48900",
        "launch_type": 1,
        "optin_description": "Bigbasket Optin",
        "trigger_description": "START",
        "interactions_description": "Demo Messages",
        "optout_description": "Stop",
        "agent_access_instructions": "This is a demo account",
        "video_uris": [
            "https://www.example.com/videos"
        ],
        "screenshot_uris": [
            "https://www.example.com/uris"
        ],
        "status": "ACTIVE",
        "create_date": "Jan 12, 2026, 12:42:58 PM",
        "modified_date": "Jan 12, 2026, 12:42:58 PM",
        "agent_launch_id": "1370ed9d-53ed-47ec-b150-e2XXXXXXXX3d"
    },
    "regions": [
        {
            "region_id": "8346a250-d7a9-47dc-8202-a8XXXXXXXXe8",
            "region": "4f4bf2b0-5110-44e1-9aa1-43392c7d3b17",
            "entry_point": 0,
            "launch_state": 0,
            "dirty_flag": "NEW"
        }
    ],
    "contacts": []
},
"error": {}
}

Sample Failure Responses

The following are the sample failure responses:

Missing Required Fields

{
  "code": "RCS904",
  "message": "Failed to create Agent launch request",
  "data": [],
  "error": {
    "error_code": "PROV_ERROR",
    "error_message": "{\"status\":\"FAILED\",\"message\":\"Missing required fields in launch payload\"}"
  }
}

Invalid JSON

{
  "code": "RCS701",
  "message": "Invalid json format passed",
  "data": [],
  "error": {
    "error_code": "INVALID_JSON_PAYLOAD",
    "error_message": "invalid character '}' looking for beginning of object key string"
  }
}

RCS Not Enabled

{
  "code": "RCS601",
  "message": "RCS Channel is not enabled for this User",
  "data": [],
  "error": {
    "error_code": "RCS_CHANNEL_DISABLED",
    "error_message": "RCS Channel is not enabled for this User"
  }
}

Method Not Allowed

{
  "code": "RCS405",
  "message": "Method not allowed",
  "data": [],
  "error": {
    "error_code": "METHOD_NOT_ALLOWED",
    "error_message": "Method not allowed"
  }
}

Gateway Error

{
  "code": "RCS502",
  "message": "Internal Gateway Error",
  "data": [],
  "error": {
    "error_code": "RCS_CHANNEL_INTERNAL_ERROR",
    "error_message": "Internal Gateway Error"
  }
}

Updated about 1 month ago