Детали беседы

Получить всю детальную информацию о беседе со всеми сообщениями в беседе

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

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

Авторизация

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

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

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

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

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

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

Ответ

200 - Успешно

application/json

Основные поля беседы

id (number) ID беседы

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

uuid (string) UUID беседы

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

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

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

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

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

Информация об активности

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

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

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

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

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

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

Настройки и атрибуты

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

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

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

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

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

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

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

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

SLA и политики

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

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

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

Сообщения

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

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

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) Объект пользователя/агента/бота-агента

Последнее сообщение

last_non_activity_message (object) Последнее сообщение, не связанное с активностью (имеет ту же структуру, что и объект сообщения)

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

meta (object) Объект метаинформации, содержащий:

Отправитель (sender)

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

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

email (string) Email отправителя

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

name (string) Имя отправителя

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

blocked (boolean) Заблокирован ли пользователь

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

thumbnail (string) Миниатюра изображения

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

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

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

Канал

channel (string) Канал связи

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

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

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

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

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

display_name (string) Отображаемое имя

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

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

accounts (object[]) Массив аккаунтов исполнителя

Верификация

hmac_verified (boolean) Статус HMAC верификации

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

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

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

{
  "id": 123,
  "messages": [
    {
      "id": 456,
      "content": "Здравствуйте, у меня проблема с заказом #12345",
      "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",
      "content_attributes": {},
      "sender_type": "contact",
      "sender_id": 789,
      "external_source_ids": {},
      "additional_attributes": {},
      "processed_message_content": "Здравствуйте, у меня проблема с заказом #12345",
      "sentiment": {
        "polarity": "neutral",
        "score": 0.1
      },
      "conversation": {},
      "attachment": {},
      "sender": {
        "id": 789,
        "name": "Мария Иванова",
        "email": "[email protected]"
      }
    },
    {
      "id": 457,
      "content": "Здравствуйте! Я помогу вам с заказом. Расскажите подробнее о проблеме.",
      "account_id": 123,
      "inbox_id": 1,
      "conversation_id": 123,
      "message_type": 1,
      "created_at": 1672531300,
      "updated_at": 1672531300,
      "private": false,
      "status": "sent",
      "source_id": "agent",
      "content_type": "text",
      "content_attributes": {},
      "sender_type": "agent",
      "sender_id": 456,
      "external_source_ids": {},
      "additional_attributes": {},
      "processed_message_content": "Здравствуйте! Я помогу вам с заказом. Расскажите подробнее о проблеме.",
      "sentiment": {
        "polarity": "positive",
        "score": 0.8
      },
      "conversation": {},
      "attachment": {},
      "sender": {
        "id": 456,
        "name": "Анна Агент",
        "email": "[email protected]"
      }
    }
  ],
  "account_id": 123,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "additional_attributes": {
    "browser": "Chrome",
    "os": "Windows"
  },
  "agent_last_seen_at": 1672531350,
  "assignee_last_seen_at": 1672531350,
  "can_reply": true,
  "contact_last_seen_at": 1672531320,
  "custom_attributes": {
    "customer_tier": "premium",
    "order_number": "12345"
  },
  "inbox_id": 1,
  "labels": ["заказ", "проблема"],
  "muted": false,
  "snoozed_until": null,
  "status": "open",
  "created_at": 1672531200,
  "updated_at": 1672531350,
  "timestamp": "2023-01-01T12:00:00Z",
  "first_reply_created_at": 1672531300,
  "unread_count": 1,
  "last_non_activity_message": {
    "id": 457,
    "content": "Здравствуйте! Я помогу вам с заказом. Расскажите подробнее о проблеме.",
    "account_id": 123,
    "inbox_id": 1,
    "conversation_id": 123,
    "message_type": 1,
    "created_at": 1672531300,
    "updated_at": 1672531300,
    "private": false,
    "status": "sent",
    "source_id": "agent",
    "content_type": "text",
    "content_attributes": {},
    "sender_type": "agent",
    "sender_id": 456,
    "external_source_ids": {},
    "additional_attributes": {},
    "processed_message_content": "Здравствуйте! Я помогу вам с заказом. Расскажите подробнее о проблеме.",
    "sentiment": {},
    "conversation": {},
    "attachment": {},
    "sender": {}
  },
  "last_activity_at": 1672531350,
  "priority": "высокий",
  "waiting_since": 1672531200,
  "sla_policy_id": 1,
  "applied_sla": {
    "first_response_time": 3600,
    "resolution_time": 86400
  },
  "sla_events": [
    {
      "event_type": "first_response",
      "target_time": 1672534800,
      "achieved": true
    }
  ],
  "meta": {
    "sender": {
      "additional_attributes": {
        "source": "website"
      },
      "availability_status": "онлайн",
      "email": "[email protected]",
      "id": 789,
      "name": "Мария Иванова",
      "phone_number": "[phone]",
      "blocked": false,
      "identifier": "customer_789",
      "thumbnail": "https://example.com/avatar.jpg",
      "custom_attributes": {
        "vip_customer": true
      },
      "last_activity_at": 1672531320,
      "created_at": 1672450000
    },
    "channel": "Website",
    "assignee": {
      "id": 456,
      "access_token": "agent_token_456",
      "account_id": 123,
      "available_name": "Анна Агент",
      "avatar_url": "https://helpdesk.vivacrm.ru/avatars/anna.jpg",
      "confirmed": true,
      "display_name": "Анна",
      "message_signature": "С уважением,\nАнна\nHelpDesk vivaCRM",
      "email": "[email protected]",
      "hmac_identifier": "hmac_anna_456",
      "inviter_id": 1,
      "name": "Анна Агент",
      "provider": "email",
      "pubsub_token": "pubsub_456",
      "role": "agent",
      "ui_settings": {
        "theme": "light",
        "language": "ru"
      },
      "uid": "anna_uid_456",
      "type": "User",
      "custom_attributes": {
        "department": "support"
      },
      "accounts": [
        {
          "id": 123,
          "name": "HelpDesk vivaCRM",
          "status": "active",
          "active_at": "2023-11-07T05:31:56Z",
          "role": "agent",
          "permissions": [
            "conversation:read",
            "conversation:write",
            "contact:read"
          ],
          "availability": "доступен",
          "availability_status": "онлайн",
          "auto_offline": false,
          "custom_role_id": 2,
          "custom_role": {
            "name": "Агент поддержки"
          }
        }
      ]
    },
    "hmac_verified": true
  }
}

Коды ответов

• 200 - Детали беседы успешно получены

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• agent - Агент

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

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

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

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

• cards - Карточки

• form - Форма

Этот API возвращает полную историю беседы со всеми сообщениями в хронологическом порядке, что позволяет получить полный контекст общения между клиентом и агентами поддержки.