8000 vapi/agency-routing: per-client Vapi call routing with an async tool via Hookdeck by leggetter · Pull Request #44 · hookdeck/hookdeck-demos · GitHub
[go: up one dir, main page]

Skip to content

vapi/agency-routing: per-client Vapi call routing with an async tool via Hookdeck - #44

Merged
leggetter merged 24 commits into
mainfrom
feat/vapi-agency-routing
Nov 18, 2026
Merged

leggetter merged 24 commits into
mainfrom
feat/vapi-agency-routing

Conversation

@leggetter
@leggetter leggetter commented Nov 12, 2026 •
Copy link
Copy Markdown
Collaborator

Adds vapi/agency-routing: a demo where each client's Vapi assistant sends its call events to its own Hookdeck VAPI source and local endpoint. The CRM lookup tool runs async and answers into the live call through Vapi's Live Call Control (controlUrl add-message). A live topology pane shows every webhook and every controlUrl call.

What's in it

  • Per-client routing: one VAPI source per client (vapi-acme-dental, vapi-globex-plumbing), each with its own CLI destination; npm run setup creates the sources, connections, assistants and HMAC credentials through the APIs.
  • Verification: Event Gateway verifies Vapi's HMAC signature (credential payload format {body}); scripts/probe.ts sends a signed and an unsigned request to prove verification is on. A bad signature gets a 401.
  • Connection rules: deduplicate (10 minutes, on message.type, call.id, status and toolCallList) and retry (exponential, 4 retries from 10 s; short so a retry is visible in the pane).
  • The page: one card per client line naming the agent (the client's Vapi assistant) and the caller (you), with a call button for an in-demo web call through the Vapi Web SDK. A "While you wait" panel follows the async lookup: the tool request, the CRM delay as a countdown, then the result posted to controlUrl. Explanations sit behind ⓘ dialogs and hover tips.
  • Switchboard theme (default; System, Light and Dark remain): restyles main only, never the Data flow pane, via _shared/theme.
  • Topology pane at the bottom, open by default: one row per client (assistant, Event Gateway source, endpoint), packets moving as real webhooks arrive, and a controlUrl return edge from each endpoint to its own call. Tabs play five scripted scenes (call and tool, two clients, duplicate dropped, bad signature, app down then retry). Clicking a packet shows its attempts and a View in Hookdeck link.
  • Captures: MP4s of the five scenes, landscape and square, in scenes/captures/.
  • Failure injection: per client, fail the next N deliveries with 503 or slow the answer.
  • Shared pieces: _shared/scenes and _shared/topology-pane byte-identical to elevenlabs/post-call-transcripts: post-call transcripts through Hookdeck with a live topology pane and a shared scene kit #47; the flow drawer's server-side state is kept, its client is replaced by the pane. Design system and CLI helpers from chore: share the design system and Hookdeck CLI helpers across demos via _shared/ and a sync check #43.

Live-run facts

  • Real web calls t 8000 o both assistants (2026-11-16): each call's events reached only its own source and endpoint, and the lookup result was spoken into the live call through controlUrl.
  • A tool call delivered after its call has ended (for example, after the app was down during the call) can't be answered: Vapi returns 500 "failed to route call", and the app shows it as a lookup-error.
  • Running two hookdeck listen processes for the same sources delivers every event twice (one per CLI client); the README says so.

Merging

Checks

node scripts/sync-shared.mjs --check and typecheck pass; npm test (32 tests: offline checks, theme copy, the While you wait logic, and browser tests for the scenes, the pane and the page) passes at the branch head.

Update 2026-11-18: Switchboard theme, roles on each card, the While you wait panel and ⓘ dialogs (ecad321..5521483). No code the tutorial (hookdeck/website#992) shows changed.

Review fixes: (5fe85ba..eaa73e1) the server binds to 127.0.0.1 (HOST overrides); malformed tool calls get a 400 and a JSON error handler replaces stack traces; sendToCall has a 10 s timeout and the controlUrl must be https and *.vapi.ai (ALLOW_LOCAL_CONTROL_URL=true for npm run simulate); the dedupe set is capped and a tool call is retried after a failed post; a redelivery after the lookup closed no longer opens a second countdown; setup updates only the Vapi objects it created; a startup warning for an unset *_ASSISTANT_ID; and one _shared commit (5fe85ba: key redaction, Verified pill, API key off the CLI command line) that can be cherry-picked onto the other demo branches. Two lines of code the tutorial shows changed: signal: AbortSignal.timeout(10_000) in sendToCall, and a controlUrl check before runLookup in handleToolCalls.

Prompt fix (07fc942): after a real off-script call, the assistants say in one sentence what they can't do (create accounts, book, check availability) and offer a call-back instead of pretending; they don't guess the CRM result before it arrives; the prompt again says Vapi answers the async tool with a placeholder "Success.".

Merge readiness (be84075): root README gets the vapi/ directory line and every shared utility row this stack uses; the demo README and .env.example match the code; the latest pane and feed polling is synced from _shared; the theme test reads the demo's own theme.js so npm test passes in a standalone copy.

🤖 Generated with Claude Code

Posted by an AI agent with human oversight.

leggetter and others added 10 commits November 12, 2026 10:38
…Call Control (pre-live-test)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d signature probe script

The CLI's --source-config is silently ignored for VAPI sources, leaving verification off. Setup now PUTs the source auth config directly.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…waiting; say what webhooks a call produces

The assistants asked small-talk questions ("how's your day") while the async
lookup ran and moved on without waiting. The prompt now forbids small talk and
stacked questions and has the assistant say one hold sentence, then wait. Each
client column shows which webhooks a call produces and when.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ystem; probe proves verification is on

setup and listen now use createHookdeckCli(), upsertSource({ auth }), upsertConnection and
runListen from _shared/hookdeck instead of the demo's own CLI wrapper and the auth PUT workaround.
npm run probe sends a correctly signed and a badly signed request to each source and checks both
the HTTP status (200 / 401) and the request record read back from the Hookdeck API.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…the shared data-flow drawer

_shared/flow-drawer is a bottom drawer (closed by default) that shows each message moving from the
platform through Event Gateway (received, verified or rejected with 401), the event, delivery
attempts (status, latency, retries) and the app's result, plus the app's own outbound calls. A
server module reads requests, events and attempts from the Hookdeck API with the project API key
and merges the app's own feed; nothing in it is specific to Vapi. The demo passes its sources,
labels and feed, records the controlUrl call, and gains npm run simulate to replay a signed call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…03, slow, include tool calls) and a short-interval retry rule so the drawer shows retries

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ng the cards

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s header

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…after ingestion show the 200 the sender gets

Defaults to 401 (edge-verified source types such as VAPI). Messages carry an explicit rejected flag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
leggetter and others added 4 commits November 16, 2026 13:31
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…er README)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Shared scene kit and pane copied byte-identical from the ElevenLabs branch (d771e77).
Scene with one row per client, the controlUrl return path, and call, two-client,
duplicate, bad-signature and app-down scenes. A dedup rule on both connections.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e and square, light)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
leggetter and others added 10 commits November 17, 2026 22:14
…e3f4e), byte-identical; vapi/agency-routing uses it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… hover tips), the agent and the caller on each card, Switchboard theme, While you wait panel

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ic and the main view in a browser

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… when verified, keep the Hookdeck API key off the CLI command line and out of errors

- flow-drawer server: an empty HOOKDECK_API_KEY made split('') insert [key] between every character of an error message.
- topology pane: verified null means the source does not verify, so no pill; Verified only for true.
- hookdeck-cli: login passes the key to `hookdeck ci` as HOOKDECK_API_KEY (the CLI reads it) instead of --api-key, so ps does not show it; failed CLI calls have the key removed from their message and output.

Synced copies: deepgram/stt-tts and vapi/agency-routing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…stants it created (IDs saved in .env), never one that shares a name

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…duplicate, which the While you wait panel ignores

The server-side half is in the next commit; the panel already keys on the log type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed tool calls, controlUrl allowlist and timeout, capped dedupe that retries after a failed post)

- Bind to 127.0.0.1 (HOST overrides); warn at startup when an *_ASSISTANT_ID is unset.
- Malformed tool calls (bad arguments JSON, non-array toolCallList) return 400 and are logged; runLookup has a .catch; a JSON error handler replaces Express's stack-trace page; express.json limit 50mb -> 2mb.
- sendToCall times out after 10 s; the controlUrl must be https and *.vapi.ai (ALLOW_LOCAL_CONTROL_URL=true allows http://localhost for npm run simulate and the tests).
- seen_tool_calls is a capped, expiring map; a tool call is removed from it when the result is not posted, so a redelivery retries. The repeat is logged as tool-calls-duplicate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…seful straight away, not "Success."

Vapi records an empty tool result for an async tool (seen in a real call log); the old wording told the model something it never receives.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… pretending, and the prompt says "Success." again

A real call showed the assistant promising to create an account and check availability (it has no tools for either), going silent after "one moment", and guessing the CRM result before it arrived. Vapi does answer an async tool with a placeholder "Success." (both tool_call_result messages in that call), so 17aa9fe's wording was wrong.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d rows, README call-button wording and run notes, all env vars in .env.example, the latest pane and feed polling from _shared, theme test reads the demo's own theme.js

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leggetter
leggetter marked this pull request as ready for review November 18, 2026 12:25
@leggetter
leggetter merged commit 0ac509e into main Nov 18, 2026
7 checks passed
@leggetter
leggetter deleted the feat/vapi-agency-routing branch November 18, 2026 12:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0