Launch Carrier

POST Method

The Launch Carrier API allows you to interact with and manage carrier-specific functionalities related to RCS services on a device.

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 Launch a Carrier

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

Request Format

The following is the request format to launch a carrier:

curl --location --request POST 'https://<api_domain>/v1/<sid>/rcs/agent/carrierlaunch'\
--header 'api-key: <api-key>' \
--header 'Content-Type: <content-type>' \
--data '{
    "agent_no":"<agent_no>",
    "agent_launch_id":"<agent_launch_id>",
    "regions": [
        {
            "region_id": "<region_id>",
            "region": "<region>"
        }
    ]
}'

Sample Request Format

The following is a sample request format to launch a carrier:

curl --location --request POST 'https://rcs.api.na.kaleyra.io/v1/xxxxx6913850xxxx/rcs/agent/carrierlaunch'\
--header 'api-key: xxxxx3b8497f58a94e84b671aca43xxxx' \
--header 'Content-Type: application/json' \
--data '{
    "agent_no":"2600",
    "agent_launch_id":"5daXXXXX-6340-4226-b846-f4XXXXXXc543",
    "regions": [
        {
            "region_id": "cbaXXXXX-c136-4XXb-a391-f7c27cXXXXX0",
            "region": "United States (US)"
        }
    ]
}'

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 a list of attributes to be used in the payload to launch a carrier:

Parameter	Data Type	Description	Example	Mandatory?
`agent_no`	String	Internal agent identifier or sequence number. In response of agent creation, you can get the ID by using the Get by Agent or Get by Agent Number.	2600	Yes
`agent_launch_id`	String	Auto-generated number by the server after successfully launching an agent request. To get all the identifiers, you need to call "Fetch Region" API and get this Region id and carrier name.	5daXXXXX-6340-4226-b846-f4XXXXXXc543	Yes
`regions`	JSON Object	List of carrier regions where the agent will be launched. customer can provide multiple carriers request up to a maximum of 5 per launch.	See the specific table for details.	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 a specific launch region.	cbaXXXXX-c136-4XXb-a391-f7c27cXXXXX0	Optional
`region`	String	The human-readable name of the region where the agent will be launched.	United States (US)	Optional

Sample Success Response

The following is a sample success response:

{
  "code": "RCS902",
  "message": "Agent launch request created successfully",
  "data": { 
    "agent_no":"2600", 
    "agent_launch_id:”5daXXXXX-6340-4226-b846-f4XXXXXXc543 ",
    "regions": [ 
        { 
            "region_id": "cbaXXXXX-c136-4XXb-a391-f7c27cXXXXX0", 
            "region": "United States (US)", 
            "entry_point": 0, 
            "launch_state": 0, 
            "dirty_flag": "NEW" 
        } 
    ], 
    "contacts": [] 
},
  "error": {}
}

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 24 days ago