Create a call-centre queue

Creates a queue and pushes the workspace's configuration to the phone system as part of the request.

API-key scope: queues.manage. Viewer members are refused (accounts.write_denied).

Create-only: a name this workspace already uses is a 409, never a silent overwrite. The queue is created EMPTY — the roster is set separately, with PUT /v1/queues/{name}/agents, so a settings save can never empty a team by omission.

Every setting is optional and every omitted setting takes its default; see CallQueueSettings.

Authorization

bearerAuth

AuthorizationBearer <token>

Long-lived ES256 JWT minted from the dashboard (https://app.sautikit.com/developers/api-keys). Signed by the platform keyring. Carries workspace_id and scopes claims; revoked via the platform deny-list.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The settings half of a queue — the body of POST /v1/queues and PUT /v1/queues/{name}. The roster is NOT here: it has its own endpoint, so a settings save cannot empty a team by omission.

On PUT this is a FULL REPLACE: an omitted field returns to the default listed below, it does not keep its previous value.

name?string

Required on create. On update it may be omitted, but if present it must equal the name in the path — queues cannot be renamed.

Bare: no workspace prefix, because the phone system staples the workspace on itself. The character set is a safety control rather than a style rule — the name is interpolated into a command line on the switch, so a name outside it is refused rather than escaped.

Match^[A-Za-z0-9._-]{1,64}$

sharing_mode?string

Default"longest_free"

Value in

"longest_free"
"take_turns"
"ring_everyone"
"chosen_order"

max_wait_seconds?integer

Hard cap on the wait. 0 — the default — means hold as long as the caller likes; nothing else ends the wait, so the caller decides when to leave by hanging up.

Range0 <= value

Default0

max_depth?integer

Concurrent waiters allowed. 0 — the default — means unlimited. Beyond the limit the caller is not parked and the rest of your voice actions run, so overflow is whatever follows the queue verb.

Range0 <= value

Default0

discard_abandoned_after_seconds?integer

How long a caller who hung up while waiting stays remembered by the queue.

Range0 <= value

Default60

announce_position?boolean

Speak the caller's place in the line while they wait.

Defaultfalse

announce_frequency_seconds?integer

How often the position is spoken. Announcing more often does not shorten the wait; it replaces hold audio with the announcement voice.

Range0 <= value

Default30

moh_url?string

Hold audio. Empty — the default — plays the platform default.

Must be a STABLE url. Never store a signed/expiring link here: a queue outlives a signature, and expired hold music simply stops with no error anywhere.

Default""

Response Body

`application/json`

curl -X POST "https://example.com/v1/queues" \  -H "Content-Type: application/json" \  -d '{    "name": "support",    "sharing_mode": "longest_free",    "max_wait_seconds": 600,    "announce_position": true,    "announce_frequency_seconds": 30  }'

{  "queue": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "sharing_mode": "longest_free",    "max_wait_seconds": 0,    "max_depth": 0,    "discard_abandoned_after_seconds": 0,    "announce_position": true,    "announce_frequency_seconds": 0,    "moh_url": "string",    "agents": [      {        "extension": "string",        "level": 0,        "position": 0      }    ],    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  }}

{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

Create a call-centre queue

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

409application/json

502application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`