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.
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 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`	No
`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. Note: A maximum of 3 entries is allowed.	See the specific table for details.	Yes (refer to the Note section below the table).
`emails`	JSON	Emails contact details associated with the agent. Note: A maximum of 3 entries is allowed.	See the specific table for details.	Yes (refer to the Note section below the table).
`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

📘
Validation Rules:

Either phones or emails contact method should be provided. 
At least one contact method (Phone or Email) is required for successful agent creation. 
If both phones and emails are missing or empty, the request will fail with a validation error. 
A maximum of 3 entries is allowed for parameters “phones”, “emails”, and “website”.

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:

Validation Failed 

{  
  "code": "RCS904",  
  "message": "Validation failed", 
  "data": [],  
  "error": {  
    "error_code": "CONTACT_REQUIRED",  
    "error_message": "Either phone or email must be provided"  
  }  
}

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"
  }
}