Skip to content
MoreVoiceDevelopers

Simulate an inbound call

POST
/test_helpers/inbound_calls
import MoreVoice from "@morevoice/sdk";


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


const call = await mv.testHelpersInboundCalls.create({
  from: "+972521234567",
  script: "dtmf:1",
  to: "+972509991234",
});
console.log(call);

Test mode only. A simulated caller dials one of your sandbox numbers: the call is routed like a real one (the number’s assistant, flow or inbound route), runs on the virtual carrier with simulated speech and AI, and sends every call event to your test-mode webhook endpoints. Returns the call (status ringing); it is answered within a second.

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

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 Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

A simulated inbound call to a sandbox number.

object
from

The simulated caller’s number (default +972521234567).

string
/^\+[1-9]\d{6,14}$/
script

What the simulated caller does: answer (default) talks for a few turns and hangs up; silent says nothing (and hangs up after 30 s); dtmf:123 presses the keys after the greeting, then talks.

string
/^(answer|silent|dtmf:[0-9*#]{1,20})$/
to
required

A sandbox number of yours (POST /v1/phone_numbers with a test key).

string
/^\+[1-9]\d{6,14}$/
Example
{
  "from": "+972521234567",
  "script": "dtmf:1",
  "to": "+972509991234"
}

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json

An inbound, outbound or browser call.

object
agent_id
required
Any of:

A user ID (prefix usr_).

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

Machine-readable marking (EU AI Act Art. 50(2)): true when the call contains speech generated by AI — an AI voice agent, or synthetic-voice IVR prompts. Recordings of such calls carry the same tag in their file metadata.

boolean
ai_segments
required

When AI-generated speech was played, in ms from the start of the call (empty when ai_generated is false).

Array<object>

A stretch of the call during which AI-generated speech was played to the other party.

object
end_ms
required
Any of:
integer
<= 9007199254740991
source
required

assistant: an AI voice agent spoke; ivr: synthetic-voice menu prompts.

string
Allowed values: assistant ivr
start_ms
required

Start, in ms from the start of the call.

integer
<= 9007199254740991
answered_at
required
Any of:

An ISO-8601 timestamp in UTC.

string format: date-time
answered_by
required
Any of:

The answering-machine detection verdict.

string
Allowed values: human machine unknown
api_key_id
required
Any of:

A api key ID (prefix key_).

string
/^key_[0-9A-Za-z]+$/
assistant

The assistant, with expand[]=assistant.

object
id
required

A assistant ID (prefix asst_).

string
/^asst_[0-9A-Za-z]+$/
name
required
string
object
required
string
Allowed value: assistant
assistant_id
required
Any of:

A assistant ID (prefix asst_).

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

A campaign ID (prefix cmp_).

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

A connection ID (prefix conn_).

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

A contact ID (prefix ctc_).

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

What the call cost (an ended call with no recorded provider usage costs 0).

object
amount
required

The amount in the currency’s minor unit (cents, agorot), rounded.

integer
>= -9007199254740991 <= 9007199254740991
amount_decimal
required

The exact amount in minor units, as a decimal string (sub-cent precision).

string
/^-?\d+(\.\d+)?$/
currency
required

ISO 4217 currency code.

string
/^[A-Z]{3}$/
estimate
required

True: an estimate from provider usage, not a billed amount.

boolean
direction
required
Any of:

browser: a call from a web page (the dashboard, a widget). Same values as the call.* webhook events.

string
Allowed values: inbound outbound browser
disposition
required

The business outcome recorded on the call (set_outcome tool, or the summary).

string | null
duration_ms
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
end_reason
required

Why the call ended, e.g. customer-ended-call, assistant-ended-call, customer-busy, customer-did-not-answer.

string | null
ended_at
required
Any of:

An ISO-8601 timestamp in UTC.

string format: date-time
flow_id
required
Any of:

A flow ID (prefix flow_).

string
/^flow_[0-9A-Za-z]+$/
flow_version
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
from
required

The calling number (E.164 when it is a phone number) or name.

string | null
has_recording
required
boolean
id
required

A call ID (prefix call_).

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

true in live mode, false in test mode.

boolean
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
object
required
string
Allowed value: call
purpose
required
Any of:

Why an outbound call is made. marketing adds the §30A consent and national do-not-call registry checks.

string
Allowed values: service marketing survey
queue_id
required
Any of:

A queue ID (prefix q_).

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

When the call started: dialled out, or rang in.

string format: date-time
status
required

queued (placed, not ringing yet), ringing, in_progress (answered, or an inbound call being handled) or ended.

string
Allowed values: queued ringing in_progress ended
summary
required
Any of:

The AI summary of a call.

object
action_items
required

Follow-ups for your business; empty when there are none.

Array<string>
call_id
required

A call ID (prefix call_).

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

An ISO-8601 timestamp in UTC.

string format: date-time
intent
required

What the caller wanted.

string
key_points
required
Array<string>
object
required
string
Allowed value: call_summary
outcome
required

How the call ended, or what was agreed.

string
sentiment
required
string
Allowed values: positive neutral negative mixed
text
required

A two-to-four sentence summary, in the language of the call.

string
to
required

The called number (E.164 when it is a phone number) or destination.

string | null
transport
required

sip for phone calls, webrtc for browser calls and conference rooms.

string
Allowed values: sip webrtc
type
required

Who handles the call: an AI assistant, a human agent, an IVR flow, a conference room, or a voicemail box.

string
Allowed values: ai human ivr conference voicemail
variables
required

The variables the call was created with.

object
key
additional properties
string
Example
{
  "agent_id": null,
  "ai_generated": true,
  "ai_segments": [
    {
      "end_ms": 99710,
      "source": "assistant",
      "start_ms": 0
    }
  ],
  "answered_at": "2026-11-03T09:14:29.410Z",
  "answered_by": "human",
  "api_key_id": "key_9i2E2pKO6g3z4nXl57Qb4g",
  "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ",
  "campaign_id": null,
  "connection_id": "conn_2bF8kQ1nR7sT3vW5xY9zA0",
  "contact_id": null,
  "cost": {
    "amount": 4,
    "amount_decimal": "4.2310",
    "currency": "USD",
    "estimate": true
  },
  "direction": "outbound",
  "disposition": null,
  "duration_ms": 99710,
  "end_reason": "customer-ended-call",
  "ended_at": "2026-11-03T09:16:02.120Z",
  "flow_id": null,
  "flow_version": null,
  "from": "+97237654321",
  "has_recording": true,
  "id": "call_8tRPaZp5hLMbrGqdJ9AmNa",
  "livemode": true,
  "metadata": {
    "crm_contact_id": "0031x00000AbCdE"
  },
  "object": "call",
  "purpose": "service",
  "queue_id": null,
  "started_at": "2026-11-03T09:14:22.000Z",
  "status": "ended",
  "summary": null,
  "to": "+972501234567",
  "transport": "sip",
  "type": "ai",
  "variables": {
    "customer_name": "Dana"
  }
}

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.

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.