TVH Voice docs

#Quickstart (sandbox)

The sandbox is the full platform with a simulated carrier: a second FreeSWITCH acting as the phone network (every number answers and echoes your audio; numbers ending in 486 are busy, 480 unavailable, 404 unallocated) and fake carrier APIs for ordering numbers. No real calls, no costs.

#1. Start it

git clone <platform repo> && cd voice-platform
./scripts/dev-env.sh            # creates .env with random secrets
docker compose up -d --build    # API :3000, dashboard :3002
./scripts/smoke.sh              # waits until every service is healthy

#2. Get an API key

docker compose exec api node dist/cli.js api-key:create --name "my CRM" --scopes admin
export VOICE_API_URL=http://localhost:3000 VOICE_API_KEY=vk_...

(Or create an admin with ADMIN_PASSWORD=... docker compose exec -e ADMIN_PASSWORD api node dist/cli.js admin:create --email you@example.com and use the dashboard at http://localhost:3002.)

#3. Connect the sandbox carrier and add a number

curl -s -X POST $VOICE_API_URL/v1/carriers -H "Authorization: Bearer $VOICE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"type":"mock","name":"Sandbox","settings":{"authMode":"register"},"credentials":{"apiKey":"mock_my_sandbox_key"}}'
curl -s -X POST $VOICE_API_URL/v1/numbers -H "Authorization: Bearer $VOICE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"e164":"+31201234567","carrier_id":"<carrier id>"}'

#4. Register a softphone and call

Create an agent (POST /v1/agents {"agent_ref":"me"}), fetch its softphone config (POST /v1/agents/me/softphone-config), open http://localhost:3000/demo/softphone, paste the JSON and press Register. Then:

curl -s -X POST $VOICE_API_URL/v1/calls -H "Authorization: Bearer $VOICE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"agent":"me","to":"+31612345678","caller_id":"+31201234567"}'

Your browser rings; answer and you hear yourself (the simulated callee echoes). Look at the call with GET /v1/calls/{call_id} or in the dashboard's call log.

#Next