Interconexión SIP

Puedes utilizar la API REST de OpenTok para conectar tu plataforma SIP a las sesiones de OpenTok. Esto te permite añadir el audio (y, opcionalmente, el vídeo) de una llamada SIP como un flujo en la sesión de OpenTok. El audio de los demás flujos de la sesión de OpenTok se mezcla y se envía a tu terminal SIP. Si incluye vídeo en la llamada SIP, los flujos de vídeo de los demás participantes (hasta 9) se organizan en una disposición en cuadrícula y se envían como un único flujo de vídeo a su terminal SIP.

La función de interconexión SIP solo es compatible con sesiones enrutadas (sesiones que utilizan el OpenTok Media Router).

Esta página incluye las siguientes secciones:

Introducción al SIP

OpenTok SIP Interconnect permite la interoperabilidad entre los terminales WebRTC y los sistemas de telefonía existentes, de modo que los usuarios puedan realizar llamadas basadas en SIP en contexto, al tiempo que navegan por el sitio web o la aplicación móvil.

Casos de uso previstos

Caso práctico del centro de contacto

  • Los clientes empresariales, como parte de su estrategia omnicanal de comunicaciones, están considerando WebRTC para que los usuarios finales puedan:

    • Utilizar navegadores o aplicaciones móviles para conectar con los centros de contacto, en lugar de utilizar sólo los teléfonos, con el fin de ofrecer una experiencia más ubicua y contextual.

    • Utiliza el vídeo y las herramientas de colaboración, además del audio, para mejorar la eficiencia y aumentar la satisfacción y la fidelización de los clientes.

Recurso de reserva de la red PSTN

  • Hay casos en los que no es posible conectarse mediante los clientes habituales de OpenTok:

    • Si uno de los participantes tiene un navegador que no admite WebRTC o
    • Si el cortafuegos es demasiado restrictivo

  • Si la conectividad a través de IP/OpenTok falla por los motivos mencionados anteriormente, los clientes necesitarán un mecanismo alternativo. OpenTok SIP Interconnect permite a los clientes realizar una llamada telefónica convencional durante una sesión de OpenTok. Para ello, los clientes deben configurar una pasarela SIP-PSTN.

Iniciar una llamada SIP

Para iniciar la llamada SIP, utiliza la API REST de OpenTok. Realiza una solicitud POST HTTPS a la siguiente URL:

https://api.opentok.com/v2/project/:apiKey/dial

Sustituir apiKey con tu clave API de OpenTok.

Fije el Content-Type encabezado a application/json. Establecer una configuración personalizada X-OPENTOK-AUTH encabezado a un token web JSON válido para su uso con las llamadas a la API REST de OpenTok. Consulta la sección sobre Autenticación de llamadas a la API REST de OpenTok.

Establezca el cuerpo de la solicitud en datos JSON con el siguiente formato:

{
  "sessionId": "OpenTok session ID",
  "token": "A valid OpenTok token",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "headers": {
      "headerKey": "headerValue"
    },
    "auth": {
      "username": "username",
      "password": "password"
    },
    "secure": true|false,
    "video": true|false,
    "observeForceMute": true|false,
    "streams": ["stream-id-1", "stream-id-2"]
  }
}

El objeto JSON incluye las siguientes propiedades:

  • sessionId​ (obligatorio) — El identificador de sesión de OpenTok de la llamada SIP a la que se desea unirse.

  • token​ (obligatorio) — El token de OpenTok que se utilizará para el participante al que se va a llamar. Puedes añadir un token data para determinar si el participante es un terminal SIP o para obtener otros datos identificativos, como números de teléfono. (Las bibliotecas de cliente de OpenTok incluyen propiedades que permiten examinar los datos de conexión de un cliente conectado a una sesión.) Consulte la Creación de fichas guía del desarrollador.

  • SIP uri ​(obligatorio): El URI SIP que se utilizará como destino de la llamada SIP iniciada desde OpenTok hacia tu plataforma SIP.

    Si el SIP uri contiene un transport=tls encabezado, la negociación entre Vonage y el terminal SIP se llevará a cabo de forma segura. Ten en cuenta que esto solo se aplicará a la negociación en sí, y no a la transmisión de audio. Si además deseas que la transmisión multimedia de audio (y de vídeo, si se incluye) esté cifrada, configura el secure propiedad a true.

    Este es un ejemplo de negociación de llamadas seguras:

    "sip:user@sip.partner.com;transport=tls"

    Este es un ejemplo de negociación de llamada insegura:

    "sip:user@sip.partner.com"

    También puede ajustar el transport encabezado a transport=tcp o transport=udp. El transporte por defecto es udp.

  • SIP from ​(opcional): El número o la cadena que se enviará al número SIP final como identificador de la persona que llama. Debe ser una cadena con el formato from@example.comdonde from puede ser una cadena o un número.

    Si from se establece en un número (por ejemplo, "14155550101@example.com"), aparecerá como número de origen en los teléfonos de la red PSTN. Si from no está definido o es una cadena (por ejemplo, "joe@example.com"), +00000000 aparecerá como número de origen en los teléfonos de la red PSTN.

    Si from no está definido, o se establece en una cadena (por ejemplo, "joe@example.com"), es decir, un número desconocido o no autorizado; en la mayoría de los casos, se convertirá en "Unknown" antes de que los proveedores SIP envíen la solicitud a un operador para su terminación en la RTPC. Dependiendo del proveedor, "Unknown" aparecerá como número entrante en los teléfonos RTC. En algunos casos, los proveedores pueden rechazar esas llamadas por motivos de seguridad, para evitar problemas como la falsificación de números. En el caso de que la llamada no sea rechazada por los proveedores, +00000000 aparecerá como número entrante en los teléfonos RTC.

    Un número se considera no reconocido cuando no es E.164 o no es un Número virtual de Vonage si se conecta a la dirección Voice API de Vonage, por ejemplo.

  • SIP headers​ (opcional) - Este objeto define las cabeceras personalizadas que se añadirán al SIP INVITE solicitud iniciada desde OpenTok hacia tu plataforma SIP.

  • SIP auth (opcional) — Este objeto contiene el username y password que se utilizará en el SIP INVITE Solicitud de autenticación HTTP Digest, si así lo exige tu plataforma SIP.

  • secure (opcional) — Un indicador booleano que indica si el contenido multimedia debe transmitirse cifrado (true) o no (false, el valor por defecto).

  • video (opcional) — Un indicador booleano que indica si la llamada SIP incluirá vídeo (true) o no (false, el valor predeterminado). Si se incluye vídeo, el vídeo del cliente SIP se incluye en el flujo de OpenTok que se envía a la sesión de OpenTok. El vídeo SIP está limitado a 480p a 800 kbps. El cliente SIP recibirá un flujo de vídeo compuesto dinámico a partir de los flujos publicados en la sesión de OpenTok.

  • observeForceMute (opcional) — Un indicador booleano que indica si el punto final SIP respeta modulación de silenciamiento forzado (true) o no (false, el valor por defecto). Además, con observeForceMute ajustado a true, la persona que llama puede pulsar «*6» para activar o desactivar el silencio del audio publicado. Para que la función de activación/desactivación del silencio mediante «*6» funcione, la persona que llama a través de SIP DEBE negociar los tonos DTMF según RFC 2833 (dígitos RFC 2833/RFC 4733). La función de activación y desactivación del silencio no es compatible con SIP INFO ni con los tonos DTMF en banda. Se reproduce un mensaje (en inglés) para la persona que llama cuando esta activa o desactiva el silencio, o cuando se silencia el cliente SIP mediante una acción de silencio forzado.

  • streams (opcional) - Una matriz de IDs de flujos para los flujos a incluir en la llamada SIP. Si no establece esta propiedad, todas las secuencias de la sesión se incluirán en la llamada. sesión se incluirán en la llamada.

Una llamada realizada correctamente devuelve una respuesta HTTP 200, en la que se incluyen el ID de conexión y el ID de flujo en los datos de la respuesta JSON:

{
  "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
  "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
  "streamId": "482bce73-f882-40fd-8ca5-cb74ff416036",
}

El objeto JSON incluye las siguientes propiedades:

  • id - Un ID único para la llamada SIP.

  • connectionId — El identificador de conexión de OpenTok correspondiente a la conexión de la llamada SIP en la sesión de OpenTok. Puedes utilizar este identificador de conexión para finalizar la llamada SIP mediante la API REST de OpenTok. Consulta la sección siguiente.

  • streamId — El identificador de transmisión de OpenTok correspondiente a la transmisión de la llamada SIP en la sesión de OpenTok.

La pasarela SIP de OpenTok envía un mensaje SIP estándar INVITE a la dirección que facilites en la llamada REST. Cuando su terminal SIP se conecta, se añade como una nueva conexión a la sesión de OpenTok, y su audio (y vídeo, si lo incluye) se añade a una nueva transmisión en la sesión de OpenTok. La nueva conexión se añade inmediatamente a la sesión de OpenTok sin esperar a que el terminal SIP reciba o acepte la llamada. En los clientes conectados a la sesión, el Client SDK de OpenTok envía eventos que indican la nueva conexión y el nuevo flujo (al igual que lo haría con otras conexiones y flujos de OpenTok). Los clientes pueden suscribirse al flujo, del mismo modo que se suscribirían a cualquier otro flujo de la sesión.

Finalizar una llamada SIP

La llamada finaliza cuando tu servidor SIP envía un BYE mensaje (para finalizar la llamada). También puedes finalizar una llamada utilizando el método de la API REST de OpenTok para desconectar a un cliente de una sesión. Utiliza el ID de conexión de la llamada SIP al invocar este método. (El método REST para iniciar la llamada SIP devuelve el ID de conexión como parte de los datos de la respuesta.)

Cuando finaliza la llamada SIP, también se interrumpen la conexión OpenTok y la transmisión de la llamada SIP. En cada cliente conectado a la sesión, el SDK de OpenTok del lado del cliente envía eventos que indican que la conexión y la transmisión han finalizado (al igual que lo haría cuando otros clientes se desconectan de la sesión).

La pasarela SIP de OpenTok finaliza automáticamente una llamada tras 5 minutos de inactividad (5 minutos sin recibir datos multimedia). Además, como medida de seguridad, la pasarela SIP de OpenTok cierra cualquier llamada SIP que dure más de 6 horas.

Envío de señales DTMF

Puedes enviar señales DTMF (multifrecuencia de doble tono) a terminales SIP mediante la API REST. Consulta Envío de dígitos DTMF a clientes SIP.

Los eventos de telefonía se negocian a través de SDP y se transmiten como dígitos RFC4733/RFC2833 al punto final remoto.

Seguimiento del progreso de la llamada

Regístrate para recibir notificaciones en tiempo real de los eventos relacionados con tu llamada SIP en tu servidor de aplicaciones.

Los desarrolladores pueden utilizar la API REST de OpenTok para conectar su plataforma SIP a las sesiones de OpenTok. Esto te permite añadir el audio (y el vídeo, si está incluido) de una llamada SIP como un flujo en la sesión de OpenTok. Gracias a la supervisión de llamadas SIP, los desarrolladores pueden supervisar el progreso de la llamada SIP desde su servidor de aplicaciones. Al registrarse para recibir notificaciones, tu URL de notificación recibirá solicitudes HTTP POST con información sobre el progreso de la llamada SIP.

Registro de funciones de devolución de llamada

La información sobre los eventos de llamadas SIP se puede registrar en puntos finales HTTP de tu servidor. Cada vez que se produce una actividad registrada, la infraestructura de OpenTok envía una solicitud HTTP a tu punto final.

Para registrar una URL de devolución de llamada:

  1. Visite su Página de cuenta de Video API de Vonage.

  2. Selecciona el proyecto de OpenTok para el que deseas registrar una llamada de retorno.

  3. Configura la URL de devolución de llamada en la sección «Supervisión SIP».

    Devoluciones de llamada seguras: Puedes proteger las solicitudes de devolución de llamada de los webhooks mediante devoluciones de llamada firmadas, utilizando un secreto de firma. Consulta Devoluciones de llamada seguras.

Supervisión de la actividad de las llamadas SIP

Una vez registrado correctamente, la infraestructura de OpenTok envía solicitudes HTTP para todas las llamadas SIP de un proyecto concreto. Esto resulta útil para realizar un seguimiento del progreso de las llamadas SIP y tomar medidas en caso de que se produzca un error. Debes esperar lo siguiente:

  • Al menos uno callCreated evento por llamada

  • Al menos uno callDestroyed evento por llamada

  • Un número indefinido de callUpdated eventos por llamada

  • Un número indefinido de muteForced eventos por llamada

Llamada Creada

Su endpoint recibirá el siguiente JSON por cada llamada SIP creada:

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456", 
  "event":  "callCreated",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

Véase Propiedades JSON a continuación para ver las descripciones.

Llamada actualizada

Tu punto final recibirá el siguiente JSON cada vez que se actualice el estado de cada llamada SIP:

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456",
  "event":  "callUpdated",
  "state":  "HANGUP",
  "timestamp":  1470257688309,
  "call": {
     "id":  "<conference-id>",
     "connectionId":  "<sip-ot-connection-id>",
     "createdAt":  1470257688143
  }
}

Véase Propiedades JSON a continuación para ver las descripciones.

Llamada Destruida

Su endpoint recibirá el siguiente JSON cuando finalice cada llamada SIP:

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456",
  "event":  "callDestroyed",
  "reason_code":  "400",
  "reason_message":  "Bad Request",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

Véase Propiedades JSON a continuación para ver las descripciones.

Silenciamiento forzado

Tu terminal recibirá el siguiente JSON cuando se silencie una llamada SIP debido a un Forzar el silenciamiento de un evento de moderación:

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456",
  "event":  "muteForced",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

Véase Propiedades JSON a continuación para ver las descripciones.

Ten en cuenta que debes configurar el observeForceMute (para true) al establecer la conexión SIP para que detecte un evento de moderación de silencio forzado.

Propiedades JSON de los eventos de supervisión SIP

El objeto JSON incluye las siguientes propiedades:

  • sessionId -- El ID de sesión asociado a este evento

  • projectId -- El ID del proyecto asociado a este evento

  • event -- callCreated | callUpdated | callDestroyed | muteForced

  • reason_code -- Para un callDestroyed evento, reason_code se establece en una de las siguientes opciones:

    • A código de respuesta SIP estándar para detectar errores en el protocolo de enlace SIP

    • 700 — «Cierre normal» — Este código indica que la llamada se está cerrando porque uno de los usuarios que participan en ella ha solicitado que se cierre.

    • 703 -- "Despeje inesperado" -- Esta causa indica que la llamada se está despejando inesperadamente.

    • 704 — «Media Timeout» — Este código indica que nuestro puente SIP no ha podido recibir ningún tráfico RTP procedente del otro terminal SIP.

    • 705 — «Duración máxima» — La llamada ha alcanzado la duración máxima.

    • 706 -- "Max Inactive" -- La llamada ha alcanzado la duración máxima de inactividad.

  • reason_message -- Para un callDestroyed evento, reason_message es una cadena que describe el motivo por el que se canceló la llamada.

  • state -- Para un callUpdated evento, state se establece en una de las siguientes opciones:

    • DIALING -- Se ha iniciado una llamada SIP

    • RINGING -- La llamada SIP está sonando en este momento

    • ON_HOLD -- La llamada SIP está en espera

    • ACTIVE -- Se ha contestado a una llamada SIP y está en curso

    • HANGUP -- Llamada SIP finalizada

  • timestamp -- La marca de tiempo del evento, en milisegundos desde la época Unix

  • call -- Un objeto que define la conexión y que contiene las siguientes propiedades:

    • id —- El ID de la conferencia

    • connectionId -- ID de conexión del cliente SIP

    • createdAt —- El valor de la marca de tiempo, en milisegundos desde la época Unix, correspondiente al momento en que se creó la llamada

Consideraciones de seguridad

Vonage recomienda seguir una serie de buenas prácticas al utilizar la interfaz SIP con tus servidores SIP. Su objetivo es mitigar los posibles ataques proporcionando mecanismos para autenticar y autorizar que las llamadas SIP recibidas en tu servidor sean legítimas, así como para cifrar toda la señalización y los datos multimedia:

  • Utilice TLS y active las llamadas seguras (SRTP) para la señalización, a fin de evitar la posibilidad de que se intercepten las comunicaciones.

  • Activa la autenticación SIP en tu servidor. De lo contrario, cualquier persona que conozca tu URI SIP podría enviar llamadas a tu servidor.

Póngase en contacto con nosotros si tienes alguna otra pregunta.

Detalles técnicos

Compatibilidad con RFC 3550 (RTP/RTCP): El tráfico multimedia puede estar cifrado (SRTP) o sin cifrar (RTP sin cifrar). En caso de cifrado, se admiten tanto el protocolo DTLS como el SDES.

Compatible con códecs: La pasarela SIP de OpenTok es compatible con los códecs de audio OPUS, G.711 y G.722; y con los códecs de vídeo H.264 y VP8. El vídeo SIP tiene una resolución máxima de 480p a 800 kbps.

Señalización: La pasarela SIP de OpenTok es compatible con el estándar RFC 3261 (SIP) a través de UDP, TCP y TLS. Ponte en contacto con Vonage si necesitas información o asistencia sobre cualquier extensión concreta.

La pasarela SIP de OpenTok rechazará cualquier mensaje SIP procedente de una plataforma SIP de terceros, a menos que forme parte de un diálogo SIP iniciado por la pasarela SIP de OpenTok. Las llamadas iniciadas con la pasarela SIP de OpenTok pueden ponerse en espera utilizando bien un re-­INVITE con el sendonly/inactive dirección en el SDP o un re-­INVITE con el puerto 0 en el SDP.

Otras consideraciones: La reproducción anticipada de archivos multimedia está desactivada.

Ejemplos de aplicaciones

Los SDK del servidor OpenTok para Node y PHP incluyen ejemplos de llamadas a la API OpenTok Dial que utilizan la funcionalidad de interconexión SIP de OpenTok. Consulta los ejemplos en:

A continuación encontrarás ejemplos de integraciones SIP que utilizan la interconexión SIP de OpenTok con Nexmo:

PREGUNTAS FRECUENTES

¿Qué es el SIP? ¿Por qué es importante el SIP?

El Protocolo de Iniciación de Sesión (SIP) es un protocolo de comunicaciones para la señalización y el control de sesiones de comunicación multimedia. Las aplicaciones más comunes del SIP son la telefonía por Internet para llamadas de voz y vídeo, así como la mensajería instantánea, a través de redes de Protocolo de Internet (IP).

En nuestro caso, se utiliza para establecer una llamada desde sesiones de OpenTok a un servidor SIP de terceros. Una vez establecida la llamada, el audio (y el vídeo, si lo hay) se envía mediante el protocolo RTP.

¿Cuál es la diferencia entre SIP y PSTN? ¿Ofrece OpenTok una pasarela PSTN?

La RTPC es la red telefónica tradicional. La RTC no es una red IP y no utiliza SIP, pero muchos proveedores, como Nexmo, tienen pasarelas para convertir los protocolos SIP en protocolos RTC. De ese modo, una llamada SIP sobre IP se convierte en una llamada telefónica.

En la práctica, aunque la Video API de Vonage no admita llamadas PSTN, podemos habilitarlas gracias a que admite llamadas SIP. A partir de ahí, solo es cuestión de encontrar un proveedor que convierta las llamadas SIP en llamadas PSTN.

¿Puedo llamar a teléfonos fijos con la función de interconexión SIP de OpenTok?

La interconexión SIP de OpenTok permite a los socios iniciar llamadas a cualquier terminal SIP. Para realizar o recibir llamadas desde o hacia un teléfono convencional, los clientes necesitan disponer de una pasarela que convierta la llamada SIP a los protocolos utilizados en las redes de telefonía móvil y fija.

¿Existe alguna forma de gestionar la marcación de salida o de entrada desde un número de teléfono normal (RTC)?

Con OpenTok SIP Interconnect, los clientes pueden realizar llamadas desde una sesión de OpenTok a cualquier destino SIP. Además, los clientes pueden configurar una pasarela SIP (propia o de terceros) para realizar llamadas a un número de teléfono convencional.

Aunque la API de interconexión SIP no admite llamadas SIP entrantes, los clientes pueden implementar la marcación desde un teléfono convencional (PSTN) utilizando una pasarela SIP (propia o de terceros) para conectar la llamada entrante recibida desde teléfonos convencionales con la llamada SIP saliente procedente de OpenTok. Puedes encontrar aplicaciones de ejemplo que muestran el caso de uso de las conferencias. aquí.

¿Admite la interconexión SIP de OpenTok el envío de vídeo?

Sí. Ajuste el video bandera a true al iniciar la llamada SIP utilizando el Método API REST. El vídeo SIP está limitado a 480p a 800 kbps.

¿Existe una diferencia notable en la calidad de audio percibida en el punto final WebRTC frente al punto final SIP?

La expectativa es tener la misma calidad, aunque con latencia adicional en el punto final SIP.

¿Cómo funciona la función de archivado con OpenTok SIP Interconnect?

La función de archivo funciona exactamente igual que en la actualidad para una sesión de WebRTC. Se incluirán en el archivo hasta 16 flujos de vídeo y los primeros 50 flujos de audio, incluidos los flujos de audio y vídeo SIP.

¿Cómo navega el usuario por el IVR? Habrá un teclado de marcación en la aplicación web/móvil?

Puedes utilizar la API REST para enviar señales DTMF a clientes SIP con el fin de dar soporte a los sistemas de respuesta de voz interactiva (IVR). Consulta Envío de señales DTMF.

¿Con qué servidores SIP es compatible OpenTok SIP Interconnect?

Hemos probado la interoperabilidad con algunos de los equipos de telecomunicaciones más populares (ACME packet, Broadsoft), algunas plataformas SIP populares (Nexmo, y otros), y el servidor SIP de código abierto más popular (freeswitch). Es imposible garantizar la interoperabilidad con todos y cada uno de los servidores SIP, pero intentamos limitar el uso de extensiones/características SIP para reducir las posibilidades de fallo. Hasta ahora, nunca hemos tenido que cambiar nuestra solución para interoperar con ningún nuevo servidor SIP.

¿Cómo se puede desconectar una llamada dirigida a un cliente SIP conectado a una sesión de OpenTok?

  • Uso de la API de cliente existente: un cliente web (JavaScript) conectado a una sesión de OpenTok con privilegios de moderador puede obligar a otros clientes, incluidos los clientes SIP, a desconectarse de una sesión.

  • Utilización de la API REST para la moderación del lado del servidor — Si los clientes WebRTC se encuentran en dispositivos móviles o si el cliente no desea conceder privilegios de moderador a los clientes, los servidores de aplicaciones pueden enviar una solicitud HTTP DELETE a un cliente conectado para forzar la desconexión desde el lado del servidor.

Problema conocido

Cuando se realiza una videollamada SIP a un cliente SIP de Linphone y la videollamada se negocia con el códec VP8, el vídeo entrante desde Linphone a la pasarela SIP de OpenTok se muestra como fotogramas negros.