Passer un appel transactionnel
Un appel transactionnel part à l'unité, au moment où votre système le décide, vers une personne qui attend une information de votre part : confirmer une réservation, lire un code, prévenir d'un retard, rappeler un rendez-vous. Trois façons d'appeler, du plus simple au plus complet :
| Mode | Ce qui se passe au bout du fil | Ce que vous recevez |
|---|---|---|
| Message lu | Un texte est lu par une voix de synthèse. | L'issue de l'appel (décroché, répondeur, pas de réponse…). |
| Message et touches | Le message demande une réponse au clavier : « tapez 1 pour confirmer ». | L'issue et les touches tapées (digits). |
| Agent vocal IA | Un agent mène une vraie conversation, dans le cadre que vous lui donnez. | L'issue et les réponses que vous avez demandées (result), avec un résumé. |
Réservez cette API aux appels qu'attend la personne appelée. La prospection passe par les campagnes téléphoniques, qui gèrent la liste d'opposition et les plages horaires.
Prérequis
- L'abonnement Campagne téléphonique et au moins un numéro de campagne actif : c'est le numéro présenté à la personne appelée.
- Une clé API secrète dotée de la permission
send_transactional_calls, etview_transactional_messagespour consulter les appels. Voir Authentification. - Des crédits pour les minutes d'appel (et les minutes d'agent, en mode agent).
- Pour le mode agent : un agent vocal créé et publié dans votre compte (Agents IA › Téléphone).
1. Lire un message
curl https://api.metaventus.com/v1/transactional/calls \
-H "X-API-Key: VOTRE_CLE_SECRETE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: retard-livraison-20481" \
-d '{
"to": "+33612345678",
"message": "Bonjour, ici Le Bistrot du Port. Votre commande aura quinze minutes de retard. Merci de votre patience.",
"reference": "commande-20481"
}'
| Champ | Obligatoire | Description |
|---|---|---|
to | oui | Numéro appelé, au format international (+33612345678). Un numéro national est lu comme français. |
message | oui (sauf mode agent) | Le texte lu, 1 000 caractères au plus. Écrivez-le comme il doit être dit : « quinze minutes » plutôt que « 15 min ». |
from | non | Un numéro de campagne actif de votre compte. Sans from, votre premier numéro de campagne. |
voice | non | La voix de synthèse : alloy (par défaut), ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse. |
repeat | non | Nombre de lectures du message, de 1 (par défaut) à 3. Utile pour un code. Sans effet avec gather ou agent. |
record | non | true pour enregistrer l'appel. L'enregistrement s'écoute dans le journal d'appels de Metaventus. |
machine_detection | non | Option facturée : reconnaître un répondeur. Voir Répondeurs. |
if_machine | non | Avec machine_detection : hangup (par défaut) ou leave_message. |
reference | non | Votre identifiant (n° de réservation…), 128 caractères au plus. Renvoyé tel quel, filtrable. |
Réponse 202 Accepted : l'appel est composé. Son issue arrive plus tard, par
webhook ou en consultant le message.
{
"id": "62f2bc4a-ec20-4db2-ada8-32165985a1ed",
"channel": "voice",
"to": "+33612345678",
"from": "+33221858132",
"body": "Bonjour, ici Le Bistrot du Port. Votre commande aura quinze minutes de retard. Merci de votre patience.",
"status": "sent",
"reference": "commande-20481",
"created_at": "2026-11-11T09:00:00Z",
"sent_at": "2026-11-11T09:00:01Z",
"updated_at": "2026-11-11T09:00:00Z"
}
Le message est lu dès que la personne décroche. L'appel se termine à la fin de la lecture.
2. Recueillir une touche
Ajoutez gather : le message est lu, puis la plateforme attend la saisie au clavier.
curl https://api.metaventus.com/v1/transactional/calls \
-H "X-API-Key: VOTRE_CLE_SECRETE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: resa-48213-confirmation" \
-d '{
"to": "+33612345678",
"message": "Bonjour, ici Le Bistrot du Port. Vous avez réservé une table pour quatre samedi à 20 h 30. Tapez 1 pour confirmer, 2 pour annuler.",
"reference": "JT-48213",
"gather": {
"valid_digits": "12",
"replies": {
"1": "Merci, votre table est confirmée. À samedi !",
"2": "C'\''est noté, votre réservation est annulée. Au revoir."
},
"invalid_message": "Je n'\''ai pas compris. Tapez 1 pour confirmer, 2 pour annuler."
}
}'
Champ de gather | Défaut | Description |
|---|---|---|
valid_digits | tous | Les touches acceptées, parmi 0123456789*#. |
min_digits, max_digits | 1, 1 | Longueur de la saisie, jusqu'à 16 chiffres. Au-delà d'un chiffre, la saisie se termine par #, ou par * si # fait partie des touches acceptées. |
max_tries | 2 | Nombre d'essais (1 à 5) : le message est rejoué après une saisie invalide ou un silence. |
timeout_seconds | 8 | Délai d'attente de la saisie, de 1 à 30 secondes. |
invalid_message | — | Phrase lue après une saisie invalide, avant le nouvel essai. |
replies | — | Une phrase par touche, lue juste après la saisie : { "1": "Merci…" }. |
default_reply | — | Phrase lue après toute saisie valide sans réponse dédiée. {digits} y est remplacé par ce qui a été tapé. |
digits_format | digits | Comment {digits} est dit : digits (chiffre par chiffre, pour un code), time (2030 → « 20 h 30 »), number (2030 → « deux mille trente »). |
language | fr | La langue de {digits} lu comme une heure : fr, en, de, es, it, pt, nl, da, sv, fi, pl, ru, ja, ko, zh ou hi (« 20 h 30 », « 8:30 p.m. », « 20:30 Uhr »…). |
Exemple : demander une heure d'arrivée sur 4 chiffres et la relire.
"gather": {
"min_digits": 4,
"max_digits": 4,
"default_reply": "Merci, nous vous attendons à {digits}.",
"digits_format": "time"
}
Une saisie de 2030 fait dire « Merci, nous vous attendons à 20 h 30. », puis l'appel se
termine. Les touches tapées vous reviennent dans digits.
Une seconde saisie après une touche : followups
Une touche peut ouvrir une seconde saisie, avec sa propre consigne : « Tapez 3 pour proposer
un autre horaire », puis « Saisissez l'heure en quatre chiffres ». followups associe la
touche à cette seconde saisie : message (la consigne, obligatoire) et les mêmes champs que
gather (min_digits, max_digits, replies, default_reply, digits_format…). La
language de gather s'applique si la suite n'en précise pas. Un seul niveau : une suite
n'a pas elle-même de followups.
"gather": {
"valid_digits": "123",
"replies": {
"1": "Merci, la réservation est acceptée. Le client est prévenu.",
"2": "C'est noté, la réservation est refusée. Le client est prévenu."
},
"followups": {
"3": {
"message": "Saisissez l'horaire proposé en quatre chiffres, par exemple 2 0 3 0 pour 20 h 30.",
"min_digits": 4,
"max_digits": 4,
"digits_format": "time",
"default_reply": "Merci, nous proposons {digits} au client."
}
}
}
La touche tapée revient dans digits ("3"), la seconde saisie dans followup_digits
("2030"). Si la personne ne tape rien à la seconde saisie, l'issue est no_input.
La phrase finale donnée par votre serveur : reply_url
Pour que la phrase entendue dépende de ce que votre système a enregistré (« C'est noté, le
client est prévenu par SMS » ou « Ce créneau vient d'être pris »), indiquez reply_url
dans gather. À la fin de la saisie, pendant l'appel, la plateforme envoie les touches
à cette adresse et lit, dans le même appel, la phrase que vous renvoyez.
reply_urldoit être l'une de vos adresses webhook actives (voir Événements). La requête est signée avec son secret, comme les webhooks : en-têtesX-Metaventus-Signature,X-Metaventus-Timestamp,X-Metaventus-Event: voice.input. Une adresse non déclarée est refusée à la demande d'appel (422 reply_url_not_registered).- Votre serveur a 5 secondes pour répondre
200avec{"reply": "…"}(1 000 caractères au plus) ; la personne patiente en silence pendant ce temps. Comptez environ une seconde de plus pour que la phrase soit prononcée. - Sans réponse à temps, en cas d'erreur ou avec une
replyvide, la plateforme lit la réponse prévue dansrepliesoudefault_reply. Prévoyez donc toujours une phrase de secours.
{
"id": "0b8a6f3e-5d0c-4a43-9a51-1c6a2e7d9f10",
"type": "voice.input",
"created_at": "2026-11-12T18:42:07Z",
"data": {
"id": "62f2bc4a-ec20-4db2-ada8-32165985a1ed",
"channel": "voice",
"to": "+33235000000",
"from": "+33221858132",
"reference": "JT-48213",
"digits": "3",
"followup_digits": "2030"
}
}
Réponse attendue :
{ "reply": "Merci, nous proposons 20 h 30 au client. Il est prévenu par SMS et par e-mail." }
L'issue de l'appel vous parvient ensuite, comme toujours, par l'événement voice.delivered
(ou voice.failed).
3. Confier l'appel à un agent vocal
Avec agent, un agent vocal IA mène la conversation : il présente l'objet de l'appel, répond
aux questions, gère les hésitations et les changements d'avis, puis vous rend les réponses
que vous avez demandées, sous une forme que votre système peut traiter.
curl https://api.metaventus.com/v1/transactional/calls \
-H "X-API-Key: VOTRE_CLE_SECRETE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: resa-48213-agent" \
-d '{
"to": "+33612345678",
"reference": "JT-48213",
"machine_detection": true,
"if_machine": "leave_message",
"message": "Bonjour, ici Le Bistrot du Port. Nous vous appelions pour confirmer votre réservation de samedi à 20 h 30. Vous pouvez la gérer depuis le SMS de réservation. Bonne journée.",
"agent": {
"id": "bbcc3932-f819-4517-9135-760a4c3ea665",
"context": "Client : M. Dupont. Restaurant : Le Bistrot du Port, à Rouen. Réservation : samedi 15 novembre 2026 à 20 h 30, pour 4 personnes. Référence : JT-48213.",
"first_message": "Bonjour, ici l'\''assistante du Bistrot du Port. Je vous appelle au sujet de votre réservation.",
"result_fields": [
{
"name": "decision",
"type": "enum",
"values": ["confirmed", "cancelled", "reschedule_requested", "no_decision", "wrong_person"],
"required": true,
"description": "La décision du client : confirmed (il confirme), cancelled (il annule), reschedule_requested (il veut changer d'\''horaire), no_decision (il ne se prononce pas), wrong_person (ce n'\''est pas la bonne personne)."
},
{ "name": "new_date", "type": "date", "description": "Seulement si reschedule_requested : le jour souhaité." },
{ "name": "new_time", "type": "time", "description": "Seulement si reschedule_requested : l'\''heure souhaitée." },
{ "name": "party_size", "type": "number", "description": "Le nombre de personnes, seulement s'\''il change." },
{ "name": "comment", "type": "text", "description": "Toute précision utile donnée par le client (allergie, retard prévu…)." }
]
}
}'
Champ de agent | Obligatoire | Description |
|---|---|---|
id | oui | L'identifiant d'un agent vocal publié de votre compte. Sa voix, sa langue, sa documentation et son rôle d'appel sortant s'appliquent. |
context | oui | Ce que l'agent doit savoir et faire pour cet appel : qui il appelle, à quel sujet, avec quelles données (date, heure, montant…), et toute consigne propre à l'appel. 4 000 caractères au plus. |
first_message | non | Sa première phrase, dite dès que la personne décroche (1 000 caractères au plus). Sans elle, celle prévue pour ses appels sortants, sinon il se présente lui-même. |
result_fields | non | Les réponses à vous rendre, 15 champs au plus (voir ci-dessous). |
Avec agent, message devient facultatif : c'est le texte déposé sur un répondeur.
gather et repeat ne s'utilisent pas.
Les réponses attendues : result_fields
Chaque champ décrit une réponse que l'agent doit obtenir de la personne :
| Propriété | Description |
|---|---|
name | Le nom du champ dans result : minuscules, chiffres et _, 40 caractères au plus. summary est réservé. |
type | text (par défaut), boolean, number, enum, date (rendu AAAA-MM-JJ) ou time (rendu HH:MM, sur 24 heures). |
values | Pour enum : les valeurs possibles (deux au moins). L'agent en choisit une. |
required | true : l'agent doit la renseigner (avec la valeur prévue pour « pas de réponse » si vous en avez une). |
description | Ce que le champ doit contenir. C'est la consigne de l'agent : soyez précis, donnez le sens de chaque valeur d'un enum. |
L'agent ne renseigne jamais un champ que la personne n'a pas donné : il reste absent de
result. result contient toujours un summary, un résumé de l'appel en une phrase,
dans la langue de la conversation.
"result": {
"decision": "reschedule_requested",
"new_date": "2026-11-13",
"new_time": "20:00",
"summary": "Le client demande à déplacer sa réservation au vendredi 13 novembre 2026 à 20 h ; le restaurant doit vérifier et confirmer par SMS."
}
Si la personne change d'avis en cours d'appel, l'agent met ses réponses à jour : vous ne recevez que la version finale.
Ce que fait l'agent
- Il parle dès que la personne décroche : pas de silence après le « allô ».
- Il reste sur l'objet de l'appel. Pour toute autre demande, il indique que votre équipe recontactera la personne.
- Il ne promet que ce que votre
contextlui permet. Pour un changement d'horaire, il note la demande et annonce une confirmation ultérieure, sans garantir de disponibilité. - S'il ne s'agit pas de la bonne personne, il s'excuse sans rien dévoiler de l'objet de l'appel.
- Il conclut par un récapitulatif et une formule de fin, puis raccroche.
Rédiger un bon context
- Donnez les faits de l'appel, pas le rôle de l'agent : son rôle se règle une fois pour toutes dans sa fiche (Agents IA › Téléphone › Appel sortant).
- Écrivez les dates et heures complètes (« samedi 15 novembre 2026 à 20 h 30 ») : l'agent connaît la date du jour et en déduit « demain » ou « vendredi prochain ».
- Dites ce qu'il peut accepter ou non : « Le restaurant est complet dimanche », « Ne proposez pas de remboursement ».
- Ne mettez dans
contextque ce que la personne appelée a le droit d'entendre.
Répondeurs et messageries
Un répondeur décroche comme une personne. Deux réglages décident de ce qui se passe :
| Réglage | Message lu ou touches | Agent vocal |
|---|---|---|
Sans machine_detection | Le message est lu dès le décroché, à la personne comme au répondeur. Issue : answered. | L'agent parle dès le décroché. S'il reconnaît une messagerie, il ne pose aucune question : il laisse un message bref (votre message s'il est fourni), puis raccroche. Issue : voicemail_left, ou machine s'il n'a rien pu dire. |
machine_detection: true | La plateforme attend son verdict (2 à 3 secondes) avant de lire le message. Sur un répondeur : if_machine: hangup raccroche (issue machine), leave_message dépose message après le bip (issue voicemail_left). | L'agent parle dès le décroché, et la détection continue pendant ce temps. Sur un répondeur, l'agent est coupé, puis if_machine s'applique comme pour un message. Ses quelques secondes ne sont pas décomptées en minutes d'agent. |
Nous recommandons machine_detection pour les appels en mode agent : l'issue est fiable, et
aucune minute d'agent n'est consommée sur une messagerie.
Suivre l'appel
Par webhook
Abonnez une adresse de votre serveur aux événements des appels (voir Événements) :
| Événement | Quand |
|---|---|
voice.sent | L'appel est composé. |
voice.delivered | Le message a été entendu : la personne a décroché (answered) ou le message a été déposé sur son répondeur (voicemail_left). |
voice.failed | L'appel n'a pas abouti : voir outcome. |
{
"id": "8810d4d4-7933-4e3d-8dd6-281cc280c13b",
"type": "voice.delivered",
"created_at": "2026-11-11T09:01:05Z",
"data": {
"id": "62f2bc4a-ec20-4db2-ada8-32165985a1ed",
"channel": "voice",
"to": "+33612345678",
"from": "+33221858132",
"status": "delivered",
"outcome": "answered",
"digits": "",
"duration_seconds": 57,
"reference": "JT-48213",
"result": {
"decision": "cancelled",
"summary": "Le client annule sa réservation du samedi 15 novembre 2026 à 20 h 30 pour 4 personnes."
},
"sent_at": "2026-11-11T09:00:01Z",
"delivered_at": "2026-11-11T09:01:05Z"
}
}
En consultant l'appel
curl https://api.metaventus.com/v1/transactional/messages/62f2bc4a-ec20-4db2-ada8-32165985a1ed \
-H "X-API-Key: VOTRE_CLE_SECRETE"
La réponse porte les mêmes champs : status, outcome, digits, followup_digits,
duration_seconds et result. Les appels se listent avec les SMS et les e-mails sur
GET /v1/transactional/messages (filtres status, reference, to).
Issues
outcome | Signification | status |
|---|---|---|
answered | La personne a décroché et entendu le message, ou parlé à l'agent. | delivered |
voicemail_left | Le message a été déposé sur le répondeur. | delivered |
no_input | La personne a décroché mais n'a tapé aucune touche valide (mode touches). | failed |
machine | Un répondeur ou un serveur vocal a répondu, et rien n'a été déposé. | failed |
no_answer | Personne n'a décroché. | failed |
busy | La ligne était occupée. | failed |
rejected | L'appel a été refusé. | failed |
failed | L'appel n'a pas pu aboutir. | failed |
Pour un appel en échec, error_code reprend l'issue et error_message l'explique.
duration_seconds compte depuis le décroché.
Facturation
- Minutes d'appel : décomptées à la minute entamée, au tarif de la destination, comme vos campagnes téléphoniques (par exemple 0,06 € HT la minute vers un fixe français). Un appel sans décroché n'est pas facturé.
- Détection de répondeur (
machine_detection) : 0,01 € HT par appel où elle est demandée. - Agent vocal : les minutes où l'agent parle à une personne sont décomptées en minutes d'agent, en plus des minutes d'appel, au tarif de l'agent vocal de votre compte (à l'usage ou depuis un pack d'heures, dans Paramètres › Crédits).
Avant de composer, la plateforme vérifie que vos crédits couvrent au moins une minute vers
ce numéro ; sinon l'appel est refusé (402 insufficient_credits) sans rien facturer.
Appels simultanés
Vos appels transactionnels partagent les appels simultanés de votre offre Campagne
téléphonique avec vos campagnes. Quand ils sont tous occupés, un nouvel appel est refusé
(429 concurrent_limit_reached) : réessayez quelques secondes plus tard, avec la même
Idempotency-Key. Pour en avoir davantage, ajoutez l'option « Appels simultanés » à votre
abonnement.
Ne jamais appeler deux fois
Passez un en-tête Idempotency-Key propre à chaque appel. Si votre requête expire et que
vous la rejouez avec la même clé, le premier appel est renvoyé avec un 200 et l'en-tête
Idempotent-Replayed: true : personne n'est rappelé, rien n'est refacturé. Réutiliser une clé
pour un autre appel est refusé (422 idempotency_key_reused).
Refus
Un appel refusé n'est ni composé ni facturé. Le corps porte un code stable et une
phrase explicative dans error.
| Statut | code | Cause | Conduite à tenir |
|---|---|---|---|
400 | invalid_to, invalid_message, message_too_long, invalid_reference, invalid_if_machine | Requête invalide | Corriger |
400 | machine_detection_required | if_machine sans machine_detection | Ajouter machine_detection: true |
400 | invalid_call | gather ou agent invalide (le message dit quel champ) | Corriger |
400 | invalid_reply_url | gather.reply_url n'est pas une adresse https:// | Corriger |
422 | reply_url_not_registered | gather.reply_url n'est pas une de vos adresses webhook actives | Déclarer l'adresse, ou corriger |
402 | insufficient_credits | Crédits insuffisants pour une minute vers ce numéro | Recharger, puis réessayer |
403 | subscription_required | Pas d'abonnement Campagne téléphonique | Souscrire |
422 | no_campaign_number | Aucun numéro de campagne actif | Ajouter un numéro de campagne |
422 | from_not_allowed | from n'est pas un numéro de campagne actif du compte | Corriger from ou le retirer |
422 | idempotency_key_reused | Clé déjà utilisée pour un autre appel | Nouvelle clé |
429 | concurrent_limit_reached | Appels simultanés de l'offre tous occupés | Réessayer dans un instant |
502 | call_not_placed | L'appel n'a pas pu partir | Réessayer avec la même Idempotency-Key |
503 | temporarily_unavailable | Incident passager | Réessayer avec la même Idempotency-Key |
Sans code : depuis un scénario
Les scénarios d'automatisation de Metaventus proposent l'action Passer un appel : message lu et saisie de touches, avec les mêmes options, déclenchés par un événement de votre compte (rendez-vous pris, commande, changement d'étape…).