Знайти чати

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

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

➡️ Запит

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.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)

Оператор має бути введений у форматі 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"
    }
  ]
}
Чи була наша стаття корисною?