Events before endpoints
Start by deciding which business events matter after a call, then map the API contract.
- call.started
- intent.detected
- booking.requested
- transfer.attempted
- call.completed
API planning
API planning for AI receptionist workflows
Plan a future API integration for structured call outcomes. API keys remain Preview until Havio exposes a consuming production API.
Technical example
Event payload shape
{
"event": "call.completed",
"callId": "call_01JLC8W9Q4P2N7A6K3",
"agentId": "agent_booking",
"occurredAt": "2026-06-30T14:22:11Z",
"caller": {
"phone": "caller_phone_e164",
"timezone": "America/New_York",
"language": "en"
},
"intent": "lead_qualification",
"outcome": "qualified",
"summary": "Caller requested a Friday quote window.",
"consent": {
"aiDisclosed": true,
"recordingEnabled": false
},
"fields": {
"service": "hvac_install",
"urgency": "routine",
"preferredWindow": "Friday morning"
},
"destinationStatus": "crm_task_created"
}Best buyer
Teams with internal systems or custom workflow software
Primary risk
Treating Preview key issuance as a live consuming API
Havio advantage
Business outcomes first, API payload second
Stable fields
API consumers need predictable names, status values, and missing-data behavior.
- Caller identity and consent fields
- Intent, urgency, language, and outcome
- Transcript, summary, recording, and destination references
Failure paths
A production API path needs idempotency, retry logic, and a human-readable failed-write state.
- Idempotency key per call outcome
- Retryable versus permanent errors
- Alert destination for unresolved writes
Auth, versioning, and limits
API key issuance and revocation exist as Preview controls; they are not proof of a usable production API surface.
- Authentication method and token owner documented before launch
- No production consumer is claimed until an API endpoint enforces the key
- Rate, concurrency, and replay expectations reviewed before any API release
Caller-data boundaries
Treat API events as operational records that may contain caller data, consent state, and business-sensitive context.
- Send only fields required by the destination system
- Keep recording and transcript links behind approved access controls
- Never include API secrets, private tokens, or raw credentials in call payloads
Related developer paths
Keep the workflow contract connected.
Technical pages work best when they point back to the operational buyer questions: source of truth, fallback, billing, security, and review.