Skip to main content
Voice lets you give your AI agent a real phone number. Callers interact with the same agent as on your website — same corpus, same tools, same personality — but through natural speech.
Voice calls use the exact same corpus, segments, system prompt, and tools as the chat widget. There is no separate configuration for voice content — changes to your knowledge base apply to both channels instantly.

​
Architecture

Phone call
  → Vapi (STT: Deepgram)
    → Animam Custom LLM endpoint (POST /voice/{slug}/chat)
      → SSE stream
        → Vapi (TTS)
          → Phone call
Animam is the brain, not the media stack. Animam acts as a Custom LLM: your voice orchestrator sends conversation turns as OpenAI-format messages, and Animam responds with an SSE stream. The hard real-time work — speech-to-text, text-to-speech, turn-taking, the telephony/SIP signalling — is handled by the voice layer. That separation is deliberate: it lets you choose how much you manage.

​
Three ways to connect telephony

Pick the level of control you want. All three use the same Animam brain.

​
Level 1 — Managed (no-code)

Animam creates the Vapi assistant and buys a phone number using the platform’s own Vapi key. Your tenant never touches Vapi. 
curl -X POST https://api.animam.ai/tenants/your-slug/voice/setup \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "fr",
    "voiceId": "aura-luna-fr",
    "firstMessage": "Bonjour, comment puis-je vous aider ?",
    "buyNumber": true,
    "numberAreaCode": "33"
  }'
# → { assistantId, phoneNumber, customLlmUrl, serverUrl }

​
Level 2 — Bring your own Vapi (and your own SIP / carrier)

You run your own Vapi account. Import your SIP trunk or phone numbers there (Vapi supports BYO carriers — Twilio, Telnyx, your own SIP), point the assistant’s Custom LLM URL at https://api.animam.ai/voice/your-slug, then link it to Animam: 
curl -X PUT https://api.animam.ai/tenants/your-slug/voice/setup \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "your_vapi_assistant_id",
    "phoneNumber": "+33123456789",
    "language": "fr"
  }'
This is the “I manage my own telephony” path: your SIP lives in your Vapi, Animam stays the brain. There is no SIP endpoint to configure on Animam’s side — and there doesn’t need to be.

​
Level 3 — Bring your own voice platform

The Custom LLM endpoint is plain OpenAI-compatible — it isn’t Vapi-specific. Any orchestrator that supports a Custom LLM URL works: Vapi, LiveKit Agents, Pipecat, Retell, Bland, or your own stack. Point its model URL at https://api.animam.ai/voice/your-slug (it calls /chat/completions, SSE), and Animam answers with the same corpus, tools and personality. You own the SIP, the STT/TTS and the latency budget; Animam owns the reasoning.

​
Tenant Settings

FieldTypeDescription
voiceEnabledbooleanEnable/disable the voice channel
voiceProviderstringAlways "vapi" for now
voicePhoneNumberstringE.164 format phone number
voiceAssistantIdstringVapi assistant ID
voiceConfigobjectVoice behavior (see below)

​
voiceConfig Fields

FieldTypeDescription
voiceIdstringVapi/Deepgram voice ID (e.g. "shimmer", "alloy")
languagestringBCP-47 language code (e.g. "fr-FR", "en-US")
firstMessagestringFirst words spoken when a call connects
endCallPhrasesstring[]Phrases that trigger call end (e.g. ["au revoir", "merci bonne journée"])
maxCallDurationintegerMaximum call duration in seconds

​
Endpoints

​
POST /voice//chat

Custom LLM endpoint for Vapi. Receives OpenAI-format messages and streams back a response in SSE format. Not intended for direct use — Vapi calls this automatically. 
# Example of what Vapi sends:
curl -X POST https://api.animam.ai/voice/your-slug/chat \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Bonjour, je voudrais prendre rendez-vous" }
    ],
    "stream": true
  }'

​
POST /voice//events

Webhook endpoint for Vapi events. Handles lifecycle events from Vapi:
EventDescription
assistant-requestVapi requesting assistant config at call start
tool-callsTool execution during a call (same tools as chat)
status-updateCall state changes (ringing, in-progress, ended)
end-of-call-reportFull call summary after hang-up
Configure this URL in your Vapi dashboard under Assistant > Server URL: 
https://api.animam.ai/voice/your-slug/events

​
GET /voice//recordings/

Download a call recording (if recording is enabled in Vapi). 
curl https://api.animam.ai/voice/your-slug/recordings/call_abc123 \
  -H "Authorization: Bearer ak_your_token" \
  --output call.mp3

​
Tools During Voice Calls

All tools configured for your tenant work during voice calls:
  • SUBMIT_FORM — Agent collects info verbally, submits the form at end of call
  • BOOK_MEETING — Agent checks availability and confirms a booking during the call
  • CHECK_AVAILABILITY — Agent reads out available time slots
  • ESCALATE_TO_HUMAN — Agent offers to transfer to a human operator
The agent adapts its language for voice — it reads out structured data (dates, prices, addresses) in a natural spoken format rather than displaying formatted text.

​
Verifying Your Setup

# Check voice is enabled
curl https://api.animam.ai/tenants/your-slug \
  -H "Authorization: Bearer ak_your_token" \
  | jq '.voiceEnabled, .voicePhoneNumber'
Then call your phone number. The firstMessage should play within 2 seconds of the call connecting.

​
Limitations

  • Managed mode links one phone number per tenant; with your own Vapi/voice platform (Level 2–3) you can route as many numbers as you like
  • Animam does not terminate SIP itself — the telephony/media layer is always your voice orchestrator’s responsibility (provisioning, audio quality, latency, fallback)
  • Recording storage is managed by Vapi, not Animam
  • Voice channel does not support file attachments
  • COLLECT_PAYMENT (Stripe) is not triggered during voice calls — the agent can describe payment options but cannot generate a checkout link mid-call