Получить сообщения

Получить список всех сообщений беседы

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

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

Авторизация

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

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

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

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

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

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

Ответ

200 - Успешно

application/json

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

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

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

Метаинформация (meta)

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

additional_attributes (object) Дополнительные атрибуты беседы

contact (object) Информация о контакте

Структура объекта контакта

payload (object[]) Массив данных контакта

Поля контакта

id (number) ID контакта

name (string) Имя контакта

email (string) Email контакта

phone_number (string) Номер телефона

additional_attributes (object) Дополнительные атрибуты

availability_status (string) Статус доступности

blocked (boolean) Заблокирован ли контакт

identifier (string) Идентификатор

thumbnail (string) URL миниатюры

custom_attributes (object) Пользовательские атрибуты

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

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

contact_inboxes (object[]) Массив входящих сообщений контакта

####### Структура contact_inboxes source_id (string) ID источника

inbox (object) Информация о входящих сообщениях

• id (number) - ID входящих

• avatar_url (string) - URL аватара

• channel_id (number) - ID канала

• name (string) - Название

• channel_type (string) - Тип канала

• provider (string) - Провайдер

Исполнитель (assignee)

id (number) ID исполнителя

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

availability_status (string) Статус доступности

auto_offline (boolean) Автоматический переход в оффлайн

confirmed (boolean) Подтвержден ли пользователь

email (string) Email исполнителя

available_name (string) Доступное имя

name (string) Имя исполнителя

role (string) Роль исполнителя

thumbnail (string) URL миниатюры

custom_role_id (number) ID пользовательской роли

Время активности

agent_last_seen_at (string<date-time>) Время последней активности агента

assignee_last_seen_at (string<date-time>) Время последней активности исполнителя

Сообщения (payload)

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

content (string) Текстовое содержимое сообщения

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

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

conversation_id (number) ID беседы

message_type (enum<integer>) Тип сообщения Доступные варианты: 0, 1, 2

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

updated_at (integer) Время обновления сообщения

private (boolean) Флаг приватности сообщения

status (enum<string>) Статус сообщения Доступные варианты: sent, delivered, read, failed

source_id (string) ID источника сообщения

content_type (enum<string>) Тип содержимого сообщения Доступные варианты: text, input_select, cards, form

content_attributes (object) Атрибуты содержимого для каждого типа content_type

sender_type (enum<string>) Тип отправителя Доступные варианты: contact, agent, agent_bot

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

external_source_ids (object) Внешние ID источников сообщения

additional_attributes (object) Дополнительные атрибуты сообщения

processed_message_content (string) Обработанное содержимое сообщения

sentiment (object) Тональность сообщения

conversation (object) Объект беседы

attachment (object) Объект файла, прикрепленного к сообщению

sender (object) Объект пользователя/агента/бота-агента

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

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

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

{
  "meta": {
    "labels": [
      "заказ",
      "срочно",
      "платежи"
    ],
    "additional_attributes": {
      "browser": "Chrome",
      "os": "Windows",
      "referrer": "https://shop.example.com"
    },
    "contact": {
      "payload": [
        {
          "additional_attributes": {
            "utm_source": "google",
            "utm_campaign": "support"
          },
          "availability_status": "онлайн",
          "email": "[email protected]",
          "id": 789,
          "name": "Марина Петрова",
          "phone_number": "[phone]",
          "blocked": false,
          "identifier": "customer_789",
          "thumbnail": "https://helpdesk.vivacrm.ru/avatars/marina.jpg",
          "custom_attributes": {
            "customer_tier": "премиум",
            "signed_up_at": "15/03/2023",
            "total_orders": 12,
            "last_order_date": "20/07/2025"
          },
          "last_activity_at": 1672531320,
          "created_at": 1679184000,
          "contact_inboxes": [
            {
              "source_id": "web_widget_contact_789",
              "inbox": {
                "id": 1,
                "avatar_url": "https://helpdesk.vivacrm.ru/inboxes/website.png",
                "channel_id": 1,
                "name": "Веб-сайт Поддержка",
                "channel_type": "Channel::WebWidget",
                "provider": "web_widget"
              }
            }
          ]
        }
      ]
    },
    "assignee": {
      "id": 456,
      "account_id": 123,
      "availability_status": "доступен",
      "auto_offline": false,
      "confirmed": true,
      "email": "[email protected]",
      "available_name": "Анна Сидорова",
      "name": "Анна Сидорова",
      "role": "agent",
      "thumbnail": "https://helpdesk.vivacrm.ru/avatars/anna.jpg",
      "custom_role_id": 3
    },
    "agent_last_seen_at": "2025-07-30T12:45:30Z",
    "assignee_last_seen_at": "2025-07-30T12:45:30Z"
  },
  "payload": [
    {
      "id": 1001,
      "content": "Здравствуйте! У меня проблема с оплатой заказа #ORD-2025-001234. Деньги списались с карты, но заказ показывает статус 'Ожидает оплаты'.",
      "account_id": 123,
      "inbox_id": 1,
      "conversation_id": 123,
      "message_type": 0,
      "created_at": 1722340800,
      "updated_at": 1722340800,
      "private": false,
      "status": "sent",
      "source_id": "web_widget",
      "content_type": "text",
      "content_attributes": {},
      "sender_type": "contact",
      "sender_id": 789,
      "external_source_ids": {
        "web_widget": "msg_web_1001"
      },
      "additional_attributes": {
        "referer": "https://shop.example.com/checkout",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
      },
      "processed_message_content": "Здравствуйте! У меня проблема с оплатой заказа #ORD-2025-001234. Деньги списались с карты, но заказ показывает статус 'Ожидает оплаты'.",
      "sentiment": {
        "polarity": "негативная",
        "score": -0.3,
        "keywords": ["проблема", "ожидает", "списались"]
      },
      "conversation": {
        "id": 123,
        "status": "open"
      },
      "attachment": null,
      "sender": {
        "id": 789,
        "name": "Марина Петрова",
        "email": "[email protected]",
        "type": "contact"
      }
    },
    {
      "id": 1002,
      "content": "Здравствуйте, Марина! Спасибо за обращение. Я помогу вам разобраться с проблемой оплаты. Проверяю информацию по заказу #ORD-2025-001234.",
      "account_id": 123,
      "inbox_id": 1,
      "conversation_id": 123,
      "message_type": 1,
      "created_at": 1722340860,
      "updated_at": 1722340860,
      "private": false,
      "status": "sent",
      "source_id": "agent",
      "content_type": "text",
      "content_attributes": {},
      "sender_type": "agent",
      "sender_id": 456,
      "external_source_ids": {},
      "additional_attributes": {
        "agent_response_time": 60,
        "auto_response": false
      },
      "processed_message_content": "Здравствуйте, Марина! Спасибо за обращение. Я помогу вам разобраться с проблемой оплаты. Проверяю информацию по заказу #ORD-2025-001234.",
      "sentiment": {
        "polarity": "позитивная",
        "score": 0.7,
        "keywords": ["спасибо", "помогу", "разобраться"]
      },
      "conversation": {
        "id": 123,
        "status": "open"
      },
      "attachment": null,
      "sender": {
        "id": 456,
        "name": "Анна Сидорова",
        "email": "[email protected]",
        "type": "agent"
      }
    },
    {
      "id": 1003,
      "content": "Я нашла ваш заказ. Действительно, платеж прошел успешно, но из-за технического сбоя статус не обновился автоматически. Сейчас я исправлю это вручную.",
      "account_id": 123,
      "inbox_id": 1,
      "conversation_id": 123,
      "message_type": 1,
      "created_at": 1722340920,
      "updated_at": 1722340920,
      "private": false,
      "status": "sent",
      "source_id": "agent",
      "content_type": "text",
      "content_attributes": {},
      "sender_type": "agent",
      "sender_id": 456,
      "external_source_ids": {},
      "additional_attributes": {
        "agent_response_time": 60,
        "auto_response": false,
        "order_checked": true
      },
      "processed_message_content": "Я нашла ваш заказ. Действительно, платеж прошел успешно, но из-за технического сбоя статус не обновился автоматически. Сейчас я исправлю это вручную.",
      "sentiment": {
        "polarity": "нейтральная",
        "score": 0.1,
        "keywords": ["нашла", "успешно", "исправлю"]
      },
      "conversation": {
        "id": 123,
        "status": "open"
      },
      "attachment": null,
      "sender": {
        "id": 456,
        "name": "Анна Сидорова",
        "email": "[email protected]",
        "type": "agent"
      }
    },
    {
      "id": 1004,
      "content": "Отлично! Статус заказа обновлен на 'Оплачен'. Ваш заказ передан в обработку. Ожидаемая дата доставки: 2 августа 2025 г.",
      "account_id": 123,
      "inbox_id": 1,
      "conversation_id": 123,
      "message_type": 1,
      "created_at": 1722340980,
      "updated_at": 1722340980,
      "private": false,
      "status": "delivered",
      "source_id": "agent",
      "content_type": "text",
      "content_attributes": {},
      "sender_type": "agent",
      "sender_id": 456,
      "external_source_ids": {},
      "additional_attributes": {
        "agent_response_time": 60,
        "auto_response": false,
        "order_updated": true,
        "delivery_date": "2025-08-02"
      },
      "processed_message_content": "Отлично! Статус заказа обновлен на 'Оплачен'. Ваш заказ передан в обработку. Ожидаемая дата доставки: 2 августа 2025 г.",
      "sentiment": {
        "polarity": "позитивная",
        "score": 0.8,
        "keywords": ["отлично", "обновлен", "передан"]
      },
      "conversation": {
        "id": 123,
        "status": "open"
      },
      "attachment": null,
      "sender": {
        "id": 456,
        "name": "Анна Сидорова",
        "email": "[email protected]",
        "type": "agent"
      }
    },
    {
      "id": 1005,
      "content": "Спасибо большое! Очень быстро решили проблему. Теперь все понятно.",
      "account_id": 123,
      "inbox_id": 1,
      "conversation_id": 123,
      "message_type": 0,
      "created_at": 1722341040,
      "updated_at": 1722341040,
      "private": false,
      "status": "sent",
      "source_id": "web_widget",
      "content_type": "text",
      "content_attributes": {},
      "sender_type": "contact",
      "sender_id": 789,
      "external_source_ids": {
        "web_widget": "msg_web_1005"
      },
      "additional_attributes": {
        "referer": "https://shop.example.com/checkout",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
      },
      "processed_message_content": "Спасибо большое! Очень быстро решили проблему. Теперь все понятно.",
      "sentiment": {
        "polarity": "позитивная",
        "score": 0.9,
        "keywords": ["спасибо", "быстро", "решили", "понятно"]
      },
      "conversation": {
        "id": 123,
        "status": "open"
      },
      "attachment": null,
      "sender": {
        "id": 789,
        "name": "Марина Петрова",
        "email": "[email protected]",
        "type": "contact"
      }
    }
  ]
}

Коды ответов

• 200 - Сообщения успешно получены

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

• 404 - Беседа не найдена

• 403 - Недостаточно прав для просмотра сообщений

Примечания по использованию

Типы сообщений (message_type)

• 0 - Входящее сообщение от контакта

• 1 - Исходящее сообщение от агента

• 2 - Активность/системное сообщение

Статусы сообщений (status)

• sent - Отправлено

• delivered - Доставлено

• read - Прочитано

• failed - Не удалось отправить

Типы отправителей (sender_type)

• contact - Контакт/клиент

• agent - Агент поддержки

• agent_bot - Бот-агент

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

• text - Текстовое сообщение

• input_select - Селектор ввода

• cards - Карточки

• form - Форма

Порядок сообщений

Сообщения возвращаются в хронологическом порядке (от старых к новым), что позволяет отследить полную историю общения.

Анализ тональности

Поле sentiment содержит автоматический анализ тональности сообщения:

• polarity - Полярность: позитивная, негативная, нейтральная

• score - Числовая оценка от -1 (очень негативная) до +1 (очень позитивная)

• keywords - Ключевые слова, влияющие на тональность

Вложения

Если к сообщению прикреплены файлы, информация о них будет в поле attachment с деталями о типе файла, размере и ссылке для скачивания.