Get Agent by Agent Number

GET Method

The Get Agent by Agent Number API allows you to fetch the agent details based on the agent number.

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

To get agent by agent number, 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 get agent by agent number:

curl --location --request GET 'https://<api_domain>/v1/<sid>/rcs/agent/<agent_number>'\
--header 'api-key: <api-key>' \ 
--header 'Content-Type: <content_type>' \

Sample Request Format

The following is the sample request format to get agent by agent number:

curl --location --request GET 'https://rcs-api.na.kaleyra.io/v1/XXXXX6913850XXXX/rcs/agent/48400'\
--header 'api-key: XXXXX3b8497f58a94e84b671aca43XXXX' \ 
--header 'Content-Type: application/json' \

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 parameters to be used in the payload to get agent by agent number:

Parameter	Data Type	Description	Example	Mandatory?
`agent_number`	string	Auto generated number by the server at the time of create agent request.	48400	Yes

Sample Success Response

The following is the sample success response:

{
    "code": "RCS902",
    "message": "RCS Agent details fetched successfully",
    "data": {
        "id": "xxxxxf5b-eb31-44aa-8fab-124c396exxxx",
        "agent_type": "1",
        "logo_url": "https://rcs-s3.smsinfini.com/1769590576110-Test_TC_Logo.jpg",
        "hero_url": "https://rcs-s3.smsinfini.com/1769590579596-1752750253172-TC_Banner_Image.jpg",
        "agent_number": "71732",
        "provider_agent_id": "brands/a6b74cca-d0c4-4f2d-8c56-3dcdd78875dd/agents/agent_test_2938_p0pxjjkr_agent",
        "service_code": "AGENTMEG",
        "description": "About RCS basket",
        "phones": [
            {
                "is_toll_free": false,
                "number": "+91736XXXXXXX",
                "label_text": "Phone Number"
            }
        ],
        "emails": [],
        "privacy": {
            "website": "https://www.airindia.com/in/en/privacy-notice.html",
            "label_text": "Privacy Policy"
        },
        "terms_conditions": {
            "website": "https://www.tatacommunications.com/tnc",
            "label_text": "Terms of Service"
        },
        "color": "#8a1e1e",
        "billing_category": "SINGLE_MESSAGE",
        "agent_use_case": "TRANSACTIONAL",
        "hosting_region": "NORTH_AMERICA",
        "status": "DELETED",
        "rcs_provider_id": 1,
        "integration_status": false,
        "website": [],
        "brand_details": {
            "brand_no": "48400",
            "provider_brand_no": "Telco_brand_001",
            "brand_name": "Bigbasket Grocery"
        },
        "display_name": "Agent T2938"
    },
    "error": {}
}

The following is the list of parameters shown in the success response:

Parameter	Data Type	Description	Example	Mandatory?
`id`	String	The agent identification number.	xxxxxf5b-eb31-44aa-8fab-124c396exxxx
`agent_type`	String	Business messaging agent (BMA) or RCS Business Messaging (RCBM). The allowed values are "1", "2".	1	Yes
`logo_url`	String	URL of the logo. Must be a valid image URL - should end with - png, jpg, and jpeg.	`https://i.pinimg.com/36xxxx3c.jpg`	Yes
`hero_url`	String	Publicly available URL of the hero image for the agent. Must be a valid image URL - should end with .png,.jpeg, and .jpg. Note: After the agent is verified, it cannot be modified.	`https://i.pinimg.com/8axxxxa1.jpg`	Yes
`agent_number`	String	The ID generated by google at the time of create agent request.	71732
`provider_agent_id`	String	The ID generated by google at the time of create agent request.	brands/a1c890fa-189a-XXXX-b5c9-be639d5126ec/agents/bigbasket_agent_1_48900_uqu4piva_agent
`service_code`	String	A unique identifier used when sending a message. Allowed value: Any non-empty string must be unique.	`AGENTMEG`	Yes
`description`	String	Short description of the agent explaining the agent’s purpose and functionality. Allowed value: Any non-empty string must be unique.	About RCS basket.	Yes
`phones`	Array of objects	Phone contact details associated with the agent.	See the specific table for details.	Yes
`emails`	Array	Emails contact details associated with the agent.	[ ]
`privacy`	object	Privacy policy information associated with the agent. Must include valid URL if provided.	See the specific table for details.	Yes
`terms_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).	#8a1e1e	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 options are: `AGENT_USE_CASE_UNSPECIFIED`, `TRANSACTIONAL` , `PROMOTIONAL`, `OTP`, `MULTI USE`	TRANSACTIONAL	Yes
`hosting_region`	String	Hosting region for an agent. The following are the available options: `HOSTING_REGION_UNSPECIFIED`, `NORTH_AMERICA`, `EUROPE`, `ASIA_PACIFIC`	`NORTH_AMERICA`	Yes
`status`	Integer	The status of the Agent.	DELETED
`rcs_provider_id`	String	Identifier of the RCS provider. Default it is set to 1.	The only allowed value is 1.	Yes
`integration_status`	Boolean	Integration status	false
`website`	Array	Official websites URLs associated with the agent or brand. An agent may have a maximum of 3 websites.	[ ]	No
`brand_details`	Object	Brand information mapped to the agent.	See the specific table for details.	Yes
`display_name`	String	The display name of the agent. Any non-empty string.	Agent T2938	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`is_toll_free`	Boolean	Set if the agent number is toll free.	false	Yes (if phone number provided)
`number`	String	Number through which agent can be contacted.	+91736XXXXXXX	Yes
`label_text`	String	Text with visible on phone number. Note: The field label is set to 25 characters.	Phone Number	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`website`	String	The web page where you have the privacy policy. Note: Must be a valid URL.	`https://www.google.com/privacy`	Yes
`label_text`	String	Text to visible for `privacy`. Note: The field label is set to 25 characters.	Privacy	Yes

The following table describes the different parameters 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. Note: Must be a valid URL.	`https://www.google.com/tnc`	Yes
`label_text`	String	Text to visible for `terms_conditions`. Note: The field label is set to 25 characters.	Terms of Service	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`brand_no`	String	Brand number associated with agent. This is a required field.	48400	Yes
`provider_brand_no`	String	Provider's brand number associated with the agent. This is an optional field.	Telco_brand_001	No
`brand_name`	String	Name of the brand associated with agent. This is an optional field.	Bigbasket Grocery	No

Sample Failure Response

The following is the sample failure response:

{
  "code": "RCS904",
  "message": "Unable to fetch RCS Agent details",
  "data": { ... },
  "error": {
          error_code:"PROV_ERROR"
          error_message:"Agent not found"
  }
}

Updated about 1 month ago