Skip to content

Put a call on-air

POST
/v1/calls/{call}/onair
curl --request POST \
--url https://api.caller9.app/v1/calls/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/onair \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "hybrid": 2 }'

Moves the caller to on-air line N (default 1). If the call is still queued (ringing), it is answered and sent straight to that line. If the caller is already on that line this is a no-op. The response returns as soon as the move is accepted; the audio connection completes a moment later.

call
required
string format: uuid

Call ID (UUID).

Media typeapplication/json
object
hybrid

On-air line number. Must be a JSON number; any non-numeric value is ignored and line 1 is used. Values below 1 are treated as 1. Not validated against the number of lines the studio has.

integer
default: 1 >= 1

Example

{
"hybrid": 2
}

Action accepted.

Media typeapplication/json
object
ok
required
boolean

Example

{
"ok": true
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

The key isn’t allowed to do this (e.g. a read-only key making a change).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

call not found — the call doesn’t exist, belongs to another organization, or has already ended (or, for reorder, call not found in queue).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

call has already ended — the caller hung up before they could be answered.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.

failed to answer call — transient carrier error; the call is returned to the queue and can be retried.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}