You are viewing the Portuguese (Brazil) site, but your language preference is set to English. Switch to English site →

Menu

Expand
Classifique esta página:

SDKs de Voice

O SDK de Client do Twilio Voice foi renomeado para SDK de JavaScript do Twilio Voice a partir da versão 2.0.

Os SDKs do Programmable Voice permitem que você adicione chamadas de voz sobre IP (VoIP) diretamente em seus aplicativos para dispositivos móveis nativos e da Web.

O Twilio fornece três SDKs de Voice:

  • SDK de JavaScript do Voice, que permite que os usuários façam e recebam chamadas VoIP em um navegador da Web ou em um aplicativo Electron
  • SDK de iOS do Voice, que permite que os usuários façam e recebam chamadas VoIP em dispositivos iOS
  • SDK de Android do Voice, que permite que os usuários façam e recebam chamadas VoIP em dispositivos Android

Inícios rápidos

Depois de escolher sua plataforma, explore o que o Programmable Voice pode fazer usando um dos guias de início rápido da Twilio:

Criar um aplicativo com SDK do Voice

A criação de um aplicativo com um SDK do Voice requer o uso de vários recursos da Twilio. Esta seção explica o que são esses recursos e como eles funcionam em conjunto com seu aplicativo para habilitar chamadas de voz VoIP em seu navegador, aplicativo Electron ou dispositivos iOS ou Android. Este não é um guia prático, mas sim uma visão geral.

Embora os SDKs de Voice sejam usados para potencializar aplicativos do lado do cliente que o usuário final verá, você ainda precisará usar algum código do lado do servidor . O lado do servidor funcionará em conjunto com a Twilio para habilitar e gerenciar chamadas de/para o aplicativo do lado do cliente.

Cada SDK do Voice tem sua própria documentação sobre como usar o SDK no lado do cliente. Clique em um SDK abaixo para visualizar a documentação do lado do cliente.

O restante desta página explica como o aplicativo do lado do servidor se comunica com o Twilio e os SDKs de Voice.

Requisitos

A criação de um aplicativo com qualquer um dos SDKs de Voice requer:

  • Uma conta da Twilio
  • Um ou mais números de telefone da Twilio
  • Um endpoint que pode lidar e responder a solicitações HTTP da Twilio
    • Algumas solicitações da Twilio (como as enviadas quando o número de telefone da Twilio recebe uma chamada) exigirão que as instruções do Voice TwiML sejam enviadas na resposta.
    • Outras solicitações, como retornos de chamada de status, fornecem ao aplicativo do lado do servidor informações relacionadas a chamadas, gravações etc. Para essas solicitações, a Twilio espera apenas um código de status HTTP bem‐sucedido na resposta.
  • AccessTokens (tokens de acesso), que contém:
  • Um dos SDKs de Voice
  • Uma biblioteca auxiliar para gerar AccessTokens (tokens de acesso) e TwiML (dependendo do seu caso de uso)

AccessTokens (Tokens de acesso)

Os AccessTokens (tokens de acesso)servem como credenciais para seus usuários finais e são a peça‐chave que conecta seu aplicativo baseado em SDK, a Twilio e seu aplicativo do lado do servidor.

AccessTokens (tokens de acesso) são tokens JSON Web (JWTs) que seu aplicativo pode criar usando uma biblioteca auxiliar. Um AccessToken (Token de acesso) contém informações que a Twilio precisa para garantir que:

  • As chamadas de/para o SDK do Voice estão associadas à conta correta da Twilio
  • As chamadas recebidas estão ativadas ou desativadas
  • A identidade do usuário final do SDK do Voice é conhecida pela Twilio
  • As chamadas outbound de seu aplicativo SDK do Voice são tratadas pela Twilio usando as instruções adequadas do TwiML
  • Os AccessTokens (tokens de acesso) expirarão no momento apropriado

Como eles contêm tantas informações necessárias, os AccessTokens (tokens de acesso) são as primeiras coisas que você deve verificar quando seu aplicativo SDK do Voice encontra um erro. Você pode decodificar um AccessToken (Token de acesso) no JWT.io.

Um payload de AccessToken (Token de acesso) decodificado e adequadamente formado para um usuário final do SDK do Voice é mostrado abaixo.

{
  "jti": "SK835c7c8ac38c0617205f41fd71d4bb38-1643132114",
  "grants": {
    "identity": "SalesDepartment",
    "voice": {
      "incoming": {
        "allow": true
      },
      "outgoing": {
        "application_sid": "APe4c9832e936010a33e130a8b3333db71"
      }
    }
  },
  "iat": 1643132114,
  "exp": 1643135714,
  "iss": "SK835c7c8ac38c0617205f41fd71d4bb38",
  "sub": "ACd29d942e419c9bdafbc55a27b1da79b1"
}

A propriedade grants.identity contém a identidade do usuário final do SDK. Para conectar uma chamada a esse usuário do SDK específico, use essa identidade entre as tags de abertura e fechamento do <Client (Cliente)>.

A propriedade grants.voice.incoming.allow é definida como true, o que permite que o usuário final do SDK receba chamadas.

A propriedade grants.voice.outgoing.application_sid contém o SID para seu aplicativo TwiML (consulte a seção Apps TwiML abaixo para obter mais informações).

Um caso de uso típico do SDK do Voice lida com a geração de AccessToken (Token de acesso) no aplicativo do lado do servidor. O cenário de exemplo a seguir ilustra uma maneira como isso pode funcionar em seu aplicativo:

  1. Seu aplicativo do lado do servidor tem um endpoint em http://www.example.com/token.
  2. Seu aplicativo do lado do cliente envia uma solicitação GET ao seu endpoint http://www.example.com/token para recuperar um AccessToken (Token de acesso).
  3. Seu aplicativo do lado do servidor recebe a solicitação GET. Usando uma Biblioteca auxiliar, seu aplicativo cria um AccessToken (Token de acesso) e o envia na resposta à solicitação GET do aplicativo do lado do cliente.
  4. Seu aplicativo do lado do cliente recebe o AccessToken (Token de acesso).

Consulte a documentação de AccessTokens (tokens de acesso) para obter mais informações. Os aplicativos de início rápido do SDK do Voice também possuem exemplos de pontos de extremidade /token que geram AccessTokens (tokens de acesso).

Aplicativos TwiML

A propriedade do AccessToken (Token de acesso) grants.voice.outgoing.application_sid contém o SID para um aplicativo TwiML. Um aplicativo TwiML é um recurso da Twilio que contém URLs de configuração de Voice e mensagens. Você só usará os URLs de configuração de voz para seu aplicativo SDK do Voice.

Você pode criar e configurar aplicativos TwiML por meio do Console (mostrado na imagem abaixo) ou da API.

Create a new TwiML App in the Console and configure the Voice Configuration Request URL

O URL de solicitação de voz (também chamado de URL de Voice) é para onde a Twilio enviará uma solicitação HTTP POST quando a Twilio precisar de algumas instruções de Voice TwiML para lidar com uma chamada. O URL de Voice pode apontar para um TwiML Bin (Repositório do TwiML), um endpoint em um servidor Web, um Studio Flow, um Twilio Function etc.

O URL de Fallback de Voice deve ser um endpoint que possa responder com o Voice TwiML. Se uma solicitação para o URL de Voice falhar por qualquer motivo (códigos de status de nível 400 ou 500, por exemplo), o URL de Fallback de Voice fará uma tentativa. Normalmente, esse endpoint deve responder com alguns Voice TwiML, como:

<Response>
  <Say>We're sorry. An error has occurred. Please try your call again.</Say>
  <Hangup/>
</Response>

O URL de retorno de chamada de status de Voice é o URL em que a Twilio enviará solicitações HTTP POST que fornecem atualizações sobre a atividade relacionada ao App TwiML.

Com as chamadas do SDK do Voice, o URL de retorno de chamada de status de Voice receberá uma solicitação quando o trecho pai da chamada for encerrada. O "parent leg" (trecho pai) é o trecho da chamada que acionou uma solicitação para o URL de Voice do aplicativo TwiML. Todas as chamadas enviadas do SDK do Voice acionarão uma solicitação para o URL de Voice do aplicativo TwiML. As chamadas recebidas tratadas com o mesmo aplicativo TwiML também dispararão uma solicitação para o URL de Voice do aplicativo TwiML.

O endpoint no URL de retorno de chamada de status de Voice deve responder ao Twilio com um código de status HTTP 200, que permite que o Twilio saiba que a solicitação foi recebida com êxito. O Twilio enviará um aviso ao Debugger se a solicitação do Twilio receber um código de status não bem‐sucedido.

Configurar o tratamento de chamadas

Manuseio de chamadas outbound

As chamadas outbound de um aplicativo SDK do Voice devem ser tratadas por meio de um URL de Voice do aplicativo TwiML, e é por isso que o acesso de um usuário contém o SID para um aplicativo TwiML. Sempre que uma chamada outbound for iniciada a partir do aplicativo do usuário final, o Twilio enviará uma solicitação HTTP para o URL de Voice do aplicativo TwiML e esperará instruções do TwiML na resposta.

Se quiser usar um servidor HTTP para responder a essas solicitações, você pode usar uma biblioteca auxiliar para ajudá‐lo a gerar um TwiML válido de forma programática.

Manuseio de chamadas inbound

Se um aplicativo SDK do Voice lida com chamadas outbound e inbound com o mesmo aplicativo TwiML, o TwiML retornado pelo URL de Voice desse aplicativo TwiML pode ser idêntico para ambas as direções de chamada ou pode haver alguma lógica que cria dinamicamente o TwiML com base nas informações da chamada. A última estratégia é usada nos guias de Início rápido do SDK do Voice.

Enquanto as chamadas outbound do SDK do Voice devem ser tratadas por um aplicativo TwiML, as chamadas inbound não precisam ser associadas a um aplicativo TwiML. Em vez disso, você poderia usar um TwiML Bin (Repositório do TwiML), um Twilio Function, um servidor da Web etc., para fornecer o TwiML necessário para chamadas inbound. Nesses casos, você precisaria definir a configuração de voz dos números de telefone do Twilio com outro endpoint que atenda ao TwiML (em vez do aplicativo TwiML que deve ser usado para o tratamento de chamadas outbound).

Para conectar um autor da chamada a um usuário do SDK do Voice, você deve fornecer ao Twilio as instruções TwiML de <Dial><Client> (Discagem/Cliente) que incluem a identity do usuário do Voice SDK.

<Response>
  <Dial>
    <Client>SalesDepartment</Client>
  </Dial>    
</Response>
Classifique esta página:

Precisa de ajuda?

Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.

        
        
        

        Obrigado pelo seu feedback!

        Selecione o(s) motivo(s) para seu feedback. As informações adicionais que você fornece nos ajudam a melhorar nossa documentação:

        Enviando seu feedback...
        🎉 Obrigado pelo seu feedback!
        Algo deu errado. Tente novamente.

        Obrigado pelo seu feedback!

        thanks-feedback-gif