Aller au contenu principal

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 :

ModeCe qui se passe au bout du filCe que vous recevez
Message luUn texte est lu par une voix de synthèse.L'issue de l'appel (décroché, répondeur, pas de réponse…).
Message et touchesLe message demande une réponse au clavier : « tapez 1 pour confirmer ».L'issue et les touches tapées (digits).
Agent vocal IAUn 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, et view_transactional_messages pour 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"
}'
ChampObligatoireDescription
toouiNuméro appelé, au format international (+33612345678). Un numéro national est lu comme français.
messageoui (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 ».
fromnonUn numéro de campagne actif de votre compte. Sans from, votre premier numéro de campagne.
voicenonLa voix de synthèse : alloy (par défaut), ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse.
repeatnonNombre de lectures du message, de 1 (par défaut) à 3. Utile pour un code. Sans effet avec gather ou agent.
recordnontrue pour enregistrer l'appel. L'enregistrement s'écoute dans le journal d'appels de Metaventus.
machine_detectionnonOption facturée : reconnaître un répondeur. Voir Répondeurs.
if_machinenonAvec machine_detection : hangup (par défaut) ou leave_message.
referencenonVotre 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 gatherDéfautDescription
valid_digitstousLes touches acceptées, parmi 0123456789*#.
min_digits, max_digits1, 1Longueur 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_tries2Nombre d'essais (1 à 5) : le message est rejoué après une saisie invalide ou un silence.
timeout_seconds8Dé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_formatdigitsComment {digits} est dit : digits (chiffre par chiffre, pour un code), time (2030 → « 20 h 30 »), number (2030 → « deux mille trente »).
languagefrLa 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_url doit ê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êtes X-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 200 avec {"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 reply vide, la plateforme lit la réponse prévue dans replies ou default_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 agentObligatoireDescription
idouiL'identifiant d'un agent vocal publié de votre compte. Sa voix, sa langue, sa documentation et son rôle d'appel sortant s'appliquent.
contextouiCe 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_messagenonSa 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_fieldsnonLes 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
nameLe nom du champ dans result : minuscules, chiffres et _, 40 caractères au plus. summary est réservé.
typetext (par défaut), boolean, number, enum, date (rendu AAAA-MM-JJ) ou time (rendu HH:MM, sur 24 heures).
valuesPour enum : les valeurs possibles (deux au moins). L'agent en choisit une.
requiredtrue : l'agent doit la renseigner (avec la valeur prévue pour « pas de réponse » si vous en avez une).
descriptionCe 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 context lui 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 context que 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églageMessage lu ou touchesAgent vocal
Sans machine_detectionLe 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: trueLa 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énementQuand
voice.sentL'appel est composé.
voice.deliveredLe message a été entendu : la personne a décroché (answered) ou le message a été déposé sur son répondeur (voicemail_left).
voice.failedL'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​

outcomeSignificationstatus
answeredLa personne a décroché et entendu le message, ou parlé à l'agent.delivered
voicemail_leftLe message a été déposé sur le répondeur.delivered
no_inputLa personne a décroché mais n'a tapé aucune touche valide (mode touches).failed
machineUn répondeur ou un serveur vocal a répondu, et rien n'a été déposé.failed
no_answerPersonne n'a décroché.failed
busyLa ligne était occupée.failed
rejectedL'appel a été refusé.failed
failedL'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.

StatutcodeCauseConduite à tenir
400invalid_to, invalid_message, message_too_long, invalid_reference, invalid_if_machineRequête invalideCorriger
400machine_detection_requiredif_machine sans machine_detectionAjouter machine_detection: true
400invalid_callgather ou agent invalide (le message dit quel champ)Corriger
400invalid_reply_urlgather.reply_url n'est pas une adresse https://Corriger
422reply_url_not_registeredgather.reply_url n'est pas une de vos adresses webhook activesDéclarer l'adresse, ou corriger
402insufficient_creditsCrédits insuffisants pour une minute vers ce numéroRecharger, puis réessayer
403subscription_requiredPas d'abonnement Campagne téléphoniqueSouscrire
422no_campaign_numberAucun numéro de campagne actifAjouter un numéro de campagne
422from_not_allowedfrom n'est pas un numéro de campagne actif du compteCorriger from ou le retirer
422idempotency_key_reusedClé déjà utilisée pour un autre appelNouvelle clé
429concurrent_limit_reachedAppels simultanés de l'offre tous occupésRéessayer dans un instant
502call_not_placedL'appel n'a pas pu partirRéessayer avec la même Idempotency-Key
503temporarily_unavailableIncident passagerRé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…).