# mv.queues

> The queues methods of @morevoice/sdk: Call queues and their live state.

Call queues and their live state. These methods are on `mv.queues`, where `mv` is your client (see [the Node.js SDK](https://docs.morevoice.ai/sdk/node/#connect)). Each one returns the response object and throws when the API answers with an error.

## `create()`

**Create a queue.** Returns the new `Queue`.

```ts
mv.queues.create(body: QueuesCreateData["body"], options?: RequestOptions): Promise<QueuesCreateResponse>
```

`POST /queues` · [API reference](https://docs.morevoice.ai/api/operations/queues_create/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `body.name` | `string` | yes |  |
| `body.away_on_missed` | `boolean` | no |  |
| `body.callbacks` | `object` | no |  |
| `body.copilot_profile_id` | `string \| null` | no | `cop_…` ID. |
| `body.enabled` | `boolean` | no |  |
| `body.hold` | `object` | no |  |
| `body.max_wait_seconds` | `integer` | no |  |
| `body.member_team_ids` | `string[]` | no |  |
| `body.member_user_ids` | `string[]` | no |  |
| `body.overflow` | `object` | no | Fields you leave out are kept. |
| `body.ring_timeout_seconds` | `integer` | no |  |
| `body.strategy` | `"longest_idle" \| "round_robin"` | no |  |
| `body.voice_assistant_id` | `string \| null` | no | `asst_…` ID. |
| `body.voicemail` | `object` | no |  |
| `body.wait_keys` | `object` | no |  |
| `body.wrap_up_seconds` | `integer` | no |  |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options.headers["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. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`Queue`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The queue's ID. |
| `object` | `"queue"` | Always `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. |
| `voicemail` | `object` | — |
| `hold` | `object` | — |
| `wait_keys` | `object` | — |
| `callbacks` | `object` | How callbacks requested in this queue are returned. |
| `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

```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);
```

## `delete()`

**Delete a queue.** Deletes the queue. Inbound routes that sent calls to it no longer target a queue; callers waiting in it now overflow.

```ts
mv.queues.delete(id: QueuesDeleteData["path"]["id"], options?: RequestOptions): Promise<QueuesDeleteResponse>
```

`DELETE /queues/{id}` · [API reference](https://docs.morevoice.ai/api/operations/queues_delete/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A queue ID (`q_…`). |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options.headers["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. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`DeletedQueue`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | A queue ID (prefix `q_`). |
| `object` | `"queue"` | Always `queue`. |
| `deleted` | `true` | — |

### Example

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

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

const deletedQueue = await mv.queues.delete("q_7Hk2Lm9Qp");
console.log(deletedQueue);
```

## `list()`

**List queues.** Your queues, newest first.

```ts
mv.queues.list(query?: NonNullable<QueuesListData["query"]>, options?: RequestOptions): PagedList<QueuesListResponse["data"][number], NonNullable<QueuesListData["query"]>>
```

`GET /queues` · [API reference](https://docs.morevoice.ai/api/operations/queues_list/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query.limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `query.starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `query.ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

A [`PagedList`](https://docs.morevoice.ai/sdk/typescript/pagination/): `await` it for the first page, `for await` it for every item.

### Example

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

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

for await (const queue of mv.queues.list()) {
	console.log(queue);
}
```

## `retrieve()`

**Retrieve a queue.** Returns the `Queue` object. Answers `404` with the code `resource_missing` when nothing has this ID in this organisation and mode.

```ts
mv.queues.retrieve(id: QueuesRetrieveData["path"]["id"], options?: RequestOptions): Promise<QueuesRetrieveResponse>
```

`GET /queues/{id}` · [API reference](https://docs.morevoice.ai/api/operations/queues_retrieve/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A queue ID (`q_…`). |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`Queue`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The queue's ID. |
| `object` | `"queue"` | Always `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. |
| `voicemail` | `object` | — |
| `hold` | `object` | — |
| `wait_keys` | `object` | — |
| `callbacks` | `object` | How callbacks requested in this queue are returned. |
| `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

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

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

const queue = await mv.queues.retrieve("q_7Hk2Lm9Qp");
console.log(queue);
```

## `retrieveLive()`

**Retrieve a queue's live state.** Who is waiting and for how long, which agents can take the calls, and today's numbers. A snapshot: poll it, or follow `queue.*` events.

```ts
mv.queues.retrieveLive(id: QueuesRetrieveLiveData["path"]["id"], options?: RequestOptions): Promise<QueuesRetrieveLiveResponse>
```

`GET /queues/{id}/live` · [API reference](https://docs.morevoice.ai/api/operations/queues_retrieve_live/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A queue ID (`q_…`). |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`QueueLive`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"queue_live"` | Always `queue_live`. |
| `queue_id` | `string` | A queue ID (prefix `q_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `enabled` | `boolean` | — |
| `waiting` | `integer` | Callers waiting for an agent right now. |
| `longest_wait_seconds` | `integer \| null` | How long the longest-waiting caller has waited (null: nobody waits). |
| `agents` | `object` | The queue's signed-in members by status. |
| `callers` | `object[]` | Waiting callers, longest wait first. |
| `members` | `object[]` | The queue's signed-in members. |
| `callbacks_offered` | `integer` | Callbacks ringing this queue's agents right now. |
| `today` | `object \| null` | Since midnight (Israel time); null when the statistics are unavailable. |
| `as_of` | `string` | An ISO-8601 timestamp in UTC. |

### Example

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

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

const queueLive = await mv.queues.retrieveLive("q_7Hk2Lm9Qp");
console.log(queueLive);
```

## `update()`

**Update a queue.** Updates the fields you send. Nested objects (`overflow`, `hold`, `callbacks`…) merge with the stored values; lists replace them.

```ts
mv.queues.update(id: QueuesUpdateData["path"]["id"], body?: QueuesUpdateData["body"], options?: RequestOptions): Promise<QueuesUpdateResponse>
```

`PATCH /queues/{id}` · [API reference](https://docs.morevoice.ai/api/operations/queues_update/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A queue ID (`q_…`). |
| `body.away_on_missed` | `boolean` | no |  |
| `body.callbacks` | `object` | no |  |
| `body.copilot_profile_id` | `string \| null` | no | `cop_…` ID. |
| `body.enabled` | `boolean` | no |  |
| `body.hold` | `object` | no |  |
| `body.max_wait_seconds` | `integer` | no |  |
| `body.member_team_ids` | `string[]` | no |  |
| `body.member_user_ids` | `string[]` | no |  |
| `body.name` | `string` | no |  |
| `body.overflow` | `object` | no | Fields you leave out are kept. |
| `body.ring_timeout_seconds` | `integer` | no |  |
| `body.strategy` | `"longest_idle" \| "round_robin"` | no |  |
| `body.voice_assistant_id` | `string \| null` | no | `asst_…` ID. |
| `body.voicemail` | `object` | no |  |
| `body.wait_keys` | `object` | no |  |
| `body.wrap_up_seconds` | `integer` | no |  |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`Queue`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The queue's ID. |
| `object` | `"queue"` | Always `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. |
| `voicemail` | `object` | — |
| `hold` | `object` | — |
| `wait_keys` | `object` | — |
| `callbacks` | `object` | How callbacks requested in this queue are returned. |
| `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

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

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

const queue = await mv.queues.update("q_7Hk2Lm9Qp", {
	enabled: false,
});
console.log(queue);
```