HTTP API v1 · Обзор

1. Быстрый старт

Создайте API-ключ в «Настройки → Интеграции», скопируйте profile_id из профиля и отправьте сообщение:

curl -X POST "https://your.host/api/v1/sync/message/send" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_id":"YOUR_PROFILE_ID","recipient":"1234567890","body":"Привет!"}'

Ответ:

{
  "status": "ok",
  "data": { "messageId": "uuid", "taskId": "uuid" }
}

2. CRM/1C интеграция

Поддерживаемый production-путь для внешних систем: профиль в кабинете, API-ключ аккаунта, webhook URL для входящих событий и импорт базы контактов из CSV/выгрузки 1C.

1. Создайте или подключите профиль Telegram, WhatsApp или MAX.
2. Скопируйте profile_id из профиля и API-ключ в «Настройки → Интеграции».
3. Импортируйте базу телефонов/имён, чтобы контакты появились в адресной книге профиля.
4. Отправляйте сообщения через sync/async endpoints нужной платформы.
5. Подпишитесь на webhook'и messages, delivery, connection и проверяйте HMAC.

Импорт контактов из CSV

Кабинетный endpoint принимает JSON или CSV с колонками phone/Телефон, name/Имя, last_name/Фамилия и external_id/client_id для сверки с CRM/1C. Для MAX контакты сохраняются в messenger_contacts; для Telegram/WhatsApp — в общей адресной книге профиля.

curl -X POST "https://chat-api.ru/api/v1/contact-import" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "YOUR_PROFILE_ID",
    "contacts": [
      { "phone": "+79990000000", "name": "Иван", "external_id": "1C-123" }
    ]
  }'

Для ручной привязки сначала получите диалог через GET /api/v1/chats?profile_id=... и возьмите из ответа поле external_chat_id или legacy alias externalChatId. Именно это значение подставляется в URL как {chat_id}. Внутренний UUID строки диалога из кабинета сюда не передаётся. Телефон, имя и CRM/1C ID передаются только в JSON body.

Если MAX lookup вернул chat_id, это и есть внешний external_chat_id для PATCH. Если клиент написал первым, телефон можно запросить чат-ботом или привязать вручную. Ручная привязка доступна только для приватных чатов; группы и каналы вернут identity.private_chat_required.

curl -X PATCH "https://chat-api.ru/api/v1/chats/1820755/identity" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "YOUR_PROFILE_ID",
    "phone": "+79990000000",
    "contact_name": "Иван",
    "crm_external_id": "1C-123",
    "identity_status": "client"
  }'

curl -X POST "https://your.host/api/contact-import" \
  -H "Content-Type: application/json" \
  -b "session=..." \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "csv": "external_id;Телефон;Имя;Фамилия\n1c-42;79991234567;Иван;Петров",
    "dryRun": false
  }'

Для ручной проверки адресной книги MAX тот же CSV можно превратить в файлmax-contacts-poc.vcf и импортировать его в отдельный тестовый телефон:

curl -X POST "https://your.host/api/contact-import/vcf" \
  -H "Content-Type: application/json" \
  -b "session=..." \
  -o max-contacts-poc.vcf \
  -d '{
    "csv": "external_id;phone;name;last_name\n1c-42;79991234567;Иван;Петров"
  }'

Ответ

{
  "data": {
    "profileId": "uuid",
    "provider": "max-direct",
    "imported": 1,
    "skipped": 0,
    "errors": 0,
    "rows": [
      {
        "row": 1,
        "phone": "79991234567",
        "name": "Иван",
        "lastName": "Петров",
        "sourceExternalId": "1c-42",
        "status": "imported",
        "registered": false,
        "externalId": null,
        "detectionStatus": "not_found"
      }
    ]
  }
}

MAX Direct не отдаёт полный список диалогов до синхронизации истории: чат появляется после входящего события, отправки сообщения или добавления контакта по телефону. Номер телефона MAX может быть недоступен, поэтому UI показывает phone, displayName или внешний ID — что реально отдала сессия.

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

API-ключ аккаунта передаётся в HTTP-заголовке Authorization (без префикса Bearer). Для POST/PATCH/PUT передавайте profile_id в JSON body; для GET/DELETE — в query.

Ротировать или отозвать ключ можно в «Настройки → Интеграции». Старый ключ отзывается мгновенно. Все эндпоинты требуют, чтобы Postgres был основным хранилищем (SESSION_STORE=postgres).

Скоупы (на будущее)

• messages:read — чтение сообщений и диалогов
• messages:send — отправка сообщений и медиа
• webhooks:write — настройка webhook-эндпоинтов

4. Формат ошибок

Все ошибки возвращаются в едином формате:

{
  "status": "error",
  "error": {
    "code": "validation.recipient_required",
    "message": "Field 'recipient' is required",
    "details": null
  }
}

5. Идемпотентность

Передайте заголовок Idempotency-Key с UUID-значением для безопасного повтора запроса. Если запрос с тем же ключом приходит повторно, возвращается кэшированный ответ. TTL — 24 часа.

curl -X POST "https://your.host/api/v1/sync/message/send" \
  -H "Authorization: ..." \
  -H "Idempotency-Key: 4a7b9e0f-1c84-4b2c-9b27-2e6e6f9e9a01" \
  -H "Content-Type: application/json" \
  -d '{"profile_id":"...","recipient":"...","body":"hi"}'

6. Эндпоинты

{
  "profileId": "uuid",
  "contacts": [{ "phone": "79991234567", "name": "Иван", "lastName": "Петров" }],
  "dryRun": false
}

{
  "profile_id": "uuid",
  "contacts": [{ "phone": "+79990000000", "name": "Иван", "external_id": "1C-123" }]
}

{
  "profile_id": "uuid",
  "phone": "+79990000000",
  "contact_name": "Иван",
  "crm_external_id": "1C-123",
  "identity_status": "client"
}

{
  "status": "ok",
  "data": {
    "external_chat_id": "1820755",
    "contact_phone": "79990000000",
    "contact_name": "Иван",
    "crm_external_id": "1C-123",
    "identity_status": "client",
    "identity_source": "manual"
  }
}

{
  "csv": "external_id;phone;name;last_name\n1c-42;79991234567;Иван;Петров"
}

{ "profile_id": "uuid", "recipient": "1234567890", "body": "Hello" }

{ "status": "ok", "data": { "messageId": "uuid", "taskId": "uuid" } }

{
  "status": "ok",
  "data": {
    "profileId": "uuid",
    "name": "Тест",
    "platform": "telegram",
    "externalProfileId": "f4f8d365-da2d",
    "authorized": true,
    "authorizedAt": "2026-05-07T18:09:45Z",
    "phone": "+79991234567",
    "username": "ccandybagg",
    "workerOnline": true
  }
}

{
  "status": "ok",
  "data": {
    "items": [
      {
        "externalChatId": "1234567890",
        "external_chat_id": "1234567890",
        "title": "Иван Иванов",
        "unreadCount": 3,
        "unread_count": 3,
        "lastMessageText": "Привет",
        "last_message_text": "Привет",
        "lastMessageAt": "2026-05-07T21:14:00Z",
        "last_message_at": "2026-05-07T21:14:00Z",
        "avatarUrl": null,
        "avatar_url": null,
        "contact_phone": "79990000000",
        "contact_name": "Иван",
        "crm_external_id": "1C-123",
        "identity_status": "client",
        "identity_source": "manual"
      }
    ],
    "nextCursor": "base64..."
  }
}

{ "url": "https://your.callback/webhook", "eventTypes": ["messages","delivery","connection"] }

{
  "status": "ok",
  "data": {
    "id": "uuid",
    "url": "https://your.callback/webhook",
    "eventTypes": ["messages","delivery","connection"],
    "active": true,
    "secret": "32-байтовый base64url секрет"
  }
}

{ "id": "uuid" }

7. Webhook'и

После регистрации URL мы отправляем POST-запрос на каждое выбранное событие. Подпись HMAC-SHA256 приходит в заголовке X-Wpcl-Signature: sha256=<hex>, тип события — в X-Wpcl-Event, идентификатор доставки — в X-Wpcl-Delivery.

Валидация подписи (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const sig = signatureHeader.replace(/^sha256=/, "");
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(sig, "hex"), Buffer.from(expected, "hex"));
}

Типы событий

• messages — входящее сообщение
• delivery — наше исходящее сообщение доставлено
• connection — подключение/отключение профиля
• statuses — резерв на будущие статусы прочтения

Payload входящего сообщения

{
  "messageId": "uuid",
  "conversationId": "uuid",
  "provider": "telegram",
  "externalChatId": "1234567890",
  "externalMessageId": "789",
  "text": "Привет",
  "createdAt": "2026-05-07T21:14:00Z",
  "attachments": [
    {
      "id": "uuid",
      "type": "image",
      "filename": "photo.jpg",
      "mimeType": "image/jpeg",
      "sizeBytes": 153120,
      "url": "/api/messenger/attachments/uuid"
    }
  ]
}

Retry-политика

На 2xx — доставлено. На 4xx (кроме 429) — failed без ретраев. На 5xx, 429 и timeout — до 6 попыток с экспоненциальным backoff: 30s, 60s, 120s, 240s, 480s, 960s.