Знайти чати

Знайдіть чати за значенням їхніх атрибутів
Написано Микола
Оновлено 2 місяці тому

Ви можете шукати кілька чатів за значенням їхніх атрибутів, щоб отримати саме ті, які вам потрібні.

➡️ Запит

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

Поточний статус чату:
Новий - 1
Відкритий - 2
В очікуванні - 3
На паузі - 4
Закритий - 5
Без спілкування - 6
Пустий - 7

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",
            "notes": null,
            "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"
        }
    ]
}
Чи була наша стаття корисною?