Actions de début et de fin d'appel ================================== Chaque appel dispose de deux points d'automatisation. Les **Actions au démarrage** récupèrent des données dans des variables avant que l'agent ne prononce un mot, pour que le message d'accueil connaisse déjà l'appelant. Les **Actions de fin d'appel** poussent le résultat de l'appel, transcription, résumé et variables collectées, vers vos systèmes une fois l'appel terminé. Les deux se configurent dans l'onglet **Initialisation** de l'éditeur d'agent. Actions au démarrage -------------------- Les Actions au démarrage sont des initialiseurs de variables qui s'exécutent **avant le début de la conversation**. Chacun récupère ou génère des données et les affecte à des variables que l'agent peut utiliser dès son premier tour de parole : rechercher l'appelant dans votre CRM par numéro de téléphone, récupérer une commande ou un ticket par ID, ou alimenter un appel de démonstration avec des données de prospect réalistes. ### Configurer les Actions au démarrage 1. Ouvrez l'éditeur d'agent → onglet **Initialisation** 2. Faites défiler jusqu'à la section **Actions au démarrage** 3. Cliquez sur **Ajouter un initialiseur** 4. Choisissez un **Type** et renseignez ses champs 5. Cliquez sur **Enregistrer** ### Types d'initialiseurs TypeDescription **Requête HTTP**Appelle un endpoint externe au démarrage de l'appel et mappe la réponse JSON vers des variables. Voir le détail des champs ci-dessous. **Action connecteur**Exécute une action sur un compte connecté Composio (ex : rechercher un contact dans votre CRM) et mappe les champs du résultat vers des variables. Voir [Connecteurs](https://www.manivox.ai/docs/integrations/composio) pour configurer l'intégration. **Prospect démo**Données de démonstration intégrées, fournies automatiquement par la plateforme, aucune URL ni identifiant requis. Utile pour tester un flux avant de brancher une vraie source de données. Trois autres types d'initialiseurs sont visibles dans l'éditeur mais pas encore actifs : **En-tête SIP**, **Entrée webhook** et **Entrée CSV** (bientôt disponibles). ### Champs de la Requête HTTP ChampDescription **URL**L'URL de votre endpoint. Supporte l'interpolation `{{variable}}` des variables système (ex : `https://api.example.com/{{from_number}}`) **Method**`GET`, `POST`, `PUT`, `PATCH` ou `DELETE` **Headers**Paires clé-valeur. Ajoutez votre en-tête d'auth ici. Les valeurs supportent `{{variable}}`. **Body**Corps brut de la requête. Supporte `{{variable}}` pour la substitution. **Mapping de réponse**Mappe des chemins de la réponse JSON (JSONPath, ex : `$.first_name`) vers des noms de variables. L'agent lit ensuite ces variables comme n'importe quelle autre, avec `{{variable}}` dans le prompt ou `[[variable]]` dans les règles. Les Actions au démarrage s'exécutent avant le message d'accueil : un endpoint lent retarde donc les premiers mots de l'agent. Gardez-les rapides, et réservez **En cas d'erreur → Arrêter l'appel** aux données sans lesquelles le flux ne peut vraiment pas continuer. Actions de fin d'appel ---------------------- Les Actions de fin d'appel sont des requêtes HTTP que votre agent émet après chaque appel terminé, quel que soit le moyen de terminaison. Utilisez-les pour synchroniser les transcriptions vers votre CRM, poster des résumés sur Slack, ou déclencher des workflows dans n'importe quel système externe. ### Fonctionnement Quand un appel atteint un statut terminal (`COMPLETED`), la plateforme met en file un **job d'actions de fin de flux** qui émet chaque requête HTTP configurée en séquence. Le job tourne après la génération du résumé d'appel et des objectifs, donc toutes les variables par-appel sont totalement peuplées quand votre endpoint reçoit la requête. 1. L'appel se termine → résumé et objectifs sont générés 2. La plateforme émet chaque action HTTP configurée dans l'ordre 3. Tous les placeholders `{{variable}}` dans l'URL, les en-têtes et le corps sont remplacés par les valeurs finales des variables de l'appel 4. Votre endpoint reçoit la requête et répond avec `2xx` 5. Une action échouée n'est pas réessayée immédiatement. Un balayage de réconciliation planifié ré-exécute plus tard l'ensemble complet des actions pour tout appel dont la livraison n'a pas été confirmée. Les Actions de fin d'appel ne se déclenchent que sur les appels `COMPLETED` ; les appels qui se terminent en `FAILED`, `NO_ANSWER`, `BUSY` ou `CANCELED` ne les déclenchent pas. **Push vs pull.** Les Actions de fin d'appel **poussent** les données vers votre URL après la fin de l'appel. Si vous voulez plutôt **tirer** à la demande le résumé d'un appel et les variables collectées (ex : un screen-pop CRM lors d'un transfert), utilisez l'[endpoint Handoff](https://www.manivox.ai/docs/api/calls#handoff). ### Configurer les Actions de fin d'appel Les Actions de fin d'appel se configurent par agent dans l'éditeur d'agent : 1. Ouvrez l'éditeur d'agent → onglet **Initialisation** 2. Faites défiler jusqu'à la section **Actions de fin d'appel** 3. Cliquez sur **Ajouter une action** 4. Renseignez le nom de l'action, la méthode HTTP, l'URL, les en-têtes et le corps 5. Cliquez sur **Enregistrer** Chaque action a ces champs : ChampDescription **Name**Étiquette interne pour identifier cette action dans les logs **Method**`POST`, `GET`, `PUT`, `PATCH` ou `DELETE` **URL**L'URL de votre endpoint. Supporte l'interpolation `{{variable}}` (ex : `https://crm.example.com/calls/{{call_id}}`) **Headers**Paires clé-valeur. Ajoutez votre en-tête d'auth ici (ex : `Authorization: Bearer `). Les valeurs supportent `{{variable}}`. **Body**Corps brut de la requête. Utilisez `{{variable}}` pour la substitution ou `[[variable]]` pour envoyer le nom littéral de la variable. Le corps est envoyé tel quel, sans encodage JSON automatique, donc utilisez `Content-Type: application/json` dans les en-têtes pour envoyer du JSON. **On error**`continue`, saute cette action et exécute la suivante. `stop`, abandonne toutes les actions restantes. **Exemple de corps d'action (JSON) :** ``` { "call_id": "{{call_id}}", "caller": "{{from_number}}", "duration_s": "{{duration}}", "summary": "{{summary}}", "transcript": "{{transcript}}", "collected": { "name": "{{caller_name}}", "intent": "{{caller_intent}}" } } ``` ### Variables disponibles Toutes les variables listées ci-dessous sont résolues depuis l'état final de l'appel avant l'émission des requêtes HTTP. VariableTypeDescription `call_id`stringIdentifiant unique de l'appel `from_number`E.164Numéro de l'appelant `to_number`E.164Numéro appelé (celui qui a été composé) `direction`string`INBOUND` ou `OUTBOUND` `duration`integerDurée de l'appel en secondes `agent_name`stringNom d'affichage de l'agent `transcript`stringTranscription complète en texte brut (`User: …\nAgent: …`) `transcript_json`JSON stringTranscription complète sous forme de tableau JSON (inclut les métriques de latence) `summary`stringRésumé d'appel généré par LLM (texte brut) `sentiment`stringSentiment détecté (ex : `positive`, `neutral`, `negative`) `key_topics`stringListe de sujets détectés dans l'appel, séparés par virgules `action_items`stringActions à entreprendre extraites de l'appel, séparées par retour à la ligne `call_summary`JSON stringObjet de résumé complet incluant sentiment, sujets et actions `objectives`JSON stringToutes les évaluations d'objectifs (si configurées sur l'agent) `objectives_collected`JSON stringUniquement les objectifs marqués comme collectés *Toute variable collectée*stringLes variables collectées pendant l'appel (ex : `{{caller_name}}`, `{{account_id}}`) sont également disponibles Si une variable n'est pas définie (ex : `summary` avant la fin du résumé), elle résout à une chaîne vide. Le job attend que les jobs de résumé et d'objectifs se terminent avant de s'exécuter, donc les deux sont peuplés en fonctionnement normal. ### Sécuriser votre endpoint La plateforme n'ajoute pas d'en-tête de signature automatique. Sécurisez votre endpoint avec l'un des patterns standards : - **Bearer token**, ajoutez un en-tête `Authorization: Bearer ` et validez-le côté serveur - **Basic auth**, ajoutez `Authorization: Basic ` - **En-tête personnalisé**, ajoutez n'importe quelle paire nom/valeur (ex : `X-Webhook-Secret: your-secret`) et vérifiez-la dans votre handler - **Liste blanche d'IPs**, autorisez les IPs des serveurs Manivox.ai au niveau de votre pare-feu ### Politique de retry Une Action de fin d'appel échouée n'est **pas réessayée immédiatement**. À la place, un balayage de réconciliation planifié ré-exécute plus tard l'ensemble complet des actions pour tout appel dont la livraison n'a pas été confirmée. Les échecs sont écrits uniquement dans le log applicatif du serveur (`Log::error`) ; ils n'apparaissent **pas** dans le log d'événements de l'enregistrement d'appel. Chaque tentative a un **timeout de 30 secondes**. Votre endpoint doit répondre dans cette fenêtre. Pour un travail long, répondez immédiatement et traitez en arrière-plan : ``` # ✅ Bon, enfilez et répondez immédiatement @app.post("/calls/end") def handle(): data = request.json task_queue.enqueue(process_call, data) # job en arrière-plan return "", 200 # ❌ Mauvais, le traitement bloque la réponse (risque de timeout 30s) @app.post("/calls/end") def handle(): data = request.json sync_to_crm(data) # peut prendre 30s return "", 200 ``` ### Actions multiples Un agent peut avoir plusieurs Actions de fin d'appel. Elles s'exécutent dans l'ordre défini dans l'onglet **Initialisation**. Si une action a `onError: stop` et échoue, la séquence s'interrompt immédiatement et les actions restantes sont sautées. Si elle a `onError: continue` (défaut), l'échec est journalisé et l'exécution continue avec l'action suivante. ``` Action 1 (onError: continue) → POST https://crm.example.com/calls Action 2 (onError: continue) → POST https://slack.example.com/notify Action 3 (onError: stop) → POST https://billing.example.com/billing ``` Les Actions de fin d'appel sont aussi le mécanisme derrière la section **Actions de fin d'appel** dans la page de configuration de l'agent (champ : `end_flow_actions`). Voir [Configuration → Actions de fin d'appel](https://www.manivox.ai/docs/agents/configuration#end-flow-actions) pour les détails de la structure JSON.