Overview

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

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

Status and error messages

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

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

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


Response error message

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

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

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

Header Parameters

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

  • Accept
  • Authorization
  • Content-Type

Accept

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

Header parameter format

Accept: application/<format>

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

Authorization

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

Header parameter format

Authorization: Bearer <access-token>

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

Content-Type

Specifies the format in which data is sent in the request body to the 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.

Authentication and Authorization

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

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

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

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

Request call to obtain the access token

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

Rate Limits

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

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

User

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

Endpoints

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

The user object

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

Attribute of the image object:

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

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

Attributes of the property object:

name (string)Mandatory
value (string)Mandatory

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

Create a user

Creates a user object with the specified user information.

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

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

Update user details

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

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

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

Retrieve user information

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

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

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

Conversation

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

Endpoints

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

The conversation object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{ "conversation_id": "c69641e9-8a85-4da1-858e-77169b0c76a7_54e59ba2-92f6-492d-bb1f-29743f1a22a8_feedback", "app_id": "c69641e9-8a85-4da1-858e-77169b0c76a7", "channel_id": "729bd0ba-2ac2-400b-abef-26d92a3f4420", "messages": [ { "app_id": "c69641e9-8a85-4da1-858e-77169b0c76a7", "actor_type": "user", "actor_id": "54e59ba2-92f6-492d-bb1f-29743f1a22a8", "channel_id": "729bd0ba-2ac2-400b-abef-26d92a3f4420", "message_type": "normal", "message_parts": [ { "text": { "content": "hey dude!!" } } ] } ], "status": "new", "users": [ {"id": "54e59ba2-92f6-492d-bb1f-29743f1a22a8"} ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
conversation_id string Identifier of the conversation. The conversation_id value is returned as part of the conversation object in response to a successful conversation creation request. The conversation_id is used to identify a conversation and post a message to the conversation or update the conversation.
created_time string Time when the conversation is created, specified in the date-time format. The time of creation is returned as part of the conversation object in response to a successful conversation creation request.
app_idMandatory string All businesses that use Freshchat are assigned an app_id that is used to integrate with Freshchat. The app_id is used to identify the Freshchat account under which the conversation is created. To know your app_id, navigate to https://web.freshchat.com and log in with your account credentials. Navigate to Settings > Account Settings > Integration Settings. The App ID is displayed under AGENT WIDGET.
channel_id string Identifier of a channel created by the business that uses Freshchat. Channels help users identify the subject in which they have a query; users can create a conversation in the identified channel. Agents can pick conversations in a specific channel and address the queries in them.
messagesMandatory array of message 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

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

Endpoints

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

The agents object

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

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

The agent object

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

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

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

List all agents

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

get
/v2/agents
Query parameters

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

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

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

Retrieve agent information

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

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

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

Update agent information

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

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

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

Channel

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

Endpoint

GET /channels

The channels object

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

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

The channel object

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

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

List all channels

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

get
/v2/channels
Query parameters

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

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

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

Group

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

Endpoint

GET /groups

The groups object

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

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

The group object

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

List all groups

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

get
/v2/groups
Query parameters

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

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

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

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 rich media template consisting of a header and body or a plain text 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.

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
36
37
38
39
40
41
42
43
44
45
46
{ "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" }, "template_data": [ { "data": "Arya Stark" } ], "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 ↓
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
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_datamandatory array of template data objects Values used to populate the variable parameters in the plain text message, specified as an array of the following format:

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

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

A business’s approved template to send a video notification to clients is as follows:

When triggering a request to send the notification message, the outbound message object sent as the request payload should be 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" }, "provider": "whatsapp", "to": { "phone_number": "+919999999999" }, "data": { "message_template": { "template_name": "hello_world", "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX", "language": { "policy": "deterministic", "code": "en_US" }, "rich_template_data": { "header": { "type": "video", "media_url": "https://sample.in/sample.mkv" }, "body": { "params": [ {"data": "John Doe"} ] } } } } }
EXPAND ↓

In the message sent, the video placeholder is populated with https://sample.in/sample.mkv and the message in the body section is, Hi John Doe, your payment is in process. Please refer to the video to understand how this will work.

A business’s approved template to send a titled text notification to clients is as follows:

When triggering a request to send the notification message, the outbound message object sent as the request payload should be 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
{ "from": { "phone_number": "+919999999999" }, "provider": "whatsapp", "to": { "phone_number": "+919999999999" }, "data": { "message_template": { "template_name": "hello_world", "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX", "language": { "policy": "deterministic", "code": "en_US" }, "rich_template_data": { "header": { "type": "text", "params": [ {"data": "John Doe"} ] }, "body": { "params": [ {"data": "XYZ"} ] } } } } }
EXPAND ↓

In the message sent, the title is Hey John Doe and the message in the body section is, You have successfully registered with our services under the name XYZ.

Send outbound messages

Creates a request to send whatsapp messages to users.

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
44
45
46
47
48
{ "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" }, "template_data": [ { "data": "Arya Stark" } ], "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.
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.

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) or logging off (inactive), 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.
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}
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.