Voice integration patterns

Every Northsun voice integration follows the same lifecycle: recall context before the first useful turn, let the voice platform run the conversation, submit the completed interaction after hangup, and verify the write-back with a later read. The voice platform owns the call; Northsun is the memory and enrichment layer the surrounding application calls.

The platform-neutral architecture

platform call-start event
  -> verify the platform request
  -> normalize phone number and stable call ID
  -> POST /v1/recall_and_enrich
  -> select safe, relevant context
  -> continue with a useful fallback if context is unavailable

platform call-end event
  -> verify and deduplicate the event
  -> normalize transcript and outcome
  -> POST /v1/calls/end
  -> retain the acknowledgement and redacted correlation data
  -> later verify the expected history with recall or caller lookup

The frozen public caller-memory surface has exactly three endpoints:

• POST /v1/recall_and_enrich
• POST /v1/calls/end
• GET /v1/caller/{phone_number}

Platform-specific guides translate vendor events into this lifecycle. They document custom integrations; they do not imply native, certified, or vendor-endorsed partnerships.

Recall before the agent needs context

Call recall_and_enrich from your server when the platform provides a verified call-start event. Supply the caller number and a stable session or call identifier when available:

curl -sS -X POST https://mcp.northsun.ai/v1/recall_and_enrich \
  -H "Authorization: Bearer $NORTHSUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "trigger": "answered",
    "session_id": "platform_call_123"
  }'

The response distinguishes caller profile, prior-call memory, and nullable person, company, and phone enrichment blocks. Handle each branch independently. An unknown caller, missing enrichment, or degraded memory read must still reach a useful first-contact conversation.

The trigger field records whether your integration fired at ringing or answered. Do not assume it changes server behavior beyond the documented contract.

Northsun is designed for sub-300ms voice recall. That exact phrase describes design intent, not a measured percentile or an end-to-end guarantee. Your platform hook, server, network, mapping logic, and model all contribute to the caller’s perceived delay. Choose a timeout from your own measurements.

Select context; do not dump the response

Treat the recall response as input to an application policy:

• Use prior interaction history only when it is relevant to the current line or workflow.
• Keep an enriched name or company as contextual evidence, not identity verification.
• Do not reveal sensitive history before the caller is appropriately identified.
• Preserve an unknown-caller greeting that works without optional context.
• Log correlation and timing information without storing secrets or raw personal data unnecessarily.

The current REST response does not prove that every item carries provenance, policy, or bi-temporal state. Governed-context substrate and future serving direction are documented separately.

Write back after every completed termination path

Map the platform’s final event to calls/end. Normalize the transcript into {role, text, ts_ms} entries and use one of the documented outcomes:

curl -i -sS -X POST https://mcp.northsun.ai/v1/calls/end \
  -H "Authorization: Bearer $NORTHSUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "platform_call_123",
    "phone_number": "+15551234567",
    "transcript": [
      {"role":"agent","text":"How can I help?","ts_ms":0},
      {"role":"user","text":"Please call Tuesday.","ts_ms":2100}
    ],
    "duration_s": 18,
    "outcome": "callback_requested"
  }'

The success response is 204 No Content. Do not parse a body. See Hangup, and what happens next for what the 204 confirms and how to verify it with a later recall.

Voice platforms often retry webhooks. Deduplicate with the platform’s stable call ID in your own integration. Avoid automatic repeated write-back when the state of an earlier attempt is unknown.

Inspect and troubleshoot outside the live call

Use GET /v1/caller/{phone_number} for a read-only profile check. It does not create a caller or trigger enrichment, and an unknown number returns 404.

A useful support receipt contains:

• UTC timestamps;
• endpoint and HTTP status;
• redacted platform call/session ID;
• recall trace_id when returned;
• whether enrichment was partial or memory was degraded;
• the later read used to verify write-back.

Do not include bearer tokens or unnecessary transcript/PII content.

Platform guides

• Vapi mapping guide — the Vapi events laid out against the three calls, step by step.
• Vapi kit, Bland kit, Twilio kit, ElevenLabs kit, Retell kit, LiveKit kit — the published npm kits that implement each mapping, if you'd rather install it than write it. The kits are published under their current scope, with Northsun-scoped names in progress; until those ship, the two calls above work without a kit, and the contact form can supply the current package names.

Before production, run the Quickstart, Errors and retries, and Production readiness gates with a controlled caller and the exact deployed platform configuration.