Introdução à Voice API

Esta página irá orientá-lo em todas as etapas necessárias para começar a utilizar a Voice API da Vonage.

Pré-requisitos

Antes de começar, você precisará do seguinte:

Crie um account na Vonage

Para trabalhar com nossas APIs, você precisará criar um Account. Isso lhe fornecerá uma chave e um segredo de API que você poderá usar para acessar nossas APIs.

Você pode usar a Voice API para fazer uma chamada de voz. Use o número de teste 123456789 como o identificação de chamadas, e ligue para o número que você forneceu originalmente durante o cadastro. Observe que esse recurso está disponível apenas para contas de demonstração ou de teste até que você recarregue sua conta.

Experimente a Voice API

Depois de Criar um account na API da Vonage, acesse o Painel do desenvolvedor e vá para o Fazer uma chamada de voz seção. Aqui, você pode fazer uma chamada de teste para ver a Voice API em ação.

Try Voice API Developer Dashboard view

Vamos aprender agora como usar a Voice API em seu aplicativo.

Criar um aplicativo

Acesse o Applicationsna página do Painel e definir um Name para a sua inscrição.

An example of brand new application

Não se esqueça de clicar no Gerar chave pública e chave privada botão e mantenha o arquivo private.key por aí.

Em seguida, habilite o Voz recurso. Por enquanto, deixe tudo com as configurações padrão.

An example of enabling Voice capabilities

Por fim, clique em Criar um novo pedido na parte inferior da página.

Confira Introdução ao Vonage CLI para obter mais informações sobre como instalar e configurar a CLI.

Use o seguinte comando para criar um aplicativo da 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

Depois de baixar o aplicativo, você precisa adicionar o voice recursos; certifique-se de substituir as URLs dos webhooks pelas suas próprias:

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

O aplicativo é então criado e conta com os recursos necessários. A criação de um aplicativo e a adição de recursos ao mesmo são abordadas em detalhes no Documentação da inscrição.

Alugue um número

Para alugar um número, você deve primeiro recarregue sua Account.

Você pode pular esta etapa se quiser usar o número de teste 123456789 como um identificação de chamadas, e ligue para o número que você forneceu inicialmente durante o cadastro.

No Painel, acesse o Números para compra página. Certifique-se de marcar a caixa Voz no filtro de busca e selecione o país onde deseja comprar um número. Em alguns países, talvez seja necessário solicitar um número, pois podem ser exigidos documentos adicionais.

An example of number research

Em seguida, você pode clicar no Comprar Clique no botão ao lado do número desejado e confirme sua compra.

Parabéns! Seu número virtual já está listado em Seus Numbers.

Você pode alugar um número usando a CLI do Vonage. O comando a seguir procura um número disponível nos 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.

Use este comando para comprar um 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

Especifique um código de país alternativo de dois caracteres para adquirir um número em outro país.

Fazer uma chamada de saída

A principal forma de interagir com a plataforma de voz da Voice API da Vonage é por meio do API pública. Para fazer uma chamada, você deve POST solicitação para https://api.nexmo.com/v1/calls.

Para fazer sua primeira chamada com a Voice API, escolha seu idioma abaixo e substitua as seguintes variáveis no código de exemplo:

Chave Descrição
VONAGE_NUMBER Seu número da Vonage a partir do qual a ligação será feita. Por exemplo 447700900000. Se você pulou a Alugue um número Nesta etapa, use o número de teste “123456789”.
TO_NUMBER O número para o qual você deseja ligar, no formato E.164. Por exemplo 447700900001. Se você pulou a Alugue um número Nesta etapa, use o número que você forneceu originalmente ao se cadastrar.

Pré-requisitos

Execute o seguinte comando no prompt do terminal para criar o arquivo ` JWT ` para autenticação:

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

Escreva o código

Adicione o seguinte ao arquivo ` 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 código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

bash make-an-outbound-call.sh

Pré-requisitos

npm install @vonage/server-sdk

Crie um arquivo chamado ` make-an-outbound-call.js ` e insira o seguinte código:

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

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

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao arquivo ` 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 código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

node make-an-outbound-call.js

Pré-requisitos

Adicione o seguinte ao arquivo ` build.gradle`:

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

Crie um arquivo chamado ` OutboundTextToSpeechCall ` e adicione o código a seguir ao método ` main `:

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

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao método ` main ` do arquivo ` OutboundTextToSpeechCall `:

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

Ver código-fonte completo

Execute seu código

Podemos usar o plugin “ aplicativo ” para o Gradle a fim de simplificar a execução do nosso aplicativo. Atualize seu arquivo ` build.gradle ` com o seguinte:

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

Execute o seguinte comando ` gradle ` para rodar seu aplicativo, substituindo ` com.vonage.quickstart.kt.voice ` pelo pacote que contém ` OutboundTextToSpeechCall`:

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

Pré-requisitos

Adicione o seguinte ao arquivo ` build.gradle`:

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

Crie um arquivo chamado ` OutboundTextToSpeech ` e adicione o código a seguir ao método ` main `:

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

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao método ` main ` do arquivo ` OutboundTextToSpeech `:

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

Ver código-fonte completo

Execute seu código

Podemos usar o plugin “ aplicativo ” para o Gradle a fim de simplificar a execução do nosso aplicativo. Atualize seu arquivo ` build.gradle ` com o seguinte:

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

Execute o seguinte comando ` gradle ` para rodar seu aplicativo, substituindo ` com.vonage.quickstart.voice ` pelo pacote que contém ` OutboundTextToSpeech`:

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

Pré-requisitos

Install-Package Vonage

Escreva o código

Adicione o seguinte ao arquivo ` 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 código-fonte completo

Pré-requisitos

composer require vonage/client

Escreva o código

Adicione o seguinte ao arquivo ` 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 código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

php text-to-speech-outbound.php

Pré-requisitos

pip install vonage python-dotenv

Escreva o código

Adicione o seguinte ao arquivo ` 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 código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

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

Pré-requisitos

gem install vonage

Escreva o código

Adicione o seguinte ao arquivo ` 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 código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

ruby outbound_tts_call.rb

Para facilitar isso, a Vonage oferece SDKs de servidor em várias linguagens que cuidam da autenticação e da criação do corpo da solicitação correto para você.

E agora?

Depois de fazer sua primeira chamada, você estará pronto para experimentar outros recursos da Voice API. Recomendamos começar com o Detalhes técnicos página para uma visão geral completa da Voice API da Vonage. Para entender os diversos fluxos de chamadas, consulte a Fluxo de chamadas guia. Se você estiver interessado em criar um aplicativo básico de notificação por voz, consulte o Notificações de voz Guia prático. Para obter mais informações, consulte nossa documentação da Voice API.