Premiers pas avec l'API Voice

Cette page vous expliquera toutes les étapes nécessaires à la mise en œuvre de l'API Voice de Vonage.

Conditions préalables

Avant de commencer, vous aurez besoin des éléments suivants :

Créer un Account Vonage

Pour utiliser nos API, vous devez ouvrir un compte. Vous obtiendrez ainsi une clé API et un secret que vous pourrez utiliser pour accéder à nos API.

Vous pouvez utiliser la Voice API pour passer un appel vocal. Utiliser le numéro de test 123456789 en tant que identification de l'appelantet appelez le numéro que vous avez indiqué lors de votre inscription. Veuillez noter que cette fonction n'est disponible que pour les comptes de démonstration ou d'essai jusqu'à ce que vous ajoutiez du crédit à votre compte.

Essayez l'API Voice

Après s'inscrire à un compte API Vonage, accéder à la Tableau de bord du développeur et se rendre sur le site Passer un appel vocal section. Ici, vous pouvez effectuer un appel test pour voir l'API Voice en action.

Voyons maintenant comment utiliser l'API Voice dans votre application.

Créer une application

Aller à la page Applicationssur le tableau de bord, et définissez une page Name pour votre Applications.

Veillez à cliquer sur le bouton Générer une clé publique et une clé privée et conserver le fichier private.key autour.

Ensuite, activez l'option Voix capacité. Pour l'instant, laissez tout par défaut.

An example of enabling Voice capabilities

Enfin, cliquez sur Générer une nouvelle application au bas de la page.

Vérifier Démarrer avec l'interface de programmation de Vonage pour plus d'informations sur l'installation et la configuration de la CLI.

Utilisez la commande suivante pour créer une application Vonage :

vonage apps create 'Your application'

✅ Creating Application
Saving private key ... Done!
Application created

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

vonage apps create 'Your application'

✅ Creating Application
Saving private key ... Done!
Application created

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

Une fois que vous avez l'application, vous devez ajouter l'élément voice veillez à remplacer les URL des webhooks par les vôtres :

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 voice `
  --voice-answer-url='https://example.com/webhooks/voice/answer' `
  --voice-event-url='https://example.com/webhooks/voice/event' `
  --voice-fallback-url='https://example.com/webhooks/voice/fallback'
  
✅ Fetching Application
✅ Adding voice capability to application 00000000-0000-0000-0000-000000000000

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
 VOICE:
    Uses Signed callbacks: On
    Conversation TTL: 41 hours
    Leg Persistence Time: 6 days
    Event URL: [POST] https://example.com/webhooks/voice/event
    Answer URL: [POST] https://example.com/webhooks/voice/answer
    Fallback URL: [POST] https://example.com/webhooks/voice/fallback

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 voice ^
  --voice-answer-url='https://example.com/webhooks/voice/answer' ^
  --voice-event-url='https://example.com/webhooks/voice/event' ^
  --voice-fallback-url='https://example.com/webhooks/voice/fallback'
  
✅ Fetching Application
✅ Adding voice capability to application 00000000-0000-0000-0000-000000000000

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
 VOICE:
    Uses Signed callbacks: On
    Conversation TTL: 41 hours
    Leg Persistence Time: 6 days
    Event URL: [POST] https://example.com/webhooks/voice/event
    Answer URL: [POST] https://example.com/webhooks/voice/answer
    Fallback URL: [POST] https://example.com/webhooks/voice/fallback

L'application est alors créée et dotée des capacités requises. La création d'une application et l'ajout de capacités d'application sont traités en détail dans la section Documentation relative à l'application.

Louer un Numbers

Pour louer un numéro, vous devez d'abord ajouter un crédit à votre Account.

Vous pouvez sauter cette étape si vous souhaitez utiliser le numéro de test 123456789 en tant que identification de l'appelantet appelez le numéro que vous avez fourni lors de votre inscription.

Dans le tableau de bord, allez dans la section Acheter des Numbers page. Veillez à cocher Voix dans le filtre de recherche, et sélectionnez le pays dans lequel vous souhaitez acheter un numéro. Dans certains pays, vous devrez peut-être demander un numéro, car des documents supplémentaires peuvent être exigés.

Vous pouvez ensuite cliquer sur le bouton Acheter à côté du numéro souhaité, et validez votre achat.

Félicitations à tous ! Votre numéro virtuel est désormais répertorié dans Vos Numbers.

Vous pouvez louer un numéro à l'aide de la CLI de Vonage. La commande suivante recherche un numéro disponible aux Etats-Unis :

vonage numbers search US

✅ Searching for numbers

There is 1 number available for purchase in United States

Number       Type    Features         Monthly Cost  Setup Cost
-----------  ------  ---------------  ------------  ----------
16127779311  Mobile  MMS, SMS, VOICE  €0.90         €0.00

Use vonage numbers buy to purchase.

vonage numbers search US

✅ Searching for numbers

There is 1 number available for purchase in United States

Number       Type    Features         Monthly Cost  Setup Cost
-----------  ------  ---------------  ------------  ----------
16127779311  Mobile  MMS, SMS, VOICE  €0.90         €0.00

Use vonage numbers buy to purchase.

Utilisez cette commande pour acheter un nombre :

vonage numbers buy US 16127779311 
✅ Searching for numbers
Are you sure you want to purchase the number 16127779311 for €0.90? [y/n] y

✅ Purchasing number
Number 16127779311 purchased

Number: 16127779311 
Country: 🇺🇸 United States
Type: Mobile
Features: MMS, SMS, VOICE
Monthly Cost: €0.90
Setup Cost: €0.00
Linked Application ID: Not linked to any application
Voice Callback: Not Set
Voice Callback Value: Not Set
Voice Status Callback: Not Set

vonage numbers buy US 16127779311 
✅ Searching for numbers
Are you sure you want to purchase the number 16127779311 for €0.90? [y/n] y

✅ Purchasing number
Number 16127779311 purchased

Number: 16127779311 
Country: 🇺🇸 United States
Type: Mobile
Features: MMS, SMS, VOICE
Monthly Cost: €0.90
Setup Cost: €0.00
Linked Application ID: Not linked to any application
Voice Callback: Not Set
Voice Callback Value: Not Set
Voice Status Callback: Not Set

Préciser un autre code de pays à deux caractères pour acheter un numéro dans dans un autre pays.

Passer un appel sortant

La principale façon d'interagir avec la plateforme vocale de l'API de Vonage est par l'intermédiaire de la fonction public API. Pour passer un appel sortant, vous effectuez un POST demande à https://api.nexmo.com/v1/calls.

Pour passer votre premier appel avec la Voice API, choisissez votre langue ci-dessous et remplacez les variables suivantes dans le code de l'exemple :

Clé	Description
`VONAGE_NUMBER`	Votre numéro Vonage à partir duquel l'appel sera effectué. Par exemple `447700900000`. Si vous avez sauté l'étape Louer un Numbers utiliser le numéro de test "123456789".
`TO_NUMBER`	Le numéro que vous souhaitez appeler au format E.164. Par exemple `447700900001`. Si vous avez sauté l'étape Louer un Numbers utilisez le numéro que vous avez fourni lors de votre inscription.

Conditions préalables

Exécutez la commande suivante à l'invite de votre terminal pour créer le site JWT pour l'authentification :

export JWT=$(nexmo jwt:generate $PATH_TO_PRIVATE_KEY application_id=$NEXMO_APPLICATION_ID)

Rédiger le code

Ajouter ce qui suit à make-an-outbound-call.sh:

curl -X POST https://api.nexmo.com/v1/calls\
  -H "Authorization: Bearer $JWT"\
  -H "Content-Type: application/json"\
  -d '{"to":[{"type": "phone","number": "'$VOICE_TO_NUMBER'"}],
      "from": {"type": "phone","number": "'$VONAGE_VIRTUAL_NUMBER'"},
      "answer_url":["'"$VOICE_ANSWER_URL"'"]}'

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

bash make-an-outbound-call.sh

Conditions préalables

npm install @vonage/server-sdk

Créez un fichier nommé make-an-outbound-call.js et ajoutez le code suivant :

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage({
  applicationId: VONAGE_APPLICATION_ID,
  privateKey: VONAGE_PRIVATE_KEY,
});

Voir la source complète

Rédiger le code

Ajouter ce qui suit à make-an-outbound-call.js:

vonage.voice.createOutboundCall({
  to: [
    {
      type: 'phone',
      number: VOICE_TO_NUMBER,
    },
  ],
  from: {
    type: 'phone',
    number: VONAGE_VIRTUAL_NUMBER,
  },
  answer_url: [VOICE_ANSWER_URL],
})
  .then((resp) => console.log(resp))
  .catch((error) => console.error(error));

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

node make-an-outbound-call.js

Conditions préalables

Ajouter ce qui suit à build.gradle:

implementation 'com.vonage:server-sdk-kotlin:2.1.1'

Créez un fichier nommé OutboundTextToSpeechCall et ajoutez le code suivant à la méthode main:

val client = Vonage {
    applicationId(VONAGE_APPLICATION_ID)
    privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}

Voir la source complète

Rédiger le code

Ajouter ce qui suit à la méthode main du fichier OutboundTextToSpeechCall:

val callEvent = client.voice.createCall {
    toPstn(VOICE_TO_NUMBER)
    from(VONAGE_VIRTUAL_NUMBER)
    answerUrl(VOICE_ANSWER_URL)
}

Voir la source complète

Exécutez votre code

Nous pouvons utiliser le plugin Applications pour Gradle afin de simplifier l'exécution de notre application. Mettez à jour votre build.gradle avec ce qui suit :

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Exécutez la commande gradle suivante pour exécuter votre application, en remplaçant com.vonage.quickstart.kt.voice par le paquet contenant OutboundTextToSpeechCall:

gradle run -Pmain=com.vonage.quickstart.kt.voice.OutboundTextToSpeechCall

Conditions préalables

Ajouter ce qui suit à build.gradle:

implementation 'com.vonage:server-sdk:9.3.1'

Créez un fichier nommé OutboundTextToSpeech et ajoutez le code suivant à la méthode main:

VonageClient client = VonageClient.builder()
        .applicationId(VONAGE_APPLICATION_ID)
        .privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
        .build();

Voir la source complète

Rédiger le code

Ajouter ce qui suit à la méthode main du fichier OutboundTextToSpeech:

client.getVoiceClient().createCall(new Call(VOICE_TO_NUMBER, VONAGE_VIRTUAL_NUMBER, VOICE_ANSWER_URL));

Voir la source complète

Exécutez votre code

Nous pouvons utiliser le plugin Applications pour Gradle afin de simplifier l'exécution de notre application. Mettez à jour votre build.gradle avec ce qui suit :

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Exécutez la commande gradle suivante pour exécuter votre application, en remplaçant com.vonage.quickstart.voice par le paquet contenant OutboundTextToSpeech:

gradle run -Pmain=com.vonage.quickstart.voice.OutboundTextToSpeech

Conditions préalables

Install-Package Vonage

Rédiger le code

Ajouter ce qui suit à MakeOutboundCall.cs:

var creds = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_PRIVATE_KEY_PATH);
var client = new VonageClient(creds);

var answerUrl = "https://nexmo-community.github.io/ncco-examples/text-to-speech.json";
var toEndpoint = new PhoneEndpoint() { Number = VOICE_TO_NUMBER };
var fromEndpoint = new PhoneEndpoint() { Number = VONAGE_VIRTUAL_NUMBER };

var command = new CallCommand() { To = new Endpoint[] { toEndpoint }, From = fromEndpoint, AnswerUrl = new[] { answerUrl } };
var response = await client.VoiceClient.CreateCallAsync(command);

Voir la source complète

Conditions préalables

composer require vonage/client

Rédiger le code

Ajouter ce qui suit à text-to-speech-outbound.php:

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

php text-to-speech-outbound.php

Conditions préalables

pip install vonage python-dotenv

Rédiger le code

Ajouter ce qui suit à make-an-outbound-call.py:

from vonage import Auth, Vonage
from vonage_voice import CreateCallRequest, Phone, ToPhone

client = Vonage(
    Auth(
        application_id=VONAGE_APPLICATION_ID,
        private_key=VONAGE_PRIVATE_KEY,
    )
)

response = client.voice.create_call(
    CreateCallRequest(
        answer_url=[VOICE_ANSWER_URL],
        to=[ToPhone(number=VOICE_TO_NUMBER)],
        from_=Phone(number=VONAGE_VIRTUAL_NUMBER),
    )
)

pprint(response)

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

python voice/make-an-outbound-call.py

Conditions préalables

gem install vonage

Rédiger le code

Ajouter ce qui suit à outbound_tts_call.rb:

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

ruby outbound_tts_call.rb

Pour faciliter cette tâche, Vonage fournit SDK de serveur dans différentes langues qui se chargent de l'authentification et de la création du corps de la requête pour vous.

Quelle est la prochaine étape ?

Une fois que vous avez passé votre premier appel, vous êtes prêt à essayer d'autres aspects de l'API Voice. Nous vous recommandons de commencer par la fonction Détails techniques pour une présentation complète de l'API Voice de Vonage. Pour comprendre les différents flux d'appels, consultez la page Flux d'appels guide. Si vous souhaitez créer une application de notification vocale de base, reportez-vous à la section Notifications vocales Guide pratique. Pour plus d'informations, veuillez consulter la documentation de notre Voice API.