Vapi

The Northsun Vapi kit is a published integration kit: assistant-request enrichment, per-turn caching, and post-call memory write-back for a Vapi voice assistant. It calls the same two frozen routes documented on Voice integration patterns — POST /v1/recall_and_enrich before the call, POST /v1/calls/end after — and nothing else. The kit is published on npm under its current scope, and the versions there are older than the behaviour described on this page, which is the kit's current source; the next release ships under the Northsun package name (in progress). Until then, the two HTTP calls documented on this page work without the kit, as shown on Voice integration patterns; the contact form can supply the current package name. This is a Northsun-built, Northsun-maintained kit against Vapi's documented webhook contract — not a native Vapi feature or a certified Vapi integration.

Prefer to see the mapping as a picture of the calls? The Vapi mapping guide lays the same two calls out step by step.

Set your key

NORTHSUN_API_KEY=sk_live_...
NORTHSUN_BASE_URL=https://mcp.northsun.ai   # set it explicitly; see below
VAPI_WEBHOOK_SECRET=...                 # shared secret from your Vapi assistant, recommended

NORTHSUN_API_KEY is your Northsun API key — see Installation for how to get one. Set it as a platform secret (wrangler secret put NORTHSUN_API_KEY on Cloudflare Workers, or your platform's equivalent), never as a plaintext environment value in a repo or client bundle.

These are names you choose. Pass the key and the base URL https://mcp.northsun.ai to the client's options explicitly: the kit reads no environment itself, and the published client defaults to an earlier hostname that serves the same surface.

Wire the webhook

The kit's Cloudflare Worker example exposes one route, /vapi/server, that handles Vapi's assistant-request, per-turn function-call, and end-of-call-report messages:

assistant-request    -> POST /v1/recall_and_enrich  (before the first turn)
function-call        -> reuse the cached context for that call.id
end-of-call-report   -> POST /v1/calls/end          (after hangup)

In your Vapi assistant configuration, set:

server.url = https://your-worker.example.com/vapi/server

Vapi calls that URL for every relevant lifecycle event; the key never leaves your server.

Use the context in your prompt

The recall is exposed as assistant variable values, not raw JSON, so your prompt template stays readable. The host-safe variables are:

• {{is_returning}}
• {{history_known}}
• {{caller_known}}
• {{has_memory_facts}}
• {{line_type}}
• {{memory_status}}

Caller-derived text (name, company, summary, facts) is not exposed as variables: a stored value would be interpolated into your agent's prompt outside the quoted data block. It reaches the model only inside the quoted memory block (memory_block). The kit appends that quoted block to the system prompt it returns, after every instruction. For a transient assistant the prompt is appended to the assistant's own model messages; for a saved assistant, pass the model to override so the prompt reaches it, because without it the saved assistant's own prompt runs without the caller's memory.

See What recall gives you back for what populates these and when a value is legitimately absent rather than wrong.

Verify it

Call the Vapi number attached to your assistant. In your worker logs you should see one recall on the first assistant-request, the same cached context reused on later per-turn function-call events for that call.id, and one POST /v1/calls/end when Vapi sends end-of-call-report. See Hangup, and what happens next for what the 204 confirms and how to verify the write. A live-account call against a deployed endpoint is still owed for this kit; treat your own test call as the proof.

Next steps

• Bland — the same lifecycle for Bland pathways.
• Voice integration patterns — the platform-neutral lifecycle this kit implements.
• Production readiness — the launch checklist before you point this at real traffic.