You can search for multiple chats by the value of their attributes in order to fetch exactly the ones you want.
➡️ Request
| URL | https://api.helpcrunch.com/v1/chats/search |
| Method | POST |
| Headers | Authorization: Bearer <your_api_key> |
Search filters should be placed to the body of your POST request. Check a couple of examples below.
Read more about authorization header here.
Example: Search with a single filter
{
"filter": [
{
"field": "chats.customer.email",
"operator": "=",
"value": "John"
}
],
"sort": "chats.createdAt",
"order": "desc",
"offset": 0,
"limit": 100
}Example: Search with multiple filters
If you want to get chats that match all the filters, use "comparison": "AND" attribute in the body of your POST request. To fetch chats matching any of the given filters, use OR value instead.
{
"comparison": "AND",
"filter": [
{
"field": "chats.customer.email",
"operator": "=",
"value": "John"
},
{
"field": "chats.assignee",
"operator": ">",
"value": 18
},
{
"field": "chats.createdAt",
"operator": ">=",
"value": 1603885746
},
{
"field": "chats.status",
"operator": "=",
"value": "John"
},
{
"field": "chats.rating",
"operator": "=",
"value": "John"
},
{
"field": "chats.customer.tagsData",
"operator": "=",
"value": [
{
"name": "Lead"
}
]
}
],
"sort": "chats.createdAt",
"order": "desc",
"offset": 0,
"limit": 100
}
Accepted searchable fields
| Field | Type | Description |
| chats.assignee | Integer | The id of the agent the chat is assigned to. How to get agent id |
| chats.agents | Integer | The id of the agent who sent at least one message to the chat. How to get agent id |
| chats.createdAt | Date (UNIX timestamp) | Date and time of chat creation |
| chats.department | Integer | The id of the department the chat is assigned to. How to get department id |
| chats.status | String |
Current chat status: |
| chats.closedAt | Date (UNIX timestamp) | Date and time the chat was closed |
| chats.rating | String | Chat rating specified by a customer after the chat closure: "great", "average" or "poor" |
| chats.customer | Integer | Unique id of the customer provided by HelpCrunch |
| chats.customer.email | String | Customer email |
| chats.customer.tagsData | Array of Strings | Tags assigned to the chat, e.g. [{"name": "Lead"}, {"name": "Paid"}] |
| chats.customer.userId | String | Unique id of the customer that you can pass to HelpCrunch with User Authentication |
Accepted operators
| Operator | Valid Field Data Types | Description |
| = | All data types | Equals |
| != | All data types (except arrays) | Doesn't Equal |
| > | Integer or Date (UNIX Timestamp) | Greater than |
| < | Integer or Date (UNIX Timestamp) | Lower than |
| >= | Integer or Date (UNIX Timestamp) | Greater than or equal |
| <= | Integer or Date (UNIX Timestamp) | Lower than or equal |
| ~ | String | Contains |
| !~ | String | Doesn't Contain |
Sorting options
To specify the sorting type, you should add sort and order attributes to the body of your POST request.
"sort": "lastCustomerMessageAt",
"order": "ASC"You can sort chats by the following fields:
| Field | Description |
| chats.createdAt | by date chats were created |
| chats.lastCustomerMessageAt | by date of the last message from customer |
| chats.lastMessageAt | by date of the last message from agent or customer |
| chats.closedAt | by date chats were closed |
To sort chats in descending order, use DESC value. For ascending order use ASC value.
✅ Successful Response
If your request has succeeded, you'll get a 200 OK success status code together with the following response body.
{
"data": [
{
"id": 542335,
"closedBy": "string",
"lastCustomerMessageAt": "1603885746",
"status": "new",
"closedAt": "1603885746",
"rating": "perfect",
"createdAt": "1603885746",
"lastMessageAt": "1603885746",
"createdWith": "string",
"snoozedUntil": "1603885746",
"lastMessageText": "string",
"lastMessageId": 542335,
"applicationId": 542335,
"lastCommunicatedAgentId": 542335,
"agents": [
{
"id": 542335,
"name": "string",
"email": "string",
"role": "string"
}
],
"customer": {
"id": 542335,
"name": "string",
"email": "string",
"userId": "string"
},
"assignee": {
"id": 542335,
"name": "string",
"email": "string",
"role": "string"
},
"department": {
"id": 542335,
"name": "string"
}
}
],
"meta": {
"total": 435
}
}You can get details on every Chat Object field in the Chat model article.
Limits
By default, this method returns only the first 100 chats. To get a different set of chats, you should use the offset and limit parameters in the body of your POST request.
"limit": 50,
"offset": 100,The overall requests limit is 120 per minute
🛑 Error Responses
You may get one of the following error status codes and responses. More info on the errors is available here.
400 Bad Request
{
"errors": [
{
"code": "invalid_request",
"message": "Invalid request"
},
{
"code": "customer",
"message": "This value should be of type numeric."
},
{
"code": "filter[0].field",
"message": "This value should not be blank."
}
]
}401 Unauthorized
{
"errors": [
{
"code": "invalid_request",
"message": "Invalid request"
},
{
"code": "unauthorized",
"message": "Unauthorized"
}
]
}429 Too Many Requests
{
"errors": [
{
"code": "invalid_request",
"message": "Invalid request"
},
{
"code": "too_many_requests",
"message": "Too many requests"
}
]
}If you have any questions regarding the REST API, feel free to chat us any time.
👩💻 Happy Coding! 👨💻
