Calls

Create a callbeta

This feature is in private beta. Contact technical support to request access for your workspace.

Currently, only WhatsApp one-to-one voice and video calls are supported. Prepare a private, single-use join_url. Open it and click Start call to place the call.

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

Supported channels

Before you call

Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.

Confirm that the workspace has private-beta access. Before creating a call, complete WhatsApp authorization and check runtime_status=running. Use the conversation_id of a private conversation under this account.

Starting the call in the browser requires microphone permission; camera access is optional.

Prepare your parameters

account_id: Use data.id from account creation or an account query. Account identifiers belong to the workspace selected by X-Api-Key. Get account
to.id · to.type: Use the API-returned conversation_id for the target private conversation under this account, unchanged, as to.id; set to.type=user. Do not substitute a phone-number string. Get conversation

Request

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"
}'

Request parameters

Headers

X-Api-Key

stringrequired

Workspace API key. The workspace is resolved from this header.

Content-Type

stringrequired

Use application/json when sending a JSON request body.

Request body

account_id

stringrequired

Account ID in this workspace.

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

to

objectrequired

Single-user call recipient.

id

stringrequired

Enter the conversation_id of the target conversation under the current account, as returned by the API.

minLength: 1

type

stringrequired

Only user is currently supported; group/channel return an unsupported error.

enum: user, group, channel

media_type

stringrequired

voice for audio; video for a video-capable call.

enum: voice, video

Understand the result

201 with state=preparing prepares a call; it does not dial the recipient. Save call_id, open the private join_url and click Start call before the returned expires_at. Confirm connection from the call state or call.answered.

Notes

Prepare a WhatsApp voice or video call (media_type: voice/video). to.id is the conversation_id and to.type must be user; phone-number strings and group calls are not supported. Preparation lasts 2 minutes from creation by default; use the returned expires_at as the actual deadline. Open join_url and click Start call before it expires. This deadline does not limit connected call duration. Microphone permission is required; camera access is optional. Keep the single-use link private.

Response 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"
  }
}

Response body

call_id

string

Call identifier, also used to hang up.

direction

string

Call direction.

enum: outbound

media_type

string

voice for audio; video for a video-capable call.

enum: voice, video

state

string

Current call state.

enum: preparing

join_url

string

Short-lived, single-use HTTPS link. Do not log or publish it.

format: uri

expires_at

string

Preparation expiry time in RFC3339 format.

format: date-time

Responses

201

201 · 201

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

403

Forbidden

The request is authenticated but is not allowed.

404

Not Found

The requested resource was not found. Check error.code and the current operation.

409

Conflict

The requested operation conflicts with an existing provider account or resource.

500

Internal Server Error

The service encountered an unexpected error.

501

Not Implemented

The selected provider does not implement this operation.

502

Bad Gateway

The provider adapter or upstream provider could not complete the operation.

503

Service Unavailable

A required backend service is temporarily unavailable.

If the request fails

Inspect HTTP status and error.code/numeric_code; keep request_id. Check private-beta access, the account and call_id. On a creation conflict, query the active call first. Check the current call before retrying creation or hangup. Error reference

invalid_request · 10000 · 400: Check required fields, formats and channel conditions, then correct the request.
missing_api_key · 11000 · 401: Check X-Api-Key and whether the workspace is active.
invalid_api_key · 11001 · 401: Check X-Api-Key and whether the workspace is active.
account_not_found · 20020 · 404: Check account_id and use an X-Api-Key for the workspace that owns the account. An account not found in this workspace cannot be accessed with this key.
unsupported_by_provider · 30003 · 501: Check the channel capability guide and choose a supported channel or action. Repeating the request does not add support.
beta_feature_not_enabled · 41002 · 403: Contact technical support to request private-beta access for the workspace. Repeating the request or changing is_beta in a request does not grant access.
call_already_active · 38000 · 409: Query the active call to obtain call_id. Wait for it to end or hang it up before creating another call.