Overview

Freshchat is a cloud based messaging solution that allows you to effectively interact with your business users. It provides an efficient messaging service for lead generation, customer engagement, and customer support and thereby, makes your business competent.

Freshchat APIs can be used by customers and partners to build custom integrations and workflows. APIs help solve the problems around customising existing workflows and tailoring it to specific business structures, integrating bot flows into messaging, syncing-up and transferring data from external systems, and so on.

Status and error messages

Freshchat uses the standard HTTP status codes to indicate the success, in-progress, or failure states of an API request. The standard HTTP staus codes used by Freshchat are as follows:

HTTP Status Code Message
200 Success Request
202 Accepted
400 Bad Request
401 Unauthenticated Request
403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Request
503 Service Unavailable

A successful request returns a response object along with the 200 Success Request status message.
A 202 Accepted status message indicates that the request is being processed.
The 500 Internal Server Request and 503 Service Unavailable status codes indicate that there is an unexpected error caused from the Freshchat side.


Response error message

An API request that fails returns an error object as the response.

Example
1
2
3
4
5
6
{ "code":404, "status":"AGENT_NOT_FOUND", "message":"agent not found", }

Attributes
Attribute Name Data Type Description
code integer HTTP status code.
status string Default HTTP status message associated with the code.
message string Message specific to Freshchat, stating why the request resulted in the error denoted by the status code.

Header Parameters

The common request header parameters that are used in the requests to the Freshchat APIs are,

  • Accept
  • Authorization
  • Content-Type

Accept

Specifies the accepted format of response. The header parameter is used in the API requests that are intended to return a response body.

Header parameter format

Accept: application/<format>

<format> is typically JSON and a parameter value of application/JSON specifies that the response must be a JSON object.
A parameter value of */* specifies that data of any type is acceptable as the response.

Authorization

Specifies the credentials required to authenticate and authorize an API call.

Header parameter format

Authorization: Bearer <access-token>

<access-token> is the value returned by a request call to the authentication server.

Content-Type

Specifies the format in which data is sent in the request body to the recipien

Header parameter format

Content-Type: application/<format>

<format> is typically JSON and a parameter value of application/JSON specifies that the request body is a JSON object.

Authentication and Authorization

Freshchat uses Oauth 2.0 for authentication and authorization and the process involves the following steps,

  1. Make a call to the Freshchat authentication server from the Freshchat user interface, to obtain an access token.
  2. Use the access token in further API requests, to make valid API calls.

In the Oauth 2.0 authentication scheme, the access token identifies the requester and defines the permissions for the requester. Each token has a defined life time.

If you send a request with an expired token, the request fails with the 401 Unauthenticated Request error message. You can obtain another token from the authentication server and retry the request with the latest token.

Request call to obtain the access token

For an approved Freshchat app, navigate to the Settings > API Tokens page and click the Generate Token button. The authentication server returns the access token (specified in the page as API KEY). You should use the access token in the authorization header parameter to make a valid API call.

Rate Limits

The number of API calls permitted (on an hourly basis) is specific to a business account and varies depending on the Freshchat plan that the business uses. The following parameters in the response header help to track the rate limits:

Parameter Name Description
X-RateLimit-Limit Specifies the total number of API calls permissible in a timeframe.
X-RateLimit-Remaining Specifies the number of API calls remaining in the timeframe.
X-RateLimitReset Specifies the time remaining to reset the previously set time.

User

Users are website visitors who converse with the business that uses Freshchat.

Endpoints

POST /users
PUT /users/{user_id}
GET /users/{user_id}

The user object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{ "email": "abc@example.com", "avatar": { "url": "https://web.freshchat.com/img/johndoe.png" }, "created_time": "2019-05-07T09:46:57.634Z", "id": "56224d31-e29a-407a-98ff-820a1ec9f15c", "phone": "123456789", "properties": [ { "name": "orderId", "value": "#1242" } ], "first_name": "ABC", "last_name": "XYZ" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
email string Email id of the user.
avatar image object Image associated with the user. The attribute value is as an image object. The image object consists of the url attribute.

Attribute of the image object:

url (string): Link from which the image is fetched.Mandatory

created_time string Time when the user information is created, specified in the date-time format. The time of creation is returned as part of the user object in response to a successful user creation request.
id string Identifier of the user information. The id value is returned as part of the user object in response to a successful user creation request. The (user) id is used to identify and retrieve user information in API calls.
phone string User’s phone number.
properties array of property object Attributes of a user, specified as an array. Each array entry is a property object.

Attributes of the property object:

name (string)Mandatory
value (string)Mandatory

first_name string Business name of the user.
last_name string Last name of the user.

Create a user

Creates a user object with the specified user information.

post
/v2/users
Sample request | Curl
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl -X POST \ https://api.freshchat.com/v2/users \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \ -H 'Content-Type: application/json' \ -d '{ "email": "abc@example.com", "avatar": { "url": "https://web.freshchat.com/img/johndoe.png" }, "phone": "123456789", "properties": [ { "name": "orderId", "value": "#1242" } ], "first_name": "ABC", "last_name": "XYZ" }'
EXPAND ↓
Response

A successful request returns a user object with the id and created_time attribute values. The id that is returned can be used to update the corresponding user information or retrieve information, in further API calls.
For information on the different status and error messages, see Status and error messages.

Update user details

Identifies a user by the user id passed in the request and updates the user information with the attribute values passed in the request body. In the data payload, if an attribute value is null or if an attribute is not passed as part of the payload, the existing value of the attribute is retained.

put
/v2/users/{user_id}
Path parameters
Parameter Name Data Type Description
user_idMandatory string The id value that is an attribute of the user object returned in response to a successful
request to create the user.
Sample request | Curl
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
curl -X PUT \ https://api.freshchat.com/v2/users/5ff807e1-5193-4825-868e-824950d1a0ef \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \ -H 'Content-Type: application/json' \ -d '{ "properties": [ { "name": "orderId", "value": "#1242" } ], "first_name": "ABC", "last_name": "XYZ", "email": "abc@example.com", "avatar": { "url": "https://web.freshchat.com/img/johndoe.png" }, "phone": "123456789" }'
EXPAND ↓
Response

A 202 Accepted message is returned, if the request is error free and accepted for processing.

Retrieve user information

Identifies a user by the user id passed in the request and returns the user information associated with the user, as the response user object.

get
/v2/users/{user_id}
Path parameters
Parameter Name Data Type Description
user_idMandatory string The id value that is an attribute of the user object returned in response to a successful
request to create the user.
Sample request | Curl
Copied Copy
1
2
3
4
curl -X GET \ https://api.freshchat.com/v2/users/5ff807e1-5193-4825-868e-824950d1a0ef \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \ -H 'Content-Type: application/x-www-form-urlencoded' \
EXPAND ↓
Response

A successful request returns the user object associated with the user id.

Conversation

Interactions between a business and its end-user are recorded as conversations. Agents (team members) use conversations to move deals to prospects, users raise support queries through conversations, and so on. Agents can be categorized into groups and conversations can be assigned to a group; any agent in the group can pick up a conversation and address the queries in the conversation.

Endpoints

POST /conversations
GET /conversations/{conversation_id}
POST /conversations/{conversation_id}/messages
PUT /conversations/{conversation_id}

The conversation object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{ "conversation_id": "c69641e9-8a85-4da1-858e-77169b0c76a7_54e59ba2-92f6-492d-bb1f-29743f1a22a8_feedback", "app_id": "c69641e9-8a85-4da1-858e-77169b0c76a7", "channel_id": "729bd0ba-2ac2-400b-abef-26d92a3f4420", "messages": [ { "app_id": "c69641e9-8a85-4da1-858e-77169b0c76a7", "actor_type": "user", "actor_id": "54e59ba2-92f6-492d-bb1f-29743f1a22a8", "channel_id": "729bd0ba-2ac2-400b-abef-26d92a3f4420", "message_type": "normal", "message_parts": [ { "text": { "content": "hey dude!!" } } ] } ], "status": "new", "users": [ {"id": "54e59ba2-92f6-492d-bb1f-29743f1a22a8"} ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
conversation_id string Identifier of the conversation. The conversation_id value is returned as part of the conversation object in response to a successful conversation creation request. The conversation_id is used to identify a conversation and post a message to the conversation or update the conversation.
created_time string Time when the conversation is created, specified in the date-time format. The time of creation is returned as part of the conversation object in response to a successful conversation creation request.
app_idMandatory string All businesses that use Freshchat are assigned an app_id that is used to integrate with Freshchat. The app_id is used to identify the Freshchat account under which the conversation is created. To know your app_id, navigate to https://web.freshchat.com and log in with your account credentials. Navigate to Settings > Account Settings > Integration Settings. The App ID is displayed under AGENT WIDGET.
channel_id string Identifier of a channel created by the business that uses Freshchat. Channels help users identify the subject in which they have a query; users can create a conversation in the identified channel. Agents can pick conversations in a specific channel and address the queries in them.
messagesMandatory array of message object Messages that constitute a conversation, specified as an array. In a conversation, a message can be posted by a user or agent. Each entry of the array is a message object with corresponding attributes.
statusMandatory string Specifies the state of a conversation.
When you update a conversation, you can use the status attribute in combination with the assigned_agent_id and assigned_group_id attributes to specify if a conversation is resolved, reopened, or assigned and to assign the conversation for further action to an agent or group. If a conversation is assigned to an agent, the assigned_agent_id is a mandatory parameter and the status must be assigned. If a conversation is assigned to a group alone, the status must be new.
Possible values (enum): new, resolved, reopened, assigned
users array of user object List of all users involved in the conversation, specified as an array. Each array value is a user object containing information that pertains to a user.
agents array of user object List of all agents involved in the conversation, specified as an array. Each array value is an agent object containing information that pertains to an agent.
assigned_agent_id string Identifier of the agent to whom a conversation is assigned for resolution.
assigned_group_id string Identifier of the group to which a conversation is assigned for resolution. An agent in the group can pick up the conversation, assign it to self, and resolve the conversation.

The message object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
"messages": [ { "app_id": "c69641e9-8a85-4da1-858e-77169b0c76a7", "actor_type": "user", "actor_id": "54e59ba2-92f6-492d-bb1f-29743f1a22a8", "channel_id": "729bd0ba-2ac2-400b-abef-26d92a3f4420", "message_type": "normal", "message_parts": [ { "text": { "content": "hey dude!!" } } ] } ],
EXPAND ↓
Attributes
Attribute Name Data Type Description
app_idMandatory string Identifier of the Freshchat account.
actor_typeMandatory string Specifies if the message posted in a conversation is by a user or an agent.
Possible values (enum): user, agnet
actor_id string If the actor_type is user, actor_id is the associated user id. If the actor_type is agent, actor_id is the associated agent_id.
channel_idMandatory string Identifier of the channel in which a message is posted to a conversation.
message_typeMandatory array of message object Specifies if the message in a conversation is a private message.
Possible values (enum): normal
message_partsMandatory message_part object Contains the message stored as different parts - plain text, images, url buttons, a combination of text and image, or a combination of text, image, and url buttons.
reply_parts message_part object In a conversation, if a message is a reply to a certain message, the reply_parts attribute contains the different parts of the reply message - a text, image, url, quick reply button, or a combination of these attributes. A reply_part attribute can exist only if there is a message part specified.

The message_part object

Example 1- Message with image, text, and links
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
"message_parts": [ {"image": { "url": "https://via.placeholder.com/1050x1050" } }, { "text": { "content": "Hello world" } }, { "url_button": { "url": "http://google.com", "label": "Google" } }, { "url_button": { "url": "https://www.yahoo.com", "label": "Yahoo", "target": "_self" } } ]
EXPAND ↓
Example 2- Message with plain text
1
2
3
4
5
6
7
"message_parts": [ { "text": { "content": "USER MESSAGE - from postman" } } ]
EXPAND ↓
Example 3- Message with only an image
1
2
3
4
5
6
7
"message_parts": [ { "image": { "url": "https://via.placeholder.com/1050x1050" } } ]
EXPAND ↓
Example 4- Message with an image and text
1
2
3
4
5
6
7
8
9
10
11
12
"message_parts": [ { "image": { "url": "https://via.placeholder.com/1050x1050" } }, { "text": { "content": "Hello world" } } ]
EXPAND ↓
Example 5- Message with links
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
"message_parts": [ { "url_button": { "url": "http://google.com", "label": "Google" } }, { "url_button": { "url": "https://www.yahoo.com", "label": "Yahoo", "target": "_self" } } ]
EXPAND ↓
Example 6- Message with a reply part that contains a collection of quick reply buttons
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
"message_parts": [ { "text": { "content": "Do you Agree?" } } ] "reply_parts": [ { "collection": { "sub_parts": [ { "quick_reply_button": { "label": "Yes đź‘Ť" } }, { "quick_reply_button": { "label": "No" } } ] } } ]
EXPAND ↓
Attributes
Attribute Name Data Type Description
text text_part object Text part of a message in a conversation.

Attribute of the text_part object:
content (string): Actual content of the text message.
Mandatory
image image_part object Image part of a message in a conversation.

Attribute of the image_part object:
url (string): Location of the image file.
Mandatory
url_button url_button_part object Links in a message.

Attributes of the url_button_part object:
url (string): The actual hyperlink that is accessed by clicking the corresponding label.
Mandatory
label (string): Text (in the message) that is used as the connector to the hyperlink.
Mandatory
target (string): Specifies where the link is opened. If the value is _self, the link is opened within the conversation widget. If the value is _blank, the link is opened in a new tab. Possible values (enum): _self, _blank Default value: _blank
quick_reply_button quick_reply_button_part object In a conversation, a reply message can be composed by using quick reply buttons. The quick replies can be custom messages or predefined labels. The quick_reply_button attribute is present only in a reply part message.

Attributes of the quick_reply_button_part object:
Custom_reply_text (string): Custom text that is used as a reply text.

label (string): Label on the button that is used to give a quick reply.
Mandatory

Create a conversation

Creates a conversation object or updates a conversation with bulk messages based on the specified conversation information.

post
/v2/conversations
Sample request | Curl
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
curl -X POST \ https://api.freshchat.com/v2/conversations \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \ -H 'Content-Type: application/json' \ -d '{ "app_id": "c69641e9-8a85-4da1-858e-77169b0c76a7", "channel_id": "729bd0ba-2ac2-400b-abef-26d92a3f4420", "messages": [ { "app_id": "c69641e9-8a85-4da1-858e-77169b0c76a7", "actor_type": "user", "actor_id": "54e59ba2-92f6-492d-bb1f-29743f1a22a8", "channel_id": "729bd0ba-2ac2-400b-abef-26d92a3f4420", "message_type": "normal", "message_parts": [ { "text": { "content": "hey dude!!" } } ] } ], "status": "new", "users": [ {"id": "54e59ba2-92f6-492d-bb1f-29743f1a22a8"} ] }'
EXPAND ↓
Response

A successful request returns a conversation object with the conversation_id and created_time attribute values. The id that is returned can be used to update the corresponding conversation information,retrieve information, or post messages to the conversation, in further API calls.

Retrieve a conversation

Identifies a conversation by the conversation_id passed in the request and returns the corresponding conversation, as the response conversation object.

get
/v2/conversations/{conversation_id}
Path parameters
Parameter Name Data Type Description
conversation_idMandatory string The conversation_id value that is an attribute of the conversation object returned in response to a successful request to create the conversation.
Sample request | Curl
Copied Copy
1
2
3
curl -X GET \ https://api.freshchat.com/v2/conversations/c69641e9-8a85-4da1-858e-77169b0c76a7_54e59ba2-92f6-492d-bb1f-29743f1a22a8_feedback \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \ -H 'Content-Type: application/json' \
EXPAND ↓
Response

A successful request returns conversation object with the conversation id.

Send a message to a conversation

Identifies a conversation by the conversation id specified as the path parameter and adds the message to the conversation. To update the conversation with a user message, in the payload sent through the request, specify the actor_type attribute value as user. To update the conversation with an agent message, specify the actor_type attribute value as agent. In an API call, you can post only one message to a conversation. To post bulk messages, use the API to create a conversation.

post
/v2/conversations/{conversation_id}/messages
Path parameters
Parameter Name Data Type Description
conversation_idMandatory string The conversation_id value that is an attribute of the conversation object returned in response to a successful request to create the conversation.
Sample request | Curl
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl -X POST \ https://api.freshchat.com/v2/conversations/8a076d71-3e46-4309-8e98-2fbdbab2e64f/messages \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \ -H 'Content-Type: application/json' \ -d '{ "actor_type": "user", "actor_id": "54e59ba2-92f6-492d-bb1f-29743f1a22a8", "message_type": "normal", "message_parts": [ { "text": { "content": "USER MESSAGE - from postman" } } ] }'
EXPAND ↓
Response

The successful processing of the request returns a 200 Success request status message along with the message object that is posted to the conversation.

Update a conversation

Identifies a conversation by the conversation id specified as the path parameter and updates the conversation with the conversation object passed in the request body. The API is typically used to update the conversation status, assign a conversation to a group or agent or both.

put
/v2/conversations/{conversation_id}
Path parameters
Parameter Name Data Type Description
conversation_idMandatory string The conversation_id value that is an attribute of the conversation object returned in response to a successful request to create the conversation.
Sample request | Curl
Copied Copy
1
2
3
4
5
6
7
curl -X PUT \ https://api.freshchat.com/v2/conversations/8a076d71-3e46-4309-8e98-2fbdbab2e64f \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \ -H 'Content-Type: application/json' \ -d '{ "status": "resolved" }'
EXPAND ↓

To resolve a conversation, in the payload passed in the request, specify the value of the status attribute as resolved.

To reopen a resolved conversation, in the payload passed in the request, specify the value of the status attribute as reopened.

To assign a conversation to a group, in the payload passed in the request, specify the value of the status attribute as new and specify the value of the assigned_group_id attribute as the group id of the group to which the conversation is assigned.

To assign a conversation to an agent, in the payload passed in the request, specify the value of the status attribute as assigned and specify the value of the assigned_agent_id attribute as the agent id of the agent to whom the conversation is assigned.

To assign a conversation to an agent in a group, in the payload passed in the request, specify the value of the status attribute as assigned, specify the value of the assigned_group_id attribute as the group id of the group to which the conversation is assigned, and specify the value of the assigned_agent_id attribute as the agent id of the agent to whom the conversation is assigned. The agent to whom the conversation is assigned must belong to the group to which the conversation is assigned.

Response

The successful processing of the request returns a 200 Success request status message along with the conversation object that is updated. A successful request to assign the conversation, returns the conversation object with the updated assigned_group_id or assigned_agnet_id attribute.

Agents

Agents are members (of the business that uses Freshchat) who converse with the users. The agents use Freshchat to converse with prospects, move deals down the funnel, resolve support queries, and so on.

Endpoints

GET /agents
GET /agents/{agent_id}
PUT /agents/{agent_id}

The agents object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{ "agents": [ { "id": "d37b9c8f-ec59-4c72-9b1d-c06edcb36de1", "first_name": "AAA", "last_name": "AAA", "email": "abc@example.com", "avatar": {}, "social_profiles": [] }, { "id": "d3ba6e61-a137-4f68-a068-2a265cb2a68c", "first_name": "XYZ", "last_name": "ABC", "email": "abc@example.com", "avatar": {}, "social_profiles": [] } ], "pagination": { "total_items": 109, "total_pages": 55, "current_page": 1, "items_per_page": 2 }, "links": { "next_page": { "href": "/v2/agents?sort_by=email&items_per_page=2&sort_order=asc&page=2", "rel": "agent", "type": "GET" }, "first_page": { "href": "/v2/agents?sort_by=email&items_per_page=2&sort_order=asc&page=1", "rel": "agent", "type": "GET" }, "last_page": { "href": "/v2/agents?sort_by=email&items_per_page=2&sort_order=asc&page=55", "rel": "agent", "type": "GET" } } }
EXPAND ↓
Attributes
Attribute Name Data Type Description
agents array of agent object All agents, specified as an array. Each array entry is an agent object, with the corresponding attributes.
pagination pagination object Specifies information on the bulk data returned. For more information, refer Response attributes in the Pagination section.
links links object Specifies the links to the various pages that can be accessed from the current page.

Attributes of the links object:
next_page (link object)
previous_page (link object)
first_page (link object)
last_page (link object)
For more information, refer Response attributes in the Pagination section.

The agent object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "biography": "Agent with advanced level proficiency", "groups": [], "status": 0, "id": "afd5102c-5443-4fe3-a069-4fe25189a0a1", "first_name": "ABC", "last_name": "ABC", "email": "abc@example.com", "avatar": { "url": "https://fc-use1-00-pics-bkt-00.s3.amazonaws.com/4b8e7fe8e49b737fc33496e42d68243a97bca875c587a74aa84f7751d1e7b24e/f_hlimage/u_3ddd06e4ce787a9ad2e04b759c6b7f87271784f8a3c32670ee187cf04a28b1dd/img_1556042624362.png" }, "social_profiles": [ { "type": "twitter", "id": "tweetme" } ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
idMandatory string Identifier of the agent, auto-created when the agent information is created.
email string Email id of the user.
avatar image object Image associated with the agent. The attribute value is as an image object.
The image object consists of the url attribute.

Attribute of the image object:
url (string): Link from which the image is fetched.Mandatory
phone string User’s phone number.
biography string Meaningful description for the agent.
first_name string Business name of the agent.
last_name string Last name of the agent.
social_profiles array of social_profile object List of all social platforms in which the agent is available, specified as an array. Each array entry is a social_profile object.

Attributes of the social_profile object
type (string): Name of the social media platform. Possible values (enum): facebook, twitter, skype, linkedin Mandatory
id (string): User id of the agent, on the platform.

List all agents

Retrieves a list of all agents configured by the business that uses Freshchat.

get
/v2/agents
Query parameters

You can use a combination of valid query parameters to limit or filter the response data.

Sample request | Curl
Copied Copy
1
2
3
curl -X GET \ 'https://api.freshchat.com/v2/agents?items_per_page=2' \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \
EXPAND ↓
Response

The successful processing of the request returns a 200 Success request status message along with the agents object. The response is curated based on the query parameters passed in the request.

Retrieve agent information

Identifies an agent by the agent_id passed in the request and returns the corresponding agent information, as the response agent object.

get
/v2/agents/{agent_id}
Path parameters
Parameter Name Data Type Description
agent_idMandatory string The agent_id that identifies an agent. The agent_id is created when the business creates an agent. You can use the List all agents API and obtain a list of all configured agents and their corresponding ids.
Sample request | Curl
Copied Copy
1
2
3
4
curl -X GET \ https://api.freshchat.com/v2/agents/afd5102c-5443-4fe3-a069-4fe25189a0a1 \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \ -H 'cache-control: no-cache'
EXPAND ↓
Response

The successful processing of the request returns a 200 Success request status message along with the agent object corresponding to the agent_id specified in the request.

Update agent information

Identifies an agent by the agent id specified as a path parameter and updates the agent information with the agent object passed in the request body. In the agent object passed in the request body, the id attribute is mandatory.

put
/v2/agents/{agent_id}
Path parameters
Parameter Name Data Type Description
agent_idMandatory string The agent_id that identifies an agent. The agent_id is created when the business creates an agent. You can use the List all agents API and obtain a list of all configured agents and their corresponding ids.
Sample request | Curl
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
curl -X PUT \ https://api.freshchat.com/v2/agents/afd5102c-5443-4fe3-a069-4fe25189a0a1 \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \ -H 'Content-Type: application/json' \ -d '{ "biography": "This is supposed to be bio for agent.", "groups": [], "status": 0, "id": "afd5102c-5443-4fe3-a069-4fe25189a0a1", "first_name": "ABC", "last_name": "ABC", "email": "abc@example.com", "avatar": { "url": "https://fc-use1-00-pics-bkt-00.s3.amazonaws.com/4b8e7fe8e49b737fc33496e42d68243a97bca875c587a74aa84f7751d1e7b24e/f_hlimage/u_3ddd06e4ce787a9ad2e04b759c6b7f87271784f8a3c32670ee187cf04a28b1dd/img_1556042624362.png" }, "social_profiles": [ { "type": "twitter", "id": "tweetme" } ] }'
EXPAND ↓
Response

The successful processing of the request returns a 200 Success request status message along with the agent object that is updated.

Channel

Message channels help streamline conversations between a business user and the business. A business can create channels and the users can use the channels to pick up the subject relevant to a query and start a conversation. When creating a channel, the business can customize welcome messages to set context or expectations, schedule campaigns and triggers to arrive inside channels, and so on.

Endpoint

GET /channels

The channels object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
{ "channels": [ { "id": "83e410bc-4af1-44a9-a39d-a64c4a4c0871", "icon": {}, "updated_time": "2019-05-15T06:56:45.474Z", "enabled": true, "public": true, "name": "Support", "tags": [ "support" ], "welcome_message": { "message_parts": [ { "text": { "content": "Hello, how can we help you today?" } } ], "message_type": "normal" } } ], "pagination": { "total_items": 39, "total_pages": 39, "current_page": 3, "items_per_page": 1 }, "links": { "next_page": { "href": "/bots/v2/channels?sort_by=name&items_per_page=1&sort_order=desc&page=4", "rel": "channel", "type": "GET" }, "previous_page": { "href": "/bots/v2/channels?sort_by=name&items_per_page=1&sort_order=desc&page=2", "rel": "channel", "type": "GET" }, "first_page": { "href": "/bots/v2/channels?sort_by=name&items_per_page=1&sort_order=desc&page=1", "rel": "channel", "type": "GET" }, "last_page": { "href": "/bots/v2/channels?sort_by=name&items_per_page=1&sort_order=desc&page=39", "rel": "channel", "type": "GET" } } }
EXPAND ↓
Attributes
Attribute Name Data Type Description
channels array of channel object All channels, specified as an array. Each array entry is a channel object, with the corresponding attributes.
pagination pagination object Specifies information on the bulk data returned. For more information, refer Response attributes in the Pagination section.
links links object Specifies the links to the various pages that can be accessed from the current page.

Attributes of the links object:
next_page (link object)
previous_page (link object)
first_page (link object)
last_page (link object)
For more information, refer Response attributes in the Pagination section.

The channel object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{ "id": "83e410bc-4af1-44a9-a39d-a64c4a4c0871", "icon": {}, "updated_time": "2019-05-15T06:56:45.474Z", "enabled": true, "public": true, "name": "Inbox", "tags": [ "sales" ], "welcome_message": { "message_parts": [ { "text": { "content": "vcb" } } ], "message_type": "normal" } }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the channel, auto-created when the channel is created by the business.
icon image object Pictorial representation of the channel. The attribute value is as an image object. The image object consists of the url attribute.

Attribute of the image object:
url (string): Link from which the image is fetched.
updated_time string Time when the channel is last updated, specified in the date-time format.
enabled boolean Specifies if a channel is available. Channels can be created by a business but can be disabled until a further point in time when there is a necessity to open the channel.
Possible values: true, false
public boolean Specifies if a channel is open to receive messages from all users.
Possible values: true, false
name string Channel name that provides a meaningful description for the channel. For example, Inbox.
tags array of string Labels using which the messages or conversations in a channel can be sorted. Each value of the array must be a unique value.
Example values: sales, support
welcome_message message object Message that sets a context about the purpose of the channel.
assign_to_group group object Specifies the group details of the group to which the channel is assigned, if the channel is assigned to a group.

List all channels

Retrieves a list of all channels configured by the business that uses Freshchat.

get
/v2/channels
Query parameters

You can use a combination of valid query parameters to limit or filter the response data.

Sample request | Curl
Copied Copy
1
2
curl -X GET \ 'https://api.freshchat.com/v2/channels?sort_by=name&items_per_page=1&sort_order=desc&page=3' \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \
EXPAND ↓
Response

The successful processing of the request returns a 200 Success request status message along with the channels object. The response is curated based on the query parameters passed in the request.

Group

A business can segment agents into various groups based on factors such as the agent’s role (sales, support, managers, and so on). Conversations can be assigned to groups. Any agent in the group can pick a conversation, assign it to self, and resolve the queries in the conversation, based on the agent’s availability and convenience. A channel can be mapped to a group; all conversations posted in the channel are directed to the group.

Endpoint

GET /groups

The groups object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
"groups": [ { "id": "f9a794c5-840b-450e-9636-6a54568596d9", "name": " Sales group", "description": "Group that handles all sales related conversations", "routing_type": "INTELLIASSIGN" } ], "pagination": { "total_items": 9, "total_pages": 9, "current_page": 3, "items_per_page": 1 }, "links": { "next_page": { "href": "/bots/v1/groups?sort_by=name&items_per_page=1&sort_order=desc&page=4", "rel": "group", "type": "GET" }, "previous_page": { "href": "/bots/v1/groups?sort_by=name&items_per_page=1&sort_order=desc&page=2", "rel": "group", "type": "GET" }, "first_page": { "href": "/bots/v1/groups?sort_by=name&items_per_page=1&sort_order=desc&page=1", "rel": "group", "type": "GET" }, "last_page": { "href": "/bots/v1/groups?sort_by=name&items_per_page=1&sort_order=desc&page=9", "rel": "group", "type": "GET" } } }
EXPAND ↓
Attributes
Attribute Name Data Type Description
groups array of group object All groups configured by a business, specified as an array. Each array entry is a group object, with the corresponding attributes.
pagination pagination object Specifies information on the bulk data returned. For more information, refer Response attributes in the Pagination section.
links links object Specifies the links to the various pages that can be accessed from the current page.

Attributes of the links object:
next_page (link object)
previous_page (link object)
first_page (link object)
last_page (link object)
For more information, refer Response attributes in the Pagination section.

The group object

Example
1
2
3
4
5
6
{ "id": "f9a794c5-840b-450e-9636-6a54568596d9", "name": "sales group", "description": "Group that addresses all sales queries", "routing_type": "INTELLIASSIGN" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the group, auto-created when the business creates the group.
name string Meaningful text identifier for the group.
description string Meaningful definition that specifies the purpose of the group.
agents array of agent object List of all agents in the group, specified as an array. Each array entry is an agent object, with the corresponding attributes.
routing_type string Specifies if the group members can accept auto-assigned conversations. If a business uses the Estate plan of Feshchat, the business can use the Intelliassign feature to auto-assign conversations to agents within a group.
Possible values: Intelliassign, Disabled

List all groups

Retrieves a list of all groups configured by the business that uses Freshchat.

get
/v2/groups
Query parameters

You can use a combination of valid query parameters to limit or filter the response data.

Sample request | Curl
Copied Copy
1
2
curl -X GET \ 'https://api.freshchat.com/v2/groups?sort_by=name&items_per_page=1&sort_order=desc&page=3' \ -H 'Authorization: Bearer eyJhbGciOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxImNsa' \
EXPAND ↓
Response

The successful processing of the request returns a 200 Success request status message along with the groups object. The response is curated based on the query parameters passed in the request.