mv.callbacks

Callback requests and their scheduling. These methods are on mv.callbacks, where mv is your client (see the Node.js SDK). 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.

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

POST /callbacks/{id}/notes · API reference

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.

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

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.

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

POST /callbacks/{id}/cancel · API reference

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.

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

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.

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

POST /callbacks/{id}/complete · API reference

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.

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

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.

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

POST /callbacks · API reference

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.

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

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.

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

GET /callbacks · API reference

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.

Returns

A PagedList: await it for the first page, for await it for every item.

Example

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.

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

GET /callbacks/{id} · API reference

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.

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

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.

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

GET /callbacks/stats · API reference

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.

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

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.

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

PATCH /callbacks/{id} · API reference

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.

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

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