Журнал изменений June 28, 2026

Обновление UnifyPort API: метки разговоров, контактные сообщения и трассировка запросов — UnifyPort

Через три недели после стабильного релиза v1 в UnifyPort API добавлен первый пакет функций: метки разговоров для организации WhatsApp-чатов, тип сообщения «контактная карточка», трассировка запросов через каждый вызов и набор улучшений для разработчиков, которые делают справочник webhook-событий значительно полезнее.

Ниже — полный список изменений с реальными именами эндпоинтов и полей.

Метки разговоров — 4 новых эндпоинта

Теперь можно создавать, перечислять, обновлять и удалять метки для разговоров, а также массово добавлять или убирать метки. Это та же система меток, которую WhatsApp предоставляет нативно — UnifyPort выводит её через четыре эндпоинта в категории Conversations.

Список меток

GET /v1/accounts/{account_id}/conversations/labels?limit=50&cursor=

Возвращает пагинированный список меток, каждая с id и name:

{
  "data": {
    "items": [
      { "id": "label_example", "name": "VIP" }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

Создание или обновление метки

POST /v1/accounts/{account_id}/conversations/labels/upsert

Пустой label_id — создание; существующий label_id — переименование:

{
  "label_id": "",
  "name": "VIP"
}

Удаление метки

POST /v1/accounts/{account_id}/conversations/labels/delete

{
  "label_id": "label_example"
}

Добавление / снятие метки с разговоров

POST /v1/accounts/{account_id}/conversations/labels

action — add или remove; conversation_ids должен содержать хотя бы один ID:

{
  "label_id": "label_example",
  "action": "add",
  "conversation_ids": ["peer_example"]
}

Все четыре эндпоинта пока работают только с WhatsApp. Остальные провайдеры возвращают 501 unsupported_by_provider. Соответствующие коды ошибок — list_conversation_labels_failed, upsert_label_failed, delete_label_failed, set_label_members_failed — задокументированы в справочнике ошибок.

Тип сообщения «контакт» (vCard)

POST /v1/messages теперь принимает message.type: "contact" со структурированным массивом contacts. UnifyPort автоматически генерирует vCard — вы отправляете структурированный JSON, получатель видит стандартную контактную карточку.

{
  "account_id": "acc_example",
  "to": {
    "id": "user_example",
    "type": "user"
  },
  "message": {
    "type": "contact",
    "contacts": [
      {
        "name": "Jane Doe",
        "phones": [{ "number": "+8613800000000", "type": "CELL" }],
        "emails": [{ "address": "jane@example.com" }],
        "organization": "ACME",
        "title": "PM"
      }
    ]
  }
}

Каждая карточка обязана содержать name. Поля phones[].number, emails[].address, organization и title — опциональные. Можно отправить одну или несколько карточек — WhatsApp сопоставляет одну карточку с типом contact, несколько — с contact_array.

Пустой массив contacts или карточка без name возвращает 400 invalid_request. Провайдеры, кроме WhatsApp, до добавления поддержки возвращают 400 unsupported_message_type.

Трассировка запросов — request_id и X-Request-Id

Каждый API-ответ — и успешный, и ошибочный — теперь содержит поле request_id верхнего уровня и дублирует его в заголовке ответа X-Request-Id. Ссылайтесь на этот ID при обращениях в поддержку или отладке сбоев.

Для сопоставления на стороне клиента отправьте свой собственный заголовок запроса X-Request-Id — он вернётся в ответе как client_request_id. Это позволяет связывать исходящие API-вызовы с вашими внутренними ID запросов без дополнительного маппинга.

Реальные примеры webhook-нагрузок

В справочнике API теперь приведены реальные структуры нагрузок из парсеров устройств (Telegram и WhatsApp).

message.received показывает нагрузки по типу контента — текст, изображение, голос, документ и геолокация — вместо пустого заполнителя data: {} вы видите точную структуру полей для каждого варианта.

group.updated показывает нагрузки по типу изменения:

Переименование — changes[].kind: "renamed" с новым name группы
Добавление/удаление участников — changes[].kind: "member_added" или "member_removed" с массивом members[] идентификаторов участников
Повышение/понижение администратора — changes[].kind: "promoted" или "demoted" с members[]

Одно событие group.updated может содержать несколько изменений одновременно — например, переименование и добавление участника в одном снимке.

Три новых инструмента для разработчиков

На странице инструментов появились три браузерные утилиты, работающие на стороне клиента:

Генератор HMAC-подписей — генерация и проверка HMAC-SHA1/SHA256/SHA512 подписей в браузере; полезно для отладки проверки webhook signing_secret
Конвертер Unix-меток времени — взаимная конвертация Unix-меток и читаемых дат с автоопределением секунд и миллисекунд
Форматирование JSON — форматирование, минификация и валидация JSON с подсветкой синтаксиса и копированием JSON Path по клику

Ломающее изменение: удалены два поля

Из справочника POST /v1/messages удалены два нереализованных поля для соответствия фактической поверхности API:

idempotency_key — удалён. Поле было задокументировано, но никогда не реализовано в API устройств.
provider_data.reply_to — удалён из документированной поверхности. Объект provider_data теперь показывает parse_mode в качестве примера поля.

Если ваш код отправлял idempotency_key или provider_data.reply_to, проверьте, не полагались ли вы на поведение, которое фактически было нерабочим. Ни одно из этих полей не обрабатывалось API.

Что дальше

Метки разговоров и контактные сообщения запускаются в первую очередь для WhatsApp, так как его API нативно поддерживает эти функции. По мере добавления аналогичных возможностей другими провайдерами — или когда слой нормализации сможет закрыть разрыв — функции станут доступны на дополнительных каналах с той же поверхностью эндпоинтов. Ответ 501 unsupported_by_provider сделан намеренно: он точно сообщает, какой провайдер ещё не поддерживает функцию, вместо молчаливого отбрасывания запроса.

Полный справочник API доступен на unifyport.ai/docs.