Ви можете шукати кілька чатів за значенням їхніх атрибутів, щоб отримати саме ті, які вам потрібні.
➡️ Запит
| URL | https://api.helpcrunch.com/v1/chats/search |
| Метод | POST |
| Headers | Authorization: Bearer <your_api_key> |
Фільтри пошуку слід розміщати в тілі вашого запиту POST. Пропонуємо до вашої уваги кілька прикладів.
Приклад: пошук за допомогою одного фільтра
{
"filter": [
{
"field": "chats.status",
"operator": "=",
"value": "3"
}
],
"limit": 5,
"offset": 0,
"sort": "chats.createdAt",
"order": "DESC"
}Приклад: пошук за допомогою кількох фільтрів
Якщо ви хочете отримати чати, які відповідають усім фільтрам, використовуйте атрибут "comparison": "AND" у тілі запиту POST. Щоб отримати контакти, які відповідають будь-якому з фільтрів, використовуйте натомість значення OR.
{
"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"
}Прийнятні поля для пошуку
Значення, яке ви шукаєте, має відповідати типу, інакше запит буде невдалим. Наприклад, chats.createdAt приймає лише дати, тому значення не може бути рядком на зразок "18 червня 2020 року".
| Поле | Тип | Опис |
| chats.assignee | Integer | ID члена команди, на якого призначено чат. Щоб отримати інформацію про члена команди скористайтесь методом REST API "Отримати всіх учасників команди" |
| chats.agents | Integer | ID члена команди, який надіслав хоча б одне повідомлення в чат (ось як його отримати) |
| chats.createdAt | Date (UNIX timestamp) | Дата і час створення чату |
| chats.updatedAt | Date (UNIX timestamp) | Дата й час останнього оновлення чату |
| chats.department | Integer | ID відділу, на який призначено чат. Щоб отримати інформацію про відділ скористайтесь методом REST API "Отримати всі відділи" |
| chats.status | String |
Поточний статус чату: |
| chats.closedAt | Date (UNIX timestamp) | Дата й час закриття чату |
| chats.rating | String | Оцінка чату від контакту після закриття чату |
| chats.customer | Integer | Унікальний ID контакту, наданий HelpCrunch |
| chats.customer.email | String | Електронна адреса контакту |
| chats.customer.tagsData | Array of Strings | Теги, закріплені за контактом: напр. {"name": "Лід"}, {"name": "Оплачено"} |
| chats.customer.userId | String | Власний унікальний ID контакту, який ви можете передати в HelpCrunch за допомогою автентифікації користувача |
Прийнятні оператори (operators)
Оператор має бути введений у вигляді рядка, наприклад >. Оператор має бути сумісним із типом даних поля. Ви не можете шукати рядкове значення за допомогою <, оскільки це працює лише для цілих чисел і дат.
| Оператор | Дійсні типи даних поля | Опис |
| = | Усі типи даних | Дорівнює |
| != | Усі типи даних (крім масивів) | Не дорівнює |
| > | Integer або Date (UNIX Timestamp) | Більше ніж |
| < | Integer або Date (UNIX Timestamp) | Менше ніж |
| >= | Integer або Date (UNIX Timestamp) | Більше ніж або дорівнює |
| <= | Integer або Date (UNIX Timestamp) | Менше ніж або дорівнює |
| ~ | String | Містить |
| !~ | String | Не містить |
Параметри сортування
Щоб указати тип сортування, вам слід додати атрибути sort і order до тіла запиту POST.
"sort": "lastCustomerMessageAt",
"order": "ASC"Ви можете сортувати чати за такими полями:
| Поле | Опис |
| chats.lastCustomerMessageAt | за датою останнього повідомлення від контакту |
| chats.lastMessageAt | за датою останнього повідомлення від оператора або контакту |
| chats.closedAt | за датою закриття чатів |
Щоб відсортувати чати в порядку спадання, використовуйте значення DESC. Щоб відсортувати у порядку зростання - використовуйте значення ASC.
✅ Відповідь на успішний запит
Якщо ваш запит пройшов успішно, ви отримаєте код статусу успішного виконання 200 OK разом із наведеним нижче тілом відповіді.
{
"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
}
}Обмеження
За замовчуванням цей метод повертає лише перші 100 чатів. Щоб отримати інший набір чатів, вам слід використовувати параметри offset і limit у тілі запиту POST.
"limit": 50,
"offset": 100,Загальний ліміт на частоту запитів становить 120 запитів за хвилину.
🛑 Відповіді з помилками
Ви можете отримати один із наведених нижче кодів статусу помилки та відповіді. Додаткову інформацію про помилки можна знайти тут.
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"
}
]
}