Ви можете шукати кілька чатів за значенням їхніх атрибутів, щоб отримати саме ті, які вам потрібні.
➡️ Запит
| URL | https://api.helpcrunch.com/v1/chats/search |
| Метод | POST |
| Headers | Authorization: Bearer <your_api_key> |
Фільтри пошуку мають бути розміщені в тілі вашого запиту POST. Пропонуємо до вашої уваги кілька прикладів.
Приклад: пошук за допомогою одного фільтра
{
"filter": [
{
"field": "chats.customer.email",
"operator": "=",
"value": "John"
}
],
"sort": "chats.createdAt",
"order": "desc",
"offset": 0,
"limit": 100
}Приклад: пошук за допомогою кількох фільтрів
Якщо ви хочете отримати чати, які відповідають усім фільтрам, використовуйте атрибут "comparison": "AND" у тілі запиту POST. Щоб отримати контакти, які відповідають будь-якому з фільтрів, використовуйте натомість значення OR.
{
"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
}Прийнятні поля для пошуку
Значення, яке ви шукаєте, має відповідати типу, інакше запит буде невдалим. Наприклад, 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)
Оператор має бути введений у форматі String, наприклад ">". Оператор має бути сумісним із типом даних поля. Ви не можете шукати String значення за допомогою "<", оскільки це працює лише для цілих чисел і дат.
| Оператор | Дійсні типи даних поля | Опис |
| = | Усі типи даних | Дорівнює |
| != | Усі типи даних (крім масивів) | Не дорівнює |
| > | 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.createdAt | за датою створення чату |
| chats.lastCustomerMessageAt | за датою останнього повідомлення від контакту |
| chats.lastMessageAt | за датою останнього повідомлення від оператора або контакту |
| chats.closedAt | за датою закриття чатів |
Щоб відсортувати чати в порядку спадання, використовуйте значення DESC. Щоб відсортувати у порядку зростання, використовуйте значення ASC.
✅ Відповідь на успішний запит
Якщо ваш запит пройшов успішно, ви отримаєте код статусу успішного виконання 200 OK разом із наведеним нижче тілом відповіді.
{
"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
}
}Ви можете отримати деталі по кожному полю обʼєкту чату у статті Модель даних чату.
Обмеження
За замовчуванням цей метод повертає лише перші 100 чатів. Щоб отримати інший набір чатів, вам слід використовувати параметри offset і limit у тілі запиту POST.
"limit": 50,
"offset": 100,Загальний ліміт на частоту запитів становить 120 запитів за хвилину.
🛑 Відповіді з помилками
Ви можете отримати один із наведених нижче кодів статусу помилки та відповіді. Детальніше про коди помилок ви можете прочитати за посиланням.
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"
}
]
}