Список бесед

Получить список всех бесед с пагинацией

Метод запроса

GET /api/v1/accounts/{account_id}/conversations

Авторизация

Заголовки авторизации

api_access_token (string, обязательный) Заголовок

Этот токен можно получить на странице профиля или через консоль rails. Предоставляет доступ к конечным точкам в зависимости от уровня разрешений пользователя. Этот токен может быть сохранен внешней системой при создании пользователя через API для выполнения действий от имени пользователя.

Параметры пути

account_id (integer, обязательный) Числовой ID аккаунта

Параметры запроса

assignee_type (enum<string>) По умолчанию: all Фильтр бесед по типу исполнителя Доступные варианты: me, unassigned, all, assigned

status (enum<string>) По умолчанию: open Фильтр по статусу беседы Доступные варианты: all, open, resolved, pending, snoozed

q (string) Фильтрует беседы с сообщениями, содержащими поисковый термин

inbox_id (integer) ID входящих сообщений

team_id (integer) ID команды

labels (string[]) Массив меток

page (integer) По умолчанию: 1 Номер страницы для пагинации бесед

Ответ

200 - Успешно

application/json

Структура ответа

data (object) Основной объект данных

data.meta (object) Метаинформация о беседах:

• mine_count (number) - Количество моих бесед

• unassigned_count (number) - Количество неназначенных бесед

• assigned_count (number) - Количество назначенных бесед

• all_count (number) - Общее количество бесед

data.payload (object[]) Массив объектов бесед

Структура объекта беседы

id (number) ID беседы

messages (object[]) Массив сообщений в беседе

account_id (number) ID аккаунта

uuid (string) UUID беседы

additional_attributes (object) Объект, содержащий дополнительные атрибуты, связанные с беседой

agent_last_seen_at (number) Время последней активности агента

assignee_last_seen_at (number) Время последней активности исполнителя

can_reply (boolean) Можно ли отвечать в беседе

contact_last_seen_at (number) Время последней активности контакта

custom_attributes (object) Объект для сохранения пользовательских атрибутов беседы

inbox_id (number) ID входящих сообщений

labels (string[]) Метки беседы

muted (boolean) Заглушена ли беседа

snoozed_until (number) Время, когда беседа будет размьючена

status (enum<string>) Статус беседы Доступные варианты: open, resolved, pending

created_at (number) Время создания беседы

updated_at (number) Время последнего обновления беседы

timestamp (string) Временная метка создания беседы

first_reply_created_at (number) Время создания первого ответа

unread_count (number) Количество непрочитанных сообщений

last_non_activity_message (object) Последнее сообщение, не связанное с активностью

last_activity_at (number) Время последней активности в беседе

priority (string) Приоритет беседы

waiting_since (number) Время, с которого беседа ожидает

sla_policy_id (number) ID политики SLA

applied_sla (object) Примененное SLA

sla_events (object[]) Массив событий SLA

meta (object) Метаинформация, включающая:

• sender - Информация об отправителе

• channel - Канал связи

• assignee - Информация об исполнителе

• hmac_verified - Статус HMAC верификации

Структура сообщения

id (number) ID сообщения

content (string) Содержимое сообщения

account_id (number) ID аккаунта

inbox_id (number) ID входящих сообщений

conversation_id (number) ID беседы

message_type (number) Тип сообщения

created_at (number) Время создания

updated_at (number) Время обновления

private (boolean) Является ли сообщение приватным

status (string) Статус сообщения

source_id (string) ID источника

content_type (string) Тип содержимого

sender_type (string) Тип отправителя

sender_id (number) ID отправителя

Пример запроса

curl --request GET \
  --url https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations \
  --header 'api_access_token: <api-key>'

Пример с параметрами фильтрации

curl --request GET \
  --url 'https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations?status=open&assignee_type=me&page=1' \
  --header 'api_access_token: <api-key>'

Пример ответа

{
  "data": {
    "meta": {
      "mine_count": 5,
      "unassigned_count": 12,
      "assigned_count": 8,
      "all_count": 25
    },
    "payload": [
      {
        "id": 123,
        "messages": [
          {
            "id": 456,
            "content": "Здравствуйте, у меня вопрос по заказу",
            "account_id": 123,
            "inbox_id": 1,
            "conversation_id": 123,
            "message_type": 0,
            "created_at": 1672531200,
            "updated_at": 1672531200,
            "private": false,
            "status": "sent",
            "source_id": "web_widget",
            "content_type": "text",
            "sender_type": "contact",
            "sender_id": 789
          }
        ],
        "account_id": 123,
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "status": "open",
        "inbox_id": 1,
        "unread_count": 1,
        "created_at": 1672531200,
        "updated_at": 1672531300,
        "can_reply": true,
        "meta": {
          "sender": {
            "id": 789,
            "name": "Иван Петров",
            "email": "[email protected]",
            "phone_number": "[phone]"
          },
          "assignee": {
            "id": 456,
            "name": "Анна Агент",
            "email": "[email protected]",
            "role": "agent"
          },
          "hmac_verified": true
        }
      }
    ]
  }
}

Коды ответов

• 200 - Список бесед успешно получен

• 400 - Неверный запрос

• 401 - Неавторизованный доступ

• 403 - Доступ запрещен

Примеры использования фильтров

Получить только мои беседы

curl --request GET \
  --url 'https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations?assignee_type=me' \
  --header 'api_access_token: <api-key>'

Получить только открытые беседы

curl --request GET \
  --url 'https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations?status=open' \
  --header 'api_access_token: <api-key>'

Поиск по содержимому сообщений

curl --request GET \
  --url 'https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations?q=заказ' \
  --header 'api_access_token: <api-key>'

Фильтр по inbox_id

curl --request GET \
  --url 'https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations?inbox_id=1' \
  --header 'api_access_token: <api-key>'