HCC Docs

Testing with the simulator

@hcc/sdk/testing runs a flow in-process. To run it end to end (your deployed flow endpoint, queues, the desk, Events and webhooks) without a phone, use a test key: test mode runs every call on a simulated carrier that never reaches the phone network. You play the caller, the callee and the AI agent.

const hcc = new Hcc({ apiKey: process.env.HCC_TEST_KEY }); // hcc_test_…

const call = await hcc.simulator.call({ to: '+12025550142', flow: 'support' });
await call.until((c) => c.prompt !== null); // the menu's gather is open
await call.press('1'); // or call.say('my order')

await call.until((c) => c.agent !== null); // connected to the simulated agent
await call.agent.tool('lookup_order', { orderId: '123456' }); // your tool's handler runs
await call.agent.end('completed'); // the code after c.connect runs

await call.waitFor((e) => e.kind === 'say' && e.text === 'Goodbye.');
console.log(await call.timeline()); // what happened, in order
  • to is one of your numbers or the workspace's simulated number (+1 202 555 01xx, shown in the dashboard's Simulator page). A workspace needs no telephony account to use it.
  • flow picks a flow deployed to test; without it, the number's flow (or the only one) runs. The simulator only runs test flows: deploy a live flow with alsoTest: true to simulate it (see Call flows).
  • For calls your flow places (a transfer to a number, hcc.calls.create in test), hcc.simulator.get(id) gives the handle: answer(), busy(), noAnswer() and hangup() act as the dialed party.
  • state() is the call as the simulator sees it (legs, the open prompt, the agent); waitFor and until poll with a 10 s default timeout.
  • A queued simulated call rings reps on the desk like any other; they accept it with no softphone.
  • /v1/simulator refuses live keys (403 test_mode_only). At most 10 simulated calls run at once; a timeline is kept for 24 hours.