Primeros pasos con la Voice API

Esta página te guiará a través de todos los pasos necesarios para comenzar a usar Vonage Voice API.

Requisitos previos

Antes de empezar, necesitarás lo siguiente:

Crear un Account de Vonage
Pruebe la Voice API
Crear una aplicación
Alquilar un número

Crear un Account de Vonage

Para trabajar con nuestras API, necesitará crear una Account. Esto le proporcionará una clave API y un secreto que podrá utilizar para acceder a nuestras API.

Puedes utilizar la Voice API para realizar una llamada de voz. Utilice el número de prueba 123456789 como el identificador de llamadas, y llama al número que facilitaste inicialmente al registrarte. Ten en cuenta que esta función solo está disponible para cuentas de demostración o de prueba hasta que recargues tu Account.

Pruebe la Voice API

En registrarse para obtener un Account de la API de VonageAcceda a Panel de control para desarrolladores e ir a la Hacer una llamada de voz sección. Aquí puedes hacer una llamada de prueba para ver la Voice API en acción.

Ahora vamos a aprender a utilizar la Voice API en tu aplicación.

Crear una aplicación

Ve a la Aplicacionesen el cuadro de mandos, y defina una página Name para su solicitud.

Asegúrate de hacer clic en el Generar clave pública y privada y guarde el archivo private.key alrededor.

A continuación, active el Voz capacidad. De momento, déjalo todo por defecto.

An example of enabling Voice capabilities

Por último, haga clic en Generar nueva aplicación en la parte inferior de la página.

Echa un vistazo Primeros pasos con la CLI de Vonage para obtener más información sobre cómo instalar y configurar la CLI.

Utiliza el siguiente comando para crear una aplicación de 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

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

Una vez que tenga la aplicación, tendrá que añadir el archivo voice funcionalidades; asegúrate de sustituir las URL de los webhooks por las tuyas propias:

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

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

A continuación, la aplicación se crea y dispone de las capacidades necesarias. La creación de una aplicación y la adición de capacidades de aplicación se tratan en detalle en la sección Documentación de las aplicaciones.

Alquilar un número

Para alquilar un número, primero debe recargar saldo en tu Account.

Puedes saltarte este paso si quieres utilizar el número de prueba 123456789 como un identificador de llamadas, y llama al número que facilitaste inicialmente al registrarte.

En el cuadro de mandos, vaya a Comprar Numbers página. Asegúrese de marcar Voz en el filtro de búsqueda y selecciona el país en el que quieres comprar un número. En algunos países, es posible que tengas que solicitar un número, ya que pueden exigirse documentos adicionales.

A continuación, puede hacer clic en el botón Comprar junto al número que desee y valide su compra.

¡Enhorabuena! Tu número virtual ya aparece en Tus Numbers.

Puedes alquilar un número mediante la CLI de Vonage. El siguiente comando busca un número disponible en Estados Unidos:

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.

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.

Utilice este comando para comprar un número:

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

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

Especificar un código de país alternativo de dos caracteres comprar un número en otro país.

Realizar una llamada saliente

La principal forma de interactuar con la plataforma de voz de la Voice API de Vonage es a través de la API pública. Para realizar una llamada saliente, se hace una POST solicitar a https://api.nexmo.com/v1/calls.

Para realizar tu primera llamada con la Voice API, elige tu idioma a continuación y sustituye las siguientes variables en el código de ejemplo:

Clave	Descripción
`VONAGE_NUMBER`	Tu número de Vonage desde el que se realizará la llamada. Por ejemplo `447700900000`. Si se ha saltado el Alquilar un número En este paso, utiliza el número de prueba «123456789».
`TO_NUMBER`	El número al que desea llamar en formato E.164. Por ejemplo `447700900001`. Si se ha saltado el Alquilar un número utilice el número que facilitó al registrarse.

Requisitos previos

Ejecute el siguiente comando en el símbolo del sistema de su terminal para crear la dirección JWT para la autenticación:

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

Escriba el código

Añada lo siguiente a 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"'"]}'

Ver fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

bash make-an-outbound-call.sh

Requisitos previos

npm install @vonage/server-sdk

Crea un archivo llamado make-an-outbound-call.js y añade el siguiente código:

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

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

Ver fuente completa

Escriba el código

Añada lo siguiente a 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));

Ver fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

node make-an-outbound-call.js

Requisitos previos

Añada lo siguiente a build.gradle:

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

Crea un archivo llamado OutboundTextToSpeechCall y añade el siguiente código al método main:

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

Ver fuente completa

Escriba el código

Añada lo siguiente al método main del archivo OutboundTextToSpeechCall:

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

Ver fuente completa

Ejecute su código

Podemos utilizar el plugin aplicación para Gradle para simplificar la ejecución de nuestra aplicación. Actualiza tu build.gradle con lo siguiente:

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

Ejecute el siguiente comando gradle para ejecutar su aplicación, sustituyendo com.vonage.quickstart.kt.voice por el paquete que contiene OutboundTextToSpeechCall:

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

Requisitos previos

Añada lo siguiente a build.gradle:

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

Crea un archivo llamado OutboundTextToSpeech y añade el siguiente código al método main:

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

Ver fuente completa

Escriba el código

Añada lo siguiente al método main del archivo OutboundTextToSpeech:

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

Ver fuente completa

Ejecute su código

Podemos utilizar el plugin aplicación para Gradle para simplificar la ejecución de nuestra aplicación. Actualiza tu build.gradle con lo siguiente:

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

Ejecute el siguiente comando gradle para ejecutar su aplicación, sustituyendo com.vonage.quickstart.voice por el paquete que contiene OutboundTextToSpeech:

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

Requisitos previos

Install-Package Vonage

Escriba el código

Añada lo siguiente a 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);

Ver fuente completa

Requisitos previos

composer require vonage/client

Escriba el código

Añada lo siguiente a text-to-speech-outbound.php:

require_once __DIR__ . '/../config.php';
require_once __DIR__ . '/../vendor/autoload.php';

// Building Blocks
// 1. Make a Phone Call
// 2. Play Text-to-Speech

$keypair = new \Vonage\Client\Credentials\Keypair(
    file_get_contents(VONAGE_APPLICATION_PRIVATE_KEY_PATH),
    VONAGE_APPLICATION_ID
);
$client = new \Vonage\Client($keypair);

$outboundCall = new \Vonage\Voice\OutboundCall(
    new \Vonage\Voice\Endpoint\Phone(TO_NUMBER),
    new \Vonage\Voice\Endpoint\Phone(VONAGE_NUMBER)
);
$outboundCall->setAnswerWebhook(
    new \Vonage\Voice\Webhook(
        'https://raw.githubusercontent.com/nexmo-community/ncco-examples/gh-pages/text-to-speech.json',
        \Vonage\Voice\Webhook::METHOD_GET
    )
);
$response = $client->voice()->createOutboundCall($outboundCall);

var_dump($response);

Ver fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

php text-to-speech-outbound.php

Requisitos previos

pip install vonage python-dotenv

Escriba el código

Añada lo siguiente a 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)

Ver fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

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

Requisitos previos

gem install vonage

Escriba el código

Añada lo siguiente a outbound_tts_call.rb:

client = Vonage::Client.new(
  application_id: VONAGE_APPLICATION_ID,
  private_key: VONAGE_PRIVATE_KEY
)

response = client.voice.create(
  to: [{
    type: 'phone',
    number: VOICE_TO_NUMBER
  }],
  from: {
    type: 'phone',
    number: VONAGE_VIRTUAL_NUMBER
  },
  answer_url: [
    VOICE_ANSWER_URL
  ]
)

Ver fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

ruby outbound_tts_call.rb

Para facilitar este proceso, Vonage ofrece SDK de servidor en varios idiomas que se encargan de la autenticación y de crear el cuerpo de la solicitud adecuado por ti.

¿Y ahora qué?

Una vez que hayas hecho tu primera llamada, estarás listo para probar otros aspectos de la Voice API. Le recomendamos que empiece por Detalles técnicos página para obtener una descripción general completa de la Voice API de Vonage. Para conocer los distintos flujos de llamadas, consulta la Flujo de llamadas guía. Si está interesado en crear una aplicación básica de notificación por voz, consulte la guía Notificaciones de voz Guía práctica. Para más información, consulte nuestra documentación sobre Voice API.