Quickstart

In about ten minutes you'll deploy a call flow and call it in test mode, with no phone and no Twilio account. Then you can point a real number at it.

You need Node 22 or later.

Create your workspace with your name, a workspace name, your email and a password.

Create a test key

Turn on Test mode with the switch in the top bar.
Open API keys and create a key with the Local dev preset.
Copy it. It starts with hcc_test_, and it's only shown once.

Create a project

This project runs on Cloudflare Workers. For other servers, see Call flows.

mkdir hello-hcc && cd hello-hcc && npm init -y
npm install @hcc/sdk
npm install --save-dev @hcc/cli wrangler

Put your key in .dev.vars, and keep that file out of git:

HCC_TEST_API_KEY=hcc_test_...

Add four files. hcc.config.ts says where HCC reaches your server. You'll change it when you go live:

import { defineConfig } from '@hcc/sdk';

export default defineConfig({
  endpoint: 'https://example.com/hcc',
});

src/flow.ts is your call logic:

import { defineCallFlow } from '@hcc/sdk';

export const hello = defineCallFlow('hello', {}, function* (c) {
  yield* c.say('Thanks for calling. Goodbye.');
  yield* c.hangup();
});

src/index.ts is the server. hcc generates the file it imports:

import { handler } from '@hcc/sdk';
import registry from './hcc.gen.ts';

export default handler(registry);

wrangler.jsonc configures the Worker:

{
  "name": "hello-hcc",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01"
}

Start it

npx hcc dev --forward-to http://127.0.0.1:8790/hcc -- npx wrangler dev --port 8790

This deploys your flow to test, runs your server, and sends test call events to it. No public URL is needed. It deploys again each time you save, and prints every event.

Keep it running.

Make your first call

In the dashboard, with Test mode on, open Simulator.
Press Start call.
You'll see the call's timeline say your line and hang up. Your terminal shows the same events.

That's a working call flow. To change it, edit src/flow.ts and save.

If the Simulator says Deploy a flow to test first, check that hcc dev is still running and press Check again.

Add a person

Send the caller to a rep instead. Add a queue, and transfer to it:

import { defineCallFlow, defineQueue, queue, TransferFailed } from '@hcc/sdk';

export const sales = defineQueue('sales', { displayName: 'Sales', maxWait: '2m' });

export const hello = defineCallFlow('hello', {}, function* (c) {
  yield* c.say('One moment.');
  try {
    yield* c.transfer(queue(sales));
  } catch (error) {
    if (!(error instanceof TransferFailed)) throw error;
    yield* c.say('Nobody is available right now.');
    yield* c.hangup();
  }
});

On Reps, press Enable as rep next to your name.
On Desk, press Go available. Test calls need no microphone.
Start another call in the Simulator, and accept it on the Desk.
Hang up and pick a disposition.

Make a real call

Test mode stops at the simulated carrier. For a real call you need:

Your Twilio account connected, and a number imported. See Twilio and numbers.
Your server on a public URL. Run npx wrangler deploy, set your keys as secrets with npx wrangler secret put, and put its URL in hcc.config.ts as endpoint, ending in /hcc.
A live key. With Test mode off, create a key with the Deploy preset, and add it to .dev.vars as HCC_API_KEY. An owner or admin has to make the key if it needs numbers:write, which pointing a number at a flow does.

Declare the number on the flow:

import { defineCallFlow, env } from '@hcc/sdk';

export const hello = defineCallFlow('hello', { numbers: [env('SALES_NUMBER')] }, function* (c) {
  yield* c.say('Thanks for calling. Goodbye.');
  yield* c.hangup();
});

Add SALES_NUMBER=+1... to .dev.vars, and set it on your server as well. Then deploy, and call your number:

npx hcc deploy --live

The deploy writes src/.hcc/versions, which keeps each call on the code it started on. Commit it with hcc.gen.ts.