Skip to content
MoreVoiceDevelopers

Simulate a call through a flow

POST
/flows/{id}/simulate
import MoreVoice from "@morevoice/sdk";


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


const flowSimulation = await mv.flows.simulate("flow_7Hk2Lm9Qp", {
  messages: [
    "Hi, I'd like to book an appointment",
    "Tomorrow at 10",
  ],
});
console.log(flowSimulation);

Runs a text-only call through the flow’s draft (or a published version) with the real flow engine and the assistant’s model, and answers what happened: the turns, the nodes entered, the actions (dry runs: no API or tool request is sent) and where the call stands. Send the caller’s lines as messages / message, keys as dtmf, silence as no_response. Continue the same simulation with sim_id (it lives 15 minutes). With a test key the models are mocks.

Send Accept: text/event-stream to receive the same simulation as Server-Sent Events while it runs: sim.started (sim_id, resumed, kind), then sim.node, sim.turn and sim.action (each with the fields of the matching FlowSimulation entry) in order, and last sim.done, whose data is this endpoint’s JSON answer; error ends a failed run. Closing the connection stops the simulation. A streamed answer counts against the key’s stream limit and is not stored for Idempotency-Key replays.

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 /^flow_[0-9A-Za-z]+$/

A flow ID (flow_…).

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

A simulated call (text only, no audio): start one, or continue it with sim_id. Test keys simulate on mock models; actions and tools are dry runs.

object
dtmf

Keys the caller presses, in order (after messages, before message); the entry then completes.

string
/^[0-9*#A-D]{1,40}$/
message

One more caller line (after messages).

string
>= 1 characters <= 2000 characters
messages

What the caller says, one line per turn, in order.

Array<string>
<= 20 items
no_response

The caller stays silent (a no-response timeout).

boolean
sim_id

Continue this simulation (the id of an earlier answer; it lives 15 minutes after its last turn). Default: a new one.

string
/^sim_[0-9A-Za-z]{22}$/
variables

Variables for the simulated call (merged over the flow’s sample values).

object
key
additional properties
Any of:
string
<= 2000 characters
version

Simulate this published version. Default: the draft.

integer
>= 1 <= 9007199254740991
Example
{
  "messages": [
    "Hi, I'd like to book an appointment",
    "Tomorrow at 10"
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

A simulated call’s progress: this request’s turns, path and actions, and where the call stands.

object
actions
required

Actions and tool calls during this request (dry runs).

Array<object>
object
detail
required
string
kind
required

Api, transfer, voicemail, operator, tool:<name>, …

string
node_key
required
string | null
outcome
required
string
coverage
required
object
node_count
required
integer
>= -9007199254740991 <= 9007199254740991
node_pct
required
number
transition_count
required
integer
>= -9007199254740991 <= 9007199254740991
transition_pct
required
number
unvisited_node_keys
required
Array<string>
visited_node_keys
required
Array<string>
current_node_key
required
string | null
end_reason
required
string | null
ended
required
boolean
flow_id
required

A flow ID (prefix flow_).

string
/^flow_[0-9A-Za-z]+$/
id
required

The simulation’s ID: send it as sim_id to continue.

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

true in live mode, false in test mode.

boolean
object
required
string
Allowed value: flow_simulation
path
required

The nodes entered during this request, in order.

Array<object>
object
from_node_key
required
string | null
node_key
required
string
node_type
required

The node’s v1 type (internal: a type outside the public subset).

string
Allowed values: start say question ai_agent kb_answer api post_api integration post_integration set_variable decision dtmf_menu hours transfer end internal
transition_key
required

The transition taken into the node (null at the start or for a global jump).

string | null
via
required
string | null
resumed
required

This request continued an existing simulation.

boolean
turns
required

What was said during this request, in order.

Array<object>
object
node_key
required

The node that spoke (assistant lines) or listened (caller lines).

string | null
role
required
string
Allowed values: assistant customer
source
required

Script: a node’s fixed line; ai: the model’s reply; speech / keypad: the caller.

string
Allowed values: script ai speech keypad
text
required
string
variables
required

The call’s variables now (sensitive ones redacted).

object
key
additional properties
Example
{
  "actions": [],
  "coverage": {
    "node_count": 5,
    "node_pct": 60,
    "transition_count": 5,
    "transition_pct": 40,
    "unvisited_node_keys": [
      "bye"
    ],
    "visited_node_keys": [
      "start",
      "ask_id"
    ]
  },
  "current_node_key": "ask_id",
  "end_reason": null,
  "ended": false,
  "flow_id": "flow_7Kp1Ns4Vy6Ab9Dg2Hj5Lm8",
  "id": "sim_7Hk2pQ9xZb4Lm8Nc3Rt6Vw",
  "livemode": false,
  "object": "flow_simulation",
  "path": [
    {
      "from_node_key": null,
      "node_key": "start",
      "node_type": "start",
      "transition_key": null,
      "via": "start"
    },
    {
      "from_node_key": "start",
      "node_key": "ask_id",
      "node_type": "question",
      "transition_key": "t_next",
      "via": "always"
    }
  ],
  "resumed": false,
  "turns": [
    {
      "node_key": "start",
      "role": "assistant",
      "source": "script",
      "text": "Hello, you've reached Acme."
    },
    {
      "node_key": "ask_id",
      "role": "customer",
      "source": "speech",
      "text": "Hi, I'd like to book an appointment"
    },
    {
      "node_key": "ask_id",
      "role": "assistant",
      "source": "ai",
      "text": "Sure! What is your ID number?"
    }
  ],
  "variables": {
    "customer_id": 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.