Voice

Effectuez un appel vers un numéro spécifique en utilisant l'API Voice de seven. Dans sa variante la plus simple, vous pouvez spécifier un texte qui est ensuite lu au destinataire via notre passerelle Text-To-Speech (TTS). Pour des applications avancées, vous avez la possibilité d'envoyer le texte au format SSML.

Envoyer un appel vocal

Créez un nouvel appel TTS vers un numéro.

curl -X POST https://gateway.seven.io/api/voice \
    -H "X-Api-Key: VOTRE_CLÉ_API" \
    -H "Accept: application/json" \
    -d "to=49176123456789" \
    -d "text=Bonjour le monde!"

{
    "success": "100",
    "total_price": 0.045,
    "balance": 3509.236,
    "debug": false,
    "messages": [
        {
            "id": 1384013,
            "sender": "sender",
            "recipient": "49176123456789",
            "text": "Bonjour le monde!",
            "price": 0.045,
            "success": true,
            "error": null,
            "error_text": null
        }
    ]
}

Terminer l'appel

Ce point de terminaison termine un appel actif. Seuls les appels avec le statut in-progress peuvent être terminés.

curl -X POST https://gateway.seven.io/api/voice/123456/hangup \
    -H "X-Api-Key: VOTRE_CLÉ_API" \
    -H "Accept: application/json"

{
    "success": true,
    "error": null
}

SSML

Avec le Speech Synthesis Markup Language (SSML), vous pouvez contrôler la génération de la parole. Utilisez SSML pour lire des fichiers audio, changer la voix et la langue, insérer des pauses, et bien plus encore.

Des informations détaillées sur l'utilisation de SSML et les commandes possibles peuvent être trouvées dans la documentation Microsoft.

Pauses

Vous voulez un peu plus de pause à un certain point ? Vous pouvez contrôler les pauses comme vous le souhaitez.

<!-- Maintenant vient une pause. -->
<break time="2s" />
<!-- La pause est terminée. -->

Différentes voix

Avec SSML, vous avez la possibilité de choisir différentes voix. Vous pouvez distinguer le genre comme voix féminine, masculine ou d'enfant. De plus, de nombreuses langues internationales sont disponibles, par exemple les dialectes anglais, français, arabe, asiatique, croate ou russe. Les voix d'enfants ne sont pas disponibles dans toutes les langues. Pour la balise voice, l'attribut name est composé de l'abréviation de région (de-DE, ou en-US) et du genre. Exemple "en-us-female".

<voice name="fr-fr-female">"La France, dont nous sommes les enfants, et dont nous parlons la langue,
ne devrait plus être notre référence ; car le goût de ses écrivains est déjà corrompu,
et sa langue en déclin." -Noah Webster, 1789 </voice>

Phrases et paragraphes

Avec les balises p et s, vous pouvez structurer un paragraphe et les phrases qu'il contient.

<p>
  <s>Bonjour, voici le livre audio de la petite fille au ballon rouge !</s>
  <s>Je me les fais lire chaque soir pour m'endormir.</s>
</p>

Codes et nombres

Pour les codes, il est recommandé de lire comme lettres et caractères individuels. Les nombres peuvent être distingués en nombres entiers, chiffres simples et ordinaux. Voici trois exemples d'usage quotidien.

<voice name="fr-fr-female">
    Le code de confirmation est :
    <prosody rate="slow">
    <say-as interpret-as="characters">967354</say-as>
    </prosody>
</voice>

Pour le transfert d'un code, il est préférable de lire caractère par caractère et un peu ralenti. Notez dans cet exemple que le petit "p" n'est aussi lu que comme "P". Par conséquent, nous divisons l'exemple de code "LK9p7U" en deux balises say-as :

<voice name="fr-fr-female">
  Votre code est :
  <prosody rate="x-slow">
    <say-as interpret-as="characters">LK9</say-as>petit P
    <say-as interpret-as="characters">7U</say-as>
  </prosody>
</voice>

Nous synthétisons les nombres entiers sans balise. La synthèse vocale reconnaît automatiquement les montants d'argent et lit "13,50 Euro" comme "13 Euro 50 centimes".

<voice name="fr-fr-female">
  Le total est de 13,50 Euro.
</voice>

Pour les spécifications de longueur ou de poids, il est préférable d'écrire les unités.

<voice name="fr-fr-female">
  Le bâtiment fait 18 mètres de haut. Le poisson pèse 3,5 kilos.
</voice>

Lecture d'un fichier audio

Dans votre SSML, vous pouvez lire des fichiers audio de n'importe quelle source.

<audio src="https://static.seven.io/sample.mp3" />

Vous pouvez aussi combiner la synthèse de votre texte et la lecture d'un fichier média externe.

<voice name="fr-fr-child">
  Salut, écoute ça
  <audio src="https://static.seven.io/sample.mp3" />
</voice>

Répétition d'une balise voice

La balise voice utilise l'attribut loop pour définir le nombre de répétitions. Avec l'attribut optionnel loop-info, vous pouvez annoncer chaque répétition.

<voice name="fr-fr-female" loop="2" loop-info="Je répète">
    Le code de confirmation est :
    <say-as interpret-as="characters">5684</say-as>
</voice>

DTMF

DTMF (Dual-Tone Multi-Frequency) est une méthode pour transmettre des chiffres sur le réseau téléphonique. Elle est aussi connue sous le nom de numérotation multifréquence. Avec DTMF, vous pouvez inviter le destinataire à appuyer sur une touche du téléphone. Cela peut être utilisé, par exemple, pour confirmer une réservation ou transférer un appel vers un département spécifique. Pour l'évaluation des signaux DTMF, vous pouvez utiliser la balise DTMF dans SSML.

Évaluation des pressions de touches DTMF sans balise <dtmf/>

Si une touche numérique est pressée pendant l'appel et si l'appel n'est pas actuellement explicitement dans une balise <dtmf/>, le signal DTMF est transmis à l'URL webhook stockée dans votre compte et affiché dans le champ dtmf_digit. Les informations sur la configuration des webhooks peuvent être trouvées sur notre page webhook.

{
  "webhook_event": "voice_dtmf",
  "webhook_timestamp": "2024-08-02T07:28:59+02:00",
  "data": {
    "id": 0,
    "callerId": "4943160049851",
    "recipient": "4943160049851",
    "status": "completed",
    "system": "4915170517246",
    "timestamp": 1722576539,
    "duration": 2.76,
    "pricePerMinute": 0.045,
    "dtmf_digit": 9,
    "total_price": 0.045
  }
}

Évaluation des pressions de touches DTMF avec balise <dtmf/>

<dtmf callback="https://gateway.seven.io/input/fs_dtmf_callback" min="3" max="4" wait="5"
      invalid="Saisie invalide. Veuillez réessayer." exit="Merci ! Au revoir">Veuillez saisir deux chiffres.</dtmf>

Vous pouvez utiliser la balise <dtmf/> pour inviter le destinataire à appuyer sur une touche du téléphone. Avec les attributs min, max et wait, vous pouvez définir le nombre de chiffres attendus, le nombre maximum de chiffres, et le temps d'attente en millisecondes. Avec l'attribut invalid, vous pouvez définir un message personnalisé pour une saisie invalide. Avec l'attribut exit, vous pouvez définir un message personnalisé pour terminer la saisie. L'attribut callback définit l'URL pour le webhook auquel la saisie DTMF est transmise comme charge utile JSON. Avec l'attribut allowed_digits, vous pouvez définir les chiffres autorisés comme expression régulière.

Exemple

<voice name = "fr-fr-female">
  <dtmf 
    callback="https://votre-url.com/dtmf-callback" 
    allowed_digits="^[0-9#*]+"
    min="3" 
    max="4" 
    wait="5000" 
    invalid="Saisie invalide. Veuillez réessayer." 
    exit="Merci ! Au revoir.">
    Veuillez saisir deux chiffres
  </dtmf>
</voice>

Une fois qu'une saisie valide est effectuée, le webhook enverra les données suivantes à l'URL spécifiée où digits est la saisie DTMF entrée :

{
  "webhook_event": "dtmf",
  "webhook_timestamp": "2024-11-05T10:23:04+01:00",
  "data": {
    "id": "1732712",
    "callerId": "4943130149270",
    "recipient": "49176123456789",
    "foreign_id": "MonForeignId",
    "voice_name": "de-DE-KatjaNeural",
    "digits": "65"
  }
}

Réponse webhook

Vous pouvez maintenant contrôler la suite de l'appel via la réponse du webhook et ainsi réaliser un contrôle d'appel en cascade. Par exemple, faire jouer au webhook une autre annonce ou terminer l'appel. Pour cela, retournez simplement la prochaine annonce ou la commande pour terminer l'appel au format JSON.

Exemples de réponses

Terminer l'appel :

{
  "hangup": true
}

Transférer l'appel :

{
  "bridge": "+49431123456789"
}

Jouer une autre annonce. Ici vous pouvez aussi utiliser n'importe quel SSML :

{
  "text": "<voice name=\"fr-fr-female\">Merci pour votre saisie. Au revoir.</voice>"
}

Si vous n'envoyez pas de réponse ou une réponse valide, l'appel se terminera automatiquement.

Statut de l'appel

Vous recevrez le statut actuel de l'appel immédiatement à chaque changement via webhook.