Skip to content
MoreVoiceDevelopers

Cancel a callback

POST
/callbacks/{id}/cancel
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);

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

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string
<= 200 characters /^cb_[0-9A-Za-z]+$/

A callback ID (cb_…).

Header Parameters

Section titled “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

Section titled “Request Body”
Media typeapplication/json
object
reason

Why (kept in the callback’s history).

string
<= 200 characters
Example
{
  "reason": "Customer called us back"
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

A request to call someone back, and its progress.

object
agent_id
required
Any of:

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

string
/^usr_[0-9A-Za-z]+$/
assistant_id
required
Any of:

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:

The call that returned it, once there is one.

string
/^call_[0-9A-Za-z]+$/
completed_at
required
Any of:

An ISO-8601 timestamp in UTC.

string format: date-time
context
required
object
web
required
Any of:
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
id
required

A callback ID (prefix cb_).

string
/^cb_[0-9A-Za-z]+$/
last_attempt_at
required
Any of:

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:

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:

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:

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:

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

Section titled “400”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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

401

Section titled “401”

No valid API key was sent.

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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

403

Section titled “403”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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

404

Section titled “404”

No object with this ID exists in this organisation and mode.

Media typeapplication/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": "resource_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#resource-missing",
    "message": "No such object: 'call_4Gk2'.",
    "param": "id",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "not_found"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

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

409

Section titled “409”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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

429

Section titled “429”

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

Media typeapplication/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

Section titled “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

Section titled “500”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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