# mv.callbacks

> The callbacks methods of @morevoice/sdk: Callback requests and their scheduling.

Callback requests and their scheduling. These methods are on `mv.callbacks`, 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.

## `addNote()`

**Add a note to a callback.** Appends a note, stamped with the time and the API key's name. Needs a live key.

```ts
mv.callbacks.addNote(id: CallbacksAddNoteData["path"]["id"], body: CallbacksAddNoteData["body"], options?: RequestOptions): Promise<CallbacksAddNoteResponse>
```

`POST /callbacks/{id}/notes` · [API reference](https://docs.morevoice.ai/api/operations/callbacks_add_note/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A callback ID (`cb_…`). |
| `body.text` | `string` | yes | The note (stamped with the time and the API key's name). |
| `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

`Callback`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"callback"` | Always `callback`. |
| `id` | `string` | A callback ID (prefix `cb_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `phone` | `string` | The number to call back, E.164. |
| `name` | `string` | The person's name, when known. |
| `status` | `string` | `pending` (waiting for its time), `offered` (ringing an agent), `dialing`, `connected` (on the call back), `completed`, `failed` (attempts used up), `cancelled` or `expired` (past its window, or too old). |
| `source` | `string` | Where the request came from: `queue` (a caller pressed the callback key), `ivr`, `flow`, `ai` (the assistant booked it), `web` (a website form), `manual`, `campaign`, `voicemail` or `api`. |
| `site_id` | `string \| null` | The website form it came from (`source` = web). |
| `due_at` | `string` | The earliest time to call back (moved into business hours). |
| `window_end` | `string \| null` | Don't call after this time; null: no limit. |
| `priority` | `integer` | 1 (low) … 10 (urgent); higher is returned sooner. |
| `route` | `string` | Who returns it: `agent_queue` (offered to the next free agent of `queue_id`, then dialled), `agent` (`agent_id` calls back) or `assistant` (the AI `assistant_id` calls back). |
| `queue_id` | `string \| null` | `q_…` ID. |
| `agent_id` | `string \| null` | `usr_…` ID. |
| `assistant_id` | `string \| null` | `asst_…` ID. |
| `attempts` | `integer` | Call-back attempts made so far. |
| `max_attempts` | `integer` | — |
| `last_attempt_at` | `string \| null` | — |
| `last_result` | `string \| null` | The last attempt's result, e.g. `answered`, `no-answer`, `busy`, `done-manually`. |
| `call_id` | `string \| null` | `call_…` ID. |
| `origin_call_id` | `string \| null` | `call_…` ID. |
| `notes` | `string` | Notes for whoever returns it (each note is stamped with its time and author). |
| `summary` | `string \| null` | The AI summary of the originating call, when there is one. |
| `sla_at` | `string \| null` | When it should have been returned by (the SLA target, in business hours). |
| `merged_requests` | `integer` | Later requests for the same number merged into this one. |
| `context` | `object` | — |
| `metadata` | `Metadata` | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `completed_at` | `string \| null` | — |
| `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 callback = await mv.callbacks.addNote("cb_7Hk2Lm9Qp", {
	text: "Prefers a call after 17:00.",
});
console.log(callback);
```

## `cancel()`

**Cancel a callback.** Cancels an open callback that is not on a call right now (409 otherwise). Emits `callback.cancelled`. Needs a live key.

```ts
mv.callbacks.cancel(id: CallbacksCancelData["path"]["id"], body?: CallbacksCancelData["body"], options?: RequestOptions): Promise<CallbacksCancelResponse>
```

`POST /callbacks/{id}/cancel` · [API reference](https://docs.morevoice.ai/api/operations/callbacks_cancel/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A callback ID (`cb_…`). |
| `body.reason` | `string` | no | Why (kept in the callback's history). |
| `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

`Callback`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"callback"` | Always `callback`. |
| `id` | `string` | A callback ID (prefix `cb_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `phone` | `string` | The number to call back, E.164. |
| `name` | `string` | The person's name, when known. |
| `status` | `string` | `pending` (waiting for its time), `offered` (ringing an agent), `dialing`, `connected` (on the call back), `completed`, `failed` (attempts used up), `cancelled` or `expired` (past its window, or too old). |
| `source` | `string` | Where the request came from: `queue` (a caller pressed the callback key), `ivr`, `flow`, `ai` (the assistant booked it), `web` (a website form), `manual`, `campaign`, `voicemail` or `api`. |
| `site_id` | `string \| null` | The website form it came from (`source` = web). |
| `due_at` | `string` | The earliest time to call back (moved into business hours). |
| `window_end` | `string \| null` | Don't call after this time; null: no limit. |
| `priority` | `integer` | 1 (low) … 10 (urgent); higher is returned sooner. |
| `route` | `string` | Who returns it: `agent_queue` (offered to the next free agent of `queue_id`, then dialled), `agent` (`agent_id` calls back) or `assistant` (the AI `assistant_id` calls back). |
| `queue_id` | `string \| null` | `q_…` ID. |
| `agent_id` | `string \| null` | `usr_…` ID. |
| `assistant_id` | `string \| null` | `asst_…` ID. |
| `attempts` | `integer` | Call-back attempts made so far. |
| `max_attempts` | `integer` | — |
| `last_attempt_at` | `string \| null` | — |
| `last_result` | `string \| null` | The last attempt's result, e.g. `answered`, `no-answer`, `busy`, `done-manually`. |
| `call_id` | `string \| null` | `call_…` ID. |
| `origin_call_id` | `string \| null` | `call_…` ID. |
| `notes` | `string` | Notes for whoever returns it (each note is stamped with its time and author). |
| `summary` | `string \| null` | The AI summary of the originating call, when there is one. |
| `sla_at` | `string \| null` | When it should have been returned by (the SLA target, in business hours). |
| `merged_requests` | `integer` | Later requests for the same number merged into this one. |
| `context` | `object` | — |
| `metadata` | `Metadata` | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `completed_at` | `string \| null` | — |
| `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 callback = await mv.callbacks.cancel("cb_7Hk2Lm9Qp", {
	reason: "Customer called us back",
});
console.log(callback);
```

## `complete()`

**Mark a callback done.** Closes an open callback that was resolved another way (409 while it is on a call). Emits `callback.completed`. Needs a live key.

```ts
mv.callbacks.complete(id: CallbacksCompleteData["path"]["id"], body?: CallbacksCompleteData["body"], options?: RequestOptions): Promise<CallbacksCompleteResponse>
```

`POST /callbacks/{id}/complete` · [API reference](https://docs.morevoice.ai/api/operations/callbacks_complete/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A callback ID (`cb_…`). |
| `body.note` | `string` | no | How it was resolved (added to the notes). |
| `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

`Callback`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"callback"` | Always `callback`. |
| `id` | `string` | A callback ID (prefix `cb_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `phone` | `string` | The number to call back, E.164. |
| `name` | `string` | The person's name, when known. |
| `status` | `string` | `pending` (waiting for its time), `offered` (ringing an agent), `dialing`, `connected` (on the call back), `completed`, `failed` (attempts used up), `cancelled` or `expired` (past its window, or too old). |
| `source` | `string` | Where the request came from: `queue` (a caller pressed the callback key), `ivr`, `flow`, `ai` (the assistant booked it), `web` (a website form), `manual`, `campaign`, `voicemail` or `api`. |
| `site_id` | `string \| null` | The website form it came from (`source` = web). |
| `due_at` | `string` | The earliest time to call back (moved into business hours). |
| `window_end` | `string \| null` | Don't call after this time; null: no limit. |
| `priority` | `integer` | 1 (low) … 10 (urgent); higher is returned sooner. |
| `route` | `string` | Who returns it: `agent_queue` (offered to the next free agent of `queue_id`, then dialled), `agent` (`agent_id` calls back) or `assistant` (the AI `assistant_id` calls back). |
| `queue_id` | `string \| null` | `q_…` ID. |
| `agent_id` | `string \| null` | `usr_…` ID. |
| `assistant_id` | `string \| null` | `asst_…` ID. |
| `attempts` | `integer` | Call-back attempts made so far. |
| `max_attempts` | `integer` | — |
| `last_attempt_at` | `string \| null` | — |
| `last_result` | `string \| null` | The last attempt's result, e.g. `answered`, `no-answer`, `busy`, `done-manually`. |
| `call_id` | `string \| null` | `call_…` ID. |
| `origin_call_id` | `string \| null` | `call_…` ID. |
| `notes` | `string` | Notes for whoever returns it (each note is stamped with its time and author). |
| `summary` | `string \| null` | The AI summary of the originating call, when there is one. |
| `sla_at` | `string \| null` | When it should have been returned by (the SLA target, in business hours). |
| `merged_requests` | `integer` | Later requests for the same number merged into this one. |
| `context` | `object` | — |
| `metadata` | `Metadata` | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `completed_at` | `string \| null` | — |
| `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 callback = await mv.callbacks.complete("cb_7Hk2Lm9Qp", {
	note: "Reached by email",
});
console.log(callback);
```

## `create()`

**Request a callback.** Books a call back to `phone`, routed like the dashboard's (to a queue's agents, an agent or an AI assistant). If the number already has an open callback, the request is merged into it and that callback is returned (`merged_requests` counts the merges). With `call_id`, repeating the request for the same call returns the first callback. Needs a live key.

```ts
mv.callbacks.create(body: CallbacksCreateData["body"], options?: RequestOptions): Promise<CallbacksCreateResponse>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `body.phone` | `string` | yes | The number to call back: E.164 (`+972501234567`) or a local form (`050-123-4567`). |
| `body.agent_id` | `string` | no | The agent who should call back (a member's user ID; `route` agent). |
| `body.assistant_id` | `string` | no | The AI assistant that should call back (`route` assistant). |
| `body.call_id` | `string` | no | The call the request came from. One callback per call: repeating the request for the same call returns the first callback. |
| `body.due_at` | `string` | no | The earliest time to call back (default: now). Moved into business hours; at most 90 days ahead. |
| `body.max_attempts` | `integer` | no | How many times to try (default: the callback settings'). |
| `body.metadata` | `MetadataInput` | no | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `body.name` | `string` | no | The person's name. |
| `body.note` | `string` | no | A note for whoever returns it. |
| `body.priority` | `integer` | no | 1 (low) … 10 (urgent). Default: the callback settings' priority for API requests. |
| `body.queue_id` | `string` | no | A queue ID (`q_…`). |
| `body.route` | `"agent_queue" \| "agent" \| "assistant"` | no | Who returns it: `agent_queue` (offered to the next free agent of `queue_id`, then dialled), `agent` (`agent_id` calls back) or `assistant` (the AI `assistant_id` calls back). Default: the callback settings' default route. |
| `body.window_end` | `string` | no | Don't call after this time. |
| `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

`Callback`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"callback"` | Always `callback`. |
| `id` | `string` | A callback ID (prefix `cb_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `phone` | `string` | The number to call back, E.164. |
| `name` | `string` | The person's name, when known. |
| `status` | `string` | `pending` (waiting for its time), `offered` (ringing an agent), `dialing`, `connected` (on the call back), `completed`, `failed` (attempts used up), `cancelled` or `expired` (past its window, or too old). |
| `source` | `string` | Where the request came from: `queue` (a caller pressed the callback key), `ivr`, `flow`, `ai` (the assistant booked it), `web` (a website form), `manual`, `campaign`, `voicemail` or `api`. |
| `site_id` | `string \| null` | The website form it came from (`source` = web). |
| `due_at` | `string` | The earliest time to call back (moved into business hours). |
| `window_end` | `string \| null` | Don't call after this time; null: no limit. |
| `priority` | `integer` | 1 (low) … 10 (urgent); higher is returned sooner. |
| `route` | `string` | Who returns it: `agent_queue` (offered to the next free agent of `queue_id`, then dialled), `agent` (`agent_id` calls back) or `assistant` (the AI `assistant_id` calls back). |
| `queue_id` | `string \| null` | `q_…` ID. |
| `agent_id` | `string \| null` | `usr_…` ID. |
| `assistant_id` | `string \| null` | `asst_…` ID. |
| `attempts` | `integer` | Call-back attempts made so far. |
| `max_attempts` | `integer` | — |
| `last_attempt_at` | `string \| null` | — |
| `last_result` | `string \| null` | The last attempt's result, e.g. `answered`, `no-answer`, `busy`, `done-manually`. |
| `call_id` | `string \| null` | `call_…` ID. |
| `origin_call_id` | `string \| null` | `call_…` ID. |
| `notes` | `string` | Notes for whoever returns it (each note is stamped with its time and author). |
| `summary` | `string \| null` | The AI summary of the originating call, when there is one. |
| `sla_at` | `string \| null` | When it should have been returned by (the SLA target, in business hours). |
| `merged_requests` | `integer` | Later requests for the same number merged into this one. |
| `context` | `object` | — |
| `metadata` | `Metadata` | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `completed_at` | `string \| null` | — |
| `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 callback = await mv.callbacks.create({
	due_at: "2026-11-03T12:00:00+02:00",
	metadata: {
		crm_ticket: "T-1042",
	},
	name: "Dana Levi",
	note: "Asked about the renewal offer.",
	phone: "+972501234567",
	queue_id: "q_3hRf8Kd2LmPq",
	route: "agent_queue",
});
console.log(callback);
```

## `list()`

**List callbacks.** Returns a page of `Callback` objects, newest first. Pass `next_cursor` as `starting_after` for the next page; the SDKs iterate every page for you.

```ts
mv.callbacks.list(query?: NonNullable<CallbacksListData["query"]>, options?: RequestOptions): PagedList<CallbacksListResponse["data"][number], NonNullable<CallbacksListData["query"]>>
```

`GET /callbacks` · [API reference](https://docs.morevoice.ai/api/operations/callbacks_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). |
| `query.status` | `string` | no | Only callbacks in this status: `pending` (waiting for its time), `offered` (ringing an agent), `dialing`, `connected` (on the call back), `completed`, `failed` (attempts used up), `cancelled` or `expired` (past its window, or too old). |
| `query.source` | `string` | no | Only callbacks from this source. |
| `query.queue_id` | `string` | no | Only callbacks routed to this queue. |
| `query.agent_id` | `string` | no | Only callbacks assigned to this agent. |
| `query.phone` | `string` | no | Only callbacks for this number (any common form). |
| `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 callback of mv.callbacks.list()) {
	console.log(callback);
}
```

## `retrieve()`

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

```ts
mv.callbacks.retrieve(id: CallbacksRetrieveData["path"]["id"], options?: RequestOptions): Promise<CallbacksRetrieveResponse>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A callback ID (`cb_…`). |
| `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

`Callback`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"callback"` | Always `callback`. |
| `id` | `string` | A callback ID (prefix `cb_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `phone` | `string` | The number to call back, E.164. |
| `name` | `string` | The person's name, when known. |
| `status` | `string` | `pending` (waiting for its time), `offered` (ringing an agent), `dialing`, `connected` (on the call back), `completed`, `failed` (attempts used up), `cancelled` or `expired` (past its window, or too old). |
| `source` | `string` | Where the request came from: `queue` (a caller pressed the callback key), `ivr`, `flow`, `ai` (the assistant booked it), `web` (a website form), `manual`, `campaign`, `voicemail` or `api`. |
| `site_id` | `string \| null` | The website form it came from (`source` = web). |
| `due_at` | `string` | The earliest time to call back (moved into business hours). |
| `window_end` | `string \| null` | Don't call after this time; null: no limit. |
| `priority` | `integer` | 1 (low) … 10 (urgent); higher is returned sooner. |
| `route` | `string` | Who returns it: `agent_queue` (offered to the next free agent of `queue_id`, then dialled), `agent` (`agent_id` calls back) or `assistant` (the AI `assistant_id` calls back). |
| `queue_id` | `string \| null` | `q_…` ID. |
| `agent_id` | `string \| null` | `usr_…` ID. |
| `assistant_id` | `string \| null` | `asst_…` ID. |
| `attempts` | `integer` | Call-back attempts made so far. |
| `max_attempts` | `integer` | — |
| `last_attempt_at` | `string \| null` | — |
| `last_result` | `string \| null` | The last attempt's result, e.g. `answered`, `no-answer`, `busy`, `done-manually`. |
| `call_id` | `string \| null` | `call_…` ID. |
| `origin_call_id` | `string \| null` | `call_…` ID. |
| `notes` | `string` | Notes for whoever returns it (each note is stamped with its time and author). |
| `summary` | `string \| null` | The AI summary of the originating call, when there is one. |
| `sla_at` | `string \| null` | When it should have been returned by (the SLA target, in business hours). |
| `merged_requests` | `integer` | Later requests for the same number merged into this one. |
| `context` | `object` | — |
| `metadata` | `Metadata` | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `completed_at` | `string \| null` | — |
| `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 callback = await mv.callbacks.retrieve("cb_7Hk2Lm9Qp");
console.log(callback);
```

## `stats()`

**Callback statistics.** Totals for callbacks requested in a period (default: the last 7 days): outcomes, SLA, time to return, by source and by agent.

```ts
mv.callbacks.stats(query?: NonNullable<CallbacksStatsData["query"]>, options?: RequestOptions): Promise<CallbacksStatsResponse>
```

`GET /callbacks/stats` · [API reference](https://docs.morevoice.ai/api/operations/callbacks_stats/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query.from` | `string` | no | Start of the period (default: 7 days before `to`). |
| `query.to` | `string` | no | End of the period (default: now). |
| `query.queue_id` | `string` | no | 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

`CallbackStats`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"callback_stats"` | Always `callback_stats`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `from` | `string` | An ISO-8601 timestamp in UTC. |
| `to` | `string` | An ISO-8601 timestamp in UTC. |
| `total` | `integer` | Requests in the period. |
| `open` | `integer` | — |
| `completed` | `integer` | — |
| `failed` | `integer` | — |
| `expired` | `integer` | — |
| `cancelled` | `integer` | — |
| `within_sla` | `integer` | Completed within their SLA target. |
| `breached_open` | `integer` | Still open past their SLA target. |
| `sla_rate` | `number \| null` | within_sla / completed; null with nothing completed. |
| `avg_return_ms` | `integer \| null` | Average time from request to completion. |
| `attempts` | `integer` | — |
| `by_source` | `object[]` | — |
| `by_agent` | `object[]` | — |

### Example

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

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

const callbackStats = await mv.callbacks.stats();
console.log(callbackStats);
```

## `update()`

**Update a callback.** Reschedule, re-route or edit an open callback. A callback on a call right now can't be re-routed (409). Needs a live key.

```ts
mv.callbacks.update(id: CallbacksUpdateData["path"]["id"], body?: CallbacksUpdateData["body"], options?: RequestOptions): Promise<CallbacksUpdateResponse>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A callback ID (`cb_…`). |
| `body.agent_id` | `string \| null` | no | `usr_…` ID. |
| `body.assistant_id` | `string \| null` | no | `asst_…` ID. |
| `body.due_at` | `string` | no | Reschedule (moved into business hours). |
| `body.max_attempts` | `integer` | no | How many times to try (default: the callback settings'). |
| `body.name` | `string` | no |  |
| `body.notes` | `string` | no | Replaces the notes (use POST …/notes to add one). |
| `body.priority` | `integer` | no | 1 (low) … 10 (urgent). Default: the callback settings' priority for API requests. |
| `body.queue_id` | `string \| null` | no | `q_…` ID. |
| `body.route` | `"agent_queue" \| "agent" \| "assistant"` | 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

`Callback`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"callback"` | Always `callback`. |
| `id` | `string` | A callback ID (prefix `cb_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `phone` | `string` | The number to call back, E.164. |
| `name` | `string` | The person's name, when known. |
| `status` | `string` | `pending` (waiting for its time), `offered` (ringing an agent), `dialing`, `connected` (on the call back), `completed`, `failed` (attempts used up), `cancelled` or `expired` (past its window, or too old). |
| `source` | `string` | Where the request came from: `queue` (a caller pressed the callback key), `ivr`, `flow`, `ai` (the assistant booked it), `web` (a website form), `manual`, `campaign`, `voicemail` or `api`. |
| `site_id` | `string \| null` | The website form it came from (`source` = web). |
| `due_at` | `string` | The earliest time to call back (moved into business hours). |
| `window_end` | `string \| null` | Don't call after this time; null: no limit. |
| `priority` | `integer` | 1 (low) … 10 (urgent); higher is returned sooner. |
| `route` | `string` | Who returns it: `agent_queue` (offered to the next free agent of `queue_id`, then dialled), `agent` (`agent_id` calls back) or `assistant` (the AI `assistant_id` calls back). |
| `queue_id` | `string \| null` | `q_…` ID. |
| `agent_id` | `string \| null` | `usr_…` ID. |
| `assistant_id` | `string \| null` | `asst_…` ID. |
| `attempts` | `integer` | Call-back attempts made so far. |
| `max_attempts` | `integer` | — |
| `last_attempt_at` | `string \| null` | — |
| `last_result` | `string \| null` | The last attempt's result, e.g. `answered`, `no-answer`, `busy`, `done-manually`. |
| `call_id` | `string \| null` | `call_…` ID. |
| `origin_call_id` | `string \| null` | `call_…` ID. |
| `notes` | `string` | Notes for whoever returns it (each note is stamped with its time and author). |
| `summary` | `string \| null` | The AI summary of the originating call, when there is one. |
| `sla_at` | `string \| null` | When it should have been returned by (the SLA target, in business hours). |
| `merged_requests` | `integer` | Later requests for the same number merged into this one. |
| `context` | `object` | — |
| `metadata` | `Metadata` | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `completed_at` | `string \| null` | — |
| `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 callback = await mv.callbacks.update("cb_7Hk2Lm9Qp", {
	due_at: "2026-11-04T09:30:00+02:00",
	priority: 8,
});
console.log(callback);
```