Update an Agent

PUT Method

The Update an AgentAPI allows you to update the agent that has been created by the end-user.

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 Update Agent

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

Request Format

The following is the request format to update an agent.

curl --location --request PUT 'https://<api-domain>/v1/<sid>/rcs/agent/agent_number' \
--header 'api-key: <api-key>' \
--header 'Content-Type: <content-type>' \
--data-raw '{
     "id": "<id>",
        "agent_type": "<agent_type>",
        "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>",
        "agent_number": "<agent_number>",
        "provider_agent_id": "<provider_agent_id>",
        "service_code": "<service_code>",
        "description": "<description>",
        "phones": [
            {
                "is_toll_free": false,
                "number": "<number>",
                "label_text": "<label_text>"
            }
        ],
        "emails": [
            {
                "is_primary": false,
                "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>",
        "status": "<status>",
        "rcs_provider_id": <rcs_provider_id>,
        "verification_name": "<verification_name>",
        "verification_state": "<verification_state>",
        "integration_status": "<integration_status>",
        "integration_name": "<integration_name>",
        "website": [
            {
                "website": "<website>",
                "label_text": "<label_text>"
            }
        ],
        "brand_details": {
            "brand_no": "<brand_no>",
            "provider_brand_no": "<provider_brand_no>",
            "brand_name": "<brand_name>"
        },
        "display_name": "<display_name>"
}'

Sample Request Format

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

curl --location --request PUT 'https://rcs-api.in.kaleyra.io/v1/XXXXX6913850XXXX/rcs/agent/73032' \
--header 'api-key: XXXXX3b8497f58a94e84b671aca43XXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
     "id": "2d8bd37f-4869-4ac4-8499-71eabXXXXd1b",
        "agent_type": "1",
        "logo_url": "https://example.com/assets/logo.png",
        "hero_url": "https://example.com/assets/hero-image.jpg",
        "default_locale": "en",
        "agent_test_url": "https://www.bigbasket.com",
        "end_point_config": "NON_LOCAL",
        "primary_interaction_type": "INTERACTION_TYPE_UNSPECIFIED",
        "agent_number": "73032",
        "provider_agent_id": "agent_001_google_rcs",
        "service_code": "rcs-bigbasket",
        "description": "rcs bigbasket updated",
        "phones": [
            {
                "is_toll_free": false,
                "number": "180XXX01001",
                "label_text": "Primary Contact Phone Number"
            }
        ],
        "emails": [
            {
                "is_primary": false,
                "email": "[email protected]",
                "label_text": "Primary Contact Email Number"
            }
        ],
        "privacy": {
            "website": "https://www.tatacommunications.com/privacy",
            "label_text": "Primary Contact Privacy Number"
        },
        "terms_conditions": {
            "website": "https://www.tatacommunications.com/tnc",
            "label_text": "Primary Contact tnc Number"
        },
        "color": "#494e0d",
        "billing_category": "SINGLE_MESSAGE",
        "agent_use_case": "MULTI_USE",
        "hosting_region": "ASIA_PACIFIC",
        "status": "ACTIVE",
        "rcs_provider_id": 3,
        "verification_name": "ver__73032_05022026",
        "verification_state": "VERIFICATION_STATE_UNVERIFIED",
        "integration_status": false,
        "integration_name": "RCS",
        "website": [
            {
                "website": "https://www.google.com",
                "label_text": "Primary Contact Website"
            }
        ],
        "brand_details": {
            "brand_no": "72932",            
            "provider_brand_no": "Telco_brand_001",
            "brand_name": "Bigbasket Grocery"
        },
        "display_name": "Bigbasket Agent 1"
}'

URL Parameters and Headers

The following is the list of parameters and headers to send the API 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 in the agent update payload:

📘
Note:
The listed fields are restricted and cannot be updated.

Parameter	Data Type	Description	Example	Mandatory?
`id`	String	System-generated unique Identifier (UUID) of the RCS Agent.	2d8bd37f-4869-4ac4-8499-71eabXXXXd1b	Yes
`agent_number`	String	Auto generated number by the server at the time of create agent request.	73032	yes
`provider_agent_id`	String	Id generated by google at the time of creation request.	INTERACTION_TYPE_UNSPECIFIED	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	Yes
`integration_status`	Boolean	Indicates the integration status of the verification process.	false	Yes
`integration_name`	String	Specifies the integration channel used for the request.	RCS	Optional
`verification_name`	String	Name of the brand or business that is displayed to end users once the sender has been verified.	ver__73032_05022026	Yes
`verification_state`	String	Indicates the current status of the verification process. The following are the supported status: `VERIFICATION_STATE_SUSPENDED_IN_GMB, VERIFICATION_STATE_UNSPECIFIED, VERIFICATION_STATE_VERIFIED, VERIFICATION_STATE_UNVERIFIED, VERIFICATION_STATE_PENDING.`	VERIFICATION_STATE_UNVERIFIED	Yes
hosting_region`	String	Hosting region for an agent. The following are the available options: `HOSTING_REGION_UNSPECIFIED, NORTH_AMERICA, EUROPE, ASIA_PACIFIC.`	ASIA_PACIFIC	Yes
`brand_details`	Brand Details object	Brand information mapped to the agent.	see the specific table for details.	Yes

The following is the list of attributes in the agent update payload:

📘
Note:
The listed fields can be updated (editable).

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.	Bigbasket Agent 1	Yes
`logo_url`	String	URL of the logo. Must be a valid image URL - should end with - png, jpg, and jpeg.	`https://example.com/assets/logo.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://example.com/assets/hero-image.jpg`	Yes
`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.	rcs bigbasket updated.	Yes
`phones`	Array of Phone	Phone contact details associated with the agent.	see the specific table for details.	Yes
`emails`	Array of Email	Emails contact details associated with the agent.	see the specific table for details.	Yes
`privacy`	Privacy object	Privacy policy information associated with the agent. Must include valid URL if provided.	see the specific table for details.	Yes
`terms_conditions`	Terms and Conditions object	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).	#494e0d	Optional
`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. Supported options are: `AGENT_USE_CASE_UNSPECIFIED, TRANSACTIONAL, PROMOTIONAL, OTP, and MULTI_ USE.`	MULTI_USE	Yes
`rcs_provider_id`	Integer	Identifier of the RCS provider. Default it is set to 1.	1	Yes
`web_site`	Array of Website	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

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

Parameter	Data Type	Description	Example	Mandatory?
`is_toll_free`	Boolean	If the agent number is toll free. The supported values are true and false.	false	Yes
`number`	String	Number through which agent can be contacted.	18002XXXXX2	Yes
`label_text`	String	Text visible with phone number.	Primary Contact Phone Number	Yes

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

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

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

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

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

Parameter	Data Type	Description	Example	Mandatory?
`website`	String	The web page where you have the terms and conditions listed.	`https://www.tatacommunications.com/tnc`	Yes
`label_text`	String	Text visible for terms and conditions.	Primary Contact tnc Number	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`website`	String	Organization's website.	`https://www.google.com`	Yes
`label_text`	String	Text to visible for privacy.	Privacy Contact Website	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.	72932	Yes
`provider_brand_no`	String	Provider's brand number asscoiated with agent.	Telco_brand_001	No
`brand_name`	String	Name of the brand associated with agent. Note: The length is up to 50 characters.	Bigbasket Grocery	No

Sample Success Response

The following is the sample success response:

{
    "code": "RCS902",
    "message": "Agent updated successfully",
    "data": {
        "id": "2d8bd37f-4869-4ac4-8499-71eabXXXXd1b",
        "agent_type": "1",
        "logo_url": "https://example.com/assets/logo.png",
        "hero_url": "https://example.com/assets/hero-image.jp",
        "default_locale": "en",
        "agent_test_url": "https://www.bigbasket.com",
        "end_point_config": "NON_LOCAL",
        "primary_interaction_type": "INTERACTION_TYPE_UNSPECIFIED",
        "agent_number": "73032",
        "provider_agent_id": "agent_001_google_rcs",
        "service_code": "rcs-bigbasket",
        "description": "rcs bigbasket updated.",
        "phones": [
            {
                "is_toll_free": false,
                "number": "18002XXXXX2",
                "label_text": "Primary Contact Phone Number"
            }
        ],
        "emails": [
            {
                "is_primary": false,
                "email": "[email protected]",
                "label_text": "Primary Contact Email Number"
            }
        ],
        "privacy": {
            "website": "https://www.tatacommunications.com/privacy",
            "label_text": "Primary Contact Privacy Number"
        },
        "terms_conditions": {
            "website": "https://www.tatacommunications.com/tnc",
            "label_text": "Primary Contact tnc Number"
        },
        "color": "#494e0d",
        "billing_category": "SINGLE_MESSAGE",
        "agent_use_case": "MULTI_USE",
        "hosting_region": "ASIA_PACIFIC",
        "status": "ACTIVE",
        "rcs_provider_id": 3,
        "integration_status": false,
        "integration_name": "RCS",
        "website": [
            {
                "website": "https://www.google.com",
                "label_text": "Primary Contact Website"
            }
        ],
        "brand_details": {
            "brand_no": "72932",
            "provider_brand_no": "Telco_brand_001",
            "brand_name": "Bigbasket Grossary"
        },
        "display_name": "Bigbasket Agent 1"
    },
    "error": {}
}

Sample Failure Response

The following are the sample failure responses:

Restricted Fields Update Attempt

{
  "code": "RCS904",
  "message": "Cannot modify restricted fields during update",
  "data": [],
  "error": {
    "error_code": "RESTRICTED_FIELDS_MODIFY_ATTEMPT",
    "error_message": "Restricted fields cannot be modified: rcs_provider_id
  }
}

Invalid Email Format

{
  "code": "RCS904",
  "message": "Fields with invalid format are passed"
  "data": [],
  "error": {
    "error_code": "INVALID_FIELD_FORMAT",
    "error_message": "invalid email format for field 'email'"
  }
}

Invalid URL 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'"
  }
}

Invalid Image URL Format

{
  "code": "RCS904",
  "message": "Fields with invalid format are passed"
  "data": [],
  "error": {
    "error_code": "INVALID_FIELD_FORMAT",
    "error_message": "invalid image URL for field 'logo_url'"
  }
}

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

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

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

Internal Server Error

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

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": "RCS Agent creation Failed",
  "data": [],
  "error": {
    "error_code": "FIELD_VALUE_ERROR",
    "error_message": "Invalid field values are passed"
  }
}