PROChat API

Быстрый старт

1. Владелец или администратор создаёт ключ в Интеграции → API-ключи и выбирает подключения, разрешения и срок.
2. После создания токен показывается один раз. Сохраните его в хранилище секретов своей серверной программы.
3. Задайте PROCHAT_API_ORIGIN — origin сервера (домен без пути), и PROCHAT_API_TOKEN — выданный токен.

Базовый путь: /api/integration/v1. Для внешнего доступа используйте HTTPS. Локальный backend по умолчанию работает на http://localhost:4000; создание ключа само по себе не публикует сервер.

curl --fail-with-body \
  --header "Authorization: Bearer ${PROCHAT_API_TOKEN}" \
  --header "Accept: application/json" \
  "${PROCHAT_API_ORIGIN}/api/integration/v1/conversations?limit=50"

Переменные в примерах заполняются вашей программой. Имена, UUID и даты в ответах ниже вымышлены.

Авторизация и разрешения

Каждый запрос использует Authorization: Bearer <токен>. Формат токена: pc_api_ и 43 символа base64url, всего 50 символов. Это непрозрачный токен. Передача ключа в URL или cookie не заменяет заголовок.

Данные обращений ограничены выбранными подключениями. Например, messages:read позволяет прочитать сообщения известного обращения без conversations:read; поиск его ID в списке требует отдельного разрешения.

Разрешение cards:read также открывает активный каталог определений тегов и полей всего рабочего пространства. Значения карточек выдаются только для доступных обращений.

Срок — 7, 30, 90 или 365 дней. Отзыв ключа, изменение роли или версии доступа автора, а также удаление любого выбранного подключения прекращают доступ всего ключа. Отключённое подключение сохраняет доступ к уже записанной истории.

Сохраняйте ключ на сервере получателя. Доступ администратора к управлению ключами использует сессию PROChat; этот bearer-токен предназначен для методов чтения ниже.

Методы API

Все шесть методов используют GET. Неизвестные параметры, workspaceId и произвольные фильтры отклоняются.

Пути ниже добавляются к /api/integration/v1. В примерах cURL замените <ID_обращения> на UUID доступного обращения, полученный из списка или вебхука.

curl --fail-with-body \
  --header "Authorization: Bearer ${PROCHAT_API_TOKEN}" \
  "${PROCHAT_API_ORIGIN}/api/integration/v1/connections"

{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "name": "Авито — вымышленный пример",
      "provider": "AVITO",
      "mode": "MOCK",
      "status": "CONNECTED"
    }
  ]
}

curl --fail-with-body \
  --header "Authorization: Bearer ${PROCHAT_API_TOKEN}" \
  "${PROCHAT_API_ORIGIN}/api/integration/v1/conversations"

{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "connectionId": "00000000-0000-4000-8000-000000000001",
      "customerName": "Покупатель из вымышленного примера",
      "status": "OPEN",
      "handlingMode": "AUTOMATION",
      "assignedUserId": null,
      "assignmentVersion": 0,
      "cardVersion": 0,
      "lastMessageAt": "2026-10-14T12:00:00.000Z",
      "createdAt": "2026-10-14T12:00:00.000Z"
    }
  ],
  "nextCursor": null
}

curl --fail-with-body \
  --header "Authorization: Bearer ${PROCHAT_API_TOKEN}" \
  "${PROCHAT_API_ORIGIN}/api/integration/v1/conversations/<ID_обращения>"

{
  "id": "00000000-0000-4000-8000-000000000002",
  "connectionId": "00000000-0000-4000-8000-000000000001",
  "customerName": "Покупатель из вымышленного примера",
  "status": "OPEN",
  "handlingMode": "AUTOMATION",
  "assignedUserId": null,
  "assignmentVersion": 0,
  "cardVersion": 0,
  "lastMessageAt": "2026-10-14T12:00:00.000Z",
  "createdAt": "2026-10-14T12:00:00.000Z"
}

curl --fail-with-body \
  --header "Authorization: Bearer ${PROCHAT_API_TOKEN}" \
  "${PROCHAT_API_ORIGIN}/api/integration/v1/conversations/<ID_обращения>/messages"

{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000005",
      "conversationId": "00000000-0000-4000-8000-000000000002",
      "connectionId": "00000000-0000-4000-8000-000000000001",
      "type": "text",
      "direction": "INBOUND",
      "senderType": "CUSTOMER",
      "status": "SENT",
      "text": "Сообщение из вымышленного примера",
      "sequence": 1,
      "sentAt": "2026-10-14T12:00:00.000Z",
      "createdAt": "2026-10-14T12:00:00.000Z"
    }
  ],
  "nextCursor": null
}

curl --fail-with-body \
  --header "Authorization: Bearer ${PROCHAT_API_TOKEN}" \
  "${PROCHAT_API_ORIGIN}/api/integration/v1/conversations/<ID_обращения>/card"

{
  "conversationId": "00000000-0000-4000-8000-000000000002",
  "version": 0,
  "tags": [
    {
      "name": "Тег из примера",
      "color": "#6366f1",
      "id": "00000000-0000-4000-8000-000000000003",
      "revision": 0,
      "archivedAt": null
    }
  ],
  "fieldDefinitions": [
    {
      "id": "00000000-0000-4000-8000-000000000004",
      "name": "Сумма из примера",
      "type": "NUMBER",
      "options": [],
      "revision": 0,
      "archivedAt": null
    }
  ],
  "fieldValues": [
    {
      "fieldId": "00000000-0000-4000-8000-000000000004",
      "value": 1000
    }
  ]
}

curl --fail-with-body \
  --header "Authorization: Bearer ${PROCHAT_API_TOKEN}" \
  "${PROCHAT_API_ORIGIN}/api/integration/v1/card-catalog"

{
  "tags": [
    {
      "name": "Тег из примера",
      "color": "#6366f1",
      "id": "00000000-0000-4000-8000-000000000003",
      "revision": 0,
      "archivedAt": null
    }
  ],
  "fields": [
    {
      "id": "00000000-0000-4000-8000-000000000004",
      "name": "Сумма из примера",
      "type": "NUMBER",
      "options": [],
      "revision": 0,
      "archivedAt": null
    }
  ]
}

Пагинация и данные

Списки обращений и сообщений возвращают items и nextCursor. Передавайте полученный курсор с теми же фильтрами. Значение null означает конец выборки. Лимит страницы — от 1 до 100, по умолчанию 50.

Обращения отсортированы по lastMessageAt DESC, id DESC. Сообщения — по sentAt ASC, sequence ASC, id ASC. Курсор должен принадлежать доступной выборке; удаление записи или смена фильтров могут потребовать начать обход заново.

const origin = process.env.PROCHAT_API_ORIGIN; // Только origin, без пути
const token = process.env.PROCHAT_API_TOKEN;  // Из хранилища секретов
if (!origin || !token) throw new Error("Настройте адрес и API-ключ");

let cursor = null;
const seen = new Set();
do {
  const url = new URL("/api/integration/v1/conversations", origin);
  url.searchParams.set("limit", "50");
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
  });
  if (!response.ok) throw new Error(`PROChat API: HTTP ${response.status}`);
  const page = await response.json();
  for (const conversation of page.items) {
    if (!seen.has(conversation.id)) {
      seen.add(conversation.id);
      // Сохраните или обновите запись во внешней системе.
    }
  }
  cursor = page.nextCursor;
} while (cursor !== null);

Пример прекращает обход при HTTP-ошибке. Для 429 дождитесь Retry-After и повторите ту же страницу. Экспорт не является замороженным снимком: во внешней системе исключайте дубли по ID и обновляйте существующие записи при повторной загрузке.

Как читать ответы

• Служебные даты передаются в ISO 8601 UTC. Версии — неотрицательные целые числа.
• У сообщения PENDING или SENDING не подтверждает доставку. Учитывайте status вместе с sentAt; порядок при совпадающем времени уточняет sequence.
• В карточке fieldValues содержит только установленные значения: строку, конечное число или boolean. Значения 0 и false сохраняются. Тип и варианты берутся из fieldDefinitions.
• Карточка сохраняет назначенные архивные теги и архивные поля со значением. Общий каталог содержит активные определения рабочего пространства.
• Внутренние заметки, файлы и их URL, секреты каналов и телефоны из данных контакта исключены. Чтение не отмечает сообщения прочитанными и не обращается к API провайдера.

Квоты и ошибки

Лимит — 60 запросов на ключ и 600 на рабочее пространство в фиксированном минутном окне. Окно определяется UTC-временем сервера. Авторизованные попытки с неверным scope или параметрами также учитываются.

Дополнительно действует предел 1200 попыток за 60 секунд на IP до проверки токена. При HTTP 429 соблюдайте заголовок Retry-After в секундах. При недоступности обязательного ограничителя запрос получит 503. Ответы имеют Cache-Control: no-store.

{
  "code": "INTEGRATION_API_SCOPE_REQUIRED"
}

Не кешируйте секреты и ответы с перепиской. Последнее использование ключа в интерфейсе обновляется примерно раз в минуту и служит ориентиром активности.

Работа с вебхуками

1. Настройте подписку на события нужного подключения во вкладке «Исходящие вебхуки».
2. Проверьте HMAC-подпись исходных байтов запроса и исключите повторную обработку по ID события.
3. Для события conversation.card_changed получите conversation.id, затем прочитайте актуальную карточку через GET /conversations/{conversationId}/card с разрешением cards:read.

Секрет подписи вебхука и API-ключ — отдельные секреты. Вебхук содержит снимок на момент события, API возвращает актуальные сохранённые данные. Пауза рабочих отправок удерживает исходящие вебхуки; чтение API остаётся доступным.

В этой версии доступны сохранённые данные PROChat. Методы записи, провайдерская аналитика, объявления, файлы и готовые CRM-коннекторы расширяются отдельными задачами.