Create an Agent

POST Method

The Create an Agent API allows you to create and register a new agent profile within the RCS messaging platform. The agent is responsible for a conversational entity representing a brand. It can be either 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 create an Agent

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

Request Format

The following is the request format to create an agent:

curl --location --request POST 'https://<api_domain>/v1/<sid>/rcs/agent'\
--header 'Content-Type: <content_type>' \
--header 'api-key: <api-key>' \
--data-raw '{
				"agent_type": "<agent_type>",
 				"display_name": "<display_name>",
				"logo_url": "<logo_url>",
				"hero_url": "<hero_url>",
				"default_locale": "<default_locale>",
				"agent_test_url": "<agent_test_url>",
				"end_point_config": "<end_point_config>",
				"primary_interaction_type": "<primary_interaction_type>",
				"service_code": "<service_code>",
				"description": "<description>",
				"phones": [                                
				{
					"is_toll_free": <is_toll_free>,
          "number": "<number>",
					"country_code": "",
					"label_text": "<label_text>"
				}
				],
				"emails": [                               
				{
					"is_primary": <is_primary>,
					"email": "<email>",
					"label_text": "<label_text>"
				}
				],
				"privacy": {                               
					"website": "<website>",
      		"label_text": "<label_text>"
				},
				"terms_conditions": {                      
				"website": "<website>",
				"label_text": "<label_text>"
				},
				"color": "<color>",
				"billing_category": "<billing_category>",
				"agent_use_case": "<agent_use_case>",
				"hosting_region": "<hosting_region>",
				"languages": ["<languages>"],
				"rcs_provider_id": "<rcs_provider_id>",
				"website": [
				{
					"website": "<website>",
					"label_text": "<label_text>"
				}
				],
				"brand_details": {
				"brand_name": "<brand_name>",
				"brand_no": "<brand_no>",
				"provider_brand_no": "<provider_brand_no>"
				}
			}'

Sample Request Format

The following is the sample request format to create an agent:

curl --location --request POST 'https://rcs-api.in.kaleyra.io/v1/XXXXX6913850XXXX/rcs/agent'\
--header 'Content-Type: application/json' \
--header 'api-key: XXXXX3b8497f58a94e84b671aca43XXXX' \
--data-raw '{
    "agent_type": "1",
    "display_name": "Basket Agent",
    "logo_url": "https://d2lXXXXXf347r.net/1752750287913-TC_Small_logo_(224_x_224)_1.png",
    "hero_url": "https://d2lXXXXXXf347r.net/1752750253172-TC_Banner_Image.jpg",
    "default_locale": "en",
    "agent_test_url": "http://wwww.basket.com",
    "end_point_config": "NON_LOCAL",
    "primary_interaction_type": "INTERACTION_TYPE_UNSPECIFIED",
    "service_code": "rcs-bigbasket",
    "description": "This is a dummy agent for RCS",
    "phones": [
        {
            "label_text": "call",
            "is_toll_free": true,
            "country_code": "",
            "number": "18001001001"
        }
    ],
    "emails": [
        {
            "label_text": "email",
            "is_primary": true,
            "email": "[email protected]"
        }
    ],
    "privacy": {
        "label_text": "Privacy",
        "website": "https://www.tatacomm.com/privacy"
    },
    "terms_conditions": {
        "label_text": "tnc",
        "website": "https://www.tatacomm.com/tnc"
    },
    "color": "#494e0d",
    "billing_category": "SINGLE_MESSAGE",
    "agent_use_case": "MULTI_USE",
    "hosting_region": "ASIA_PACIFIC",
    "status": "ACTIVE",
    "languages": [
        "English",
        "Hindi"
    ],
    "rcs_provider_id": "1",
    "website": [
        {
            "label_text": "company",
            "website": "https://www.tatacomm.com"
        }
    ],
    "brand_details": {
        "brand_no": "8032", 
        "provider_brand_no": "",
        "brand_name": ""
    }
}'

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 create an agent:

Parameter	Data Type	Description	Example	Mandatory?
`agent_type`	String	Business messaging agent (BMA) or RCS Business Messaging (RCBM). The `agent_type` supports the following values: 1 2	1	Yes
`display_name`	String	Name that will appear for the agent. Allowed values: Any non-empty string.	Basket Agent	Yes
`logo_url`	String	URL of the logo. Must be a valid image URL - should end with - png, jpg, and jpeg.	`https://d2lXXXXXf347r.net/1752750287913-TC_Small_logo_(224_x_224)_1.png`	Yes
`hero_url`	String	Publicly available URL of the hero image for the agent. Must be a valid image URL - should end with - png, jpg, and jpeg. Note: After the agent is verified, it cannot be modified.	`https://d2lXXXXXXf347r.net/1752750253172-TC_Banner_Image.jpg`	Yes
`default_locale`	String	Default locale for the agent. By default, `default_locale` is set to "en".	"en"	No
`agent_test_url`	String	Test URL for the agent (must start with https://www). Allowed value is URL.	`http://wwww.basket.com`	No
`end_point_config`	Integer	Defines the end point configuration of the RCS agent. Allowed value is endpoint.	`ENTRY_POINT_UNSPECIFIED`	No
`primary_interaction_type`	String	Defines the primary interaction type of the agent.	`INTERACTION_TYPE_UNSPECIFIED`
`service_code`	String	A unique identifier used when sending a message. Allowed value: Any non-empty string must be unique.	rcs-bigbasket	Yes
`description`	String	Short description of the agent explaining the agent’s purpose and functionality. Allowed value: Any non-empty string must be unique. The character length limit is set to 100.	This is a dummy agent for RCS.	Yes
`phones`	JSON	Phone contact details associated with the agent.	See the specific table for details.	Yes
`emails`	JSON	Emails contact details associated with the agent.	See the specific table for details.	Yes
`privacy`	JSON	Privacy policy information associated with the agent. Must include valid URL if provided.	See the specific table for details.	Yes
`terms_conditions`	JSON	Terms and Conditions related to agent usage. Must include valid URL if provided.	See the specific table for details	Yes
`color`	String	Primary brand color used for User Interface representation. Note: The Hex color (must be from allowed list).	`#94e0d`	Yes
`billing_category`	String	Billing configuration for the agent. The following are the available options: `"CONVERSATIONAL"`, `NON-CONVERSATIONAL`.	`"SINGLE_MESSAGE"`	Yes
`agent_use_case`	String	Business use case category of the agent. The following are the available options: `"TRANSACTIONAL"`, `"PROMOTIONAL"`, `"OTP"`, `"MULTI_USE"`, `"AGENT_USE_CASE_UNSPECIFIED"`	`"MULTI_USE"`	Yes
`hosting_region`	String	Hosting region for an agent. The following are the available options: `"NORTH_AMERICA"`, `"EUROPE"`, `"ASIA_PACIFIC"`, `"HOSTING_REGION_UNSPECIFIED"`	ASIA_PACIFIC	Yes
`status`	String	Status of the Agent. The supported statuses include: ACTIVE, PENDING, INACTIVE, DELETED, CREATED, INITIATED, ACCEPTED, REGISTRATION_IN_PROGRESS, REGISTRATION_COMPLETED, DRAFT, PENDING_APPROVAL, and REJECTED.	"ACTIVE"	No
`languages`	Array of string	A master list of languages supported by system.	["English", "Hindi"]	No
`rcs_provider_id`	String	Identifier of the RCS provider. Default it is set to 1.	1	Yes
`website`	JSON	Official websites URLs associated with the agent or brand. An agent may have a maximum of 3 websites.	See the specific table for details.	Yes
`brand_details`	JSON	Brand information mapped to the agent.	See the specific table for details.	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`label_text`	String	Text with visible on phone number.	call	Yes
`is_toll_free`	Boolean	Set if the agent number is toll free.	true	Yes
`country_code`	String	Country code of the number.	""	Yes
`number`	String	Number through which agent can be contacted.	18XXXX01001	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`label_text`	String	Text with visible for email address.	email	Yes
`is_primary`	Boolean	Agent's email to communicate when the phone number is not provided.	true	Yes
`email`	String	Emails associated with the agent.	`[email protected]`	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`label_text`	String	Text with visible for privacy.	Privacy	Optional
`website`	String	The web page where you have the privacy policy.	`https://www.tatacomm.com/privacy`	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`label_text`	String	Text with visible for website.	tnc	Yes
`website`	String	Organization's website.	`https://www.tatacomm.com/tnc`	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`brand_no`	String	Brand number associated with agent.	8032	Yes
`provider_brand_no`	String	Provider's brand number asscoiated with agent.	""	No
`brand_name`	String	Name of the brand associated with agent. Note: The length is up to 50 characters.	""	No

Sample Success Response

The following is a sample success response:

{
  "code": "RCS902",
  "message": "RCS Agent created successfully",
  "data": {
    "agent_type": "1",
    "display_name": "Basket Agent",
    "logo_url": "https://d2lXXXXXf347r.net/1752750287913-TC_Small_logo_(224_x_224)_1.png",
    "hero_url": "https://d2lXXXXXXf347r.net/1752750253172-TC_Banner_Image.jpg",
    "default_locale": "",
    "agent_test_url": "http://wwww.basket.com",
    "end_point_config": "NON_LOCAL",
    "primary_interaction_type": "INTERACTION_TYPE_UNSPECIFIED",
    "service_code": "rcs-bigbasket",
    "description": "This is a dummy agent for RCS",
    "phones": [
        {
            "label_text": "call",
            "is_toll_free": true,
            "country_code": "",
            "number": "18001001001"
        }
    ],
    "emails": [
        {
            "label_text": "email",
            "is_primary": true,
            "email": "[email protected]"
        }
    ],
    "privacy": {
        "label_text": "Privacy",
        "website": "https://www.tatacomm.com/privacy"
    },
    "terms_conditions": {
        "label_text": "tnc",
        "website": "https://www.tatacomm.com/tnc"
    },
    "color": "#494e0d",
    "billing_category": "SINGLE_MESSAGE",
    "agent_use_case": "MULTI_USE",
    "hosting_region": "ASIA_PACIFIC",
    "status": "",
    "languages": [
        "English",
        "Hindi"
    ],
    "rcs_provider_id": "1",
    "website": [
        {
            "label_text": "company",
            "website": "https://www.tatacomm.com"
        }
    ],
    "brand_details": {
        "brand_no": "8032", 
        "provider_brand_no": "",
        "brand_name": ""
    }
},
  "error": {}
}

Sample Failure Response

The following are the sample failure responses:

Incorrect SID

{
  "code": "RBC001",
  "message": "Incorrect SID or API key.",
  "data": [],
  "error": {
    "body": "Incorrect SID or API key.",
    "error": "record not found"
  }
}

Incorrect API-Key

{
  "code": "RBC201",
  "message": "Incorrect SID or API key.",
  "data": [],
  "error": {
    "body": "Incorrect SID or API key.",
    "error": "API Key Not Found"
  }
}

Error response - PROV error

{
  "code":"RCS904",
  "message":"RCS Agent creation Failed",
  "data":[],
  "error":{
    "error_code":"PROV_ERROR",
    "error_message":"{\"status\":\"FAILED\",\"message\":\"Service code already mapped with another agent.\",\"messageKey\":\"message\"}"}}

Missing Required Feilds

{
  "code": "RCS904",
  "message": "Required fields are missing",
  "data": [],
  "error": {
    "error_code": "MISSING_REQUIRED_FIELDS",
    "error_message": "missing required fields: rcs_provider_id"
  }
}

Invalid Field format

{
  "code": "RCS904",
  "message": "Fields with invalid format are passed",
  "data": [],
  "error": {
    "error_code": "INVALID_FIELD_FORMAT",
    "error_message": "invalid URL format for field 'agent_test_url': www.example.com (example url - https://www.testurl.com)"
  }
}

Invalid Allowed Values

{
  "code": "RCS904",
  "message": "Invalid field values are passed",
  "data": [],
  "error": {
    "error_code": "FIELD_VALUE_ERROR",
    "error_message": "invalid value for 'agent_use_case': INVALID_USE_CASE. Allowed values: TRANSACTIONAL, PROMOTIONAL, OTP, MULTI_USE, AGENT_USE_CASE_UNSPECIFIED"
  }
}

Updated about 9 hours ago