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

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

UnifyPort сейчас доступен избранным клиентам — свяжитесь с командой, чтобы получить доступ к рабочей области. Каждый запрос ниже аутентифицируется заголовком X-Api-Key.

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

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

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

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",
  "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

Один аккаунт — одно виртуальное устройство. Используйте регион, отмеченный как allocatable на предыдущем шаге. Для сопряжения WhatsApp по номеру телефона используйте auth_mode=code и задайте в provider_data.phone номер в формате E.164, только цифры — он сохраняется на аккаунте и переиспользуется на следующем шаге.

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": "global",
  "status": "active",
  "auth_mode": "code",
  "provider_data": { "phone": "8613800138000" }
}'

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

Запустите поток с пустым телом — сохранённый номер переиспользуется, а в ответе под auth_payload приходит 8-значный verify_code. На телефоне откройте WhatsApp → «Связанные устройства» → «Связать по номеру телефона» и введите код в течение ~3 минут. Успех приходит на ваш webhook как account.auth.succeeded, за которым следует account.started; runtime запускается автоматически, вызывать /runtime/start не нужно.

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

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

Отправляйте нормализованный JSON — UnifyPort переводит его на язык провайдера. Для WhatsApp id получателя — <E.164>@s.whatsapp.net.

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": "8613912345678@s.whatsapp.net", "type": "user" },
  "message": { "type": "text", "text": "Hello from UnifyPort" }
}'

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

Ответьте с другого телефона: событие message.received придёт на ваш webhook-эндпоинт за считанные секунды. Дальше — проверяйте подпись доставки и обрабатывайте стандартный каталог событий.