Звонки

Создать звонокbeta

Эта функция находится в закрытом тестировании. Обратитесь в техническую поддержку, чтобы запросить доступ для рабочего пространства.

В настоящее время поддерживаются только личные голосовые и видеозвонки WhatsApp. Подготовьте приватную одноразовую ссылку join_url. Откройте её и нажмите Start call, чтобы начать звонок.

POSThttps://api.unifyport.ai/v1/calls

Поддерживаемые каналы

Перед вызовом

Используйте X-Api-Key нужного рабочего пространства на сервере. Перед запуском замените все заполнители.

Проверьте доступ рабочего пространства к закрытому тестированию. Перед созданием звонка завершите авторизацию WhatsApp и проверьте runtime_status=running. Используйте conversation_id личного диалога этого аккаунта.

Для звонка в браузере нужен доступ к микрофону; доступ к камере необязателен.

Откуда взять параметры

account_id: Возьмите data.id из создания или запроса аккаунта. Идентификатор относится к рабочему пространству X-Api-Key. Получить аккаунт
to.id · to.type: Передайте в to.id возвращённый API conversation_id целевого личного диалога этого аккаунта без изменений; задайте to.type=user. Не заменяйте его строкой номера телефона. Детали беседы

Запрос

curl -X POST 'https://api.unifyport.ai/v1/calls' \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "to": {
    "id": "<conversation_id>",
    "type": "user"
  },
  "media_type": "video"
}'

Параметры запроса

Заголовки

X-Api-Key

stringобязательно

API-ключ рабочей области. Рабочая область определяется по этому заголовку.

Content-Type

stringобязательно

Используйте application/json при отправке JSON-тела запроса.

Тело запроса

account_id

stringобязательно

ID аккаунта текущего рабочего пространства.

pattern: ^acc_[A-Za-z0-9][A-Za-z0-9_-]*$

to

objectобязательно

Получатель индивидуального звонка.

id

stringобязательно

Укажите conversation_id целевого диалога текущего аккаунта, используя значение, возвращённое API, без изменений.

minLength: 1

type

stringобязательно

Поддерживается только user; group/channel возвращают ошибку неподдерживаемого типа.

enum: user, group, channel

media_type

stringобязательно

voice — аудио, video — звонок с поддержкой видео.

enum: voice, video

Как понять результат

201 со state=preparing подготавливает звонок, но ещё не вызывает получателя. Сохраните call_id, откройте конфиденциальный join_url и нажмите Start call до возвращённого expires_at. Подтвердите соединение по состоянию звонка или call.answered.

Примечания

Подготовка личного голосового или видеозвонка WhatsApp (media_type: voice/video). to.id — conversation_id, to.type — user. Номера телефонов строкой и групповые звонки не поддерживаются. Срок подготовки по умолчанию — 2 минуты с момента создания; точный срок указан в expires_at. До его истечения откройте join_url и нажмите Start call. Этот срок не ограничивает длительность соединённого звонка. Микрофон обязателен, камера — нет. Не публикуйте одноразовую ссылку.

Ответ 201 · 201

{
  "request_id": "req_example",
  "data": {
    "call_id": "call_example",
    "direction": "outbound",
    "media_type": "video",
    "state": "preparing",
    "join_url": "https://calls.example.com/call/call_example#ticket=example-only",
    "expires_at": "2026-09-07T12:02:00Z"
  }
}

Тело ответа

call_id

string

Идентификатор звонка, также используется для завершения.

direction

string

Направление звонка.

enum: outbound

media_type

string

voice — аудио, video — звонок с поддержкой видео.

enum: voice, video

state

string

Текущее состояние звонка.

enum: preparing

join_url

string

Краткосрочная одноразовая HTTPS-ссылка. Не публикуйте и не записывайте её в журнал.

format: uri

expires_at

string

Срок подготовки в формате RFC3339.

format: date-time

Ответы

201

201 · 201

Запрос выполнен. См. пример тела ответа.

400

Bad Request

Тело запроса, путь или параметры некорректны.

401

Unauthorized

Заголовок X-Api-Key отсутствует или недействителен.

403

Forbidden

Запрос распознан, но операция запрещена.

404

Not Found

Запрошенный ресурс не найден. Сверьте error.code с текущей операцией.

409

Conflict

Запрошенная операция конфликтует с существующим аккаунтом провайдера или ресурсом.

500

Internal Server Error

Сервис столкнулся с неожиданной ошибкой.

501

Not Implemented

Выбранный провайдер не реализует эту операцию.

502

Bad Gateway

Адаптер или вышестоящий провайдер не смог завершить операцию.

503

Service Unavailable

Необходимая серверная служба временно недоступна.

При ошибке запроса

Проверьте HTTP-статус и error.code/numeric_code; сохраните request_id. Уточните доступ к тестированию, аккаунт и call_id. При конфликте создания сначала запросите текущий звонок. Перед повтором создания или завершения проверьте состояние звонка. Справочник ошибок

invalid_request · 10000 · 400: Проверьте обязательные поля, форматы и условия канала, затем исправьте запрос.
missing_api_key · 11000 · 401: Проверьте X-Api-Key и активность рабочего пространства.
invalid_api_key · 11001 · 401: Проверьте X-Api-Key и активность рабочего пространства.
account_not_found · 20020 · 404: Проверьте account_id и используйте X-Api-Key рабочего пространства владельца аккаунта. Текущий ключ не даёт доступа к аккаунту, которого нет в этом пространстве.
unsupported_by_provider · 30003 · 501: Проверьте руководство по возможностям канала и выберите поддерживаемый канал или действие. Повтор не добавляет поддержку.
beta_feature_not_enabled · 41002 · 403: Обратитесь в техническую поддержку за доступом рабочего пространства к закрытому тестированию. Повтор запроса или изменение is_beta в запросе не дают доступа.
call_already_active · 38000 · 409: Запросите текущий звонок, чтобы получить call_id. Дождитесь его окончания или завершите его перед созданием нового.