> ## 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.

# Voix (téléphonie Vapi)

> Donnez un numéro de téléphone à votre agent IA — même cerveau, adapté à la voix

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.

<Note>
  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.
</Note>

## 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.

```bash theme={null}
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 :

```bash theme={null}
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/{slug}/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.

```bash theme={null}
# 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/{slug}/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/{slug}/recordings/{callId}

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

```bash theme={null}
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

```bash theme={null}
# 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