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

Menu

Expand
Calificar esta página:

SDK de Voice

El SDK de Twilio Voice Client se llamará SDK de Twilio Voice para JavaScript a partir de la versión 2.0.

Los SDK de Programmable Voice te permiten agregar llamadas de voz sobre IP (VoIP) directamente a tus aplicaciones web y móviles nativas.

Twilio proporciona tres SDK de Voice:

Inicios rápidos

Una vez que hayas decidido qué plataforma usar, explora lo que puedes hacer con Programmable Voice mediante una de las guías de inicio rápido de Twilio:

Crea una aplicación con el SDK de Voice

La creación de una aplicación con un SDK de Voice requiere del uso de varios recursos de Twilio. En esta sección, se explica cuáles son estos recursos y cómo funcionan junto con tu aplicación para permitir las llamadas de VoIP de Voice en tu navegador, app Electron o dispositivos iOS o Android. No se trata de una guía paso a paso, sino de una descripción general.

Aunque los SDK de Voice se utilizan para potenciar las aplicaciones del lado del cliente que el usuario final verá, deberás utilizar código del lado del servidor. El lado del servidor trabajará en conjunto con Twilio para permitir y administrar las llamadas hacia y desde tu aplicación del lado del cliente.

Cada SDK de Voice tiene su propia documentación en la que se explica cómo utilizar el SDK en el lado del cliente. Haz clic en un SDK a continuación para ver la documentación del lado del cliente.

En el resto de esta página se explica cómo tu aplicación del lado del servidor se comunica con Twilio y los SDK de Voice.

Requisitos

Para la creación de una aplicación con cualquiera de los SDK de Voice se deben cumplir los siguientes requisitos:

  • una cuenta de Twilio;
  • uno o más números de teléfono de Twilio;
  • un punto final que pueda manejar y responder a las peticiones HTTP de Twilio:
    • En el caso de algunas solicitudes de Twilio (como las enviadas cuando el número de teléfono de Twilio recibe una llamada entrante), se requerirá el envío de instrucciones Voice TwiML en la respuesta.
    • Otras solicitudes, como las de información sobre el estado, proporcionan a tu aplicación del lado del servidor información relacionada con las llamadas, grabaciones, etc. En el caso de estas solicitudes, Twilio solo espera un código de estado HTTP satisfactorio en respuesta.
  • AccessTokens (tokens de acceso), que contienen:
  • uno de los SDK de Voice;
  • una biblioteca auxiliar para generar AccessTokens y TwiML (según el caso de uso).

AccessTokens

Los AccessTokens (tokens de acceso) sirven como credenciales de los usuarios finales, y son la pieza clave que conecta la aplicación en la que usas el SDK, Twilio y tu aplicación del lado del servidor.

Los AccessTokens son JSON Web Tokens (JWT) que la aplicación puede crear mediante una biblioteca auxiliar. Un AccessToken contiene información que Twilio necesita para garantizar que:

  • las llamadas hacia y desde el SDK de Voice estén asociadas a la cuenta de Twilio correcta;
  • las llamadas entrantes estén activadas o desactivadas;
  • Twilio conozca la identidad del usuario final del SDK de Voice;
  • Twilio maneje las llamadas salientes desde la aplicación que utiliza el SDK de Voice mediante instrucciones TwiML apropiadas;
  • los AccessTokens caduquen en el momento adecuado.

Puesto que contienen tanta información necesaria, los AccessTokens son lo primero que debes revisar cuando la aplicación que utiliza el SDK de Voice encuentre un error. Puedes decodificar un AccessToken en JWT.io.

A continuación, se muestra la carga útil correctamente formada de un AccessToken perteneciente a un usuario final del SDK de Voice.

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

La propiedad grants.identity contiene la identidad del usuario final del SDK. Para conectar una llamada a este usuario del SDK en particular, utiliza esta identidad entre las etiquetas de apertura y cierre de <Client> (Cliente).

La propiedad grants.voice.incoming.allow está configurada en true, lo que permite al usuario final del SDK recibir llamadas.

La propiedad grants.voice.outgoing.application_sid contiene el SID de la app TwiML (consulta la sección Apps TwiML que aparece a continuación para obtener más información).

Un caso de uso típico del SDK de Voice se trata de la generación de AccessToken dentro de la aplicación del lado del servidor. En la siguiente situación de ejemplo se ilustra una forma en la que esto podría funcionar en la aplicación:

  1. La aplicación del lado del servidor tiene un punto final en http://www.example.com/token.
  2. La aplicación del lado del cliente envía una solicitud GET al punto final http://www.example.com/token para obtener un AccessToken.
  3. La aplicación del lado del servidor recibe la solicitud GET. Mediante una biblioteca auxiliar, la aplicación crea un AccessToken y lo envía en respuesta a la solicitud GET de la aplicación del lado del cliente.
  4. La aplicación del lado del cliente recibe el AccessToken.

Consulta la documentación de AccessTokens para obtener más información. Las aplicaciones de inicio rápido del SDK de Voice también tienen ejemplos de puntos finales /token que generan AccessTokens.

Apps TwiML

La propiedad grants.voice.outgoing.application_sid del AccessToken contiene el SID de una app TwiML. Una app TwiML es un recurso de Twilio que contiene direcciones URL de configuración de Voice y Messaging. Solo utilizarás las URL de configuración de Voice para la aplicación en la que uses el SDK de Voice.

Puedes crear y configurar apps TwiML a través de la consola (que se muestra en la siguiente imagen) o de la API.

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

La URL de solicitud de Voice (también llamada URL de Voice) es la URL a la que Twilio enviará una solicitud HTTP POST cuando necesite instrucciones Voice TwiML para gestionar una llamada. La URL de Voice podría apuntar a un contenedor TwiML, un punto final en un servidor web, un flujo de Studio, una Twilio Function, etc.

La URL de respaldo de Voice debe ser un punto final que pueda responder con instrucciones Voice TwiML. Si una solicitud a la URL de Voice falla por cualquier motivo (códigos de estado de nivel 400 o 500, por ejemplo), se intentará utilizar la URL de respaldo de Voice. Normalmente, este punto final debería responder con algunas instrucciones Voice TwiML como esta:

<Response>
  <Say>Lo sentimos. Se ha producido un error. Vuelva a intentar la llamada.</Say>
  <Hangup/>
</Response>

La URL de información sobre el estado de Voice es la URL a la que Twilio enviará solicitudes HTTP POST que proporcionan actualizaciones sobre la actividad relacionada con la app TwiML.

Con las llamadas del SDK de Voice, la URL de información sobre el estado de Voice recibirá una solicitud cuando el tramo principal de la llamada haya finalizado. El "tramo principal" es el tramo de la llamada que ha desencadenado una solicitud a la URL de Voice de la app TwiML. Todas las llamadas salientes del SDK de Voice activarán una solicitud a la URL de Voice de la app TwiML. Las llamadas entrantes que se gestionen con la misma app TwiML también activarán una solicitud a la URL de Voice de la app TwiML.

El punto final de la URL de información sobre el estado de Voice debería responder a Twilio con un código de estado HTTP 200, lo que permite a Twilio saber que la petición se ha recibido con éxito. Twilio enviará una advertencia a tu depurador si su solicitud recibe un código de estado no exitoso.

Configurar la gestión de llamadas

Gestionar llamadas salientes

Las llamadas salientes desde una aplicación que utiliza el SDK de Voice se deben gestionar a través de la URL de Voice de una app TwiML, razón por la cual el AccessToken del usuario contiene el SID de una app TwiML. Cada vez que se inicia una llamada saliente desde la aplicación del usuario final, Twilio enviará una solicitud HTTP a la URL de Voice de esa app TwiML y esperará instrucciones TwiML en la respuesta.

Si deseas utilizar un servidor HTTP para responder a estas solicitudes, puedes utilizar una biblioteca auxiliar que te ayude a generar instrucciones TwiML válidas mediante programación.

Gestionar llamadas entrantes

Si una aplicación que utiliza el SDK de Voice gestiona las llamadas entrantes y salientes con la misma app TwiML, la dirección URL de Voice de la app TwiML devuelta por dicha aplicación puede ser idéntica en ambas direcciones de llamada, o puede haber alguna lógica que cree de forma dinámica las instrucciones TwiML con base en la información de la llamada. Esta última estrategia se utiliza en los inicios rápidos del SDK de Voice.

Aunque las llamadas salientes desde el SDK de Voice se deben gestionar mediante una app TwiML, no es necesario asociar las llamadas entrantes a una app TwiML. En su lugar, podrías utilizar un contenedor TwiML, una Twilio Function, un servidor web, etc. a fin de proporcionar la instrucción TwiML necesaria para las llamadas entrantes. En estos casos, necesitarás ajustar la configuración de Voice de los números de teléfono de Twilio con otro punto final que sirva instrucciones TwiML (en lugar de la app TwiML que se debe utilizar para el manejo de llamadas salientes).

Para conectar al agente de llamada a un usuario del SDK de Voice, debes proporcionar a Twilio instrucciones TwiML de tipo <Dial><Client> en las que se incluya la propiedad identity del usuario del SDK de Voice.

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

¿Necesitas ayuda?

Todos la necesitamos a veces; la programación es difícil. Obtén ayuda ahora de nuestro equipo de soporte, o recurre a la sabiduría de la multitud visitando Stack Overflow Collective de Twilio o navegando por la etiqueta de Twilio en Stack Overflow.

        
        
        

        Gracias por tus comentarios.

        Selecciona los motivos de tus comentarios. La información adicional que nos brindas nos ayuda a mejorar nuestra documentación:

        Enviando tus comentarios…
        🎉 Gracias por tus comentarios.
        Se produjo un error. Inténtalo de nuevo.

        Gracias por tus comentarios.

        thanks-feedback-gif