Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.animam.ai/llms.txt

Use this file to discover all available pages before exploring further.

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
The voice layer is handled entirely by Vapi. Animam acts as a Custom LLM in the Vapi configuration — Vapi sends conversation turns as OpenAI-format messages, and Animam responds with an SSE stream.

​
Setup: Option A (One Number Per Tenant)

Each tenant gets one Vapi phone number linked to their Animam agent.
  1. Create a Vapi assistant in your Vapi dashboard
  2. Set the Custom LLM URL to https://api.animam.ai/voice/your-slug/chat
  3. Configure your preferred voice (voice ID, language, first message)
  4. Assign a phone number to the assistant
  5. Save the assistantId and phoneNumber to your Animam tenant settings
curl -X PATCH https://api.animam.ai/tenants/your-slug \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "voiceEnabled": true,
    "voiceProvider": "vapi",
    "voicePhoneNumber": "+33123456789",
    "voiceAssistantId": "vapi_assistant_id",
    "voiceConfig": {
      "voiceId": "shimmer",
      "language": "fr-FR",
      "firstMessage": "Bonjour, je suis l'\''assistant de votre cabinet. Comment puis-je vous aider ?"
    }
  }'

​
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

  • One phone number per tenant (Option A)
  • 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