Get Launch Status

GET Method

The Get Launch Details API allows you to get the agent details based on agent number and agent launch ID. The launch details can be for Business Message Agent (BMA) or RCS Business Message Agent (RBMA).

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.

Base URL

URL	Region
`https://rcs-api.<pod>.kaleyra.io`	For North America (NA).
`https://rcs-api.<pod>.kaleyra.io`	For the 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.io`

API request to get an Agent Launch Details

To get an agent launch details, use the https://rcs-api.<pod>.kaleyra.io/v1/<sid>/rcs/agentlaunchstatus?agent_number=<agent_number>&agent_launch_id=<agent_launch_id>' endpoint with the following request method:

Request Format

The following is the request format to get an agent launch details:

curl --location 'https://<api_domain>/v1/<sid>/rcs/agent/agentlaunchstatus?agent_number=<agent_number>&agent_launch_id=<agent_launch_id>'\
--header 'Content-Type: <content_type>' \
--header 'api-key: <api-key>'

Sample Request Format

The following is the sample request format to get an agent launch details:

curl --location 'https://rcs.api.<pod>.kaleyra.io/v1/xxxxx6913850xxxx/rcs/agent/agentlaunchstatus?agent_number=94xx0&agent_launch_id=c6xxxx89-1xx9-4xx7-axxc-80xxxxxxxxb5'\
--header 'Content-Type: application/json' \
--header 'api-key: xxxxx3b8497f58a94e84b671aca43xxxx'

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 get an agent launch details:

Parameter	Data Type	Description	Example	Mandatory?
`agent_number`	String	Auto generated number by the server after successfully sending the create agent request. Agent identifier	94xx0	Yes
`agent_launch_id`	String	Auto generated number by the server after successfully launching an agent request. Launch identifier	c6xxxx89-1xx9-4xx7-80xxxxxxxxb5	Yes

Sample Success Response

The following is a sample success response:

{
  "code": "RCS902",
  "message": "Agent launch request fetched successfully",
  "data": {
   "launch":{
        "optin_description": "you can opt in through the website https://www.XXXXd.com/contact-us-dotgo by submitting their details to connect with the Dotgo RCS Bot",
        "trigger_description": "you can trigger the agent by clicking on the Connect Me button and signing up on the portal https://dotXX.com.",
        "interactions_description": "Dotgo Bot helps users explore RCS features, check device compatibility, and learn to share media, use suggestions, and interact via rich cards and GIFs.",
        "optout_description": "Sorry to see you leave. You will no longer receive notifications from this agent on RCS. To start receiving notifications on RCS again, send ‘START’.",
        "agent_access_instructions": "Reviewers can trigger the agent via a test number. Contact [email protected] to add devices or get keywords.",
        "provider_launch_id": "",
        "launch_name": "launch__16800_130XXXXX",
        "launch_type": "1",
        "video_uris": [
            "https://www.example.com/video"
        ],
        "screenshot_uris": [
            "https://www.example.com/uri"
        ],
        "agent_no": "{{agent_number}}"
    },
    "regions": [
       {
            "region_id": "74cXXXXe-decd-4fac-b1c1-b6822ac9635c",
            "region": "9dXXX8ac-1c03-4466-9d1c-bf2XXXXXXXXb"
        },
         {
            "region_id": "74cXXXXe-decd-4fac-b1c1-b6822ac9635c",
            "region": "4721XXXf-8f73-4503-a611-75XXXXXXXXa1"
        },
         {
            "region_id": "74cXXXXe-decd-4fac-b1c1-b6822ac9635c",
            "region": "d1b7XXX2-69b9-463f-aff2-078fXXXXXXXX"
        }

    ]
}

Integration Exception Note:

The launch request failed due to missing brand verification details (email, contact name, website URL, or contracts). Brand verification must be completed before attempting the launch.

Parameters and Descriptions for Success Response

The following are the parameters and descriptions for success response:

Parameter	Description	Example	Data Type	Mandatory?
`providerLaunchId`	A unique identifier assigned by the carrier or Google when the agent is submitted for launch. Used for tracking.		String	Optional
`launchName`	The unique name for this launch instance.	launch__16800_130XXXXX	String	Optional
`launchType`	Defines the type of launch. Determines who approves and controls the rollout.	1	String	Optional
`optinDescription`	A short explanation of how users give consent to interact with your agent.	you can opt in through the website https://www.XXXXd.com/contact-us-dotgo by submitting their details to connect with the Dotgo RCS Bot.	String	Optional
`triggerDescription`	Explains when or how the conversation is initiated with users.	you can trigger the agent by clicking on the Connect Me button and signing up on the portal https://dotXX.com.	String	Optional
`interactionsDescription`	A description of what type of interactions the agent supports.	Dotgo Bot helps users explore RCS features, check device compatibility, and learn to share media, use suggestions, and interact via rich cards and GIFs.	String	Optional
`optoutDescription`	Instructions for how users can stop receiving messages.	Sorry to see you leave. You will no longer receive notifications from this agent on RCS. To start receiving notifications on RCS again, send ‘START’.	String	Optional
`agentAccessInstructions`	Details on how reviewers or carriers can access or test your agent during verification.	Reviewers can trigger the agent via a test number. Contact [email protected] to add devices or get keywords.	String	Optional
`videoUris`	URLs pointing to demo videos that showcase how the agent works. Used during review.	`https://www.example.com/video`	String	Optional
`screenshotUris`	URLs pointing to screenshots of the agent’s user experience. Required for verification and carrier approval.	`https://www.example.com/uri`	String	Optional
`agent_no`	The phone number or messaging identifier associated with the agent used for communication with end users.	+155XXXXXXXX	String	Optional
`regionId`	A UUID that represents a specific launch region.	74cXXXXe-decd-4fac-b1c1-b6822ac9635c	UUID	Optional
`region`	The human-readable name of the region where the agent will be launched.	9dXXX8ac-1c03-4466-9d1c-bf2XXXXXXXXb	String	Optional

Sample Failure Responses

The following are the sample failure responses:

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 5 hours ago