# Create a queue

`POST https://api.morevoice.ai/v1/queues`

Returns the new `Queue`.

Authenticate with a secret API key: `Authorization: Bearer $MOREVOICE_API_KEY`.

Operation ID: `queues_create`.

## Parameters

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `MoreVoice-Version` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `Idempotency-Key` | `string` | no | A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice. |

## Request body

Required, `application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | — |
| `away_on_missed` | `boolean` | no | — |
| `callbacks` | `object` | no | — |
| `callbacks.agent_id` | `string \| null` | no | `usr_…` ID. |
| `callbacks.assistant_id` | `string \| null` | no | `asst_…` ID. |
| `callbacks.priority` | `integer` | no | — |
| `callbacks.route` | `"agent_queue" \| "agent" \| "assistant"` | no | — |
| `callbacks.voicemail_to_callback` | `boolean` | no | — |
| `copilot_profile_id` | `string \| null` | no | `cop_…` ID. |
| `enabled` | `boolean` | no | — |
| `hold` | `object` | no | — |
| `hold.announce_position` | `boolean` | no | — |
| `hold.announcement` | `string` | no | — |
| `hold.audio` | `"music" \| "ringback" \| "silence" \| "asset"` | no | — |
| `hold.audio_asset_id` | `string \| null` | no | `aud_…` ID. |
| `hold.position_interval_seconds` | `integer` | no | — |
| `max_wait_seconds` | `integer` | no | — |
| `member_team_ids` | `string[]` | no | — |
| `member_user_ids` | `string[]` | no | — |
| `overflow` | `object` | no | Fields you leave out are kept. |
| `overflow.action` | `"assistant" \| "voicemail" \| "busy" \| "agent" \| "queue" \| "number"` | no | — |
| `overflow.assistant_id` | `string \| null` | no | `asst_…` ID. |
| `overflow.number` | `string` | no | — |
| `overflow.queue_id` | `string \| null` | no | `q_…` ID. |
| `overflow.user_id` | `string \| null` | no | `usr_…` ID. |
| `overflow.when_no_agents` | `boolean` | no | — |
| `ring_timeout_seconds` | `integer` | no | — |
| `strategy` | `"longest_idle" \| "round_robin"` | no | — |
| `voice_assistant_id` | `string \| null` | no | `asst_…` ID. |
| `voicemail` | `object` | no | — |
| `voicemail.max_seconds` | `integer` | no | — |
| `voicemail.message` | `string` | no | — |
| `wait_keys` | `object` | no | — |
| `wait_keys.callback` | `string` | no | — |
| `wait_keys.voicemail` | `string` | no | — |
| `wrap_up_seconds` | `integer` | no | — |

Example:

```json
{
  "max_wait_seconds": 180,
  "member_team_ids": [
    "team_7Hj2Kl4Mn6Pq8Rs0Tu2Vw"
  ],
  "name": "Support",
  "overflow": {
    "action": "voicemail"
  }
}
```

## Responses

### 201 Created

The new queue. Returns `Queue`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The queue's ID. |
| `object` | `"queue"` | — |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | — |
| `enabled` | `boolean` | A disabled queue takes no calls: they overflow. |
| `strategy` | `"longest_idle" \| "round_robin"` | Which available agent rings first: the one idle longest, or in turn. |
| `member_user_ids` | `string[]` | Users who answer this queue's calls. |
| `member_team_ids` | `string[]` | Teams whose members answer this queue's calls. |
| `ring_timeout_seconds` | `integer` | How long an agent's phone rings before the next agent is tried. |
| `max_wait_seconds` | `integer` | How long a caller waits before the overflow action (0: no limit). |
| `wrap_up_seconds` | `integer` | After-call time before an agent gets the next call. |
| `away_on_missed` | `boolean` | An agent who misses a call is set to away. |
| `overflow` | `object` | What happens to callers who waited too long, or when nobody can answer. |
| `overflow.when_no_agents` | `boolean` | Overflow at once when no agent is signed in. |
| `overflow.action` | `"assistant" \| "voicemail" \| "busy" \| "agent" \| "queue" \| "number"` | — |
| `overflow.assistant_id` | `string \| null` | Action `assistant`: the AI assistant that answers. |
| `overflow.user_id` | `string \| null` | Action `agent`: the user who gets the call. |
| `overflow.queue_id` | `string \| null` | Action `queue`: the queue the call moves to. |
| `overflow.number` | `string` | Action `number`: the phone number the call is forwarded to. |
| `voicemail` | `object` | — |
| `voicemail.message` | `string` | Played before the beep (empty: the default). |
| `voicemail.max_seconds` | `integer` | — |
| `hold` | `object` | — |
| `hold.audio` | `"music" \| "ringback" \| "silence" \| "asset"` | What callers hear while they wait; `asset` plays `audio_asset_id` in a loop. |
| `hold.audio_asset_id` | `string \| null` | `aud_…` ID. |
| `hold.announcement` | `string` | Said to callers when they join the queue. |
| `hold.announce_position` | `boolean` | Tell callers their place in line. |
| `hold.position_interval_seconds` | `integer` | — |
| `wait_keys` | `object` | — |
| `wait_keys.voicemail` | `string` | Pressed while waiting: leave a voicemail (empty: off). |
| `wait_keys.callback` | `string` | Pressed while waiting: ask for a callback (empty: off). |
| `callbacks` | `object` | How callbacks requested in this queue are returned. |
| `callbacks.route` | `"agent_queue" \| "agent" \| "assistant"` | Who returns this queue's callbacks: its agents, one agent or an AI assistant. |
| `callbacks.agent_id` | `string \| null` | `usr_…` ID. |
| `callbacks.assistant_id` | `string \| null` | `asst_…` ID. |
| `callbacks.priority` | `integer` | 1 (low) to 10 (urgent). |
| `callbacks.voicemail_to_callback` | `boolean` | A voicemail left in this queue becomes a callback task too. |
| `voice_assistant_id` | `string \| null` | The assistant whose voice speaks the queue's announcements. |
| `copilot_profile_id` | `string \| null` | The copilot profile agents get on this queue's calls. |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

Example:

```json
{
  "away_on_missed": true,
  "callbacks": {
    "agent_id": null,
    "assistant_id": null,
    "priority": 5,
    "route": "agent_queue",
    "voicemail_to_callback": false
  },
  "copilot_profile_id": null,
  "created": "2026-11-03T09:14:22.000Z",
  "enabled": true,
  "hold": {
    "announce_position": false,
    "announcement": "",
    "audio": "music",
    "audio_asset_id": null,
    "position_interval_seconds": 45
  },
  "id": "q_4Gk2LmN9pQ4rS6tV8wX0yZ",
  "livemode": true,
  "max_wait_seconds": 120,
  "member_team_ids": [
    "team_7Hj2Kl4Mn6Pq8Rs0Tu2Vw"
  ],
  "member_user_ids": [
    "usr_2Lm8Pq4Rt6Vx0Zb3Nd5Fh7"
  ],
  "name": "Support",
  "object": "queue",
  "overflow": {
    "action": "assistant",
    "assistant_id": "asst_3cYbE6uYvGkH8w4ZK1rTqd",
    "number": "",
    "queue_id": null,
    "user_id": null,
    "when_no_agents": true
  },
  "ring_timeout_seconds": 20,
  "strategy": "longest_idle",
  "updated": "2026-11-03T09:14:22.000Z",
  "voice_assistant_id": null,
  "voicemail": {
    "max_seconds": 90,
    "message": ""
  },
  "wait_keys": {
    "callback": "",
    "voicemail": ""
  },
  "wrap_up_seconds": 15
}
```

### 400 Bad Request

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown. Returns `ErrorEnvelope`.

### 401 Unauthorized

No valid API key was sent. Returns `ErrorEnvelope`.

### 403 Forbidden

The key may not do this (a missing scope, a plan limit, or a compliance block). Returns `ErrorEnvelope`.

### 409 Conflict

The request conflicts with the object's state, or the Idempotency-Key was reused with other parameters. Returns `ErrorEnvelope`.

### 429 Too Many Requests

Too many requests, or no call capacity right now. Retry after the Retry-After delay. Returns `ErrorEnvelope`.

### 500 Internal Server Error

Something went wrong on MoreVoice's side. Retry with the same Idempotency-Key. Returns `ErrorEnvelope`.

## Code samples

**TypeScript**

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const queue = await mv.queues.create({
	max_wait_seconds: 180,
	member_team_ids: [
		"team_7Hj2Kl4Mn6Pq8Rs0Tu2Vw",
	],
	name: "Support",
	overflow: {
		action: "voicemail",
	},
});
console.log(queue);
```

**Python**

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

queue = client.queues.create({
    "max_wait_seconds": 180,
    "member_team_ids": [
        "team_7Hj2Kl4Mn6Pq8Rs0Tu2Vw",
    ],
    "name": "Support",
    "overflow": {
        "action": "voicemail",
    },
})
print(queue)
```

**cURL**

```sh
curl -X POST https://api.morevoice.ai/v1/queues \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "max_wait_seconds": 180,
  "member_team_ids": [
    "team_7Hj2Kl4Mn6Pq8Rs0Tu2Vw"
  ],
  "name": "Support",
  "overflow": {
    "action": "voicemail"
  }
}'
```