You are viewing the French site, but your language preference is set to English. Switch to English site →

Menu

Expand
Rate this page:

TwiML™ pour Programmable Voice

Qu'est-ce que TwiML ?

TwiML (Twilio Markup Language, ou langage de balisage de Twilio) est un ensemble d'instructions vous permettant d'indiquer à Twilio quoi faire lorsque vous recevez un appel, un SMS ou un fax entrant.

Fonctionnement de TwiML

Lorsque quelqu'un appelle l'un de vos numéros Twilio, Twilio recherche l'URL associée à ce numéro de téléphone et lui envoie une requête. Twilio lit ensuite les instructions TwiML hébergées sur cette URL pour déterminer la marche à suivre, qu'il s'agisse d'enregistrer l'appel, de lire un message pour l'appelant ou d'inviter l'appelant à appuyer sur les chiffres de son clavier.

TwiML est essentiellement un document XML avec des balises spéciales définies par Twilio pour vous aider à créer votre application Programmable Voice.

Vous ne passez pas d'appels téléphoniques ? TwiML alimente bien plus que Twilio Programmable Voice ; consultez la documentation sur l'utilisation de TwiML avec Programmable SMS et Programmable Fax.

Le code suivant affiche « Hello, world! » lorsqu'un utilisateur compose un numéro Twilio configuré avec ce TwiML :

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Hello, world!</Say>
</Response>

Vous pouvez toujours renvoyer du langage TwiML brut à partir du langage de votre choix, ou utiliser ‌les librairies Twilio afin de créer automatiquement des langages TwiML valides pour vous. Dans l'exemple de code ci-dessous, basculez vers votre langage de programmation Web préféré pour voir à quoi ressemble le langage TwiML ci-dessus en utilisant la librairie.

        
        
        

        Consultez notre court tutoriel sur la réponse aux appels téléphoniques entrants, disponible dans nos six librairies associées aux langages pris en charge. Vous pouvez également tirer parti de Twilio TwiML Bins, notre solution sans serveur qui vous permet d'écrire des langages TwiML que Twilio hébergera pour vous afin de pouvoir rapidement créer un prototype de solution sans faire tourner le moindre serveur Web.

        Les appels sortants (appels d'un numéro Twilio vers un numéro externe) sont contrôlés de la même manière à l'aide de TwiML. Lorsque vous lancez un appel sortant avec l'API Twilio, Twilio demande ensuite à votre TwiML d'apprendre à gérer l'appel.

        Twilio n'exécute qu'un seul document TwiML à la fois pour l'appelant, mais de nombreux documents TwiML peuvent être reliés entre eux pour créer des applications vocales interactives complexes.

        Éléments TwiML

        Dans la section TwiML, les éléments XML sont divisés en trois groupes : l'élément <Response>, les verbes et les noms.

        Les éléments TwiML (verbes et noms) ont des noms sensibles à la casse. Par exemple, l'utilisation de <say> au lieu de <Say> entraînera une erreur. Les noms d'attribut sont également sensibles à la casse et à la concaténation.

        Vous pouvez utiliser des commentaires XML librement dans votre langage TwiML ; l'interprèteur les ignore.

        L'élément <Response>

        Dans toutes les réponses TwiML à une requête Twilio, vous devez imbriquer tous les éléments verbe dans <Response>, l'élément racine du balisage XML de Twilio :

        <?xml version="1.0" encoding="UTF-8"?>
        <Response>
            <Say>
              Ce message doit être imbriqué dans un élément Response
              pour que Twilio le dise à votre appelant.
            </Say>
        </Response>

        Toute autre structure est considérée comme non valide.

        Verbes TwiML pour Programmable Voice

        Les verbes TwiML indiquent à Twilio les mesures à prendre lors d'un appel donné. Pour cette raison, la plupart des éléments d'un document TwiML sont des verbes TwiML. Les noms de verbes sont sensibles à la casse, tout comme les noms de leurs attributs.

        Vous pouvez utiliser différentes combinaisons de verbes TwiML pour créer toutes sortes d'applications vocales interactives. Les verbes TwiML principaux pour Programmable Voice sont les suivants :

        • <Say> - Lire le texte à l'appelant
        • <Play> - Lire un fichier audio à l'appelant
        • <Dial> - Ajouter un autre correspondant à l'appel
        • <Record> - Enregistrer la voix de l'appelant
        • <Gather> - Collecter les chiffres que l'appelant saisit sur son clavier

        Les verbes suivants peuvent être utilisés pour contrôler le flux de votre appel :

        • <Hangup> - Raccrocher
        • <Enqueue> - Ajouter l'appelant à une file d'attente d'appelants
        • <Leave> - Supprimer un appelant d'une file d'attente d'appelants
        • <Pause> - Attendre avant d'exécuter d'autres instructions
        • <Redirect> - Rediriger le flux d'appels vers un autre document TwiML
        • <Refer> - Twilio lance SIP REFER vers l'infrastructure de communication IP
        • <Reject> - Refuser un appel entrant sans être facturé

        Les noms suivants offrent des fonctionnalités avancées :

        • <Autopilot> - Créer un SVI conversationnel basé sur l'IA

        Dans certains cas, l'interpréteur TwiML peut ne pas atteindre les verbes d'un document TwiML, car le flux de contrôle a été transmis à un autre document. Cela se produit généralement lorsque l'attribut action d'un verbe est défini.

        Par exemple, si un verbe <Say> est suivi de <Redirect>, puis d'un autre <Say>, le deuxième <Say> est inaccessible, car <Redirect> transfère le contrôle total d'un appel au TwiML à une autre URL.

        Noms TwiML

        Un nom TwiML décrit les numéros de téléphone et les ressources API sur lesquels vous souhaitez agir. En fait, un nom TwiML correspond à tout ce qui est imbriqué dans un verbe qui n'est pas un verbe même : c'est l'élément sur lequel le verbe agit.

        Les noms TwiML ne sont généralement que du texte. Cependant, comme dans le cas de <Dial> avec ses noms <Number> et <Conference>, il arrive parfois qu'il y ait des éléments XML imbriqués qui sont des noms.

        La requête de Twilio à votre application

        Lorsqu'une personne effectue un appel entrant vers l'un de vos numéros de téléphone Twilio, Twilio doit demander à TwilML d'obtenir des instructions de votre application pour traiter l'appel.

        Vous pouvez configurer votre numéro de téléphone Twilio pour qu'il pointe vers l'URL de votre application en vous rendant dans la section des numéros de téléphone de la console. Sélectionnez votre numéro de téléphone, puis faites défiler jusqu'à la section « Voice & Fax » (Synthèse vocale et télécopie) pour définir un webhook, un TwiML Bin ou une fonction Twilio pour que Twilio envoie cette requête HTTP lorsqu'un appel arrive :

        Configure webhook on phone number for voice

        Twilio effectue sa requête via HTTP, soit sous forme d'éléments GET ou POST, comme pour demander une page Web dans votre navigateur ou envoyer un formulaire.

        Twilio ne peut pas mettre en cache les éléments POST. Si vous souhaitez que Twilio mette en cache des pages TwiML statiques, vous devez demander à Twilio d'envoyer des requêtes à votre application à l'aide de GET.

        En incluant les paramètres et les valeurs dans sa requête, Twilio envoie des données à votre application sur lesquelles vous pouvez agir avant de répondre.

        Paramètres de requête

        Twilio envoie toujours les paramètres suivants lorsqu'il envoie une requête à votre application pour récupérer des instructions sur la façon de traiter un appel.

        Ils seront envoyés sous forme de paramètres POST ou de paramètres de requête URL, selon la méthode HTTP que vous avez configurée.

        Paramètre Description
        CallSid Un identifiant unique pour cet appel, généré par Twilio.
        AccountSid L'identifiant de votre compte Twilio. Il comporte 34 caractères et commence toujours par les lettres AC.
        À partir de

        Numéro de téléphone ou identifiant client du correspondant qui a lancé l'appel.

        Les numéros de téléphone sont formatés avec un « + » et un code pays, par exemple +16175551212 (format E.164). Les identifiants du client commencent par le schéma URI client: par exemple, lors d'un appel d'un client nommé « Charlie », le paramètre From (De) sera client:charlie.

        Numéro de téléphone ou identifiant client du correspondant appelé.

        Les numéros de téléphone sont formatés avec un « + » et un code pays, par exemple +16175551212 (format E.164). Les identifiants du client commencent par le schéma URI client: par exemple, lors d'un appel d'un client nommé « Joey », le paramètre To (À) sera client:joey.

        CallStatus

        Un statut descriptif de l'appel.

        La valeur est l'une des suivantes : queued (file d'attente), ringing (sonnerie), in-progress (en cours), completed (terminé), busy (occupé), failed (échec) ou no-answer (sans réponse). Reportez-vous à la section CallStatus ci-dessous pour plus de détails.

        ApiVersion

        La version de l'API Twilio utilisée pour gérer cet appel.

        Pour les appels entrants, cela est déterminé par la version de l'API définie sur le numéro appelé. Pour les appels sortants, il s'agit de la version utilisée par la requête d'API REST de l'appel sortant.

        Direction

        Une chaîne décrivant la direction de l'appel :

        inbound pour les appels entrants

        outbound-api pour les appels initiés via l'API REST

        outbound-dial pour les appels initiés par un verbe <Dial>.

        ForwardedFrom

        Ce paramètre est défini uniquement lorsque Twilio reçoit un appel renvoyé, mais sa valeur dépend de l'opérateur de l'appelant, y compris les informations lors du renvoi.

        Tous les opérateurs ne prennent pas en charge la transmission de ces informations.

        CallerName Ce paramètre est défini lorsque le paramètre IncomingPhoneNumber qui a reçu l'appel a sa valeur VoiceCallerIdLookup définie sur true (0,01 $ par recherche).
        ParentCallSid

        Un identifiant unique pour l'appel qui a créé ce tronçon.

        Ce paramètre n'est pas transmis s'il s'agit du premier tronçon d'un appel.

        Twilio tente également de rechercher des données géographiques en fonction des numéros de téléphone To (À) et From (De). Sous réserve de disponibilité, Twilio envoie les paramètres suivants avec sa requête :

        Paramètre Description
        FromCity La ville de l'appelant
        FromState L'état ou la province de l'appelant
        FromZip Le code postal de l'appelant
        FromCountry Le pays de l'appelant
        ToCity La ville du correspondant appelé
        ToState L'état ou la province du correspondant appelé
        ToZip Le code postal du correspondant appelé
        ToCountry Le pays du correspondant appelé

        Twilio fournira les paramètres répertoriés ci-dessus lorsqu'il crée une requête pour votre application afin de récupérer des instructions sur la façon de traiter un appel. Cela peut se produire lorsqu'un appel entrant arrive sur votre numéro Twilio, ou après qu'un verbe TwiML a été exécuté et que vous avez fourni une URL action où Twilio peut récupérer l'ensemble d'instructions suivant. En fonction de ce qui se passe lors d'un appel, d'autres variables peuvent également être envoyées.

        Par exemple, lorsque Twilio reçoit un SIP, il envoie des paramètres supplémentaires à votre application Web : vous trouverez la liste des paramètres envoyés avec un SIP dans « SIP and TwiML interaction » (Interaction SIP et TwiML).

        Dans certains cas, Twilio envoie une demande qui ne contient pas tous les paramètres ci-dessus. Par exemple, si vous avez fourni une URL statusCallback dans un nom TwiML tel que <VirtualAgent> ou <Pay>, la requête de Twilio à votre application ne contiendra pas tous les paramètres répertoriés ci-dessus, car ils peuvent ne pas tous être pertinents pour le rappel de statut particulier. Dans ce cas, vous pouvez trouver les paramètres attendus dans la documentation spécifique du verbe TwiML.

        Valeurs CallStatus

        Voici les valeurs possibles pour le paramètre CallStatus. Ces valeurs s'appliquent également au paramètre DialCallStatus, qui est envoyé avec des requêtes HTTP à une URL d'action <Dial>.

        Statut Description
        queued (file d'attente) L'appel est prêt et en attente avant de sortir.
        ringing (sonnerie) L'appel sonne actuellement.
        in-progress (en cours) L'appel a reçu une réponse et est en cours.
        completed (terminé) L'appel a été pris et s'est terminé normalement.
        busy (occupé) L'appelant a reçu un signal occupé.
        failed (échec) L'appel n'a pas pu être terminé une fois composé, probablement parce que le numéro de téléphone n'existait pas.
        no-answer (sans réponse) L'appel s'est terminé sans réponse.
        canceled (annulé) L'appel a été annulé via l'API REST pendant la mise en file d'attente ou la sonnerie.

        Mettre fin à l'appel : requêtes de rappel

        Après avoir reçu un appel, sollicité TwiML dans votre application, l'avoir traité et finalement mis fin à l'appel, Twilio effectue une requête HTTP asynchrone vers l'URL StatusCallback configurée pour le numéro Twilio qui a été appelé.

        Vous devez fournir explicitement cette URL à votre application dans le paramètre StatusCallback de chaque message pour lequel vous souhaitez obtenir des rappels de statut. Le langage TwiML brut se présente comme suit :

        <?xml version="1.0" encoding="UTF-8"?>
        <Response>
            <Dial>
                <Number
                 statusCallbackEvent="initiated ringing answered completed"
                 statusCallback="https://myapp.com/calls/events"
                 statusCallbackMethod="POST">
                    +12316851234
                </Number>
            </Dial>
        </Response>
        

        L'exemple de code ci-dessous montre comment définir votre URL StatusCallback avec du TwiML simple ou à l'aide de la librairie de votre choix :

              
              
              

              En fournissant une URL StatusCallback pour votre numéro Twilio et en capturant cette demande, vous pouvez déterminer quand un appel se termine et recevoir des informations sur l'appel. Veuillez noter que les URL non relatives doivent contenir un nom d'hôte valide, et que les underscores ne sont pas autorisés.

              Paramètres de requête StatusCallback

              Lorsque Twilio envoie des paramètres à votre application dans une requête asynchrone à l'URL StatusCallback, ils incluent les mêmes paramètres transmis dans une requête TwiML synchrone.

              La requête de rappel de statut transmet également les paramètres supplémentaires suivants :

              Paramètre Description
              CallDuration La durée en secondes de l'appel qui vient d'être terminé.
              RecordingUrl L'URL de l'audio enregistré de l'appel téléphonique. Ce paramètre est inclus uniquement si Record=true est défini dans la requête d'API REST et n'inclut pas les enregistrements de <Dial> ou <Record>.
              RecordingSid L'ID unique de l'enregistrement de cet appel.
              RecordingDuration La durée de l'enregistrement audio (en secondes).

              Formats de données

              Numéros de téléphone

              Tous les numéros de téléphone dans les requêtes de Twilio sont au format E.164 si possible. Par exemple, (231) 685-1234 apparaît sous la forme « +12316851234 ». Cependant, il arrive que Twilio ne puisse pas normaliser un ID d'appelant entrant au format E.164. Dans ces situations, Twilio signale la chaîne d'ID d'appelant brute.

              Dates et heures

              Toutes les dates et heures des requêtes de Twilio sont alignées sur l'heure GMT au format RFC 2822. Par exemple, 6:13 PM (heure du Pacifique) August 19th (19 Août), 2010 serait « Fri, 20 Aug 2010 01:13:42 +0000 »

              Twilio est un client HTTP au comportement adéquat

              Twilio se comporte comme un navigateur Web lorsque vous effectuez des requêtes HTTP vers des URL :

              • Cookies : Twilio accepte les cookies HTTP et les inclut dans chaque requête, comme dans un navigateur Web normal.
              • Redirections : Twilio suit les redirections HTTP (codes de statut HTTP 301, 307, etc.), tout comme un navigateur Web normal. Twilio prend en charge un maximum de 10 redirections avant de mettre la requête en échec avec le code d'erreur 11215.
              • Mise en cache : Twilio met en cache les fichiers lorsque les en-têtes HTTP le permettent (via ETag et les en-têtes de dernière modification) et lorsque la méthode HTTP est GET, comme dans un navigateur Web normal.

              Twilio comprend les types MIME

              Twilio fait ce qu'il faut lorsque votre application répond avec différents types MIME :

              Type MIME Comportement
              texte/xml, application/xml, texte/html Twilio interprète le document renvoyé comme un ensemble d'instructions XML (que nous appelons TwiML). Il s'agit de la réponse la plus couramment utilisée.
              différents types audio Twilio lit le fichier audio à l'appelant, puis raccroche. Reportez-vous à la documentation <Play> pour connaître les types MIME pris en charge.
              text/plain Twilio lit le contenu du texte à voix haute pour l'appelant, puis raccroche.

              Réponse à Twilio

              Dans votre réponse à la requête de Twilio à votre URL configurée, vous pouvez indiquer à Twilio ce qu'il faut faire lors d'un appel.

              Fonctionnement de l'interpréteur TwiML

              Lorsque votre application répond à une requête Twilio avec XML, Twilio exécute votre document via l'interpréteur Twilio. Pour simplifier les choses, l'interpréteur TwiML ne comprend que les quelques éléments XML spécialement nommés qui composent TwiML : <Response>, les verbes et les noms.

              L'interpréteur commence en haut de votre document TwiML et exécute les instructions (verbes) dans l'ordre de haut en bas.

              L'extrait de code suivant indique « Hello World » à l'appelant avant de lire Cowbell.mp3 pour l'appelant, puis de raccrocher.

              <?xml version="1.0" encoding="UTF-8"?>
              <Response> 
                  <Say>Hello, World!</Say>
                  <Play>https://api.twilio.com/Cowbell.mp3</Play>
              </Response>
              

              Tout comme avec tous les fichiers TwiML, vous pouvez utiliser les bibliothèques d'aide pour jouer de la musique à un appelant. Incluez l'attribut loop pour demander à Twilio de mettre cet enregistrement en boucle 10 fois (ou jusqu'à ce que l'appelant raccroche) :

                    
                    
                    

                    Rappels de statut dans votre réponse

                    Les rappels de statut ne contrôlent pas le flux d'appels, il n'est donc pas nécessaire de renvoyer TwiML. Si vous répondez, utilisez le code de statut 204 Aucun contenu ou 200 OK avec le type de contenu : texte/xml et un verbe <Response/> dans le corps. Une mauvaise réponse entraînera des avertissements dans le débogueur.

                    Et ensuite ?

                    Approfondissez pour en savoir plus sur les différents verbes TwiML que vous utiliserez avec Twilio Programmable Voice, comme <Dial> pour connecter un appel ou <Gather> pour la reconnaissance vocale et la collecte des touches activées par l'utilisateur. Vous trouverez les liens vers tous les documents de référence ci-dessus.

                    Vous pouvez également découvrir comment générer TwiML à l'aide des librairies de Twilio, fournies pour vous permettre de générer TwiML dans votre langage préféré.

                    Pour une démonstration guidée, consultez nos quickstarts qui vous montreront comment passer et recevoir des appels téléphoniques avec Twilio en C#/.NET, Java, Node.js, PHP, Python ou Ruby.

                    Rate this page:

                    Besoin d'aide ?

                    Ça arrive à tout le monde, il est difficile de coder. Obtenez de l'aide dès maintenant auprès de notre équipe d'assistance, ou appuyez-vous sur la sagesse collective en visitant les Forums de la communauté Twilio ou en parcourant Twilio tag sur Stack Overflow.

                          
                          
                          

                          Thank you for your feedback!

                          We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

                          Sending your feedback...
                          🎉 Thank you for your feedback!
                          Something went wrong. Please try again.

                          Thanks for your feedback!

                          Refer us and get $10 in 3 simple steps!

                          Step 1

                          Get link

                          Get a free personal referral link here

                          Step 2

                          Give $10

                          Your user signs up and upgrade using link

                          Step 3

                          Get $10

                          1,250 free SMSes
                          OR 1,000 free voice mins
                          OR 12,000 chats
                          OR more