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 status 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 message

An API request returns an object as the response.
Example 1
1
2
3
4
5
6
{ "code":202, "status":"ACCEPTED", "message":"Agent deletion request accepted", }
Example 2
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 the results of the API request.

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 recipient.

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.

Content-Type: multipart/<format>

<format> is typically form-data and a parameter value of multipart/form-data specifies that the request body contains key-value pairs that represent form fields and values. It is used for file uploads.

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.

Accounts

An organization can have multiple accounts configured within the Freshworks ecosystem. Account information identifies an account and entails other miscellaneous configuration details pertaining to the account. You can use the Account API to access and work with the account information.

Endpoints

GET /accounts/configuration

The accounts object

Example
1
2
3
4
5
6
7
8
9
10
11
{ "organisation_id": 1775382926361, "organisation_domain": "example.freshworks.com", "account_id": 8762573821, "account_domain": "example.freshchat.com", "app_id": "9d83ebc5-e036-4b48-b655-b0d79584b2c5", "bundle_id": 991773928113, "bundle_type": "support360", "plan_type": "Enterprise Annual Plan 2021", "datacenter": "US" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
organisation_id integer Unique Identifier of an organization, auto-generated when the organization is configured in the Freshworks system.
organisation_domain string Full domain name of the organisation.
account_id integer Unique identifier for the Freshchat account whose account information is retrieved. The account_id is auto-generated when an account is created.
account_domain string Domain name of the Freshchat account whose account information is retrieved by using the account API.
app_id string Organizations that use Freshchat are assigned an app_id that can be used to integrate an application with Freshchat. To obtain the app_id, navigate to https://web.freshchat.com and log in with the corresponding account credentials. Navigate to Settings > Account Settings > Integration Settings. The app_id is displayed under AGENT WIDGET.
bundle_id integer Bundle refers to the group of products extended to an organization from the Freshworks ecosystem. bundle_id is the unique identifier of the bundle to which the Freshchat account belongs.

Note: If the account is not available as part of a bundle, the bundle_id value is 0.
bundle_type string Type of the bundle to which the Freshchat account belongs. It indicates whether the account uses Freshchat as a stand-alone product or as part of a bundle.

Possible values: freshchat, sales 360, and support360.
plan_type string Organization’s subscription plan that specifies whether the account is a Free, Growth, Pro or Enterprise account.
datacenter string Datacenter where the Freshchat account is deployed.

Possible values: US, EUC, AUS, IND and US2.

Retrieve account information

Retrieves information pertaining to the account configured for an organization, in the Freshchat system.

get
/v2/accounts/configuration
Sample request | Curl
Copied Copy
1
2
3
4
5
6
curl -X GET \ https://example.freshchat.com/v2/accounts/configuration\ -H 'accept: application/json' -H 'Authorization: Bearer eyJraWQiOiJjdXN0b20tb2F1dGgta2V5aWQiLCJ0eXxxxxxxxxxxisXh3E4cX8tY' \ -H 'content-type: application/json' --data-raw
EXPAND ↓
Response

A successful request returns a 200 OK along with the retrieved accounts object.

Users

Users are an organization’s customers who use Freshchat to converse with the organization.

Endpoints

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

The user 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
{ "id": "ca03d5ea-9615-4069-8938-bc39e522a436", "created_time": "2022-08-29T07:32:07.003Z", "updated_time": "2022-10-27T12:30:39.591Z" "avatar": { "url":"https://fc-pics.s3.amazonaws.com/img/johndoe.png" }, "email": "alice.john@email.com", "first_name": "Alice", "last_name": "John", "login_status": false, "org_contact_id": " ", "phone": "174285396", "properties": [ { "name": "fc_user_timezone", "value": "Asia/Calcutta" }, { "name": "siteId", "value": "213123" } ], "reference_id": "121", "restore_id": "0663d5f0-f6cc-43f6-bd74-e5d0c0e2cf09" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the user object, auto-generated when a user record is created in the Freshchat system.
created_time string Timestamp of when the user record is created in the Freshchat system, specified in the UTC format.
updated_time string Timestamp of when the user details are last updated in the Freshchat system, specified in the UTC format.
avatar object Image used as the display picture in the user’s profile.
Attributes of the object:
url (string): Link from which the image is fetched.
email string Email address of the user.
first_name string First name of the user.
last_name string Last name of the user.
login_status boolean Specifies whether the user is logged into the Freshchat system.
Possible values: true, false
org_contact_id string Organization-level identifier of the user.
phone string Phone number of the user.
properties array of objects Additional user information. This attribute contains custom property names and the corresponding values, as a valid JSON object of name (custom property name)-value (custom property’s value) pairs.
ttributes of the object:
name (string): Name of the custom property.
value (string): Value of the custom property.
reference_id string User identifier that the system sets for a user when Freshchat is integrated with our Customer Experience suite of products.
restore_id string Unique identifier of the user, auto-generated when a conversation is initiated in the Freshchat system. When a logged-in user uses a new device or browser to initiate a conversation, restore_id identifies the user and restores the past conversations.
This attribute value is returned as part of the response to the create a user API call.

List users by specified criteria

Retrieves a list of all the users who meet a specific search query.

get
/v2/users
Query parameters

You can use a combination of the following query parameters and pagination parameters to retrieve the appropriate set of users. Ensure that the query parameter values are URL encoded.

Note: At least one of the following query parameters is mandatory for a successful response.

Parameter Name Description Example
first_name Limits the response to user objects whose first_name value matches the parameter value.

GET /users?first_name=Alice

last_name Limits the response to user objects whose last_name value matches the parameter value.

GET /users?last_name=Doe

email Limits the response to user objects whose email value matches the parameter value.

GET /users?email=alice.doe@mail.com

reference_id Limits the response to user objects whose reference_id value matches the parameter value.

GET /users?reference_id=121

phone_no Limits the response to user objects whose phone_no value matches the parameter value.

GET /users?phone_no=639528417

created_from

Should be a date-time value specified in the UTC format.
Limits the response to user objects whose created_time value is a time after the parameter value or matches the parameter value.

GET /users?created_from=2022-10-13T09:03:34.709Z

created_to

Should be a date-time value specified in the UTC format.
Limits the response to user objects whose created_time value is a time before the parameter value.

GET /users?GET /users?created_to=2022-10-13T09:03:34.709Z

updated_from

Should be a date-time value specified in the UTC format.
Limits the response to user objects whose updated_time value is a time after the parameter value.

GET /users?updated_from=2022-10-27T12:25:15.831Z

updated_to

Should be a date-time value specified in the UTC format.
Limits the response to user objects whose updated_time value is a time before the parameter value.

GET /users?updated_to=2022-10-27T12:25:15.831Z

Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/users?first_name=Alice&page=1&items_per_page=100&sort_order=asc&sort_by=email" -H "accept: application/json" -H "Authorization: Bearer eyJraxxxdQ"
EXPAND ↓
Response

A successful request returns 200 OK along with all users’ details, as an array. Each array entry is a user object with the corresponding attributes. The response data is limited by the query and pagination parameters passed in the request. The response also contains response parameters pertaining to pagination.

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
54
55
56
57
58
59
60
61
62
63
64
{ "users": [ { "properties": [ { "name": "fc_user_timezone", "value": "Asia/Calcutta" } ], "reference_id": "random123@random.com", "restore_id": "d323efcb-1a2e-4ccc-96d0-cb0791481f61", "created_time": "2022-10-13T09:03:34.709Z", "updated_time": "2022-10-27T12:25:15.831Z", "id": "2079f4e7-e608-43d9-acb1-593908ca5426", "first_name": "Alice", "last_name": "Doe", "email": "alice.doe@mail.com", "avatar": {}, "phone": "639528417", "login_status": false }, { "properties": [ { "name": "fc_user_timezone", "value": "Asia/Calcutta" }, { "name": "siteId", "value": "213123" } ], "reference_id": "121", "restore_id": "0663d5f0-f6cc-43f6-bd74-e5d0c0e2cf09", "created_time": "2022-08-29T07:32:07.003Z", "updated_time": "2022-10-27T12:30:39.591Z", "id": "ca03d5ea-9615-4069-8938-bc39e522a436", "first_name": "Alice", "last_name": "John", "email": "alice.john@email.com", "avatar": {}, "phone": "174285396", "login_status": false } ], "pagination": { "total_items": 4, "total_pages": 1, "current_page": 1, "items_per_page": 100 }, "links": { "first_page": { "href": "/v2/users?first_name=Alice&items_per_page=100&sort_order=asc&sort_by=email&page=1", "rel": "user", "type": "GET" }, "last_page": { "href": "/v2/users?first_name=Alice&items_per_page=100&sort_order=asc&sort_by=email&page=1", "rel": "user", "type": "GET" } } }
EXPAND ↓

List a subset of users

Identifies users by the user.ids specified in the request body and retrieves the users’ details, as an array of user objects.

Note: A maximum of 100 user’s details can be retrieved using this API.

post
/v2/users/fetch
Sample request | Curl
Copied Copy
1
2
3
4
5
6
7
8
9
10
curl -X POST "https://peacock.freshchat.com/v2/users/fetch" -H "accept: application/json" -H "Authorization: Bearer eyJraxxxdQ" -H "Content-Type: application/JSON" -d "{ 'ids': [ '2079f4e7-e608-43d9-acb1-593908ca5426', '2deb2a22-703e-4f1d-8527-7bd123c84fd4' ] }"
EXPAND ↓
The request body parameter
Example
1
2
3
4
5
6
{ "ids": [ "2079f4e7-e608-43d9-acb1-593908ca5426", "2deb2a22-703e-4f1d-8527-7bd123c84fd4" ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
ids array of strings Identifiers of the user objects that must be retrieved.
The user.id value is auto-generated when a user record is created in the Freshchat system.
Response

A successful request returns 200 OK along with the retrieved users’ details, as an array. Each array entry is a user object with the corresponding attributes.

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
{ "users": [ { "id": "2079f4e7-e608-43d9-acb1-593908ca5426", "created_time": "2022-10-13T09:03:34.709Z", "updated_time": "2022-10-27T12:25:15.831Z" "avatar": {}, "email": "alice.doe@mail.com", "first_name": "Alice", "last_name": "Doe", "login_status": false, "phone": "639528417", "reference_id": "random123@random.com" }, { "id": "2deb2a22-703e-4f1d-8527-7bd123c84fd4", "created_time": "2022-10-31T00:56:40.218Z", "updated_time": "2022-10-31T10:22:52.190Z" "avatar": { "url": "https://web.freshchat.com/img/johndoe.png" }, "email": "milton.doe@mail.com", "first_name": "Milton", "last_name": "Doe", "login_status": false, "phone": "1234567890", "reference_id": "milton@doe", "restore_id": "2dd06fc0-a48c-4f48-bf7a-ca1ec164a7a0" } ] }
EXPAND ↓

Retrieve user information

Identifies a user by the user_id passed in the request and returns the corresponding information as a user object.

get
/v2/users/{user_id}
Path parameters
Parameter Name Data Type Description
user_idMandatory string Identifier of the user object, auto-generated when a user record is created in the Freshchat system.
Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/users/2deb2a22-703e-4f1d-8527-7bd123c84fd4" -H "accept: application/json" -H "Authorization: Bearer eyJraxxxdQ"
EXPAND ↓
Response

A successful request returns 200 OK along with the retrieved user object.

Create a user

Creates a user object based on the information in the request body. The request body parameter should be a valid JSON object of the specified format.

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
20
21
22
curl -X POST "https://<account>.freshchat.com/v2/users" -H "accept: application/json" -H "Authorization: Bearer eyJraxxxdQ" -H "Content-Type: application/JSON" -d "{ 'avatar': { 'url': 'https://web.freshchat.com/img/johndoe.png' }, 'email': 'milton.doe@mail.com', 'first_name': 'Milton', 'last_name': 'Doe', 'org_contact_id': ' ', 'phone': '235689714', 'properties': [ { 'name': 'orderId', 'value': '#1242' } ], 'reference_id': 'milton@doe', 'restore_id': 'aa0db509-82ac-4043-9b90-7714a8f12e09' }"
EXPAND ↓
The request body parameter
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{ "avatar": { "url": "https://web.freshchat.com/img/johndoe.png" }, "email": "milton.doe@mail.com", "first_name": "Milton", "last_name": "Doe", "phone": "235689714", "properties": [ { "name": "orderId", "value": "#1242" } ], "reference_id": "milton@doe" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
avatar object Image used as the display picture in the user’s profile.
Attributes of the object:
url (string): Link from which the image is fetched.
email string Email address of the user.
first_name string First name of the user.
last_name string Last name of the user.
phone string Phone number of the user.
properties array of objects Custom properties for additional user information. This attribute contains custom property names and the corresponding values, as a valid JSON object of name(custom property name)-value (custom property’s value) pairs.
Attributes of the object:
name (string): Name of the custom property.
value (string): Value of the custom property.
reference_id string User identifier that the system sets for a user when Freshchat is integrated with our Customer Experience suite of products.
Response

A successful request returns 201 Created along with the created user object. The object contains the id, created_at, updated_at, and restore_id attributes. In further API calls, the id that is returned can be used to update the corresponding user information or retrieve further information.

Update user information

Identifies a user object by the user_id passed in the request and updates the object with the information specified in the request body. The request body parameter should be a valid JSON object of the specified format. If an attribute value is null or not passed as part of the request payload, the attribute’s existing value is retained.
Note: Only the values of the attributes email, first_name, last_name, and phone can be updated using this API.

put
/v2/users/{user_id}
Path parameters
Parameter Name Data Type Description
user_idMandatory string Identifier of the user object, auto-generated when a user record is created in the Freshchat system.
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
curl -X PUT "https://<account>.freshchat.com/v2/users/2deb2a22-703e-4f1d-8527-7bd123c84fd4" -H "accept: application/JSON" -H "authorization: Bearer eyJraxxxdQ" -H "content-type: application/JSON" -d "{ 'email': 'milton.doe@mail.com', 'avatar': { 'url': 'https://web.freshchat.com/img/johndoe.png' }, 'phone': '1234567890', 'org_contact_id': 'abcd12345', 'restore_id': ' ', 'properties': [{ 'name': 'orderId', 'value': '#1242' }], 'reference_id': 'milton@doe', 'first_name': 'Milton', 'last_name': 'Doe', 'social_profiles': [{ 'type': 'facebook', 'id': 'milton.doe' }] }"
EXPAND ↓
Response

A successful request returns 202 Accepted. You can use the Retrieve user information API to retrieve and view the updated values.

Retrieve all conversations for a user

Identifies a user by the user_id passed in the request and returns the list of all the conversations associated with the user.

get
/v2/users/{user_id}/conversations
Path parameters
Parameter Name Data Type Description
user_idMandatory string Identifier of the user object, auto-generated when a user record is created in the Freshchat system.
Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/users/16d1bcc2-803a-48f7-bb00-60558d b0b80e/conversations" -H "accept: application/json" -H "Authorization: Bearer eyJraxxxdQ"
EXPAND ↓
Response

A successful request returns 200 OK along with the retrieved conversation ids.

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{ "conversations": [ { "id": "59b838d2-f0ce-4a08-b037-4d8752c95bb3" }, { "id": "317d8288-f770-4dd1-8e27-538a164c2d85" }, { "id": "879dd410-7340-4948-b24e-fb91515ee1d2" }, { "id": "7aa70911-9631-4a81-9424-1a790c7df1aa" } ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the conversation object, auto-generated when a new conversation is created in the Freshchat system.

Delete a user

Identifies a user by the user_id passed in the request and permanently deletes the user’s record from the Freshchat system. The user details cannot be retrieved from the Freshchat system after this delete which primarily serves to meet General Data Protection Regulation (GDPR) requirements.

delete
/v2/users/{user_id}
Path parameters
Parameter Name Data Type Description
user_idMandatory string Identifier of the user object, auto-generated when an user’s information is stored in the Freshchat system.
Sample request | Curl
Copied Copy
1
2
3
curl -X DELETE "https://<account>.freshchat.com/v2/users/ca03d5ea-9615-4069-8938-bc39e522a436" -H "accept: application/json" -H "Authorization: Bearer eyJraxxx7odQ"
EXPAND ↓
Response

A successful request returns 202 Accepted along with the following response.

Example
1
2
3
4
5
6
7
8
{ "id":"ca03d5ea-9615-4069-8938-bc39e522a436", "link":{ "rel":"self", "href":"/users/ca03d5ea-9615-4069-8938-bc39e522a436", "type":"GET" } }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the user object that is to be deleted.
link object Reference to the object being deleted; this reference can be used to construct another API call and verify the deletion status.
Attributes of the object:
rel (string): Relation to the hypertext reference specified as the href value.
href (string): Hypertext reference to verify the deletion status.
type (string): Type of call that must be used when constructing the API call to verify deletion status.

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 objects 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 objects 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 objects 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
17
18
19
20
21
22
23
24
25
26
"messages": [ { "message_parts": [ { "text": { "content": "Conversation was reopened by John" } } ], "reply_parts": [ { "text": { "content": "hello" } } ], "app_id": "032c91b6-4b46-4f5b-adcb-102c72cd4efa", "actor_id": "2823233e-7122-4f87-9d56-38aaaaeb676a", "id": "f0cf8a2a-0772-4cce-be54-ebcb1bc68860", "channel_id": "d2f99658-ff98-44b8-b5c1-3a19dbfe2a2d", "conversation_id": "4ec945ec-6717-409d-9549-198d5d121bd1", "message_type": "normal", "actor_type": "agent", "created_time": "2019-07-29T15:27:17.972Z" } ]
EXPAND ↓
Attributes
Attribute Name Data Type Description
message_partsMandatory array of message part objects Different parts of a message posted to the conversation - plain text, images, or url buttons. The message can be a combination of these attributes.
reply_parts array of message part objects The message an agent posts to a conversation can contain segments (response enablers) that enable a user to respond to the message. The reply_parts attribute contains these segments. The segments can be a text, image, url button, quick reply button, or a collection of these attributes.
A reply_part attribute can exist only if message_part is present.
app_idMandatory string Identifier of the Freshchat account.
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.
actor_id string Identifier of the person who posted the message to the conversation. Must be a valid user.id or agent.id value.
id string Identifier of the message, auto-generated when a message is successfully posted to a conversation.
channel_idMandatory string Identifier of the topic under which the message is posted. Must be a valid channel.id value.
conversation_idMandatory string Identifier of the conversation object. This is an auto-generated value.
message_typeMandatory string Specifies whether the message posted to the conversation is a private message.
Possible values (enum): normal, private
actor_typeMandatory string Descriptive identifier specifying the person who posted the message in the conversation.
Possible values (enum): user, agent
created_time string Timestamp of when the message is posted, specified in the date-time format. The timestamp is returned as part of the response conversation object, when a message is successfully posted.

The message part object

Example 1 - Message with an 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 ↓
Example 7 - Template message with carousel cards
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
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
{ "actor_id": "74e6b867-2dde-4bf9-9bdd-ffb62dcfdde5", "message_type": "normal", "actor_type": "agent", "message_parts": [ { "text": { "content": "Choose one of the following shoes." } } ], "reply_parts": [ { "template_content": { "type": "carousel", "sections": [ { "name": "carousel_title", "parts":[ { "text": { "content": "Choose one of the following shoes." } } ] }, { "name": "cards", "parts": [ { "template_content": { "type": "carousel_card_default", "sections": [ { "name": "hero_image", "parts": [ { "image": { "url": "https://test-s3-local.s3.amazonaws.com/Hyperfeel.jpg" } } ] }, { "name": "title", "parts": [ { "text": { "content": "Nike SB Koston Hyperfeel 3" } } ] }, { "name": "callback", "parts": [ { "callback": { "payload": "sample payload, that is sent in webhooks", "label": "Select" } } ] } ] } }, { "template_content": { "type": "carousel_card_default", "sections": [ { "name": "hero_image", "parts": [ { "image": { "url": "https://test-s3-local.s3.amazonaws.com/NikeLab.jpg" } } ] }, { "name": "title", "parts": [ { "text": { "content": "NikeLab ACG Lupinek Flyknit Low SFB" } } ] }, { "name": "description", "parts": [ { "text": { "content": "Description is optional" } } ] }, { "name": "callback", "parts": [ { "callback": { "payload": "this is payload", "label": "Select" } } ] }, { "name": "view", "parts": [ { "url_button": { "url": "https://test-s3-local.s3.amazonaws.com/NikeLab.jpg", "label": "View", "target": "_self" } } ] } ] } } ] } ] } } ] }
EXPAND ↓
Example 8 - Template message with a drop-down list
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
{ "actor_id": "afd5102c-5443-4fe3-a069-4fe25189a0a1", "message_type": "normal", "actor_type": "agent", "message_parts": [ { "text": { "content": "How many employees do you have?" } } ], "reply_parts": [ { "template_content": { "type": "quick_reply_dropdown", "sections" : [ { "name": "options", "parts" : [ { "quick_reply_button":{ "label": "0-50", "custom_reply_text": "Zero to Fifty", "payload": "Zero to Fifty" } }, { "quick_reply_button":{ "label": "50-100", "custom_reply_text": "Fifty to hundred", "payload": "Fifty to hundred" } }, { "quick_reply_button":{ "label": "500+" } } ] }] } } ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
text text part object Text part of the message posted to a conversation.
Attribute of the text part object:
content (string): Actual content of the text message.
Mandatory
image image part object Image part of the message posted to 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): Location where the link is opened.
Possible values (enum):
_self: Link is opened within the conversation widget.
_blank: Link is opened in a new tab.
Default value: _blank
quick_reply_buttonValid only for reply_part quick reply object The response enabler an agent posts to the conversation can be a quick reply button. The quick_reply_button attribute contains the different components of the button.
Attributes of the quick_reply object:
Custom_reply_text (string): Custom text that is used as reply text.
label (string): Label on the button that is used to give a quick reply.
Mandatory payload (string): Data that is passed to the Freshchat system when a user responds using the quick reply button.
collection Valid only for reply_part collection part object Helps compose a response enabler that is a combination of text, image, url button, and quick reply buttons.
Attribute of the collection part object:
sub_parts (array of message part objects): Different parts of a response enabler posted to a conversation.
In a response object, the collection attribute contains the different segments of the response enabler posted to the conversation. See example 6 for reference.
template_content Valid only for reply_part template content object The response enabler an agent posts to the conversation can be a templated message such as a carousel or drop-down list. The template_content attribute helps compose such a message.
In a response object, the template_content attribute contains different segments of the templated response enabler posted to the conversation.
Attributes of the template content object:
type (string): Identifier of the type of templated message. Mandatory Possible values (enum):
  • carousel: A scrollable list of carousel cards are displayed as response enablers. The template_content.sections values are used to populate the carousel cards. See example 7 for reference.
  • carousel_card_default: A single carousel card is displayed as a response enabler. The template_content.sections values are used to populate the carousel card.
  • quick_reply_dropdown: A drop-down list is displayed as the response enabler. The template_content.sections values are used to populate the drop-down list. See example 8 for reference.

sections (array of sections objects): Segments of the carousel card or drop-down list.
Attributes of the sections object:
name (string): Title of the carousel card or drop-down list displayed in the conversation window.Mandatory parts (array of message part objects): Segments of the carousel card or values for the drop-down list. Mandatory
callback callback part object In a conversation, the reply message can be a carousel card which has the callback attribute.
Attributes of the callback part object:
payload (string): Data that is passed to the Freshchat system when a user responds using the carousel card.
label (string): Text that is displayed on the button.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_agent_id attribute.

Agents

Freshchat enables organizations to converse with their customers. Agents are the organization’s members who use Freshchat to converse with their customers.
When a conversation is initiated, an agent is manually or automatically assigned based on the assignment rules defined in the Freshchat system.

Endpoints

GET /agents
POST /agents
GET /agents/status
DELETE /agents/{agent_id}
PATCH /agents/{agent_id}
GET /agents/{agent_id}
PUT /agents/{agent_id}

The agent 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
{ "id": "1ab37a05-7b3e-42ee-bcbe-283fd093408c", "created_time": "2022-10-12T22:56:14.825Z", "agent_capacity": 0, "agent_status": { "name": "Inactive on Intelli Assign" }, "availability_status": "UNAVAILABLE", "avatar": { "url": "https://web.freshchat.com/img/johndoe.png" }, "biography": "Hi!!I am your Technical Support Engineer", "email": "alice.adrian@email.com", "first_name": "Alice", "freshid_group_ids": [], "freshid_uuid": "", "groups": [ "a9a02944-cadd-454f-91a4-2165f37a2737" ], "is_deactivated": false, "is_deleted": false, "last_name": "Adrian", "license_type": "fulltime", "locale": "en-us", "login_status": false, "org_contact_id": "", "role_id": "AGENT", "role_name": "Agent", "routing_type": "INTELLIASSIGN", "skill_id": "44bb89c8-0aa3-4f83-a07c-d75e909f253d", "social_profiles": [{ "type": "facebook", "id": "alice.adrian" }], "timezone": "Asia/Kolkata" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the agent object, auto-generated when an agent information is configured in the Freshchat system.
created_time string Timestamp of when the agent’s record was created in the Freshchat system, specified in the UTC format.
agent_capacity integer Number of active conversations that the agent can handle when the agent is active on IntelliAssign.
agent_status object Omniroute, Intelliassign, or Custom status of the agent.
A business can add new custom statuses, such as Away, In a meeting, and so on, if the custom activity state feature is enabled for a business account that uses Freshchat.
Attributes of the object:
id (string): Identifier of custom status, auto-generated when a new status is added to the Freshchat system.
name (string): Status message.
availability_status string Status of the agent’s availability for conversation auto-assignment.
Possible values: AVAILABLE, UNAVAILABLE
Default value: AVAILABLE
avatar object Image used as the display picture in the agent’s profile.
Attributes of the object:
url (string): Link from which the image is fetched.
biography string Meaningful description about the agent.
email string Email address of the agent.
first_name string First name of the agent.
freshid_group_ids array of strings Identifiers (in the Freshworks’ master record) of the groups to which the agent belongs, specified as an array.
freshid_uuid string Universally unique identifier of the agent across Freshworks’ master record.
groups array of strings Identifiers (in the Freshchat system) of the groups to which the agent belongs, specified as an array.
is_deactivated boolean Specifies whether the agent is deactivated in the Freshchat system.
Possible values: true, false
is_deleted boolean Specifies whether the agent’s details are deleted from the Freshchat system.
Possible values: true, false
last_name string Last name of the agent.
license_type string Employment terms that apply to the agent. For example, Fulltime, Occasional, and so on.
locale string Language associated with the agent’s location, specified in the ISO-639 code.
login_status boolean Specifies whether the agent is logged into the Freshchat system.
Possible values: true, false
org_contact_id string Auto-generated identifier of the Freshchat agent, created when the agent is saved as a contact in the Freshworks’ system.
phone string Phone number of the agent.
role_id string System-generated identifier of the role assigned to the agent, that specifies the level of access permissions the agent has in the Freshchat system.
role_name string Meaningful identifier of the agent’s role that specifies the agent’s level of access in the Freshchat system.
The default roles are Account admin, Admin, Super user, and Agent. An account admin can define custom roles in the Freshchat system.
routing_type string Assignment rule to which the agent is associated.
Incoming conversations can be auto-assigned to agents either through custom defined assignment rules or through (load-based, bandwidth-based) IntelliAssign/Omniroute rules.
Possible values:
  • Intelliassign: Agent is associated with an IntelliAssign rule.
  • OCR: Agent is associated with an Omniroute rule.
DISABLED: Agent is not associated with IntelliAssign/Omniroute rules or is associated with a custom assignment rule.
scope string Level of access that the agent has to the conversations created in the Freshchat system. scope values depend on the role associated with the agent.
Possible values:
Global: Agent can use specific features on all conversations in the Freshchat system.
Group: Agent can use specific features on all conversations assigned to the group to which the agent belongs.
Me: Agent can use specific features only on conversations assigned to the agent.
None: Agent has not been assigned any role.
skill_id string Identifier of the load level mapped to the agent. Load levels define the number of active conversations that an agent can handle, when incoming conversations are assigned to the agent, through IntelliAssign.
When a new load level is created in the Freshchat system, a skill_id value is auto-generated and assigned to the load level.
social_profiles array of objects Details of the agent’s social media profiles, specified as an array of objects.
Attributes of the object:
id (string): User handle of the agent’s social profile.
type (string): Name of the social media platform.
Possible values: facebook, twitter, skype, linkedin
timezone string Timezone to which the agent belongs, in the Area/Location format. For example, Asia/Kolkata, America/Toronto, US/Michigan, and so on.

List all agents

Retrieves a list of all the agents configured in the Freshchat system.

get
/v2/agents
Query parameters

You can use a combination of the following query parameters and pagination parameters to limit or filter the bulk response data. Ensure that the query parameter values are URL encoded.

Parameter Name Description Example
is_deactivated Limits the response to agent objects whose is_deactivated value matches the parameter value.
Valid values: true, false

GET /agents?is_deactivated=true

groups Limits the response to agent objects where at least one of the groups value matches the string specified as the parameter value.

GET /agents?groups=38dd7cdc-d022-4489-8cb5-4fdc35f0b5a7

availability_status Limits the response to agent objects whose availability_status value matches the parameter value.
Valid values: AVAILABLE, UNAVAILABLE

GET /agents?availability_status=UNAVAILABLE

Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/agents?page=1&items_per_page=2&sort_order=asc" -H "accept: application/json" -H "Authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
EXPAND ↓
Response

A successful request returns 200 OK along with all agents’ details, as an array. Each array entry is an agent object with the corresponding attributes. The response data is limited by the query and pagination parameters passed in the request. The response also contains response parameters pertaining to pagination.

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
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
{ "agents": [ { "groups": [], "role_id": "ACCOUNT_ADMIN", "role_name": "Account Admin", "is_deactivated": true, "is_deleted": false, "locale": "en-us", "timezone": "Asia/Kolkata", "availability_status": "UNAVAILABLE", "agent_status": { "name": "Inactive on OCR" }, "routing_type": "INTELLIASSIGN", "agent_capacity": 2, "created_time": "2019-08-14T09:08:11.215Z", "id": "a6cc8807-0bc5-49d9-88fc-d9e06ace8c09", "first_name": "John", "last_name": "Doe", "email": "newagent.helouser@yopamil.com", "avatar": {}, "social_profiles": [], "login_status": false }, { "biography": "This is supposed to be bio for agent.", "groups": [], "role_id": "ACCOUNT_ADMIN", "role_name": "Account Admin", "is_deactivated": true, "is_deleted": false, "locale": "en-us", "availability_status": "UNAVAILABLE", "agent_status": { "name": "Inactive on Intelli Assign" }, "routing_type": "INTELLIASSIGN", "agent_capacity": 2, "created_time": "2019-04-11T13:38:16.485Z", "id": "d37b9c8f-ec59-4c72-9b1d-c06edcb36de1", "first_name": "Jane", "last_name": "Doe", "email": "aaa.aaa@yopmail.com", "avatar": {}, "social_profiles": [ { "type": "twitter", "id": "tweetme" } ], "login_status": false }], "pagination": { "total_items": 632, "total_pages": 316, "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=316", "rel": "agent", "type": "GET" } } }
EXPAND ↓

Create an agent

Creates an agent object based on the information specified in the request body. The request body parameter should be a valid JSON object of the specified format.

post
/v2/agents
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
29
curl -X POST "https://<account>.freshchat.com/v2/agents" -H "accept: application/JSON" -H "authorization: Bearer eyJraWQiOiJjxxxdz2Dkl-I" -H "content-type: application/JSON" -d "{ 'email': 'alice.adrian@email.com', 'avatar': { 'url': 'https://web.freshchat.com/img/johndoe.png' }, 'phone': '123456789', 'biography': 'Hi, I am your Technical Support Engineer.', 'role_id': 'AGENT', 'role_name': 'Agent', 'skill_id': '44bb89c8-0aa3-4f83-a07c-d75e909f253d ', 'locale': 'en-us', 'timezone': 'Asia/Kolkata', 'first_name': 'Alice', 'last_name': 'Adian', 'social_profiles': [ { 'id': alice.adrian', 'type': 'facebook' } ], 'groups': [ 'a9a02944-cadd-454f-91a4-2165f37a2737' ] }"
EXPAND ↓
The request body parameter
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
{ "avatar": { "url": "https://web.freshchat.com/img/johndoe.png" }, "biography": "Hi, I am your Technical Support Engineer.", "email": "alice.adrian@email.com", "first_name": "Alice", "groups": [ "a9a02944-cadd-454f-91a4-2165f37a2737" ], "last_name": "Adian", "license_type": "FULLTIME" "locale": "en-us", "org_contact_id": "138763287863827323", "phone": "123456789", "role_id": "AGENT", "role_name": "Agent", "skill_id": "44bb89c8-0aa3-4f83-a07c-d75e909f253d", "social_profiles": [ { "type": "facebook", "id": "alice.adrian" } ], "timezone": "Asia/Kolkata" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
avatar object Details of the image used as the avatar for the agent profile.
Attributes of the object:
url (string): Link from which the image is fetched.
biography string Meaningful description about the agent.
emailMandatory string Email address of the agent.
first_name string First name of the agent.
groups array of strings Identifiers of the groups to which the agent belongs, specified as an array.
last_name string Last name of the agent.
locale string Language associated with the agent’s location, specified in the ISO-639 code.
phone string Phone number of the agent.
role_id string System-generated identifier of the role assigned to the agent.
role_name string Meaningful identifier of the agent’s role in the Freshchat system.
skill_id string Identifiers of the skill or load mapped to the agent.
social_profiles array of objects Details of the agent’s social media profiles, specified as an array.
Attributes of the object:
id (string): User handle of the agent’s social profile.
type (string): Name of the social media platform.
Possible values: facebook, twitter, skype, linkedin
timezone string Timezone to which the agent belongs, in the Area/Location format. For example, Asia/Kolkata, America/Toronto, US/Michigan, and so on.
Response

A successful request returns 201 Created along with the created agent object. The object contains the id, created_at, and updated_at attributes. In further API calls, the id that is returned can be used to update the corresponding agent information or retrieve information.

Retrieve agent information

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

get
/v2/agents/{agent_id}
Path parameters
Parameter Name Data Type Description
agent_idMandatory string Identifier of the agent object, auto-generated when an agent information is configured in the Freshchat system.
Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/agents/1ab37a05-7b3e-42ee-bcbe-283fd093408c" -H "accept: application/json" -H "Authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
EXPAND ↓
Response

A successful request returns 200 OK along with the retrieved agent object.

Update agent information

Identifies an agent object by the agent_id passed in the request and updates the object with the information specified in the request body. The request body parameter should be a valid JSON object of the specified format. If an attribute value is null or not passed as part of the request payload, the attribute’s existing value is retained.

put
/v2/agents/{agent_id}
Path parameters
Parameter Name Data Type Description
agent_idMandatory string Identifier of the agent object, auto-generated when an agent information is configured in the Freshchat system.
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
29
30
curl -X PUT "https://<account>.freshchat.com/v2/agents/1ab37a05-7b3e-42ee-bcbe-283fd093408c" -H "accept: application/JSON" -H "authorization: Bearer eyJraWQiOiJjxxskdz2Dkl-I" -H "content-type: application/JSON" -d "{ 'email': 'alice.adrian@email.com', 'avatar': { 'url': 'https://web.freshchat.com/img/johndoe.png' }, 'phone': '123456789', 'biography': 'Hi!!I am your Technical Support Engineer', 'role_id': 'AGENT', 'role_name': 'Agent', 'skill_id': '44bb89c8-0aa3-4f83-a07c-d75e909f253d ', 'locale': 'en-us', 'timezone': 'Asia/Kolkata', 'first_name': 'Alice', 'last_name': 'Adrian', 'social_profiles': [ { 'type': 'facebook', 'id': 'alice.adrian' } ], 'groups': [ 'a9a02944-cadd-454f-91a4-2165f37a2737' ], 'license_type': 'FULLTIME' }"
EXPAND ↓
Response

A successful request returns 200 OK along with the updated agent object.

List all agent statuses

Retrieves a list of all custom statuses configured in the Freshchat system. A business can add new custom statuses, such as Away, In a meeting, and so on, if the custom activity state feature is enabled for a business account that uses Freshchat.

get
v2/agents/status
Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/agents/status" -H "accept: application/json" -H "Authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
EXPAND ↓
Response

A successful request returns 200 OK along with all agents’ status, as an array. Each array entry is an agent status object with the corresponding attributes.

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
{ "states": [ { "id": "b75c38ce-7471-4db9-900f-238cd1b51938", "name": "BRB" }, { "id": "0c5a8e92-a6ad-4a7b-918f-5279760d2c4f", "name": "lol" }, { "id": "3f2c438e-cb78-45dc-a395-fa53363119f3", "name": "online test" }, { "id": "f5f09dc1-f09d-45f5-b776-e577874a08ac", "name": "testStatus" }, { "id": "fa8230ff-cfbc-4e62-8ecc-419d38ffb068", "name": "Testing " }, { "id": "ca6cfff6-73c9-4b0d-808f-d195990f136f", "name": "test" }, { "id": "edca4f45-6fda-4613-a17c-7c118931c4bc", "name": "Happy vacations" }, { "id": "0062b314-5b7d-466f-963e-1e0a723d4d64", "name": "In a meeting" }, { "id": "822965c6-4069-4d37-ab20-9086fca35d58", "name": "sleep" }, { "id": "f3e21aee-b5b0-417e-a113-796e865ad273", "name": "Unstoppable" }, { "id": "4e669421-ff3a-461e-8a34-e28f73d6e817", "name": "Vacation" } ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the status object, auto-generated when a new custom status is configured in the Freshchat system.
name string Status message.

Update agent status

Identifies an agent by the agent_id passed in the request and updates the status of the agent with the status specified in the request body.

Notes:
1. To view the list of status values that can be used to update an agent’s current status, use the List all agent statuses API.
2. You can use this API only to update an agent’s existing status (IntelliAssign/OCR/Custom status) to a custom status. You cannot use this API to update a custom status to IntelliAssign/OCR states (Active/Inactive).

patch
/v2/agents/{agent_id}
Path parameters
Parameter Name Data Type Description
agent_idMandatory string Identifier of the agent object, auto-generated when an agent information is configured in the Freshchat system.
Sample request | Curl
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
curl -X PATCH https://<account>.freshchat.com/v2/agents/1de5d130-1c62-48cf-8349-1b39c60d0c28 -H "accept: application/JSON" -H "authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I" -H "content-type: application/JSON" -d "{ "agent_status": { "id": "0062b314-5b7d-466f-963e-1e0a723d4d64", "name": "In a meeting" } }"
EXPAND ↓
The request body parameter
Example
1
2
3
4
5
"agent_status": { "id": "0062b314-5b7d-466f-963e-1e0a723d4d64", "name": "In a meeting" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
agent_status object Value that has to be updated as the current agent status.
Attributes of the object:
id (string): Identifier of custom status, auto-generated when a new status is added to the Freshchat system. Should be a valid states.id value.
name (string): Status message. Should be a valid states.name value.
Note: If no value is specified for agent_status the previous status is retained.
Response

A successful request returns 200 OK along with the following response; availability_status specifies the agent’s availability for conversation auto-assignment, based on the updated status.

Example
1
2
3
4
5
6
7
{ "availability_status": "UNAVAILABLE", "agent_status": { "id": "0062b314-5b7d-466f-963e-1e0a723d4d64", "name": "In a meeting" } }
EXPAND ↓

Delete an agent

Identifies an agent by the agent_id passed in the request and permanently deletes the agent’s record from the Freshchat system. The agent details cannot be retrieved from the Freshchat system after this delete which primarily serves to meet General Data Protection Regulation (GDPR) requirements.

delete
/v2/agents/{agent_id}
Path parameters
Parameter Name Data Type Description
agent_idMandatory string Identifier of the agent object, auto-generated when an agent information is configured in the Freshchat system.
Sample request | Curl
Copied Copy
1
2
3
curl -X DELETE "https://<account>.freshchat.com/v2/agents/c6c3a1b2-00d8-4d42-8ff7-4abb4c7fc496" -H "accept: application/json" -H "Authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
EXPAND ↓
Response

A successful request returns 202 Accepted along with the corresponding response message.

Example
1
2
3
4
5
{ "code": 202, "status": "ACCEPTED", "message": "Agent deletion request accepted" }
EXPAND ↓

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.

Groups

A business can organize its agents into different groups. Conversations can be assigned to these groups manually or through auto-routing. Any agent in the group can pick a conversation, assign it to self, and resolve the queries in the conversation.

Endpoint

GET /groups

The group object

Example
1
2
3
4
5
6
7
{ "id": "b23cd57a-0c28-47a5-8fbf-3807cdcf80c0", "name": "Automation", "description": "Group that handles automation", "routing_type": "OCR", "routing_logic": "OCR" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the group, auto-generated when a group is configured in the Freshchat system.
name string Name of the group.
description string Meaningful description about the group.
routing_type string Type of auto-routing associated with the group.
Possible values:
  • INTELLIASSIGN: The auto-routing mechanism that assigns conversations to the group is IntelliAssign. For information on how IntelliAssign works, see What is IntelliAssign in Freshchat?
  • OCR: The auto-routing mechanism that assigns conversations to the group is Omni-channel routing. For information on how Omni-channel routing works, see What is Omni-route?
  • DISABLED: Auto-assignment through IntelliAssign/omniroute is disabled.

Note: If conversations are routed to a group through Assignment rules, routing_type is DISABLED.
routing_logic string Routing logic based on which conversations are auto-assigned.
Possible values:
  • DISABLED: If auto-routing through Intelliassign/Omiroute is disabled for all groups (at account level), routing_logic is DISABLED.

If routing_type is INTELLIASSIGN, the routing_logic can be one of the following:
  • LOAD_BASED
  • ROUND_ROBIN

For information on load based and round robin logic, see Choose IntelliAssign logic.
If routing_type is OCR, the routing_logic is OCR.
Note: For a specific group, if IntelliAssign/Omniroute is disabled, the routing_logic attribute specifies the logic that is set at the account level.

List all groups

Retrieves a list of all the groups configured in the Freshchat system.

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
3
4
curl -X GET "https://<account>.freshchat.com/v2/groups?page=1&items_per_page=10&sort_order=asc&sort_by=name" -H "accept: application/json" -H "Authorization: Bearer eyJxyzQ"
EXPAND ↓
Response

A successful request returns a 200 OK along with the groups array. Each array element is a group object. The response is curated based on the pagination parameters passed in the request. The response also contains response parameters pertaining to pagination.

Example 1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{ "groups": [ { "id": "d56d224e-1a7c-4520-8134-074143f8d958", "name": "Sales", "description": "Group to handle Sales related queries", "routing_type": "OCR", "routing_logic": "OCR" }, { "id": "1cb699d5-12c1-4cac-acbd-d95c8f75e497", "name": "Support", "description": "Group to handle support tickets", "routing_type": "DISABLED", "routing_logic": "OCR" }, { "id": "b23cd57a-0c28-47a5-8fbf-3807cdcf80c0", "name": "Automation", "description": "Group that handles automation", "routing_type": "OCR", "routing_logic": "OCR" } ] }
EXPAND ↓
Example 2
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{"groups": [ { "id": "d56d224e-1a7c-4520-8134-074143f8d958", "name": "Sales", "description": "Group to handle Sales related queries", "routing_type": "DISABLED", "routing_logic": "DISABLED" }, { "id": "1cb699d5-12c1-4cac-acbd-d95c8f75e497", "name": "Support", "description": "Group to handle support tickets", "routing_type": "DISABLED", "routing_logic": "DISABLED" }, { "id": "b23cd57a-0c28-47a5-8fbf-3807cdcf80c0", "name": "Automation", "description": "Group that handles automation", "routing_type": "DISABLED", "routing_logic": "DISABLED" } ] }
EXPAND ↓
Example 3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{"groups": [ { "id": "d56d224e-1a7c-4520-8134-074143f8d958", "name": "Sales", "description": "Group to handle Sales related queries", "routing_type": "INTELLIASSIGN", "routing_logic": "ROUND_ROBIN" }, { "id": "1cb699d5-12c1-4cac-acbd-d95c8f75e497", "name": "Support", "description": "Group to handle support tickets", "routing_type": "INTELLIASSIGN", "routing_logic": "ROUND_ROBIN" }, { "id": "b23cd57a-0c28-47a5-8fbf-3807cdcf80c0", "name": "Automation", "description": "Group that handles automation", "routing_type": "DISABLED", "routing_logic": "ROUND_ROBIN" } ] }
EXPAND ↓

Images

As part of Freshchat conversations, agents can send and receive images. The agents can upload, store, and retrieve the images from a file system (backed by an S3 bucket) in Freshchat. This API enables uploading an image to an S3 bucket linked to the Freshchat account.

Endpoints

POST /images/upload

Upload an image

Uploads an image from the file path passed in the request and returns a pre-signed URL to access the image from the S3 bucket to which the image is uploaded.

post
v2/images/upload
Sample request | Curl
Copied Copy
1
2
3
4
5
curl -X POST "https://<account>.freshchat.com/v2/images/upload" -H "accept: application/json" -H "Authorization: Bearer eyJraWQiOiJjxxxk6xsM" -H "Content-Type: multipart/form-data" -F "image=@C:\Users\abc\Desktop\sample_image.PNG;type=image/png"
EXPAND ↓
The request body parameter
Example
1
image=@C:\Users\abc\Desktop\sample_image.PNG;type=image/png
EXPAND ↓
Attributes
Attribute Name Data Type Description
imageMandatory multipart formData
Note: Ensure that the Content-Type request header is set to multipart/form-data
[Part1] image part specifies the location from which the media file is retrieved for upload.
[Part2] type part specifies the media format.
Response

A successful request returns 201 Created along with a pre-signed URL from which the image can be retrieved.

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{ "id": "fe2c7241-46b5-42c2-8ef4-f814a79f2768", "content_type": "image/png", "height": 345, "name":"img_h7nco0371v_7c2bf570.png", "thumbnail": { "url":"https://fc-bkt-00.s3.amazonaws.com/f5axxxc4f1/f_marketingPicThumb/u_1710xxx23d7/img_coak8f09m7_38bb429e3b9428xxx4e11f.jpeg", "content_type": "image/jpeg", "width": 400, "height": 309 }, "url":"https://fc-bkt-00.s3.amazonaws.com/f5axxxc4f1/img_h7nco0371v_7c2bf570.png", "width": 446 }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the image object, auto-generated when an image is uploaded to the S3 bucket.
content_type string Format of the uploaded file. For example, image/png.
height integer Original height of the image uploaded.
name string Identifier of the uploaded image.
thumbnail object Details of the image that can be retrieved from the S3 bucket.
Attributes of the object:
url (string): S3 bucket from where the uploaded image can be retrieved.
content_type (string): Format of the image on retrieval. For example, image/jpeg.
width (integer): Width of the compressed image.
height (integer): Height of the compressed image.
url string S3 bucket where the uploaded image is stored in its original format.
width integer Original width of the uploaded image.

Roles

An agent's access privileges within the Freshchat system is based on the role assigned to the agent. Each role comes with a predefined set of privileges. In addition to the default roles such as account admin, admin, support manager, and support agent can configure custom roles with customized privileges in the Freshchat system. For more information on roles, see Roles and permissions in Freshchat.

Endpoints

GET /roles

The role object

Example
1
2
3
4
5
6
{ "id": "ACCOUNT_ADMIN", "name": "Account Admin", "is_custom_role": false, "description": "Primary stakeholder of the business account" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the role object, auto-generated when a new role is configured in the Freshchat system.
name string Name of the role.
is_custom_role boolean Specifies whether the role is a custom role.
Possible values: true, false
description string Meaningful description about the role.

List all roles

Retrieves a list of all valid roles configured in the Freshchat system.

get
/v2/roles
Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/roles?page=1&items_per_page=10&sort_order=asc&sort_by=name" -H "accept: application/json" -H "Authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
EXPAND ↓
Response

A successful request returns 200 OK along with all roles’ details, as an array. Each array entry is a role object with the corresponding attributes. The response data is limited by the valid query parameters passed in the request. The response also contains response parameters pertaining to pagination.

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
{ "roles": [ { "id": "ACCOUNT_ADMIN", "name": "Account Admin", "is_custom_role": false, "description": "Primary stakeholder for the business account." }, { "id": "ADMIN", "name": "Admin", "is_custom_role": false, "description": "Stakeholder with all Admin permissions." }, { "id": "AGENT", "name": "Agent", "is_custom_role": false, "description": "Account partner with agent level permissions." }, { "id": "8bee5c99-2695-436c-a266-5cb310190406", "name": "Internal agent", "is_custom_role": true, "description": "Account executive identified as an internal agent." }], "pagination": { "total_items": 37, "total_pages": 4, "current_page": 1, "items_per_page": 10 }, "links": { "next_page": { "href": "/v2/roles?sort_by=name&items_per_page=10&sort_order=asc&page=2", "rel": "role", "type": "GET" }, "first_page": { "href": "/v2/roles?sort_by=name&items_per_page=10&sort_order=asc&page=1", "rel": "role", "type": "GET" }, "last_page": { "href": "/v2/roles?sort_by=name&items_per_page=10&sort_order=asc&page=4", "rel": "role", "type": "GET" } } }
EXPAND ↓

Outbound-messages

A business can use its Freshchat account and send messages, in predefined formats, to clients who opt for notifications. These messages could be information about deliveries, purchases, payments, appointments, and so on.

The templated message that a business sends to its clients can be a plain text message, a rich media templated message consisting of a header and body or an interactive message with Call-to-Action and Quick Reply buttons attached to the text message or rich-media message. The rich media header can consist of an image, video, document attachment, and title with any number of variables. The body can consist of a text with any number of variables. A business defines the message template, with placeholders for rich media and parameters that can be populated when the message is sent, and submits the template to Freshchat. Freshchat seeks approval from the third-party provider whose services are used to send the templated message to clients. After the provider approves the template, Freshchat provides the template identifier and namespace obtained from the third-party provider to the business. The business can use this data and the Freshchat outbound-messages API to populate the message template with actual data and send the message to the business user. For information on the process around message template submission and approval, see WhatsApp Proactive Messages.

Note: For more information on interactive message templates, see Sending Interactive Message Templates.

Endpoints

POST /outbound-messages/whatsapp
GET /outbound-messages

The outbound message 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
{ "message_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9", "from": { "phone_number": "+919999999999" }, "provider": "whatsapp", "to": [ { "phone_number": "+919999999999" } ], "data": { "message_template": { "storage": "conversation", "template_name": "shipping_update", "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX", "language": { "policy": "deterministic", "code": "en_US" }, "rich_template_data": { "body": { "params": [{ "data": "Username"} ] } } } }, "request_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9", "status": "Failed", "created_on": 1566970961, "failure_code": "OBM001", "failure_reason": "no template exists" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
message_id (response attribute) string Identifier of an outbound message, auto-generated when a request to send an outbound message is triggered.
from mandatory user handle object Business number integrated with the Freshchat account, from which the message is sent.
providermandatory string Channel through which messages are received by the client.
Possible value: whatsapp
tomandatory array of user handle objects List of recipient’s numbers or handles to which the message is sent.
datamandatory data object Data posted to the recipient, specified as a message template object.
request_id(response attribute) string Identifier of the request to send an outbound message, auto-generated when the request is triggered. A successful API request to send outbound messages, returns this attribute as part of the response object. Further API requests can use the returned value to identify the request and retrieve all outbound messages sent through the processing of the request.
status mandatory string Status of the message.
Possible values (enum):
Accepted: Message receipt is acknowledged by the recipient.
Sent: Message is sent to the recipient.
Delivered: Message is delivered to the recipient.
Failed: Message delivery failed. If status is failed, the failure_code and failure_reason attributes are present in the response object.
failure_code(response attribute) string Code that can be cross-referenced with failure_reason to understand why the request to send an outbound message failed.
failure_reason(response attribute) string Reason why the request to send an outbound message failed.
created_on(response attribute) integer Timestamp of when the request to send the message is triggered, specified in the epoch format.

Attributes of the user handle object

Attribute Name Data Type Description
phone_number string Number from or to which messages are sent.

Attributes of the message template object

Attribute Name Data Type Description
storage string Specifies whether the templated message sent to the user is reconstructed for the agent, in a conversation.
When a user replies to a templated message, the response is sent as a message to the Freshchat account. The templated message sent to the user is reconstructed and displayed in the conversation, based on the value of storage.
Possible values:
  • none (string): Details of the templated message sent to the user are not displayed in the conversation. Instead, the default message, Proactive message was sent to the user is displayed in the conversation.
  • conversation (string): The templated message sent to the user is reconstructed in the conversation. The user’s chosen reply to the templated message is also displayed in the conversation.
    Note: When the storage attribute value is conversation, the templated message is reconstructed for the agent only if a user replies to the templated message within 30 days from when the message is sent.
template_namemandatory string Identifier of a template within a namespace.
This is the template name that Freshchat submits to WhatsApp, on behalf of the business that uses Freshchat.
For information on the process around message template submission and approval, see WhatsApp Proactive Messages.
namespacemandatory string Unique identifier of a business’s Whatsapp account.
This is the namespace generated by Whatsapp and shared with Freshchat after the business’s message templates are approved by Whatsapp.
For information on the process around message template submission and approval, see WhatsApp Proactive Messages.
languagemandatory language object Language in which the message is sent.
To send messages in a language other than English, the business must submit the other language’s template content to Freshchat. Freshchat would submit the template content to WhatsApp and return the approved template ID and namespace to the business.
For more information, see WhatsApp Proactive Messages.
Attributes of the language object:
  • policy (string): The language policy used for sending messages based on language or locale.
    Possible value:
    deterministic: Message is delivered in the specified language irrespective of the language or locale of the device the message is delivered to.
  • code (string): Code corresponding to the supported languages for WhatsApp Proactive Messaging templates.
template_dataDEPRECATED array of template data objects Deprecation notice: This attribute is deprecated and exists only for backward compatibility.
To specify the values that are used to populate the variable parameters in a plain text message, use the rich_template_data attribute with the rich_template_data.type value set to text.
rich_template_dataMANDATORY rich media template data object Components, such as image, video, or document attachment, that are used to populate the header section of a templated message and the variable parameters that are used to populate the placeholders defined in the title and body text of the templated message, specified in a format that follows the WhatsApp proactive messaging guidelines.
Attributes of the rich media template data object:
  • header (object): Header components, specified as an object with the following attributes:
    • type (string): Type of the header component. For example, text, image, document, video.
    • media_url (string): Link to the location from where the image, video, or document to be attached is fetched and populated in the header section.
    • params (array of data objects): Values used to populate the variable parameters in the message title, if header.type is text.
  • body (object): Values used to populate the variable parameters in the body section of the predefined template message, specified as an object of the following format:

    {
    "params": [
    {"data": "<variableParam1>"},
    {"data": "<variableParam2>"}
    ]
    }

Example:
The template message is: Hi {{1}}, your order no. {{2}} has been placed.
The rich_template_data.body is:

{
"params": [
{"data": "John Doe"},
{"data": "IDxyz"}
]
}

The message body sent to the business user’s Whatsapp number is:
Hi John Doe, your order no. IDxyz has been placed.
Examples
  • In the request to send a plain text templated message, the outbound message object used as the request payload is as follows:

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
{ "message_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9", "from": { "phone_number": "+919999999999"}, "provider": "whatsapp", "to": [{ "phone_number": "+919999999999" }], "data": { "message_template": { "storage": "conversation", "template_name": "shipping_update", "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX", "language": { "policy": "deterministic", "code": "en_US" }, "rich_template_data": { "body": { "params": [{ "data": "Username"} ] } } } }, "request_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9", "status": "Failed", "created_on": 1566970961, "failure_code": "OBM001", "failure_reason": "no template exists" }
EXPAND ↓
  • In the request to send templated message with image and text, the outbound message object used as the request payload is as follows:

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
{ "from": { "phone_number": "+919999999999" }, "to": [{ "phone_number": "+919999999999" }], "data": { "message_template": { "storage": "none", "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX", "template_name": "shipping_update_1", "language": { "policy": "deterministic", "code": "en_US" } "rich_template_data": { "header": { "type": "image", "media_url": "https://sample.in/sample.jpg" }, "body": { "params": [{ "data": "Username"} ] } } } } }
EXPAND ↓
  • In a request to send a plain text message with interactive buttons such as Quick Reply, the outbound message object sent as the request payload is as follows:
    Note: In the payload, as the data.message_template.storage value is none, the templated message is not reconstructed for the agent.

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
{ "from": { "phone_number": "+919999999999" }, "provider": "whatsapp", "to": [{ "phone_number": "+919999999999"}], "data": { "message_template": { "storage": "conversation", "template_name": "shipping_update_2", "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX", "language": { "policy": "deterministic", "code": "en_US" }, "rich_template_data": { "body": { "params": [{ "data": "Username"} ] } } } } }
EXPAND ↓
  • In a request to send a rich-media templated message with interactive buttons, the outbound message object sent as the request payload is as follows:
    Note: In the payload, as the data.message_template.storage value is none, the templated message is not reconstructed for the agent.

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
{ "from": { "phone_number": "+919999999999"}, "to": [{ "phone_number": "+919999999999"}], "data": { "message_template": { "storage": "none", "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX", "template_name": " shipping_update_3", "language": { "policy": "deterministic", "code": "en_US" }, "rich_template_data": { "header": { "type": "image", "media_url": "https://sample.in/sample.jpg" }, "body": { "params": [{ "data": "Username"} ]} } } } }
EXPAND ↓
  • In a request to send a rich-media templated message with interactive call to action buttons, the outbound message object sent as the request payload is as follows:
    Note: In the payload, as the data.message_template.storage value is none, the templated message is not reconstructed for the agent.

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
{ "from": { "phone_number": "+919999999999"}, "to": [{ "phone_number": "+919999999999"}], "data": { "message_template": { "storage": "none", "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX", "template_name": " shipping_update_4", "language": { "policy": "deterministic", "code": "en_US" }, "rich_template_data": { "header": { "type": "image", "media_url": "https://sample.in/sample.jpg" }, "body": { "params": [{ "data": "Username"} ]} } } } }
EXPAND ↓

Send outbound messages

Creates a request to send whatsapp messages to users.
Note: If the request to send a templated message contains an incorrect template name, the request fails. If a template with the name specified in the request is approved, you can send a message with the approved template name only after 30 minutes from the initial failure.

post
/v2/outbound-messages/whatsapp
Sample request | Curl
Copied Copy
1
2
3
4
curl -X POST "https://api.freshchat.com/v2/outbound-messages/whatsapp" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpS216TTVXXX_U5X2A" -d '{ "from": { "phone_number": "+919999999999" }, "provider": "whatsapp", "to": [ { "phone_number": "+919999999999" } ], "data": { "message_template": { "storage": "none", "template_name": "hello_world", "namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3f", "language": { "policy": "deterministic", "code": "en_US" }, "rich_template_data": { "header": { "type": "text", "params": [ { "data": "John Doe" } ] }, "body": { "params": [ {"data": "XYZ"} ] } } } } }'
EXPAND ↓
Response
A successful request returns 202 along with the following response object.
Response object
1
2
3
4
5
6
7
8
{ "request_id": "0fcdd6b6-1f80-4643-a294-8e0625ce30dd", "request_process_time": "1", "link": { "rel": "string", "href": "string" } }
EXPAND ↓
Attributes
Attribute Name Data Type Description
request_idmandatory string System-generated identifier for the request.
request_process_timemandatory string Time taken to process the request, specified in seconds.
linkmandatory link object Reference to the request.
Attributes of the link object:
rel (string): Type of link relationship between the resource accessed by the href URL and the source from which the resource is referenced.
href (string): Reference to access the request.

List all outbound messages

Retrieves a list of all outbound messages sent from the Freshchat account.

get
/v2/outbound-messages
Query parameters

You can use the following query parameter to filter the bulk response data by request_id.

Parameter Name Description Example
request_id Identifier of the request to send an outbound message. A successful API request to send outbound messages, returns this attribute as part of the response object.
This parameter limits the bulk response to only outbound messages associated with a specific request.

GET /outbound-messages?request_id=5841b28c-7869-474f-9b25-c2b1ba9aa7b9

Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://api.freshchat.com/v2/outbound-messages?request_id=5841b28c-7869-474f-9b25-c2b1ba9aa7b9" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpS216TTVXXX_U5X2A"
EXPAND ↓
Response

A successful request returns 200 along with all outbound messages from the Freshchat account, as an array. Each array entry is an outbound message object, with the corresponding attributes. The response data is limited by the query parameter passed in the request.

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
{ "outbound_messages": [ { "message_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9", "from": { "phone_number": "+919999999999" }, "provider": "whatsapp", "to": { "phone_number": "+919999999999" }, "data": { "message_template": { "storage": "none", "template_name": "hello_world", "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX", "language": { "policy": "deterministic", "code": "en_US" }, "rich_template_data": { "header": { "type": "image", "media_url": "https://sample.in/sample.jpg" }, "body": { "params": [ { "data": "John Doe" } ] } } } }, "request_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9", "status": "Failed", "created_on": 1566970961, "failure_code": "OBM001", "failure_reason": "no template exists" } ] }
EXPAND ↓

Reports

Reports help obtain certain raw metrics related to team performance, agent availability, conversation overview, customer satisfaction, and resolution types. Collectively, the reports cover all metrics related to the entire interaction life cycle and agent activity. You can extract the Freshchat reports with unprocessed data and create custom reports or populate data in a Business Intelligence (BI) tool.

Endpoints

POST /reports/raw
GET /reports/raw/{id}

Extract a report

Submits a request to extract a report. The response object contains a unique identifier of the report and a reference to the requested report.

post
/reports/raw
Request object
1
2
3
4
5
6
{ "start": "2020-01-23T00:30:00.000Z", "end": "2020-01-23T18:59:59.000Z", "event": "Conversation-Group-Assigned", "format": "csv" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
start string Starting date for report generation, specified in the UTC format. Must not be a date earlier than 15 months from the current date.
end string Ending date for report generation, specified in the UTC format. Must not be a date later than a month from the starting date.
event string Name of the event whose data is to be extracted.
Possible values:
Chat-Transcript: The raw report lists all chat transcripts (conversations and the corresponding messages) created within a time frame of 24 hours. For this report, the end value should not be more than 24 hours from the start value.
Conversation-Created: The raw report lists the details of all conversations created within a time frame. This helps track the volume of incoming conversations.
Message-Sent: The raw reports lists the details of all messages sent within a time frame. This helps track the volume of agent activity.
Conversation-Resolved: The raw reports lists the details of all conversations resolved within a time frame. This helps track the volume of resolved conversations.
Conversation-Resolution-Label: The raw report lists the details of all resolution labels attached to a conversation when the conversation is resolved. This helps track the trend in conversation volumes by aggregating the percentage of conversations belonging to a specific category and sub-category of resolution.
For information on how resolution labels can help identify trends in customer queries, see Conversation labels and label reports.
CSAT-Score: The raw report lists all customer satisfaction ratings received agent-wise, within a specific time frame. This helps monitor the customer satisfaction levels and also generate useful actionable metrics such as the number of unsatisfactory conversations.
First-Response-Time: The raw report tracks the time agents and groups take to send the first response to a customer message. This helps evaluate productivity and team performance.
Response-Time: The raw report tracks the time agents and groups take to reply to a message in a conversation. This helps evaluate productivity and team performance.
Resolution-Time: The raw report tracks the time agents and groups take to resolve a conversation assigned to the agent or group. This helps evaluate productivity and team performance.
Conversation-Agent-Assigned: Tracks the time taken to assign a conversation to an agent.
Conversation-Group-Assigned: Tracks the time taken to assign a conversation to a group.
Agent-Activity: Tracks agent activity in the Freshchat dashboard.
Agent-Intelliassign-Activity: Tracks agent activity when a conversation is auto-assigned through IntelliAssign.
Conversation-Activity: The raw report lists the details of all conversations created, reopened and resolved within a time frame. This helps track the volume of incoming and resolved conversations. The report also tracks the time taken to assign a conversation to an agent.
Classic: The raw report lists the details of an interaction within a time frame of 24 hours. For this report, the end value should not be more than 24 hours from the start value.
Agent-performance: Tracks the agent performance within a time frame of 24 hours. For this report, the end value should not be more than 24 hours from the start value.
format string Format in which the reports are to be extracted.
Possible value: csv

The various csv reports and their parameters are as follows.

Chat-Transcript report
  • conversation_id:: System generated identifier of the conversation that is created. The conversation_id is the same for the entire conversation thread. A chat transcript contains all conversations that happened in the specified time window.
  • conversation_url: URL using which agents and teams can access the conversation from the inbox.
  • interaction_raw_id: System generated identifier of an interaction - a conversation from the time the first message is created to the time the conversation is closed, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • message_id: System generated identifier of a message in a conversation. Each message in an interaction would have a unique identifier.
  • message_type: Message type based on the actor who sends a message. Possible values: normal (sent by user or agent), private (private message sent by user or agent), and system (system generated message).
  • message_parts: Different parts of a message posted to the conversation - plain text, images, or url buttons. The message can be a combination of these attributes. In the report, message_parts field is an array of JSON objects. For more information, see the message part object.
  • created_time: Timestamp of when the message is sent, specified in the UTC format.
  • actor_id: System generated identifier of the entity who sends the message to the conversation. If the message is a user message, the actor_id is the user id that is auto-generated when the user is created in the Freshchat system. If the message is an agent’s message, the actor_id is the agent id that is auto-generated when the agent is configured in the Freshchat system.
  • actor_type: Name of the entity who initiated the conversation. Possible values: USER, AGENT, SYSTEM, and BOT.
  • actor_sub_entity: When actor_type is SYSTEM, actor_sub_entity identifies the routing type, such as assignment rules, Intelliassign, topic-group mapping, and so on, that causes the message to be assigned to a specific agent/group. Possible values: intelliAssign, rule, api, dsat (system assignment is a result of the dissatisfied customer analysis), and channel (system assignment is a result of topic-group mapping).
  • actor_email: Email id of the agent or user who sent the message. For system messages, an empty value is returned.
  • actor_phone: Phone number of the user who sent the message. For system messages, an empty value is returned.
  • actor_first_name: First Name of the agent or user who sent the message. For system messages, an empty value is returned.
  • actor_last_name: Last Name of the agent/ user who sent the message. For system messages, an empty value is returned.
  • message_source: Source from which the message in the conversation is initiated. Possible values: web, system, mobile, api, freshdesk, zendesk, smooch, and facebook_native.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.
  • channel_name: Name of the topic, such as Billing or Sales, under which the conversation is created. Topics channelise customers to the appropriate groups.

Conversation-Created report
  • channel_name: Name of the topic, such as Billing or Sales, under which the conversation is created. Topics channelise customers to the appropriate groups.
  • reopened: If true, specifies that the conversation is a reopened conversation.
  • actor_type: Name of the entity who initiated the conversation. Possible values: USER, AGENT, SYSTEM, and BOT.
  • group_name: Name of the group to which the created conversation is assigned. As soon as they are created, conversations can be auto-assigned based on topic-group mapping, IntelliAssign, and so on.
  • reopen_cause: System generated reason for reopening the conversation. Possible values: AGENT_REOPEN, USER_MESSAGE, CUSTOMER_DISSATISFACTION, BOT, and FREDDY_BOT.
  • created_at: Timestamp of when the conversation is created, specified in the UTC format.
  • interaction_id: System generated identifier of an interaction - a conversation from the time the first message is created to the time the conversation is closed. If the conversation is reopened a new interaction_id is assigned to the conversation.
  • conv_url: URL using which agents and teams can access the conversation from the inbox.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • group_id: System generated identifier of the group to which the conversation is assigned. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • conversation_id: System generated identifier of the conversation that is created. The conversation_id is the same for the entire conversation thread irrespective of the number of resolutions and reopenings that happen.
  • is_conv_offline: If true, specifies that the conversation is created or reopened outside business hours, through Freshchat’s Offline Experience workflow.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Message-Sent report
  • channel_name: Name of the topic, such as Billing or Sales, under which the message in a conversation is sent.
  • actor_sub_type: When actor_type is SYSTEM, actor_sub_type identifies the routing type, such as assignment rules, Intelliassign, topic-group mapping, and so on, that causes the message to be assigned to a specific agent/group. Possible values: intelliAssign, rule, api, dsat, and channel.
  • reopened: If true, specifies that the conversation to which the message is sent is a reopened conversation.
  • actor_type: Name of the entity who sends the message to the conversation. Possible values: USER, AGENT, SYSTEM, and BOT.
  • group_name: Name of the group from which an agent responds through the message sent or is expected to respond to a user message.
  • actor_name: Name of the entity who sent the message. If the message is a user message, the actor_name is the user’s name. If the message is an agent’s message, the actor_name is the agent’s name. If the message is sent by a system or BOT, the actor_name is a system generated value.
  • created_at: Timestamp of when the message is sent, specified in the UTC format.
  • interaction_id: System generated identifier of the interaction (a conversation from the time the first message is created to the time the conversation is closed) to which the message sent belongs.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp of when the conversation is created format.
  • group_id: System generated identifier of the group to which the conversation is assigned. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • conversation_id: System generated identifier of the conversation to which the message sent belongs.
  • actor_id: System generated identifier of the entity who sends the message to the conversation. If the message is a user message, the actor_id is the user id that is auto-generated when the user is created in the Freshchat system. If the message is an agent’s message, the actor_id is the agent id that is auto-generated when the agent is configured in the Freshchat system.
  • channel_id: System generated identifier of the topic under which the message is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Conversation-Resolved report
  • channel_name: Name of the topic under which the conversation that is resolved is created.
  • reopened: If true, specifies that the conversation that is resolved is a reopened conversation.
  • actor_type: Name of the entity who resolved the conversation. Possible values: AGENT, SYSTEM, and BOT.
  • resolve_type: Identifier of the entity who resolved the conversation. Possible values: AGENT_RESOLVE, AUTO_RESOLVE, BOTS_RESOLVE, and FREDDY_BOT_RESOLVE
  • agent_name: Name of the agent to whom the conversation is assigned for resolution.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution.
  • group_name: Name of the group to which the conversation is assigned for resolution or the name of the group to which the agent to whom the conversation is assigned for resolution belongs.
  • actor_name: Name of the entity who resolved the conversation. If the conversation is resolved by an agent, actor_name is the agent’s name.
  • created_at: Timestamp of when the conversation that is assigned for resolution is created, specified in the UTC format.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • actor_belongs_to_group: If true, specifies that the actor who resolved the conversation belongs to the group to which the conversation is assigned.
  • conversation_id: System generated identifier of the conversation that is assigned for resolution.
  • actor_id: System generated identifier of the entity that resolved the conversation.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Conversation-Resolution-Label report
  • channel_name: Name of the topic under which the conversation that is resolved is created.
  • reopened: If true, specifies that the conversation that is resolved is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution.
  • actor_type: Name of the entity who resolved the conversation. Possible values: user, AGENT, SYSTEM, and BOT.
  • label_sub_category_id: System generated identifier for the resolution label sub-category. When a sub-category is configured in the Freshchat system, a label_sub_category_id is auto-generated and assigned to the sub-category.
  • group_name: Name of the group to which the conversation is assigned for resolution or the name of the group to which the agent to whom the conversation is assigned for resolution belongs.
  • user_name: Name of the user who is involved in the conversation with the agent.
  • actor_name: Name of the entity who resolved the conversation. If the message is resolved by an agent, actor_name is the agent’s name.
  • label_category_name: Meaningful name of the resolution label configured in the Freshchat system. When processing the raw data from this report, conversations can be grouped by labels to study the volume of conversations belonging to specific categories.
  • created_at: Timestamp of when the resolution label is attached to the conversation and the conversation is resolved.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • actor_belongs_to_group: If true, specifies that the actor who resolved the conversation belongs to the group to which the conversation is assigned.
  • conversation_id: System generated identifier of the conversation that is assigned for resolution.
  • label_category_id: System generated identifier for the resolution label primary category. When a label is configured in the Freshchat system, a label_category_id is auto-generated and assigned to the label.
  • actor_id: System generated identifier of the entity that resolved the conversation.
  • abel_sub_category_name: Meaningful name of the resolution label’s sub-category specified when the label is configured in the Freshchat system.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.
  • labelled_by_type: Identifier of the entity who attached the pre-configured label to the conversation and resolved the conversation. Possible values: AUTO_RESOLVE and AGENT.
  •   Note: Freshchat customers can associate resolution labels for auto-resolution rules.

CSAT-Score report
  • channel_name: Name of the topic under which the conversation for which the user provided a CSAT rating is created.
  • reopened: If true, specifies that the conversation for which the user provided a CSAT rating is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution.
  • csat_id: System generated identifier of the CSAT setting configured for the business account. When a CSAT setting is configured in a Freshchat system, a csat_id is auto-generated and assigned to the setting.
  • csat_submitter_user_name: Name of the user who provides the CSAT rating for the agent who resolved the conversation.
  • csat_submitter_user_id: System generated identifier of the user who provides the CSAT rating. When a user is created in the Freshchat system, a user_id is auto-generated and associated with the user.
  • group_name: Name of the group to which the conversation is assigned for resolution or the name of the group to which the agent to whom the conversation is assigned for resolution belongs.
  • actor_name: Name of the entity who resolves the conversation and thereby triggers the CSAT survey.
  • created_at: Timestamp of when the CSAT rating is provided.
  • has_response: If true, specifies that the user has provided additional comments along with the rating.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved. CSAT survey is triggered at the end of every interaction, if Customer Satisfaction Rating is enabled for the business account.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp of when the conversation is created format.
  • issue_resolved: If true, specifies that the user who provided the CSAT rating has confirmed that the issue associated with the conversation has been resolved.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • actor_belongs_to_group: If true, specifies that the actor who resolves the conversation and thereby triggers the CSAT survey, belongs to the group to which the conversation is assigned for resolution.
  • conversation_id: System generated identifier of the conversation for which the user provides the CSAT rating.
  • csat_reopen: If true, specifies that the conversation is reopened based on the CSAT rating.
  • csat_response: Comment provided by the user as part of the rating.
  • actor_id: System generated identifier of the entity who resolved the conversation.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.
  • value: Numeric value of the CSAT rating. Possible values: 0 - 5

First-Response-Time report
  • channel_name: Name of the topic under which the conversation is created.
  • reopened: If true, specifies that the conversation is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution. If there is a response to the message that initiated the conversation before assignment to an agent, in the report, this field value is empty.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution. If there is a response to the message that initiated the conversation before assignment to an agent, in the report, this field value is empty.
  • group_name: Name of the group to which the conversation is assigned for resolution. If there is a response before assignment, this field value is empty.
  • actor_name: Name of the entity who responds to the conversation.
  • created_at: Timestamp of when the first response is received for the conversation.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • total_first_response_time_in_seconds: Time taken for the conversation to receive the first response, without considering the business hours set up for the organization, specified in seconds.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If there is a response before assignment, this field value is empty.
  • actor_belongs_to_group: If true, specifies that the actor who responded to the conversation, belongs to the group to which the conversation is assigned for resolution. If there is a response before assignment, this field value is false.
  • conversation_id: System generated identifier for the conversation.
  • value_in_seconds: Time taken for the conversation to receive the first response, taking into consideration the business hours set up for the organization, specified in seconds.
  • actor_id: System generated identifier of the actor who responds first to the conversation.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Response-Time report
  • channel_name: Name of the topic under which the conversation is created.
  • actor_sub_type: When actor_type is SYSTEM, actor_sub_type identifies the routing type, such as assignment rules, Intelliassign, topic-group mapping, and so on, that causes the conversation to be assigned to a specific agent/group. Possible values: intelliAssign, rule, api, dsat, and channel.
  • reopened: If true, specifies that the conversation is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report, this field is empty.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report, this field is empty.
  • actor_type: Name of the entity who responds to the user messages in the conversation. Possible values: AGENT, SYSTEM, and BOT.
  • group_name: Name of the group to which the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report, this field is empty.
  • actor_name: Name of the entity who responds to user messages in the conversation. If the actor_type is AGENT, this is the agent’s name.
  • created_at: Timestamp of when the conversation is resolved, specified in the UTC format.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report, this field is empty.
  • actor_belongs_to_group: If true, specifies that the actor who responded to the user messages in the conversation, belongs to the group to which the conversation is assigned for resolution. If there is no specific assignment, this field value is false.
  • conversation_id: System generated identifier for the conversation.
  • value_in_seconds: Response time is the time taken to send reply messages for the user messages in the conversation. This field specifies the sum of all response times recorded for an interaction.
  • actor_id: System generated identifier of the actor who responds to the user messages in the conversation.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Resolution-Time report
  • channel_name: Name of the topic under which the conversation is created.
  • actor_sub_type: Routing type, such as assignment rules, Intelliassign, topic-group mapping, and so on, that causes the conversation to be assigned to a specific agent/group.
  • reopened: If true, specifies that the conversation is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report this field is empty.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report this field is empty.
  • actor_type: Name of the entity who interacts with the user, in the conversation. Possible values: AGENT, SYSTEM, and BOT.
  • group_name: Name of the group to which the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report this field is empty.
  • actor_name: Name of the entity who interacts with the user, in the conversation. If the actor_type is AGENT, this is the agent’s name.
  • created_at: Timestamp of when the conversation is resolved, specified in UTC format.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report, this field is empty.
  • actor_belongs_to_group: If true, specifies that the actor who interacted with the user, belongs to the group to which the conversation is assigned for resolution. If there is no specific assignment, this field value is false.
  • conversation_id: System generated identifier for the conversation.
  • value_in_seconds: Average time taken to resolve the conversation, during an interaction.
  • actor_id: System generated identifier of the actor who interacts with the user, in the conversation.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Conversation-Agent-Assigned report
  • conversation_id: System generated identifier of the conversation assigned to the agent.
  • interaction_id: System generated identifier of an interaction - a conversation from the time it is initiated to the time it is resolved.
  • channel_id: System generated identifier of the topic under which the assigned conversation is posted.
  • channel_name: Descriptive identifier of the topic.
  • group_id: System generated identifier of the group to which the agent to whom the conversation is assigned belongs.
  • group_name: Descriptive identifier of the group.
  • agent_id: Identifier of the agent to whom a conversation is assigned for resolution.
  • actor_id: Identifier of the entity that assigned the conversation to the agent.
  • actor_type: Descriptive identifier of the entity that assigned the conversation to the agent.
  • created_at: Timestamp of when the conversation is assigned to an agent, specified in the UTC format.
  • reassigned: If true, specifies that a conversation is reassigned to the agent.
  • value: Time taken to assign a conversation to an agent, specified in seconds.

Conversation-Group-Assigned report
  • conversation_id: System generated identifier of the conversation assigned to the group.
  • interaction_id: System generated identifier of an interaction - a conversation from the time it is assigned to a group to the time it is resolved.
  • channel_id: System generated identifier of the topic under which the assigned conversation is posted.
  • channel_name: Descriptive identifier of the topic.
  • group_id: System generated identifier of the group to which the conversation is assigned.
  • group_name: Descriptive identifier of the group.
  • actor_id: Identifier of the entity that assigned the conversation to the group.
  • actor_type: Descriptive identifier of the entity that assigned the conversation to the group.
  • created_at: Timestamp of when the conversation is assigned to the group, specified in the UTC format.
  • reassigned: If true, specifies that a conversation is reassigned to the group.
  • value: Time taken to assign a conversation to a group, specified in seconds.
  • reopened: If true, specifies that the conversation assigned to the group is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution.
  • actor_name: Name of the entity that assigned the conversation to the group.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.

Agent-Activity report
  • agent_name: Name of the agent whose activity on the Freshchat dashboard is tracked.
  • agent_id: System generated identifier of the agent.
  • activity_type: Type of activity, agent logging in (online) or logging off (offline), that triggered the agent activity data to be recorded.
  • created_at: Timestamp of when an agent logs in or logs off, specified in the UTC format.

Agent-Intelliassign-Activity report
  • agent_name: Name of the agent to whom a conversation is assigned through IntelliAssign.
  • agent_id: System generated identifier of the agent.
  • activity_type: Type of activity, agent logging in (active), logging off (inactive), or setting a custom status, that triggered the agent activity data to be recorded.
  • created_at: Timestamp of when an agent logs in or logs off, specified in the UTC format.
  • If the custom activity state feature (in beta) is enabled for a business account that uses Freshchat, the business can configure custom statuses, such as Away, In a meeting, and so on, for their agents to use. The following two fields are available as part of the Agent-Intelliassign-Activity report only if this feature is enabled for an account.

  • agent_status: Custom status set by the agent.
  • agent_status in seconds: Duration for which the agent has set the custom status, specified in seconds.

Conversation-Activity report
  • created_at: Timestamp of when the conversation is initiated, specified in the UTC format.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • interaction_id: System generated identifier of an interaction - a conversation from the time the first message is created to the time the conversation is closed. If the conversation is reopened a new interaction_id is assigned to the conversation.
  • conversation_id: System generated identifier of the conversation that is created. The conversation_id is the same for the entire conversation thread irrespective of the number of resolutions and reopenings that happen.
  • user_id: System generated identifier of the user who initiated the conversation.
  • org_contact_id: Organization-level identifier of the user who sent the message.
  • assigned_at: Timestamp of when the conversation is assigned to an agent in the Freshchat system, specified in the UTC format.
  • agent_id: Identifier of the agent to whom a conversation is assigned for resolution.
  • org_agent_id: Organization-level identifier of the agent to whom a conversation is assigned for resolution.
  • resolved_at: Timestamp of when the conversation is resolved, specified in the UTC format.
  • resolved_by: System generated identifier of the agent who resolved the conversation.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • org_group_id: Organization-level identifier of the group to which the conversation is assigned for resolution.
  • group_name: Name of the group to which the conversation is assigned for resolution or the name of the group to which the agent to whom the conversation is assigned for resolution belongs.
  • channel_id: System generated identifier of the topic under which the message is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.
  • channel_name: Name of the topic under which the conversation is created.

Classic report
  • agent_reopen: If true, specifies that an agent reopened the conversation.
  • avg_response_time_secs: Average time an agent takes to respond to a message in the interaction, specified in seconds.
  • channel: Name of the topic, such as Billing or Sales, under which the conversation associated with the interaction is created.
  • channel_id: System generated identifier of the topic under which the conversation associated with the interaction is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.
  • conversation_alias: Unique system generated identifier of the conversation (to which the interaction belongs) record in the Freshchat system.
  • conversation_id: System generated identifier of the conversation to which the interaction belongs.
  • created_timestamp: Timestamp of when the interaction is created in the Freshchat system, specified in the UTC format.
  • created_timestamp_millis: Timestamp of when the interaction is created in the Freshchat system, specified in milliseconds.
  • csat_agent: Name of the agent who resolved the conversation and thereby triggered the CSAT survey.
  • csat_agent_id: Email address of the agent who resolved the conversation and thereby triggered the CSAT survey.
  • csat_group: Name of the group (to which the agent who resolved the conversation belongs) that resolved the conversation and triggered the CSAT survey.
  • csat_group_id: System generated identifier of the group to which the resolved conversation which triggered the CSAT survey is assigned. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs.
  • csat_issue_resolved: If true, specifies that the user who provided the CSAT rating has confirmed that the issue associated with the conversation is resolved.
  • csat_rating: Numeric value of the CSAT rating. Possible values: 0 - 5
  • csat_response: Comment provided by the user as part of the rating.
  • csat_timestamp: Timestamp of when a CSAT survey is triggered after the conversation associated with the interaction is resolved, specified in the UTC format.
  • csat_timestamp_millis: Timestamp of when a CSAT survey is triggered after a conversation associated with the interaction is resolved, specified in milliseconds.
  • first_assigned_group: Name of the group to which the interaction is first assigned.
  • first_assigned_group_id: System generated identifier of the group to which the interaction is first assigned for resolution. If the interaction is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group. This group_id is reflected as the first_assigned_group_id.
  • first_group_assigned_by: Assignment process that assigned the interaction to a group.
    Possible values: channel_group_mapping, api.
    When an interaction is assigned to a specific group based on the topic under which the associated conversation is created, the value of first_group_assigned_by is channel_group_mapping.
  • first_assigned_timestamp: Timestamp of when the interaction is first assigned to an agent, specified in the UTC format.
  • first_assigned_timestamp_millis: Timestamp of when the interaction is first assigned to an agent, specified in milliseconds.
  • first_assigned_by: Name of the entity who first assigned the interaction to an agent.
    Possible values: AGENT, BOT, and SYSTEM
  • first_assigned_to: Name of the agent to whom the interaction is first assigned.
  • first_assigned_to_id: System generated identifier of the agent to whom the interaction is first assigned.
  • first_group_assigned_timestamp: Timestamp of when the interaction is first assigned to a group, specified in the UTC format.
  • first_group_assigned_timestamp_millis: Timestamp of when the interaction is first assigned to a group, specified in milliseconds.
  • first_response_timestamp: Timestamp of when the first response is sent after the interaction is initiated, specified in the UTC format.
  • first_response_timestamp_millis: Timestamp of when the first response is sent after the interaction is initiated, specified in milliseconds.
  • first_response_time_secs: Time an agent takes to send the first response to an interaction after it is assigned, specified in seconds.
  • first_response_time_formatted: first_response_time_secs in the hh:mm:ss format.
  • first_responded_by: Name of the agent who first responded to the interaction.
  • first_responded_by_id: System generated identifier of the entity who first responded to the interaction.
  • first_response_assigned_agent: Email address of the agent to whom the conversation associated with the interaction was assigned, when the first response was sent.
  • first_response_assigned_agent_id: System generated identifier of the agent to whom the conversation associated with the interaction was assigned, when the first response was sent.
  • first_response_group: Name of the group to which the conversation associated with the interaction was assigned, when the first response was sent.
  • first_response_group_id: System generated identifier of the group to which the conversation associated with the interaction was assigned, when the first response was sent.
  • interaction_id: System generated identifier of an interaction - a conversation from the time the first message is created to the time the conversation is closed. If the conversation is reopened a new interaction_id is assigned to the conversation.
  • is_offline_conversation: If true, specifies that the interaction belongs to an offline conversation. A conversation is specified as an offline conversation when it is created, reopened, or a message is sent to it outside business hours.
  • last_response_timestamp: Timestamp of when the last response was sent to the interaction, specified in the UTC format.
  • lastresponse_timestamp_millis: Timestamp of when the last response was sent to the interaction, specified in milliseconds.
  • last_responded_by: Name of the agent who last responded to the interaction.
  • last_responded_by_id: System generated identifier of the agent who last responded to the interaction.
  • last_response_assigned_agent: Email address of the agent to whom the conversation associated with the interaction was assigned, when the last response was sent.
  • last_response_assigned_agent_id: System generated identifier of the agent to whom the conversation associated with the interaction was assigned, when the last response was sent.
  • last_response_assigned_group: Name of the group to which the conversation associated with the interaction was assigned, when the last response was sent.
  • last_response_assigned_group_id: System generated identifier of the group assigned to the conversation associated with the interaction when the last response was sent.
  • label_timestamp: Timestamp of when the resolution label is assigned to the conversation associated with the interaction, specified in the UTC format.
  • label_timestamp_millis: Timestamp of when the resolution label is assigned to the conversation associated with the interaction, specified in milliseconds.
  • label_applied_by: Email address of the agent who attached the pre-configured label to the conversation and resolved the conversation. For labels applied by the system, this value is null.
  • label_applied_by_id: System generated identifier of the entity who attached the pre-configured label to the conversation and resolved the conversation.
  • reassigns: Number of times the interaction is reassigned.
  • resolution_timestamp: Timestamp of when the conversation associated with the interaction is resolved, specified in the UTC format.
  • resolution_timestamp_millis: Timestamp of when the conversation associated with the interaction is resolved, specified in milliseconds.
  • resolution_time_secs: Time taken to resolve the conversation associated with the interaction, specified in seconds.
  • resolution_time_formatted: resolution_time_secs in the hh:mm:ss format.
  • resolved_by: Name of the entity who resolved the conversation associated with the interaction.
  • resolved_by_id: System generated identifier of the entity who resolved the interaction. When an agent resolves the conversation, the value of resolved_by_id is a valid agent_id.
  • resolution_assigned_agent: Email address of the agent to whom the interaction is assigned when the associated conversation is resolved.
  • resolution_assigned_agent_id: Identifier of the agent to whom the interaction is assigned when the associated conversation is resolved.
  • resolution_assigned_group: Name of the group to which the interaction is assigned when the associated conversation is resolved or the name of the group to which the agent to whom the conversation is assigned for resolution belongs.
  • resolution_assigned_group_id: System generated identifier of the group to which the interaction is assigned when the associated conversation is resolved. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • resolution_label: Name of the resolution label associated with the resolved interaction. Resolution labels help to track the trends in conversation volumes by aggregating the percentage of conversations belonging to a specific category and sub-category of resolution.
  • resolution_label_subcategory: Name of the resolution label’s sub-category associated with the resolved conversation to which the interaction belongs.
  • reopened: If true, specifies that the interaction is associated with a reopened conversation.
  • response_count: Number of responses the agent has sent in the interaction.
  • time_to_first_assign_secs: Time taken to first assign the interaction to an agent, specified in seconds.
  • time_to_first_response_from_create_secs: Time taken to send the first response after the interaction is initiated, specified in seconds.
  • time_to_first_response_from_create_formatted: time_to_first_response_from_create_secs in the hh:mm:ss format.
  • time_to_resolve_from_create_secs: Total time taken to resolve the interaction, specified in seconds.
  • time_to_resolve_from_create_formatted: time_to_resolve_from_create_secs in the hh:mm:ss format.
  • user_id: System generated identifier of the user who initiated the interaction.
  • user_name: Name of the user who initiated the interaction.
  • user_email: Email address of the user who initiated the interaction.
  • user_phone: Phone number of the user who initiated the interaction.
  • user_identifier: External identifier (reference) that the organization that uses Freshchat configures in Freshchat, to identify a user in another (external) system. Default value: null.
  • user_source: Source through which a user initiates the interaction. For example, FRESHBOT_WIDGET, WEBCHAT, and so on.

Agent-performance report
  • agent_id: System generated identifier of the agent.
  • agent_email: Email address of the agent.
  • agent_name: Name of the agent.
  • average_first_response_time_secs: Average time the agent takes to respond first to a conversation after it is assigned to the agent, specified in seconds.
  • average_response_time_secs: Average time the agent takes to respond to messages, specified in seconds.
  • average_handle_time_secs: Average time the agent takes to resolve a conversation, specified in seconds.
  • active_time_mins: Time for which the agent is active on IntelliAssign, specified in minutes.
  • average_csat_score: Average of all the CSAT scores received for resolved conversations assigned to the agent.
  • count_assigned: Number of conversations assigned to the agent for resolving.
  • count_resolved: Number of conversations that the agent resolves.
  • count_unique_resolved: Number of unique conversations resolved by the agent.
  • count_transfers_out: Number of conversations reassigned to other agents from the agent whose productivity is tracked through this report.
  • count_messages: Number of messages the agent sends in the specified time frame.
  • count_responses: Number of responses the agent sends in the specified time frame.
  • concurrency: Average number of conversations assigned to the agent for resolution simultaneously.
  • engagement_time_secs: Time for which the agent is in the assigned mode on Freshchat (that is, the agent is handling at least one conversation), specified in seconds.
  • online_time_mins: Time for which the agent has been online on Freshchat, specified in minutes.
  • report_start_time: Starting time of the report generation.
  • report_end_time: Ending time of the report generation.

Sample request | Curl
Copied Copy
1
curl -X POST "https://api.freshchat.com/v2/reports/raw" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpS216TTVkenRIWmprdmdSY3VrVHgxTzJ2SFlTM0U5YmVJME9XbXRNR1ZzIn0.eyJqdGkiOiIyYTJiNTAwNi04NDk2LTQyMDctYWUyOC1mYzY4MTI4MGRkMmEiLCJleHAiOjE5MDM5Mzg1MTYsIm5iZiI6MCwiaWF0IjoxNTg4NTc4NTE2LCJpc3MiOiJodHRwOi8vaW50ZXJuYWwtZmMtdXNlMS0wMC1rZXljbG9hay1vYXV0aC0xMzA3MzU3NDU5LnVzLWVhc3QtMS5lbGIuYW1hem9uYXdzLmNvbS9hdXRoL3JlYWxtcy9wcm9kdWN0aW9uIiwiYXVkIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwic3ViIjoiN2VlYTUzNzctYzEzNy00MDI1LWFlYzgtMDhmZjE4MzkwN2EyIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMjMyOTcwOWMtMTVjZS00NzA5LWE1MDctZjcwNGRmNmNmOTFmIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6W10sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJhZ2VudDp1cGRhdGUgbWVzc2FnZTpjcmVhdGUgYWdlbnQ6Y3JlYXRlIG1lc3NhZ2U6Z2V0IGRhc2hib2FyZDpyZWFkIHJlcG9ydHM6ZXh0cmFjdDpyZWFkIHJlcG9ydHM6cmVhZCBhZ2VudDpyZWFkIGNvbnZlcnNhdGlvbjp1cGRhdGUgdXNlcjpkZWxldGUgY29udmVyc2F0aW9uOmNyZWF0ZSBvdXRib3VuZG1lc3NhZ2U6Z2V0IG91dGJvdW5kbWVzc2FnZTpzZW5kIHVzZXI6Y3JlYXRlIHJlcG9ydHM6ZmV0Y2ggdXNlcjp1cGRhdGUgdXNlcjpyZWFkIHJlcG9ydHM6ZXh0cmFjdCBjb252ZXJzYXRpb246cmVhZCIsImNsaWVudElkIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwiY2xpZW50SG9zdCI6IjE5Mi4xNjguMTI5LjE1NyIsImNsaWVudEFkZHJlc3MiOiIxOTIuMTY4LjEyOS4xNTcifQ.wE6Kec6OYhsD-CfW2YKf1XsIfGXhXMBZdlZuuACJ8HPukABaNRS3iMDmv0scPdIJJGKmN0w1_DIPQSwiigeA3Xb5NTVOFIKniICVMIwoBMcmeo3njJa4kFwkIo6dD-29xOG5B2flv9F-Nw0jX9qZ-G6oVRvYUS6Ra4-MISLIbe6qJWCVle_1b2I3VRWFNb4MLMcAnMVXeHH5lwR8ZXngHBoKhNsNlGDtxAQEYjlzPlOBaI0IcSN4AO_T7S0LPYZRHuZMAVLbk0DlaDB8WO9-TVSyN0ac7b8o3oRf-C6moZgcTtwC0SeDSvki-pNFy3WXDujQcz1Isa27fPJd_U5X2A" -H "Content-Type: application/json" -d "{ "start": "2019-05-20T10:00:00.000Z", "end": "2019-05-25T10:00:00.000Z", "event": "Conversation-Group-Assigned", "format": "csv"}"
EXPAND ↓
Response

A successful request returns 202 along with the reports response object.

Response object
1
2
3
4
5
6
7
{ "id": "1ac520cf-b1a4-4741-8b01-e383563ae402", "link": { "rel": "extracts", "href": "/reports/raw/"1ac520cf-b1a4-4741-8b01-e383563ae402 } }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Unique identifier for the requested report. This is an auto-generated value. In further API requests, you can use this value to identify and retrieve the URL to a report.
link link object Reference to the requested report.
Attributes of the link object
Attribute Name Data Type Description
rel string Type of link relationship between the resource accessed by the href URL and the source from which the resource is referenced.
href string Reference or URL to access the requested report.

Retrieve a report

Identifies a report by the id passed in the request and returns the links containing the location and status of the requested report.

get
/reports/raw/{id}
Query parameters

You can use the following query parameter to filter the bulk response data.

Parameter Name Description Example
status Limits the response to conversation objects whose status value matches the parameter value.
Valid values: COMPLETED, PENDING, FAILED

GET /reports/raw/{id}?status=COMPLETED

Path parameters
Parameter Name Data Type Description
id string Unique identifier for the requested report.
Sample request | Curl
Copied Copy
1
curl -X GET "https://api.freshchat.com/v2/reports/raw/1ac520cf-b1a4-4741-8b01-e383563ae402" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpS216TTVkenRIWmprdmdSY3VrVHgxTzJ2SFlTM0U5YmVJME9XbXRNR1ZzIn0.eyJqdGkiOiIyYTJiNTAwNi04NDk2LTQyMDctYWUyOC1mYzY4MTI4MGRkMmEiLCJleHAiOjE5MDM5Mzg1MTYsIm5iZiI6MCwiaWF0IjoxNTg4NTc4NTE2LCJpc3MiOiJodHRwOi8vaW50ZXJuYWwtZmMtdXNlMS0wMC1rZXljbG9hay1vYXV0aC0xMzA3MzU3NDU5LnVzLWVhc3QtMS5lbGIuYW1hem9uYXdzLmNvbS9hdXRoL3JlYWxtcy9wcm9kdWN0aW9uIiwiYXVkIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwic3ViIjoiN2VlYTUzNzctYzEzNy00MDI1LWFlYzgtMDhmZjE4MzkwN2EyIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMjMyOTcwOWMtMTVjZS00NzA5LWE1MDctZjcwNGRmNmNmOTFmIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6W10sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJhZ2VudDp1cGRhdGUgbWVzc2FnZTpjcmVhdGUgYWdlbnQ6Y3JlYXRlIG1lc3NhZ2U6Z2V0IGRhc2hib2FyZDpyZWFkIHJlcG9ydHM6ZXh0cmFjdDpyZWFkIHJlcG9ydHM6cmVhZCBhZ2VudDpyZWFkIGNvbnZlcnNhdGlvbjp1cGRhdGUgdXNlcjpkZWxldGUgY29udmVyc2F0aW9uOmNyZWF0ZSBvdXRib3VuZG1lc3NhZ2U6Z2V0IG91dGJvdW5kbWVzc2FnZTpzZW5kIHVzZXI6Y3JlYXRlIHJlcG9ydHM6ZmV0Y2ggdXNlcjp1cGRhdGUgdXNlcjpyZWFkIHJlcG9ydHM6ZXh0cmFjdCBjb252ZXJzYXRpb246cmVhZCIsImNsaWVudElkIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwiY2xpZW50SG9zdCI6IjE5Mi4xNjguMTI5LjE1NyIsImNsaWVudEFkZHJlc3MiOiIxOTIuMTY4LjEyOS4xNTcifQ.wE6Kec6OYhsD-CfW2YKf1XsIfGXhXMBZdlZuuACJ8HPukABaNRS3iMDmv0scPdIJJGKmN0w1_DIPQSwiigeA3Xb5NTVOFIKniICVMIwoBMcmeo3njJa4kFwkIo6dD-29xOG5B2flv9F-Nw0jX9qZ-G6oVRvYUS6Ra4-MISLIbe6qJWCVle_1b2I3VRWFNb4MLMcAnMVXeHH5lwR8ZXngHBoKhNsNlGDtxAQEYjlzPlOBaI0IcSN4AO_T7S0LPYZRHuZMAVLbk0DlaDB8WO9-TVSyN0ac7b8o3oRf-C6moZgcTtwC0SeDSvki-pNFy3WXDujQcz1Isa27fPJd_U5X2A"
EXPAND ↓
Response

A successful request returns 200 along with the links of the requested reports, as an array

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{ "id": "unique_id", "status": "COMPLETED", "interval": "2020-01-23 00:30:00.0 2020-01-23 18:59:59.0", "links": [ { "link": { "rel": "extraction", "href": "private_s3_url" }, "from_date": "2020-01-23T00:30:00.000Z", "to_date": "2020-01-23T18:59:59.000Z", "status": "COMPLETED" } ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Unique identifier for the requested report.
status string Status of the requested report.
Possible values:
PENDING - Report generation is in progress.
FAILED - Report generation has failed.
COMPLETED - Report generation is complete.
interval string Time period for which the report is generated.
links array of reports link objects List of URLs that point to the location of the requested report. The requested report is split into sub-reports according to the interval attribute. The lifespan of the links is one hour.
Attributes of the reports link object:
link object: Location of the requested report.
from (string): Starting date of the sub-report generation, specified in the UTC format.
to (string): Ending date of the sub-report generation, specified in the UTC format.
status(string): Status of the sub-report.
Possible values:
PENDING - Sub-report generation is in progress.
FAILED - Sub-report generation has failed.
COMPLETED - Sub-report generation is complete.

Metrics

Through a live UI dashboard, Freshchat provides a mechanism to view the real-time summary (metrics) of activities in a Freshchat account. You can use the metrics APIs to retrieve the dashboard metrics for further analysis and processing. You can retrieve,

  • Instant metrics: Metrics at the current instant. For the list of metrics that can be retrieved under this category, see Instant metrics.
  • Historical metrics: Metrics accurate up to five minutes before the current instant. For the list of metrics that can be retrieved under this category, see Historical metrics.

Endpoints

GET /metrics/historical
GET /metrics/instant

Retrieve historical metrics

Retrieves historical metrics based on the retrieval criteria specified through query parameters.

get
/v2/metrics/historical
Query parameters

You can use a combination of the following query parameters to retrieve the appropriate historical metric. Ensure that the query parameter values are URL encoded.

Parameter Name Description
metricMandatory Name of the metric to be retrieved.
For a list of valid values and metrics definition, see Historic metrics.
startMandatory
Should be a date-time value specified in the UTC format.
Starting date of the time period for which the metric is to be retrieved.
endMandatory
Should be a date-time value specified in the UTC format.
Ending date of the time period for which the metric is to be retrieved.
interval

Frequency at which the metrics are retrieved.
In an API call, the retrieval time period is specified through the start and end parameter values. If there is an interval specified, the time period is broken down into subsets based on the interval value and the metric is retrieved for each subset.
For example, for a time period of one month, if the interval is 1w (1 week), the retrieved metrics contains four values - one for each week.

Valid values: 1m, 5m, 15m, 1h, 1d, 1w, 1mo
aggregatorMandatory for aggregate metrics
Note: Ensure not to pass an aggregator value for count metrics.

Metrics can be count or aggregate metrics. Count metrics sum the number of metric values in the specified time period. For example, if the time period spans a month and the metric is conversation_metrics.resolved_interactions, an API call to retrieve this metric returns the number of resolved interactions in the month. Aggregate metrics summarize the atomic metrics values over the specified time period. For example, if the time period spans a month and the metric is conversation_metrics.wait_time, an API call to retrieve this metric returns the aggregated (mean) wait time for all incoming conversations, in the month.
aggregator parameter value is the method used to summarize (find mean value of ) atomic metrics.

Valid values:
  • min: The minimum of all values in the specified time period.
  • max: The maximum of all values in the specified time period.
  • avg: The mean value is calculated by finding the sum of all values in the data set and dividing the result by the total number of values in the data set.
  • median: The mean value is calculated by sorting the values in the data set, in ascending or descending order and finding the middle value.
  • p90: The mean value is calculated by sorting the values in the data set, in ascending order and finding the lowest value that is greater than 90% of the values.
Ensure to specify an aggregator value only for aggregate metrics. For the list of aggregate and count metrics, see Historical metrics.
x_timeMandatory for conversation_metrics.assigned_x_mins_ago_and_not_replied_to, conversation_metrics.created_x_mins_ago_and_unassigned, and conversation_metrics

For certain metrics, the retrieval calls do not consider the time period specified through start and end values. These calls act like instant metric calls and consider a combination of the current instant and the x_time value, to retrieve the appropriate metrics. These calls retrieve the metrics in the time period spanning x-minutes-from-the-current-instant to the current instant.
x_time value is the value of the “x minutes”.

Note: start and end are mandatory parameters. So, ensure to specify a value with the valid format for start and end even when retrieving metrics that are only dependent on x_time.
Grouping and filtering metrics values
When retrieving the historical metrics, you can specify an appropriate group_by parameter value and retrieve historical metrics group-wise or agent-wise.
Notes:
  1. The csat_metrics.rating metric can additionally be retrieved rating-wise. For example, if the group_by value for this metric is rating, the API call retrieves the number of CSAT surveys under each of the five possible ratings - that is, number of CSATs that have returned with a rating of 5, number of CSATs that have returned with a rating of 4, and so on.
  2. The conversation_metrics.created_interactions is an account-level metric and cannot be retrieved group-wise or agent-wise. For this metric, if you try to run an API call with the group_by query param value as group, agent, or rating, the call fails.

You can use the filter_by query parameter to filter the (group-wise or agent-wise) retrieved metrics and view only a subset of the results.
For the valid group_by and filter_by values for each metric, see Historic metrics.

group_by Grouping criteria for the metrics. Metrics can be organized based on groups or agents configured in the Freshchat system or based on rating for csat_metrics.rating metrics.
Valid values: group, agent, rating
filter_by Filtering criteria for retrieved metrics. Bulk retrieved metrics can be filtered by agents or groups, specified as valid agent.id or group.id.
For example, to filter the metrics by the groups identifiers, group_id_1 and group_id_2, the filter_by parameter value must be in the format group=group_id_1,group=group_id_2
Example 1:
To retrieve the csat_metrics.count_per_rating metric, aggregated by the average method of finding mean value, filtered for two groups with ids - c7e65b1f-a360-4154-87a6-951b1967dd15 and 713834e0-d031-4aee-90d8-fadcb0bbfa47

GET /metrics/historical?metric=csat_metrics.count_per_rating&start=2022-01-01T10:00:00.000Z&end=2022-11-01T10:00:00.000Z&aggregator=avg&filter_by=group%3Dc7e65b1f-a360-4154-87a6-951b1967dd15%2Cgroup%3D713834e0-d031-4aee-90d8-fadcb0bbfa47

Example 2:
To perform a group-wise retrieval of the team_performance.responses_sent metric and filter the retrieved data for two groups with ids - c7e65b1f-a360-4154-87a6-951b1967dd15 and 713834e0-d031-4aee-90d8-fadcb0bbfa47

GET /metrics/historical?metric=team_performance.responses_sent&start=2022-01-01T10:00:00.000Z&end=2022-11-01T10:00:00.000Z&filter_by=group%3Dc7e65b1f-a360-4154-87a6-951b1967dd15%2Cgroup%3D713834e0-d031-4aee-90d8-fadcb0bbfa47&group_by=group

Example 3:
To perform an agent-wise retrieval of the team_performance.first_response_time metric and filter the retrieved data for two agents with ids - 9a463df8-9655-4d44-a9e3-eda9d6ec89f2 and 1de5d130-1c62-48cf-8349-1b39c60d0c28

GET /metrics/historical?metric=team_performance.first_response_time&start=2022-01-01T10:00:00.000Z&end=2022-11-01T10:00:00.000Z&aggregator=avg&filter_by=agent%3D9a463df8-9655-4d44-a9e3-eda9d6ec89f2%2Cagent%3D1de5d130-1c62-48cf-8349-1b39c60d0c28&group_by=agent

Example 4:
To perform a group-wise retrieval of the conversation_metrics.assigned_interactions metric and filter the retrieved data for two agents with ids - 6e7a0d23-bbd4-45ff-87b2-b46c339050f7 and 1de5d130-1c62-48cf-8349-1b39c60d0c28

GET /metric=conversation_metrics.assigned_interactions&start=2022-11-01T10:00:00.000Z&end=2022-11-20T10:00:00.000Z&group_by=group&filter_by=agent%3D1de5d130-1c62-48cf-8349-1b39c60d0c28%2Cagent%3D6e7a0d23-bbd4-45ff-87b2-b46c339050f7

Example 5:
To retrieve conversation_metrics.created_interactions metric for a time period of one month and interval of one week

GET /metrics/historical?metric=conversation_metrics.created_interactions&start=2022-10-01T10:00:00.000Z&end=2022-10-31T10:00:00.000Z&&interval=1w

Example 6:
To retrieve conversation_metrics.created_x_mins_ago_and_unassigned metric

GET /metrics/historical?metric=conversation_metrics.created_x_mins_ago_and_unassigned&start=2022-10-02T10:00:00.000Z&end=2022-11-04T10:00:00.000Z&x_time=17

Historical metrics
Valid value for metric_name and its description Aggregate or count metric Valid values for group_by Valid values for filter_by
csat_metrics:
A summary of the CSAT (Customer Satisfaction) survey ratings, within the specified time period. An API call to retrieve the csat_metrics lists all the following sub metrics and their corresponding values:
  • csat_metrics.satisfactory_interactions
  • csat_metrics.unsatisfactory_interactions
  • csat_metrics.total_rated_interactions
  • csat_metrics.count_per_rating: If an aggregator is not specified, the default aggregator is average.
NA group or agent Any valid group.id or agent.id
csat_metrics.satisfactory_interactions:
A count of the number of satisfactory interactions recorded through CSAT surveys, within the specified time period.
Count group or agent Any valid group.id or agent.id
csat_metrics.unsatisfactory_interactions:
A count of the number of unsatisfactory interactions recorded through CSAT surveys, within the specified time period.
Count group or agent Any valid group.id or agent.id
csat_metrics.total_rated_interactions:
A count of the number of interactions that received a CSAT rating, within the specified time period.
Count group or agent Any valid group.id or agent.id
csat_metrics.count_per_rating:
Average rating received in the specified time period.
Aggregate group or agent Any valid group.id or agent.id
csat_metrics.rating:
A count of the number of CSAT surveys under each of the five possible ratings.
Count group, agent, or rating Any valid group.id or agent.id
conversation_metrics.created_interactions:
A count of the number of interactions created for an account, in the Freshchat system, for the specified time period.
Count NA
This is an account-level metric.
conversation_metrics:
A summary of all the conversation related metrics, within the specified time period. An API call to retrieve the conversation_metrics lists the following sub metrics and their corresponding values:
  • conversation_metrics.assigned_interactions
  • conversation_metrics.assigned_x_mins_ago_and_not_replied_to
  • conversation_metrics.created_x_mins_ago_and_unassigned
Count group or agent Any valid group.id or agent.id
conversation_metrics.assigned_interactions:
A count of the number of interactions assigned to an agent or group, in the specified time period.

If the group_by value is group, the number of interactions assigned to each group is retrieved for all groups. The retrieved values are filtered by the group ids or agent ids specified in the filter_by value.

If the group_by value is agent, the number of interactions assigned to each agent is retrieved for all agents configured in the Freshchat system. The retrieved values are filtered by the group ids or agent ids specified in the filter_by value.
Count group or agent Any valid group.id or agent.id
conversation_metrics.resolved_interactions:
A count of the number of interactions that a group or agent resolves, in the specified time periods.

If the group_by value is group, the number of interactions resolved by each group is retrieved for all groups. The retrieved values are filtered by the group ids or agent ids specified in the filter_by value.

If the group_by value is agent, the number of interactions resolved by each agent is retrieved for all agents configured in the Freshchat system. The retrieved values are filtered by the group ids or agent ids specified in the filter_by value.
Count group or agent Any valid group.id or agent.id
conversation_metrics.assigned_x_mins_ago_and_not_replied_to:
A count of the number of conversations that were assigned to an agent or group x minutes from the current instant and are still pending a first response.

For retrieving this metric, you must provide a valid x_time value in the request. This specifies a value for the “x minutes”. For example, if x_time is 5, on retrieval, the conversation_metrics.assigned_x_mins_ago_and_not_replied_to value contains the count of conversations that were assigned to an agent or group five minutes before the current time and are still awaiting a response.

Count group or agent Any valid group.id or agent.id
conversation_metrics.created_x_mins_ago_and_unassigned:
A count of the number of conversations that were created x minutes from the current instant and are still unassigned.
For retrieving this metric, you must provide a valid x_time value in the request. This specifies a value for the “x” minutes. For example, if x_time is 5, on retrieval, the conversation_metrics.created_x_mins_ago_and_unassigned value contains the count of conversations that were created five minutes before the current time and are still unassigned.
Count group or agent Any valid group.id or agent.id
conversation_metrics.wait_time:
Average time a user has to wait before getting a response from the group or agent.
Aggregate group or agent Any valid group.id or agent.id
team_performance: A summary of all performance related aggregate metrics, within the specified time period. An API call to retrieve the team_performance metrics lists the following sub metrics and their corresponding values:
  • team_performance.first_response_time
  • team_performance.response_time
  • team_performance.resolution_time
  • team_performance.wait_time: Average time a user has to wait before getting a response from the group or agent, after the conversation is assigned to a group or agent. This metric cannot be retrieved as an independent metric; it can only be retrieved as part of the team_performance metrics.
Aggregate group or agent Any valid group.id or agent.id
team_performance.first_response_time:
Average time that a group or agent takes to send the first response to an assigned conversation.
Aggregate group or agent Any valid group.id or agent.id.
team_performance.response_time:
Average time that a group or agent takes to send responses to an assigned conversation, after the first response.
Aggregate group or agent Any valid group.id or agent.id
team_performance.resolution_time:
Average time that a group or agent takes to resolve an assigned conversation, from the time it is assigned.
Aggregate group or agent Any valid group.id or agent.id
team_performance.responses_sent:
A count of the number of responses that the group or agent sends, in the specified time period.
Count group or agent Any valid group.id or agent.id
team_performance.concurrency_ratio:
Average number of conversations that a group or agent handles simultaneously, in the specified time period.
Aggregate group or agent Any valid group.id or agent.id
Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/metrics/historical?metric=csat_metrics.count_per_rating&start=2022-03-08T10:00:00.000Z&end=2022-03-09T10:00:00.000Z&aggregator=avg&filter_by=group%3Dc7e65b1f-a360-4154-87a6-951b1967dd15%2Cgroup%3D713834e0-d031-4aee-90d8-fadcb0bbfa47&group_by=group&interval=1h" -H "accept: application/json" -H "Authorization: Bearer eyJxxxdQ"
EXPAND ↓
Response

A successful request returns 200 OK along with the following response.

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
{ "metrics": [ "csat_metrics.count_per_rating" ], "start": "2022-03-08T10:00:00.000Z", "end": "2022-03-09T10:00:00.000Z", "filters": { "metric_filters": [ { "key": "group", "value": "c7e65b1f-a360-4154-87a6-951b1967dd15" }, { "key": "group", "value": "713834e0-d031-4aee-90d8-fadcb0bbfa47" } ] }, "aggregator": "avg", "interval": "1h", "data": [ { "groupings": [ { "key": "group", "value": "c7e65b1f-a360-4154-87a6-951b1967dd15" } ], "series": [ { "start": "2022-03-08T14:00:00.000Z", "end": "2022-03-08T15:00:00.000Z", "values": [{ "key": "csat_metrics.count_per_rating", "value": "4.0" }] } ] } ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
metrics array of strings Name of the retrieved metric.
start string Starting date of the time period for which the metric is retrieved, specified in the UTC format.
end string Ending date of the time period for which the metric is retrieved, specified in the UTC format.
filters object Details of the metric filter used to limit the retrieved metrics based on the specified group.ids or agent.ids.
Attributes of the object:
metric_filters (array of objects): Details of the metric filter, specified as a valid JSON object with two attributes:
  • key (string): Type of filter used.
    Possible values: group, agent
  • value (string): Identifier of the group or agent.
In the metric_filters array, there are as many objects as the number of ids used in the filter_by value.
aggregator string Method used to summarize the metrics. The attribute has a value only if the metric retrieved is an aggregate metric. For count metrics, aggregator is “ ”.
Possible values: min, max, avg, median, p90
interval string Frequency at which the metrics are retrieved.
Possible values: 1m, 5m, 15m, 1h, 1d, 1w, 1mo
data array of objects Grouping details based on which the metrics are retrieved and the corresponding metrics values.

Attributes of the object:
groupings (array of objects): When retrieving metrics, multiple combinations of grouping and filtering are possible. The groupings array contains the final grouping/filtering applied to the metrics during retrieval.

    Attributes of the object:
  • key (string): Type of grouping used when retrieving the metrics.
    Possible values: group, agent, rating
  • value (string): Further values by which the metrics are filtered. If no filter_by value is specified during retrieval, value is null.

series (array of objects): The retrieved metrics and the corresponding time period. Each array element represents an interval of the entire time period.

    Attributes of the object:
  • start (string): Starting date of the interval for which the metric is retrieved, specified in the UTC format.
  • end (string): Ending date of the interval for which the metric is retrieved, specified in the UTC format.
  • values (array of objects): Details of the metrics, specified as a valid JSON object of key (name of the metric) -value (actual value of the metric).

Retrieve instant metrics

Retrieves instant metrics based on the retrieval criteria specified through query parameters.

get
/v2/metrics/instant
Query parameters

You can use a combination of the following query parameters to retrieve the appropriate instant metric. Ensure that the query parameter values are URL encoded.

Parameter Name Description
metricMandatory Name of the metric to be retrieved.
For a list of valid values and metrics definition, see Instant metrics.
group_by Grouping criteria for the metrics. When retrieving the instant metrics, you can specify an appropriate group_by parameter value and retrieve instant metrics organized group-wise.
Valid value: group
filter_by Filtering criteria for the metrics. You can use the filter_by query parameter to filter the (group-wise) retrieved metrics and view only a subset of the results.
For example, to filter the metrics by the groups identifiers, group_id_1 and group_id_2, the filter_by parameter value must be in the format group=group_id_1,group=group_id_2.
Valid value: Any valid group.id(s).
summary Specifies whether the retrieved values are to be presented as a summary or as a detailed list. If summary is true, the response contains only the count of agents in each group. If summary is false, the response also includes the corresponding agent.ids.
Valid values: true, false
Example
To retrieve the team_presence.online metric, organized based on groups, summarized, and, filtered for two group IDs - 601b70f2-435f-4232-8db2-7cde8e4bda86 and 7c6ec228-023d-4142-9c7b-0d42c06c1154

GET /metrics/instant?metric=team_presense.online&filter_by=group%3D601b70f2-435f-4232-8db2-7cde8e4bda86%2Cgroup%3D7c6ec228-023d-4142-9c7b-0d42c06c1154&group_by=group&summary=true

Instant metrics
Valid value for metric Description
team_presence.online A count of the number of agents who are online, at the instant when the metric is being retrieved.
team_presence.offline A count of the number of agents who are offline, at the instant when the metric is being retrieved.
team_presence.active_on_intelliassign A count of the number of agents who are active for IntelliAssign, at the instant when the metric is being retrieved.
team_presence.inactive_on_intelliassign A count of the number of online agents who are inactive on IntelliAssign, at the instant when the metric is being retrieved.
team_presence.total_members A count of the total number of agents in the Freshchat system (online and offline), at the instant when the metric is being retrieved.
Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/metrics/instant?metric=team_presence.online&filter_by=group%3D388c61d3-d564-4b55-a650-38dd3c287f21%2Cgroup%3Dbfdc3b66-6de3-4124-b8b7-c37059087d88&group_by=group&summary=false" -H "accept: application/json" -H "Authorization: Bearer eyJxxxUIV4"
EXPAND ↓
Response

A successful request returns 200 OK along with the following response.

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
{ "metric": "team_presence.online", "filters": { "metric_filters": [{ "key": "group", "value": "bfdc3b66-6de3-4124-b8b7-c37059087d88" }, { "key": "group", "value": "388c61d3-d564-4b55-a650-38dd3c287f21" } ] }, "data": [{ "groupings": [{ "key": "group", "value": "bfdc3b66-6de3-4124-b8b7-c37059087d88" }], "values": [{ "key": "team_presence.online", "resources": [{ "id": "1de5d130-1c62-48cf-8349-1b39c60d0c28" }], "count": 1 }] }, { "groupings": [{ "key": "group", "value": "388c61d3-d564-4b55-a650-38dd3c287f21" }], "values": [{ "key": "team_presence.online", "resources": [{ "id": "1de5d130-1c62-48cf-8349-1b39c60d0c28" }], "count": 1 } ] } ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
metric string Name of the retrieved metric.
filters object Details of the metric filters used to limit the retrieved metrics based on the specified group.ids.
Attributes of the object:
metric_filters (array of objects): Details of the metric filter, specified as a valid JSON object with two attributes:
  • key (string): Type of filter used. For now, it is always group.
  • value (string): Identifier of the group.
In the metric_filters array, there are as many objects as the number of ids used in the filter_by value.
data array of objects Grouping details based on which the metrics are retrieved and the corresponding metrics values.

Attributes of the object:
Note: There are as many objects as the number of ids used in the filter_by value.
groupings (array of objects): When retrieving metrics, a combination of grouping and filtering is applied. The groupings array contains the final grouping/filtering applied to the metrics during retrieval.

    Attributes of the object:
  • key (string): Type of grouping used when retrieving the metrics.
    Possible value: group
  • value (string): Identifier of the group.

values (array of objects): Details of the retrieved metric.

    Attributes of the object:
  • key (string): Name of the metric.
  • resources (array of strings): Identifiers of the agents who satisfy the specified metric, if during retrieval summary is set as false. The resources array is empty if summary was set to true or the count value is 0.
  • count (integer): Number of agents who satisfy the specified metric.

Business Hours

Business hours convey the working hours of a group. If business hours are configured for a group, conversations can be assigned to the group only during the specified business hours.

Endpoint

GET /business-hours/within-bh

Verify whether a group is within business hours

Identifies a group by the group_id specified (as a query parameter value) and returns a boolean response specifying whether the group is within business hours.

get
/v2/business-hours/within-bh
Query parameters
Parameter Name Data Type Description
group_id string Identifier of the group, auto-generated when a group is configured in the Freshchat system.
Note: If no group_id is specified, the API call returns a default response.
Sample request | Curl
Copied Copy
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/business-hours/within-bh?group_id=e71aa24a-3ec8-4ddb-93db-bc32d8afded1" -H "accept: application/json" -H "Authorization: Bearer eyashV4"
EXPAND ↓
Response

A successful request returns 200 OK along with a boolean verification.

Example
1
2
3
{ "with_in_business_hours": false }
EXPAND ↓
Attributes
Attribute Name Data Type Description
with_in_business_hours boolean Specifies whether the group is within the business hours at the instant when the group’s business hours is verified.
Possible values: true, false
Default value: true
Note: If business hours are not configured for the group or if the group.id isn’t added to the request, the API call returns the default value.