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.status",
"operator": "=",
"value": "3"
}
],
"limit": 5,
"offset": 0,
"sort": "chats.createdAt",
"order": "DESC"
}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": "OR",
"filter": [
{
"field": "chats.status",
"operator": "=",
"value": "5"
},
{
"field": "chats.customer.tagsData",
"operator": "=",
"value": [
{
"name": "Paid"
}
]
}
],
"limit": 10,
"offset": 0,
"sort": "lastCustomerMessageAt",
"order": "ASC"
}
Accepted searchable fields
The value you search for has to match the type, otherwise the query will fail. For example, chats.createdAt accepts a date, so the value can't be a string such as "18 Jun 2020".
| 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.updatedAt | Date (UNIX timestamp) | Date and time of the last chat update |
| 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
The operator should be put in as a string, for example ">"
The operator has to be compatible with the field's data type. You can't search with "<" for a string value as it works for integers and dates only.
| 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.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": 5215537,
"closedBy": null,
"lastCustomerMessageAt": 1592962537,
"status": "pending",
"closedAt": null,
"rating": null,
"createdAt": 1592962538,
"lastMessageAt": 1592992577,
"snoozedUntil": null,
"lastMessageText": "May I know how crucial is this for you?",
"lastMessageId": 9575496,
"lastCommunicatedAgentId": 3129,
"agents": [],
"customer": {
"id": 8740723,
"name": "Michael",
"email": "mike.nike@hellomail.com",
"userId": null
},
"assignee": {
"id": 3129,
"name": "Kosta",
"email": "kosta@company.com",
"role": "admin"
},
"department": null
},
{
"id": 5215503,
"closedBy": null,
"lastCustomerMessageAt": 1592945917,
"status": "pending",
"notes": null,
"closedAt": null,
"rating": null,
"createdAt": 1592945918,
"lastMessageAt": 1592989608,
"snoozedUntil": null,
"lastMessageText": "Can you bear with us for a while? :slightly_smiling_face:",
"lastMessageId": 9575349,
"lastCommunicatedAgentId": 3129,
"agents": [],
"customer": {
"id": 8740719,
"name": "Laura",
"email": "laura@mybusiness.io",
"userId": null
},
"assignee": {
"id": 3129,
"name": "Kosta",
"email": "kosta@company.com",
"role": "admin"
},
"department": null
},
{
"id": 5215590,
"closedBy": null,
"lastCustomerMessageAt": 1593032899,
"status": "pending",
"notes": null,
"closedAt": null,
"rating": null,
"createdAt": 1592941965,
"lastMessageAt": 1593032899,
"snoozedUntil": null,
"lastMessageText": "That would be great, thanks!",
"lastMessageId": 9575944,
"lastCommunicatedAgentId": 3129,
"agents": [],
"customer": {
"id": 8740715,
"name": "Emanuel",
"email": "emanuel.kushe@example.co.uk",
"userId": null
},
"assignee": {
"id": 3129,
"name": "Kosta",
"email": "kosta@company.com",
"role": "admin"
},
"department": null
},
{
"id": 5215447,
"closedBy": null,
"lastCustomerMessageAt": 1592875613,
"status": "pending",
"notes": null,
"closedAt": null,
"rating": null,
"createdAt": 1592875613,
"lastMessageAt": 1592912137,
"snoozedUntil": null,
"lastMessageText": "Hi Kevin,\nThank you for reaching out. That integration is one of the most requested features.",
"lastMessageId": 9574226,
"lastCommunicatedAgentId": 6668,
"agents": [],
"customer": {
"id": 8740684,
"name": "Kevin",
"email": "kevin@homealone.io",
"userId": null
},
"assignee": {
"id": 6668,
"name": "Donald",
"email": "donald@blabla.co",
"role": "admin"
},
"department": null
},
{
"id": 5215446,
"closedBy": null,
"lastCustomerMessageAt": 1592874288,
"status": "pending",
"notes": null,
"closedAt": null,
"rating": null,
"createdAt": 1592874289,
"lastMessageAt": 1592912308,
"snoozedUntil": null,
"lastMessageText": "Hello Borat,\nThank you for reaching out.",
"lastMessageId": 9574409,
"lastCommunicatedAgentId": 6668,
"agents": [],
"customer": {
"id": 7831592,
"name": "Borat",
"email": "borat@example.com",
"userId": null
},
"assignee": {
"id": 6668,
"name": "Donald",
"email": "donald@blabla.co",
"role": "admin"
},
"department": null
}
],
"meta": {
"total": 2244
}
}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_chat_value",
"message": "comparison"
}
{
"code": "invalid_chat_value",
"message": "Invalid chat ID"
}
{
"code": "invalid_chat_value",
"message": "customer value is invalid"
},
{
"code": "invalid_chat_value",
"message": "assignee value is invalid"
}
{
"code": "invalid_value",
"message": "status is not a valid integer"
}
{
"code": "invalid_field",
"message": "Field chats.customer.tagsDataff is invalid"
}
{
"code": "invalid_operator",
"message": "Operator ~~~~ is invalid"
}
]
}401 Unauthorized
{
"errors": [
{
"code": "invalid_token",
"message": "Invalid token"
}
]
}404 Not Found
{
"errors": [
{
"code": "chat_not_found",
"message": "Chat is missing"
}
]
}429 Too Many Requests
{
"errors": [
{
"code": "too_many_requests",
"message": "You have exceeded your requests limit"
}
]
}If you have any questions regarding the REST API, feel free to chat us any time.
👩💻 Happy Coding! 👨💻
