HCC Docs

Simulator

The simulated number, the numbers and test flows you can call, and the limits

GET /v1/simulator simulator:write

Responses

  • 200

    OK

    Fields
    • data SimulatorInfo required
      Fields
      • simulatedNumber string required
      • numbers object[] required
      • flows object[] required
      • limits object required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

List simulated calls (kept for 24 hours)

GET /v1/simulator/calls simulator:write

Responses

  • 200

    OK

    Fields
    • data SimulatedCall[] required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Start a simulated inbound call to one of your numbers

POST /v1/simulator/calls simulator:write

Body

  • to string required

    One of your numbers, or the simulated number

  • from string

    The caller; a fixed test number by default

  • flow string

    A flow deployed to test; by default the number’s flow, or the only one

Responses

  • 201

    OK

    Fields
    • data Call required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • from string required
      • to string required
      • phoneNumberId string | null required
      • agentId string | null required
      • environment "live" | "test" required

        test calls run on the simulated carrier and never reach a phone

      • startedAt string | null required
      • answeredAt string | null required
      • endedAt string | null required
      • durationSeconds integer | null required
      • flow string | null required

        The call flow this call runs, if any

      • flowVersion string | null required

        The flow version the call started with

      • disposition string | null required

        Set by the flow's hangup({ disposition }), or a rep's wrap-up

      • repId string | null required

        A rep outbound call: the rep it was placed for

      • context any

        A rep outbound call: its context

      • outcome "completed" | "rep_unavailable" | "busy" | "no_answer" | "failed" | "cancelled" | "voicemail_left" | null required

        How a rep outbound call ended: completed, rep_unavailable (the rep never answered, the customer was not dialed), busy, no_answer, failed or cancelled. On a campaign's call: voicemail_left, when onVoicemail left a message on a machine

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

A simulated call as the simulator sees it: legs, the open prompt, the agent

GET /v1/simulator/calls/{id} simulator:write

Path

  • id string required

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Everything that happened on a simulated call, in order

GET /v1/simulator/calls/{id}/timeline simulator:write

Path

  • id string required

Responses

  • 200

    OK

    Fields
    • data SimulatorTimelineEntry[] required
      Fields
      • id string required
      • seq integer required
      • at string required
      • actor "hcc" | "caller" | "callee" | "agent" | "rep" | "supervisor" | "system" required
      • kind string required
      • text string required
      • data any
      • leg string | null required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Press keys: answers the open prompt

POST /v1/simulator/calls/{id}/digits simulator:write

Path

  • id string required

Body

  • digits string required

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Say something: answers the open prompt as speech

POST /v1/simulator/calls/{id}/speech simulator:write

Path

  • id string required

Body

  • text string required

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Act as the far end of a leg: answer

POST /v1/simulator/calls/{id}/answer simulator:write

Path

  • id string required

Body

  • leg string

    The leg to act on (SC…); by default the far end

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Act as the far end of a leg: machine

POST /v1/simulator/calls/{id}/machine simulator:write

Path

  • id string required

Body

  • leg string

    The leg to act on (SC…); by default the far end

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Act as the far end of a leg: greeting

POST /v1/simulator/calls/{id}/greeting simulator:write

Path

  • id string required

Body

  • leg string

    The leg to act on (SC…); by default the far end

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Act as the far end of a leg: greeting-end

POST /v1/simulator/calls/{id}/greeting-end simulator:write

Path

  • id string required

Body

  • leg string

    The leg to act on (SC…); by default the far end

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Act as the far end of a leg: busy

POST /v1/simulator/calls/{id}/busy simulator:write

Path

  • id string required

Body

  • leg string

    The leg to act on (SC…); by default the far end

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Act as the far end of a leg: no-answer

POST /v1/simulator/calls/{id}/no-answer simulator:write

Path

  • id string required

Body

  • leg string

    The leg to act on (SC…); by default the far end

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Act as the far end of a leg: fail

POST /v1/simulator/calls/{id}/fail simulator:write

Path

  • id string required

Body

  • leg string

    The leg to act on (SC…); by default the far end

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Act as the far end of a leg: hangup

POST /v1/simulator/calls/{id}/hangup simulator:write

Path

  • id string required

Body

  • leg string

    The leg to act on (SC…); by default the far end

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Play the AI agent: call one of its tools through the flow’s tool path

POST /v1/simulator/calls/{id}/agent/tool simulator:write

Path

  • id string required

Body

  • name string required
  • arguments object

    Default {}.

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Play the AI agent: say something to the caller

POST /v1/simulator/calls/{id}/agent/say simulator:write

Path

  • id string required

Body

  • text string required

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Play the monitoring supervisor: whispering, only the rep hears it; barging, everyone does

POST /v1/simulator/calls/{id}/supervisor/say simulator:write

Path

  • id string required

Body

  • text string required

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Play the rep: what they say is in a test call's transcript

POST /v1/simulator/calls/{id}/rep/say simulator:write

Path

  • id string required

Body

  • text string required

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Play the AI agent: end the conversation (runs onEnd / onAgentEnd)

POST /v1/simulator/calls/{id}/agent/end simulator:write

Path

  • id string required

Body

  • outcome string

    Default "completed".

  • order "webhook_first" | "stream_first"

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Play the AI agent's platform: deliver its post-call report and summary now, whether or not it has ended

POST /v1/simulator/calls/{id}/agent/report simulator:write

Path

  • id string required

Body

  • summary string required
  • startedAt string

Responses

  • 200

    OK

    Fields
    • data SimulatedCall required
      Fields
      • id string required
      • direction "inbound" | "outbound" required
      • from string required
      • to string required
      • status "queued" | "ringing" | "in_progress" | "completed" | "busy" | "no_answer" | "failed" | "canceled" required
      • startedAt string required
      • endedAt string | null required
      • legs SimulatedLeg[] required
      • prompt object required

        The open gather the far end is asked to answer

      • agent object required

        The simulated AI agent on the call, which you play

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 403

    A live key (test_mode_only): the simulator runs in test mode only

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code