# client.callbacks

> The callbacks methods of the morevoice Python SDK: Callback requests and their scheduling.

Callback requests and their scheduling. These methods are on `client.callbacks`, where `client` is a `MoreVoice` client (see [the Python SDK](https://docs.morevoice.ai/sdk/python/#connect)). On `AsyncMoreVoice` the same methods are awaited. Each one returns the response object and raises an exception when the API answers with an error.

## `add_note()`

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

```python
# client.callbacks
def add_note(self, id: str, body: _m.CallbacksAddNoteBody | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.Callback
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A callback ID (`cb_…`). |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | yes | The note (stamped with the time and the API key's name). |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

callback = client.callbacks.add_note("cb_7Hk2Lm9Qp", {
    "text": "Prefers a call after 17:00.",
})
print(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.

```python
# client.callbacks
def cancel(self, id: str, body: _m.CallbacksCancelBody | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.Callback
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A callback ID (`cb_…`). |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | `string` | no | Why (kept in the callback's history). |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

callback = client.callbacks.cancel("cb_7Hk2Lm9Qp", {
    "reason": "Customer called us back",
})
print(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.

```python
# client.callbacks
def complete(self, id: str, body: _m.CallbacksCompleteBody | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.Callback
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A callback ID (`cb_…`). |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | `string` | no | How it was resolved (added to the notes). |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

callback = client.callbacks.complete("cb_7Hk2Lm9Qp", {
    "note": "Reached by email",
})
print(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.

```python
# client.callbacks
def create(self, body: _m.CallbacksCreateBody | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.Callback
```

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | `string` | yes | The number to call back: E.164 (`+972501234567`) or a local form (`050-123-4567`). |
| `agent_id` | `string` | no | The agent who should call back (a member's user ID; `route` agent). |
| `assistant_id` | `string` | no | The AI assistant that should call back (`route` assistant). |
| `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. |
| `due_at` | `string` | no | The earliest time to call back (default: now). Moved into business hours; at most 90 days ahead. |
| `max_attempts` | `integer` | no | How many times to try (default: the callback settings'). |
| `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. |
| `name` | `string` | no | The person's name. |
| `note` | `string` | no | A note for whoever returns it. |
| `priority` | `integer` | no | 1 (low) … 10 (urgent). Default: the callback settings' priority for API requests. |
| `queue_id` | `string` | no | A queue ID (`q_…`). |
| `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. |
| `window_end` | `string` | no | Don't call after this time. |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

callback = client.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",
})
print(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.

```python
# client.callbacks
def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, status: _m.CallbacksListStatus | Unset = UNSET, source: _m.CallbacksListSource | Unset = UNSET, queue_id: str | Unset = UNSET, agent_id: str | Unset = UNSET, phone: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.Callback]
```

`client.callbacks.list()` · `await async_client.callbacks.list()` · `GET /callbacks` · [API reference](https://docs.morevoice.ai/api/operations/callbacks_list/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |
| `status` | `"pending" \| "offered" \| "dialing" \| "connected" \| "completed" \| "failed" \| "cancelled" \| "expired"` | 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). |
| `source` | `"queue" \| "ivr" \| "flow" \| "ai" \| "web" \| "manual" \| "campaign" \| "voicemail" \| …` | no | Only callbacks from this source. |
| `queue_id` | `string` | no | Only callbacks routed to this queue. |
| `agent_id` | `string` | no | Only callbacks assigned to this agent. |
| `phone` | `string` | no | Only callbacks for this number (any common form). |

### Returns

A page of results (`CallbackList`): `data`, `has_more` and `next_cursor`.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for callback in client.callbacks.list():
    print(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.

```python
# client.callbacks
def retrieve(self, id: str, *, more_voice_version: str | Unset = UNSET) -> _m.Callback
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A callback ID (`cb_…`). |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

callback = client.callbacks.retrieve("cb_7Hk2Lm9Qp")
print(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.

```python
# client.callbacks
def stats(self, *, from_: _dt.datetime | Unset = UNSET, to: _dt.datetime | Unset = UNSET, queue_id: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> _m.CallbackStats
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `string` | no | Start of the period (default: 7 days before `to`). |
| `to` | `string` | no | End of the period (default: now). |
| `queue_id` | `string` | no | A queue ID (`q_…`). |

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

callback_stats = client.callbacks.stats()
print(callback_stats)
```

## `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.

```python
# client.callbacks
def update(self, id: str, body: _m.CallbacksUpdateBody | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET) -> _m.Callback
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A callback ID (`cb_…`). |

### Request body

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

### 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

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

callback = client.callbacks.update("cb_7Hk2Lm9Qp", {
    "due_at": "2026-11-04T09:30:00+02:00",
    "priority": 8,
})
print(callback)
```