Request a callback

POST

/callbacks

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

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)

curl -X POST https://api.morevoice.ai/v1/callbacks \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "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"
}'

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.

Try it in the API playground with a test-mode key.

Authorizations

bearerAuth

Parameters

Header Parameters

MoreVoice-Version

string

/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example

2026-11-01

Idempotency-Key

string

>= 1 characters <= 255 characters

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.

Example

5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17

Request Body^required

application/json

object

agent_id

The agent who should call back (a member’s user ID; route agent).

string

<= 200 characters /^usr_[0-9A-Za-z]+$/

assistant_id

The AI assistant that should call back (route assistant).

string

<= 200 characters /^asst_[0-9A-Za-z]+$/

call_id

The call the request came from. One callback per call: repeating the request for the same call returns the first callback.

string

<= 200 characters /^call_[0-9A-Za-z]+$/

due_at

The earliest time to call back (default: now). Moved into business hours; at most 90 days ahead.

string format: date-time

max_attempts

How many times to try (default: the callback settings’).

integer

>= 1 <= 10

metadata

Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent.

object

<= 50 properties

key

additional properties

string

<= 500 characters

name

The person’s name.

string

<= 120 characters

note

A note for whoever returns it.

string

<= 2000 characters

phone

required

The number to call back: E.164 (+972501234567) or a local form (050-123-4567).

string

>= 3 characters <= 40 characters

priority

1 (low) … 10 (urgent). Default: the callback settings’ priority for API requests.

integer

>= 1 <= 10

queue_id

A queue ID (q_…).

string

<= 200 characters /^q_[0-9A-Za-z]+$/

route

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.

string

Allowed values: agent_queue agent assistant

window_end

Don’t call after this time.

string format: date-time

Example

{
  "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"
}

Responses

200

application/json

A request to call someone back, and its progress.

object

agent_id

required

Any of:

string
null

The agent who returns it (a user ID), or null.

string

/^usr_[0-9A-Za-z]+$/

assistant_id

required

Any of:

string
null

A assistant ID (prefix asst_).

string

/^asst_[0-9A-Za-z]+$/

attempts

required

Call-back attempts made so far.

integer

>= -9007199254740991 <= 9007199254740991

call_id

required

Any of:

string
null

The call that returned it, once there is one.

string

/^call_[0-9A-Za-z]+$/

completed_at

required

Any of:

string
null

An ISO-8601 timestamp in UTC.

string format: date-time

context

required

object

web

required

Any of:

object
null

object

language

required

string | null

page

required

string | null

created

required

An ISO-8601 timestamp in UTC.

string format: date-time

due_at

required

The earliest time to call back (moved into business hours).

string format: date-time

required

A callback ID (prefix cb_).

string

/^cb_[0-9A-Za-z]+$/

last_attempt_at

required

Any of:

string
null

An ISO-8601 timestamp in UTC.

string format: date-time

last_result

required

The last attempt’s result, e.g. answered, no-answer, busy, done-manually.

string | null

livemode

required

true in live mode, false in test mode.

boolean

max_attempts

required

integer

>= -9007199254740991 <= 9007199254740991

merged_requests

required

Later requests for the same number merged into this one.

integer

>= -9007199254740991 <= 9007199254740991

metadata

required

Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent.

object

<= 50 properties

key

additional properties

string

<= 500 characters

name

required

The person’s name, when known.

string

notes

required

Notes for whoever returns it (each note is stamped with its time and author).

string

object

required

string

Allowed value: callback

origin_call_id

required

Any of:

string
null

The call the request came from, if any.

string

/^call_[0-9A-Za-z]+$/

phone

required

The number to call back, E.164.

string

priority

required

1 (low) … 10 (urgent); higher is returned sooner.

integer

>= -9007199254740991 <= 9007199254740991

queue_id

required

Any of:

string
null

A queue ID (prefix q_).

string

/^q_[0-9A-Za-z]+$/

route

required

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).

string

site_id

required

The website form it came from (source = web).

string | null

sla_at

required

Any of:

string
null

An ISO-8601 timestamp in UTC.

string format: date-time

source

required

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.

string

status

required

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).

string

summary

required

The AI summary of the originating call, when there is one.

string | null

updated

required

An ISO-8601 timestamp in UTC.

string format: date-time

window_end

required

Any of:

string
null

An ISO-8601 timestamp in UTC.

string format: date-time

Example

{
  "agent_id": null,
  "assistant_id": null,
  "attempts": 0,
  "call_id": null,
  "completed_at": null,
  "context": {
    "web": null
  },
  "created": "2026-11-03T09:14:22.000Z",
  "due_at": "2026-11-03T10:00:00.000Z",
  "id": "cb_2dXk9QmZ4rTv",
  "last_attempt_at": null,
  "last_result": null,
  "livemode": true,
  "max_attempts": 3,
  "merged_requests": 0,
  "metadata": {
    "crm_ticket": "T-1042"
  },
  "name": "Dana Levi",
  "notes": "Asked about the renewal offer.",
  "object": "callback",
  "origin_call_id": null,
  "phone": "+972501234567",
  "priority": 5,
  "queue_id": "q_3hRf8Kd2LmPq",
  "route": "agent_queue",
  "site_id": null,
  "sla_at": "2026-11-03T11:00:00.000Z",
  "source": "api",
  "status": "pending",
  "summary": null,
  "updated": "2026-11-03T09:14:22.000Z",
  "window_end": null
}

400

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

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

401

No valid API key was sent.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

403

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

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

409

The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "idempotency_mismatch",
    "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch",
    "message": "This Idempotency-Key was already used with different parameters.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "idempotency_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

429

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

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying.

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

500

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

Request a callback

Authorizations

Parameters

Header Parameters

Example

Example

Request Bodyrequired

Example

Responses

200

Example

400

Example

Headers

401

Example

Headers

403

Example

Headers

409

Example

Headers

429

Example

Headers

500

Example

Headers

Request Body^required