Чат-API и автоответы

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

База API: https://api.millida.net/v2/chat. Все сообщения проходят те же правила, что и в веб-чате (защита от увода сделки за пределы Millida, блокировки, статус сделки).

Получение ключа

Ключ выпускается в личном кабинете: Профиль → API и вебхуки → Создать ключ. При создании вы один раз получаете секрет вида mck_live_… — сохраните его, повторно он не показывается.

Ключ можно ограничить правами (scopes):

• chat:read — читать диалоги и сообщения, получать вебхуки;
• chat:write — отправлять сообщения;
• autoreply:manage — управлять правилами автоответов.

Пустой набор прав = ключ ничего не может (в отличие от Merchant-ключа). Ключ привязан к вашему аккаунту и охватывает все ваши сделки как продавца и как покупателя. Отозвать или перевыпустить — там же в ЛК.

Аутентификация

Передавайте ключ в заголовке Authorization: Bearer или X-Api-Key:

Authorization: Bearer mck_live_xxxxxxxxxxxxxxxx

Лимит запросов — 120/мин на ключ (отправка сообщений — 60/мин).

Диалоги и сообщения

Список диалогов

GET /v2/chat/dialogs?role=seller&status=ESCROW

role — buyer или seller (по умолчанию оба). status — необязательный фильтр по статусу сделки. Возвращает список сделок с участниками, товаром/услугой и последними сообщениями.

Сообщения диалога

GET /v2/chat/dialogs/{dealId}/messages?limit=50

Для подгрузки более старых сообщений передайте before — идентификатор самого раннего уже загруженного сообщения.

Отправить сообщение

POST /v2/chat/dialogs/{dealId}/messages
Content-Type: application/json

{ "text": "Здравствуйте! Приступаю к работе." }

Можно приложить картинку или файл: attachmentUrl, attachmentKind (image | file), attachmentName. Обязателен текст или вложение. Сообщение отправляется от вашего имени; роль (продавец/покупатель) определяется по сделке.

Отметить прочитанным

POST /v2/chat/dialogs/{dealId}/read

Вебхуки о новых сообщениях

Укажите webhookUrl у ключа — и на каждое входящее сообщение в ваших сделках прилетит уведомление. Вместе с URL выдаётся webhookSecret для проверки подписи.

Событие: message.new.

POST https://ваш-сайт/webhook
X-Millida-Event: message.new
X-Millida-Signature: sha256=…

{
  "event": "message.new",
  "data": {
    "dealId": "clx…",
    "dealStatus": "NEGOTIATION",
    "listingTitle": "Настройка плагинов",
    "from": "buyer",
    "counterparty": { "id": "usr_…", "nickname": "Steve", "displayName": "Steve" },
    "message": {
      "id": "msg_…",
      "text": "Здравствуйте, возьмётесь?",
      "attachmentUrl": null,
      "attachmentKind": null,
      "attachmentName": null,
      "createdAt": "2026-07-05T10:00:00.000Z"
    }
  }
}

Вебхук приходит на входящие сообщения (от собеседника), не на ваши собственные ответы.

Проверка подписи

Подпись — HMAC-SHA256 от «сырого» тела запроса с вашим webhookSecret. Сравнивайте безопасно (constant-time):

import { createHmac, timingSafeEqual } from 'crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Пример: авто-ответ на своём боте

app.post('/webhook', (req, res) => {
  if (!verify(req.rawBody, req.headers['x-millida-signature'], SECRET)) {
    return res.sendStatus(401);
  }
  const { dealId, from, message } = req.body.data;
  if (from === 'buyer' && /цена|стоимость/i.test(message.text ?? '')) {
    fetch(`https://api.millida.net/v2/chat/dialogs/${dealId}/messages`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${API_KEY}` },
      body: JSON.stringify({ text: 'Стоимость зависит от объёма — опишите задачу.' }),
    });
  }
  res.sendStatus(200);
});

Автоответы без своего бота

Если поднимать свой сервер не хочется, настройте автоответы прямо в ЛК: Профиль → API и вебхуки → Автоответы. Платформа сама ответит на входящее сообщение, если оно совпало с ключевым словом.

Параметры правила:

• Ключевое слово — текст-триггер (регистр не важен);
• Тип совпадения — contains (содержит, по умолчанию), exact (точное совпадение), prefix (начинается с);
• Ответ — что отправить;
• Приоритет — правила проверяются от меньшего к большему, срабатывает первое совпавшее.

Автоответы работают и вместе с вебхуком, и без него.

Безопасность

• Секрет ключа храните на сервере, не на фронтенде. Скомпрометированный ключ — отзовите и перевыпустите в ЛК.
• Всегда проверяйте подпись вебхука.
• Не дублируйте ответы: вебхук может прийти повторно — ориентируйтесь на message.id.
• Общение и передачу файлов держите внутри сделки: попытки увести переписку за пределы Millida блокируются, как и в веб-чате.