Voix (téléphonie Vapi) - Animam Documentation

La voix permet de donner un vrai numéro de téléphone à votre agent IA. Les appelants parlent au même agent que sur votre site — même corpus, mêmes outils, même personnalité — mais par la parole.

Les appels vocaux utilisent exactement le même corpus, les mêmes segments, le même system prompt et les mêmes outils que le widget de chat. Il n’y a pas de configuration de contenu séparée pour la voix — toute modification de votre base de connaissances s’applique aux deux canaux instantanément.

Architecture

Appel téléphonique
  → Vapi (STT : Deepgram)
    → Endpoint Custom LLM Animam (POST /voice/{slug}/chat)
      → flux SSE
        → Vapi (TTS)
          → Appel téléphonique

Animam est le cerveau, pas la couche média. Animam agit comme un Custom LLM : votre orchestrateur vocal envoie les tours de conversation en messages au format OpenAI, et Animam répond par un flux SSE. Le dur du temps réel — speech-to-text, text-to-speech, gestion des tours de parole, signalisation téléphonique/SIP — est géré par la couche voix. Cette séparation est volontaire : elle vous laisse choisir le niveau de gestion que vous voulez.

Trois façons de connecter la téléphonie

Choisissez le niveau de contrôle souhaité. Les trois utilisent le même cerveau Animam.

Niveau 1 — Managé (sans code)

Animam crée l’assistant Vapi et achète un numéro avec la clé Vapi de la plateforme. Votre tenant ne touche jamais à 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 }

Niveau 2 — Votre propre Vapi (et votre propre SIP / opérateur)

Vous gérez votre propre compte Vapi. Importez-y votre trunk SIP ou vos numéros (Vapi gère les opérateurs BYO — Twilio, Telnyx, votre propre SIP), pointez l’URL Custom LLM de l’assistant vers https://api.animam.ai/voice/your-slug, puis liez-le à 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"
  }'

C’est le chemin « je gère ma propre téléphonie » : votre SIP vit dans votre Vapi, Animam reste le cerveau. Il n’y a aucun endpoint SIP à configurer côté Animam — et il n’y en a pas besoin.

Niveau 3 — Votre propre plateforme vocale

L’endpoint Custom LLM est compatible OpenAI standard — il n’est pas spécifique à Vapi. Tout orchestrateur qui accepte une URL Custom LLM fonctionne : Vapi, LiveKit Agents, Pipecat, Retell, Bland, ou votre propre stack. Pointez l’URL du modèle vers https://api.animam.ai/voice/your-slug (il appelle /chat/completions, en SSE), et Animam répond avec le même corpus, les mêmes outils et la même personnalité. Vous possédez le SIP, le STT/TTS et le budget de latence ; Animam possède le raisonnement.

Réglages du tenant

Champ	Type	Description
`voiceEnabled`	boolean	Active/désactive le canal voix
`voiceProvider`	string	Toujours `"vapi"` pour l’instant
`voicePhoneNumber`	string	Numéro au format E.164
`voiceAssistantId`	string	ID de l’assistant Vapi
`voiceConfig`	object	Comportement vocal (voir ci-dessous)

Champs voiceConfig

Champ	Type	Description
`voiceId`	string	ID de voix Vapi/Deepgram (ex. `"shimmer"`, `"alloy"`)
`language`	string	Code langue BCP-47 (ex. `"fr-FR"`, `"en-US"`)
`firstMessage`	string	Première phrase prononcée à la connexion de l’appel
`endCallPhrases`	string[]	Phrases qui terminent l’appel (ex. `["au revoir", "merci bonne journée"]`)
`maxCallDuration`	integer	Durée maximale d’appel en secondes

Endpoints

POST /voice//chat/completions

Endpoint Custom LLM (compatible OpenAI). Reçoit des messages au format OpenAI et renvoie une réponse en flux SSE. Pointez l’URL Custom LLM de votre orchestrateur vers https://api.animam.ai/voice/your-slug — il appelle /chat/completions automatiquement.

# Exemple de ce que l'orchestrateur envoie :
curl -X POST https://api.animam.ai/voice/your-slug/chat/completions \
  -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

Endpoint webhook pour les événements Vapi. Gère les événements de cycle de vie :

Événement	Description
`assistant-request`	Vapi demande la config de l’assistant au début de l’appel
`tool-calls`	Exécution d’outils pendant un appel (mêmes outils que le chat)
`status-update`	Changements d’état de l’appel (sonnerie, en cours, terminé)
`end-of-call-report`	Résumé complet de l’appel après raccrochage

Configurez cette URL dans votre dashboard Vapi sous Assistant > Server URL :

https://api.animam.ai/voice/your-slug/events

GET /voice//recordings/

Télécharge un enregistrement d’appel (si l’enregistrement est activé dans Vapi).

curl https://api.animam.ai/voice/your-slug/recordings/call_abc123 \
  -H "Authorization: Bearer ak_your_token" \
  --output call.mp3

Outils pendant les appels vocaux

Tous les outils configurés pour votre tenant fonctionnent pendant les appels :

SUBMIT_FORM — l’agent collecte les infos à l’oral, soumet le formulaire en fin d’appel
BOOK_MEETING — l’agent vérifie les disponibilités et confirme un rendez-vous pendant l’appel
CHECK_AVAILABILITY — l’agent énonce les créneaux disponibles
ESCALATE_TO_HUMAN — l’agent propose de transférer vers un humain

L’agent adapte sa langue à la voix — il énonce les données structurées (dates, prix, adresses) dans un format parlé naturel plutôt que du texte formaté.

Vérifier votre configuration

# Vérifier que la voix est activée
curl https://api.animam.ai/tenants/your-slug \
  -H "Authorization: Bearer ak_your_token" \
  | jq '.voiceEnabled, .voicePhoneNumber'

Appelez ensuite votre numéro. Le firstMessage doit se jouer dans les 2 secondes suivant la connexion.

Limites

En mode managé, un numéro par tenant ; avec votre propre Vapi/plateforme vocale (niveaux 2–3), vous pouvez router autant de numéros que vous voulez
Animam ne termine pas le SIP lui-même — la couche téléphonie/média est toujours la responsabilité de votre orchestrateur vocal (provisioning, qualité audio, latence, fallback)
Le stockage des enregistrements est géré par Vapi, pas par Animam
Le canal voix ne supporte pas les pièces jointes
COLLECT_PAYMENT (Stripe) n’est pas déclenché pendant les appels — l’agent peut décrire les options de paiement mais ne peut pas générer de lien de paiement en cours d’appel

Documentation Index

​Architecture

​Trois façons de connecter la téléphonie

​Niveau 1 — Managé (sans code)

​Niveau 2 — Votre propre Vapi (et votre propre SIP / opérateur)

​Niveau 3 — Votre propre plateforme vocale

​Réglages du tenant

​Champs voiceConfig

​Endpoints

​POST /voice//chat/completions

​POST /voice//events

​GET /voice//recordings/

​Outils pendant les appels vocaux

​Vérifier votre configuration

​Limites

Architecture

Trois façons de connecter la téléphonie

Niveau 1 — Managé (sans code)

Niveau 2 — Votre propre Vapi (et votre propre SIP / opérateur)

Niveau 3 — Votre propre plateforme vocale

Réglages du tenant

Champs voiceConfig

Endpoints

POST /voice//chat/completions

POST /voice//events

GET /voice//recordings/

Outils pendant les appels vocaux

Vérifier votre configuration

Limites