Быстрый старт: первое сообщение в WhatsApp

Подготовьте API-ключ

Подготовьте API Key рабочего пространства, аккаунт WhatsApp и публичный HTTPS-приёмник Webhook. Храните API Key и секрет подписи на сервере. Проверьте ключ запросом ниже.

curl "https://api.unifyport.ai/v1/workspace" \
  -H "X-Api-Key: <YOUR_API_KEY>"

Зарегистрируйте webhook-эндпоинт

Сделайте это первым: прогресс авторизации и входящие сообщения в реальном времени приходят через webhook, без гарантированного повтора пропущенных доставок. ["*"] подписывает на все публичные стандартные события; WhatsApp HistorySync даёт лишь ограниченную недавнюю непрерывность, а не постоянный архив.

curl -X POST "https://api.unifyport.ai/v1/webhook-endpoints" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook",
  "status": "active",
  "subscribed_events": ["*"],
  "signing_secret": "<WEBHOOK_SIGNING_SECRET>"
}'

Проверьте доступные регионы

Аккаунт привязывается к региону, и не каждый провайдер работает везде. Сначала получите список регионов провайдера и выберите регион с allocatable: true — создание аккаунта в регионе, где выделение невозможно, завершается ошибкой 409 no_allocatable_server.

curl "https://api.unifyport.ai/v1/providers/whatsapp/regions" \
  -H "X-Api-Key: <YOUR_API_KEY>"

Создайте аккаунт WhatsApp

Создайте аккаунт для сообщений в выбранном доступном регионе. Для сопряжения WhatsApp по номеру телефона используйте auth_mode=code и полный международный номер только из цифр в provider_data.phone. Сохраните data.id как account_id для следующих шагов.

curl -X POST "https://api.unifyport.ai/v1/accounts" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "WhatsApp Support",
  "provider": "whatsapp",
  "region": "<REGION>",
  "status": "active",
  "auth_mode": "code",
  "provider_data": { "phone": "8600000000000" }
}'

Выполните сопряжение телефона

Отправьте {} в POST /auth/start с сохранённым номером. Покажите data.verify_code для ввода в WhatsApp на телефоне. Не отправляйте его в /auth/code. Перед отправкой сообщений проверьте авторизацию и подключение.

curl -X POST "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth/start" \
  -H "X-Api-Key: <YOUR_API_KEY>"

Проверьте готовность аккаунта

С тем же account_id запросите /auth и данные аккаунта. Дождитесь authorized и runtime_status=running. При необходимости продолжите авторизацию; если аккаунт авторизован, но не в сети, проверьте или обновите runtime.

curl -X GET "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth" \
  -H "X-Api-Key: <YOUR_API_KEY>"

curl -X GET "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>" \
  -H "X-Api-Key: <YOUR_API_KEY>"

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

Используйте сохранённый account_id. В этом примере WhatsApp адресат — полный международный номер с @s.whatsapp.net. Для ответа используйте data.conversation.id входящего события. Не переносите этот формат на другие каналы.

curl -X POST "https://api.unifyport.ai/v1/messages" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "<ACCOUNT_ID>",
  "to": { "id": "8600000000000@s.whatsapp.net", "type": "user" },
  "message": { "type": "text", "text": "Hello from UnifyPort" }
}'

Получите первое событие

Ответьте с тестового аккаунта получателя. Проверьте подпись, сохраните событие и подтвердите доставку. Удаляйте дубликаты обычных событий по ID и учитывайте нарушение порядка. Для conversation.history объединяйте сообщения по provider + account_id + conversation.id + messages[].id, не отбрасывая весь пакет по ID события. Если события нет, проверьте подписки, доступность получателя Webhook и ответы доставки.