Создание нового сообщения

Создать новое сообщение в беседе

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

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

Авторизация

• userApiKey

• agentBotApiKey

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

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

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

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

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

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

Тело запроса

application/json

Обязательные параметры

content (string, обязательный) Содержимое сообщения Пример: "Здравствуйте, как я могу вам помочь?"

Необязательные параметры

message_type (enum<string>) Тип сообщения Доступные варианты: outgoing, incoming Пример: "outgoing"

private (boolean) Флаг для идентификации приватной заметки Пример: false

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

content_attributes (object) Атрибуты на основе типа содержимого Пример: {}

campaign_id (integer) ID кампании, к которой принадлежит сообщение Пример: 1

template_params (object) Параметры шаблона для сообщения в случае канала WhatsApp

Структура template_params

name (string) Название шаблона Пример: "sample_issue_resolution"

category (string) Категория шаблона Пример: "UTILITY"

language (string) Язык шаблона Пример: "ru_RU"

processed_params (object) Обработанные параметры шаблона Пример: {"1": "HelpDesk vivaCRM"}

Ответ

200 - Успешно

application/json

Основные поля сообщения

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 POST \
  --url https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '{
  "content": "Спасибо за ваше обращение! Я рассмотрю вашу проблему и свяжусь с вами в ближайшее время.",
  "message_type": "outgoing",
  "private": false,
  "content_type": "text"
}'

Создание приватной заметки для команды

curl --request POST \
  --url https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '{
  "content": "Клиент VIP-уровня. Требует особого внимания. Связаться с менеджером по работе с ключевыми клиентами.",
  "message_type": "outgoing",
  "private": true,
  "content_type": "text"
}'

Создание сообщения с шаблоном для WhatsApp

curl --request POST \
  --url https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '{
  "content": "Ваша проблема решена в системе {{1}}",
  "message_type": "outgoing",
  "private": false,
  "content_type": "text",
  "template_params": {
    "name": "problem_resolution_template",
    "category": "UTILITY",
    "language": "ru_RU",
    "processed_params": {
      "1": "HelpDesk vivaCRM"
    }
  }
}'

Создание сообщения с карточками

curl --request POST \
  --url https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '{
  "content": "Выберите интересующую вас категорию:",
  "message_type": "outgoing",
  "private": false,
  "content_type": "cards",
  "content_attributes": {
    "items": [
      {
        "title": "Заказы и доставка",
        "description": "Вопросы по заказам, доставке и возврату",
        "media_url": "https://helpdesk.vivacrm.ru/images/orders.png",
        "actions": [
          {
            "type": "link",
            "text": "Выбрать",
            "uri": "orders"
          }
        ]
      },
      {
        "title": "Платежи и счета",
        "description": "Помощь с оплатой и финансовыми вопросами",
        "media_url": "https://helpdesk.vivacrm.ru/images/payments.png",
        "actions": [
          {
            "type": "link",
            "text": "Выбрать",
            "uri": "payments"
          }
        ]
      }
    ]
  }
}'

Создание сообщения с формой

curl --request POST \
  --url https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '{
  "content": "Пожалуйста, заполните форму обратной связи:",
  "message_type": "outgoing",
  "private": false,
  "content_type": "form",
  "content_attributes": {
    "items": [
      {
        "name": "customer_name",
        "label": "Ваше имя",
        "type": "text",
        "required": true
      },
      {
        "name": "issue_category",
        "label": "Категория проблемы",
        "type": "select",
        "required": true,
        "options": [
          {"label": "Технические вопросы", "value": "technical"},
          {"label": "Биллинг", "value": "billing"},
          {"label": "Общие вопросы", "value": "general"}
        ]
      },
      {
        "name": "description",
        "label": "Описание проблемы",
        "type": "textarea",
        "required": true
      }
    ]
  }
}'

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

{
  "id": 1234,
  "content": "Спасибо за ваше обращение! Я рассмотрю вашу проблему и свяжусь с вами в ближайшее время.",
  "account_id": 123,
  "inbox_id": 1,
  "conversation_id": 456,
  "message_type": 1,
  "created_at": 1722341100,
  "updated_at": 1722341100,
  "private": false,
  "status": "sent",
  "source_id": "agent_api",
  "content_type": "text",
  "content_attributes": {},
  "sender_type": "agent",
  "sender_id": 789,
  "external_source_ids": {
    "api": "msg_api_1234"
  },
  "additional_attributes": {
    "created_via": "api",
    "agent_response_time": 0
  },
  "processed_message_content": "Спасибо за ваше обращение! Я рассмотрю вашу проблему и свяжусь с вами в ближайшее время.",
  "sentiment": {
    "polarity": "позитивная",
    "score": 0.8,
    "keywords": ["спасибо", "рассмотрю", "свяжусь"]
  },
  "conversation": {
    "id": 456,
    "status": "open",
    "updated_at": 1722341100
  },
  "attachment": null,
  "sender": {
    "id": 789,
    "name": "Анна Сидорова",
    "email": "[email protected]",
    "role": "agent",
    "avatar_url": "https://helpdesk.vivacrm.ru/avatars/anna.jpg"
  }
}

Коды ответов

• 200 - Сообщение успешно создано

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

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

• 400 - Неверный запрос (некорректные параметры)

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

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

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

• outgoing - Исходящее сообщение (от агента к клиенту)

• incoming - Входящее сообщение (от клиента к агенту)

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

• text - Обычное текстовое сообщение

• input_email - Поле ввода email

• cards - Интерактивные карточки с изображениями и действиями

• input_select - Выпадающий список для выбора

• form - Форма с несколькими полями ввода

• article - Статья из базы знаний

Приватные сообщения

Приватные сообщения (private: true) видны только агентам и используются для:

• Внутренних заметок о клиенте

• Инструкций для других агентов

• Эскалации проблем

• Комментариев о ходе решения

Шаблоны сообщений

При использовании template_params система автоматически:

• Подставляет параметры в текст шаблона

• Проверяет соответствие языку и категории

• Отслеживает использование шаблонов для аналитики

Интерактивные элементы

Карточки (cards)

Поддерживают:

• Заголовок и описание

• Изображения

• Кнопки действий

• Ссылки на внешние ресурсы

Формы (form)

Поддерживают типы полей:

• text - Текстовое поле

• textarea - Многострочный текст

• select - Выпадающий список

• email - Поле email с валидацией

• number - Числовое поле

• date - Поле даты

Автоматическая обработка

После создания сообщения система автоматически:

• Анализирует тональность текста

• Обновляет статус беседы

• Отправляет уведомления участникам

• Обновляет метрики времени ответа

• Запускает автоматические правила (если настроены)

Лимиты и ограничения

• Максимальная длина текста: 10,000 символов

• Максимальное количество карточек: 10

• Максимальное количество полей в форме: 20

• Поддерживаемые форматы вложений: изображения, документы, видео