Introdução ao SIP

A Interconexão SIP da Vonage permite a interoperabilidade entre terminais WebRTC e sistemas de telefonia existentes, para que os usuários possam fazer chamadas baseadas em SIP no contexto em que estão, enquanto navegam simultaneamente no site ou no aplicativo móvel.

Você pode usar a API REST para conectar sua plataforma SIP às sessões. Isso permite que você adicione áudio (e, opcionalmente, vídeo) de uma chamada SIP como um fluxo na sessão. O áudio de outros fluxos na sessão é mixado e enviado para o seu terminal SIP. Se você incluir vídeo na chamada SIP, os vídeos dos fluxos dos outros participantes (até 9) são organizados em um layout de grade e enviados como um único fluxo de vídeo para o seu terminal SIP.

O recurso de interconexão SIP é compatível apenas com sessões roteadas (sessões que utilizam o Roteador de mídia).

Casos de uso-alvo

Caso de uso de central de atendimento

Os clientes corporativos, como parte de sua estratégia omnicanal de comunicação, estão considerando o WebRTC para que os usuários finais possam:
- Utilize navegadores ou Applications móveis para se conectar a centrais de atendimento, em vez de usar apenas telefones, a fim de proporcionar uma experiência mais onipresente e contextual
- Utilize vídeo e ferramentas de colaboração, além do áudio, para melhorar a eficiência e aumentar a satisfação e a retenção dos clientes

Recurso de fallback para PSTN

Há casos em que não é possível estabelecer conexão usando os Clients SDK padrão:
- Se um dos participantes tiver um navegador que não seja compatível com WebRTC ou
- Se o firewall for muito restritivo
Caso a conectividade via IP/Vonage falhe devido aos motivos mencionados acima, os clientes precisarão de um mecanismo alternativo. A interconexão SIP permite que os clientes façam uma chamada telefônica comum durante uma sessão. Para isso, os clientes devem configurar um gateway SIP-PSTN.

Iniciando uma chamada SIP

Para iniciar a chamada SIP, use a API REST. Envie uma solicitação POST via HTTPS para a seguinte URL:

/v2/project/:app-id/dial

Substituir :app-id com o seu ID do aplicativo.

Defina o Content-Type cabeçalho para application/json. Além disso, defina um cabeçalho de autenticação de portador, por exemplo: Authorization: Bearer <token> onde <token> é um JWT token gerado usando o seu credenciais.

Defina o corpo da solicitação com dados JSON no seguinte formato:

{
  "sessionId": "session ID",
  "token": "A valid 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
  }
}

O objeto JSON inclui as seguintes propriedades:

sessionId (obrigatório) — O ID da sessão da chamada SIP à qual se deseja ingressar.
token (obrigatório) — O token a ser usado para o participante que está sendo chamado. É possível adicionar dados ao token para identificar se o participante é um terminal SIP ou para outros dados de identificação, como números de telefone. (As bibliotecas de cliente incluem propriedades para inspecionar os dados de conexão de um cliente conectado a uma sessão.) Consulte o Criação de tokens guia.
SIP uri (obrigatório): O URI SIP a ser usado como destino da chamada SIP iniciada pela Vonage para a sua plataforma SIP.

Se o SIP uri contém um transport=tls cabeçalho, a negociação entre a Vonage e o terminal SIP será realizada de forma segura. Observe que isso se aplica apenas à negociação em si, e não à transmissão de áudio. Se você também desejar que a transmissão de mídia de áudio (e vídeo, se houver) seja criptografada, defina o secure propriedade para true.

Este é um exemplo de negociação de chamada segura:

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

Este é um exemplo de negociação de chamada não segura:

"sip:user@sip.partner.com"

Você também pode definir o transport cabeçalho para transport=tcp ou transport=udp. O transporte padrão é udp.

SIP from (opcional): O número ou sequência de caracteres que será enviado ao número SIP final como o autor da chamada. Deve ser uma sequência de caracteres no formato from@example.com, onde from pode ser uma sequência de caracteres ou um número.

Se from é definido como um número (por exemplo, "14155550101@example.com"), ele aparecerá como o número de origem nos telefones da rede PSTN. Se from não está definido ou está definido como uma string (por exemplo, "joe@example.com"), +00000000 aparecerá como o número de origem nos telefones da rede PSTN.

Se from não está definido ou está definido como uma string (por exemplo, "joe@example.com"), ou seja, um número desconhecido ou não autorizado; na maioria dos casos, ele será convertido para "Unknown" antes que a solicitação seja encaminhada a uma operadora para terminação na PSTN por provedores SIP. Dependendo do provedor, "Unknown" aparecerá como o número de origem nos telefones PSTN. Em alguns casos, as operadoras podem rejeitar essas chamadas por motivos de segurança, para evitar problemas como a falsificação de números. Caso a chamada não seja rejeitada pelas operadoras, +00000000 aparecerá como o número de origem nos telefones PSTN.

Um número é considerado não reconhecido quando não está em conformidade com a norma E.164 ou não é um Número virtual da Vonage se estiver conectando ao o Voice API da Vonage, por exemplo.

SIP headers (opcional) — Este objeto define cabeçalhos personalizados a serem adicionados ao SIP INVITE solicitação iniciada pelo OpenTok para sua plataforma SIP.
SIP auth (opcional) — Este objeto contém o username e password para ser usado no SIP INVITE solicitação de autenticação HTTP Digest, caso seja exigida pela sua plataforma SIP.
secure (opcional) — Um indicador booleano que indica se a mídia deve ser transmitida criptografada (true) ou não (false, o padrão).

Uma chamada bem-sucedida resulta em uma resposta HTTP 200, com o ID da conexão e o ID do fluxo incluídos nos dados da resposta JSON:

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

video (opcional) — Um indicador booleano que indica se a chamada SIP incluirá vídeo (true) ou não (false, (padrão). Quando há vídeo, o vídeo do cliente SIP é incluído no fluxo da Vonage enviado para a sessão. O vídeo SIP está limitado a 480p a 800 kbps. O cliente SIP receberá um fluxo de vídeo composto dinamicamente a partir dos fluxos publicados na sessão.
observeForceMute (opcional) — Um sinalizador booleano que indica se o ponto final SIP observa force mute moderation (true) ou não (false, o padrão). Além disso, com observeForceMute definir como true, o chamador pode pressionar “*6” para ativar ou desativar o som do áudio transmitido. Para que a função de ativação/desativação de som com “*6” funcione, o chamador SIP DEVE negociar DTMFs conforme a RFC 2833 (dígitos RFC 2833/RFC 4733). A alternância de mudo não é compatível com SIP INFO ou DTMFs em banda. Uma mensagem (em inglês) é reproduzida para o chamador quando ele ativa ou desativa o mudo, ou quando o cliente SIP é silenciado por meio de uma ação de silenciamento forçado.
streams (opcional) — Uma matriz de IDs de fluxos a serem incluídos na chamada SIP. Se essa propriedade não for definida, todos os fluxos da sessão serão incluídos na chamada.

Uma chamada bem-sucedida resulta em uma resposta HTTP 200, com o ID da conexão e o ID do fluxo incluídos nos dados da resposta JSON:

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

O objeto JSON inclui as seguintes propriedades:

id — Um identificador único para a chamada SIP.
connectionId — O ID da conexão da chamada SIP na sessão. É possível usar esse ID de conexão para encerrar a chamada SIP por meio da API REST. Consulte a próxima seção.

streamId — O ID do fluxo da chamada SIP na sessão.

O gateway SIP envia um SIP padrão INVITE para o endereço que você fornecer na chamada REST. Quando seu terminal SIP se conecta, ele é adicionado como uma nova conexão à sessão, e seu áudio (e vídeo, se houver) é adicionado a um novo fluxo na sessão. A nova conexão é adicionada imediatamente à sessão, sem esperar que o terminal SIP receba ou aceite a chamada. Nos clientes conectados à sessão, o Client SDK envia eventos indicando a nova conexão e o novo fluxo (da mesma forma que faria para outras conexões e fluxos). Os clientes podem se inscrever no fluxo, da mesma forma que se inscreveriam em qualquer outro fluxo na sessão.

Encerramento de uma chamada SIP

A chamada é encerrada quando o servidor SIP envia uma mensagem BYE (para encerrar a chamada). Você também pode encerrar uma chamada usando o método da API REST para desconectar um cliente de uma sessão. Utilize o ID de conexão da chamada SIP ao chamar este método. (O método REST para iniciando o SIP A chamada retorna o ID da conexão como parte dos dados da resposta.)

Quando a chamada SIP é encerrada, a conexão e o fluxo da chamada SIP também são encerrados. Em cada cliente conectado à sessão, o Client SDK envia eventos indicando que a conexão e o fluxo foram encerrados (da mesma forma que ocorreria quando outros clientes se desconectassem da sessão).

O gateway SIP da Vonage encerra automaticamente uma chamada após 5 minutos de inatividade (5 minutos sem recepção de dados de mídia). Além disso, como medida de segurança, o gateway SIP da Vonage encerra qualquer chamada SIP que dure mais de 6 horas.

Envio de sinais DTMF

É possível enviar sinais DTMF (multifrequência de dois tons) para terminais SIP usando a API REST. Consulte Envio de dígitos DTMF para clientes SIP.

Os eventos de telefonia são negociados por meio do SDP e transmitidos como dígitos RFC4733/RFC2833 para o terminal remoto.

Acompanhamento do andamento da chamada

Cadastre-se para receber chamadas de retorno em tempo real relacionadas à sua chamada SIP no servidor do seu aplicativo.

Os desenvolvedores podem usar a API REST da Vonage para conectar sua plataforma SIP às sessões. Isso permite adicionar áudio (e vídeo, se houver) de uma chamada SIP como um fluxo na sessão.

Com o monitoramento de chamadas SIP, os desenvolvedores podem acompanhar o andamento da chamada SIP diretamente do servidor de aplicativos. Ao se cadastrar para receber callbacks, sua URL de callback receberá solicitações HTTP POST com informações sobre o andamento da chamada SIP.

Registrando callbacks

As informações sobre eventos de chamadas SIP podem ser registradas em pontos de extremidade HTTP no seu servidor. Sempre que ocorrer uma atividade registrada, uma solicitação HTTP é enviada da infraestrutura da Vonage para o seu ponto de extremidade.

Para registrar uma URL de retorno de chamada:

Visite o seu Account da Video API da Vonage página.
Selecione o projeto para o qual você deseja registrar um retorno de chamada.
Defina a URL de retorno de chamada na seção “Monitoramento SIP”.

Monitoramento da atividade de chamadas SIP

Depois de devidamente registrada, a infraestrutura envia solicitações HTTP para todas as chamadas SIP de um projeto específico. Isso é útil para acompanhar o andamento das chamadas SIP e tomar medidas caso ocorra um erro. Você deve esperar:

Pelo menos um callCreated evento por chamada
Pelo menos um callDestroyed evento por chamada
Um número indefinido de callUpdated eventos por chamada
Um número indefinido de muteForced eventos por chamada

Chamada criada

Seu endpoint receberá o seguinte JSON para cada chamada SIP criada:

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

Veja Propriedades JSON Veja abaixo as descrições.

Atualização da chamada

Seu endpoint receberá o seguinte JSON sempre que o estado de cada chamada SIP for atualizado:

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

Veja Propriedades JSON Veja abaixo as descrições.

Chamada interrompida

Seu endpoint receberá o seguinte JSON quando cada chamada SIP for encerrada:

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

Veja Propriedades JSON Veja abaixo as descrições.

Silenciamento forçado

Seu endpoint receberá o seguinte JSON quando uma chamada SIP for silenciada devido a um evento de moderação de silenciamento forçado:

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

Veja Propriedades JSON Veja abaixo as descrições.

Observe que é necessário definir o observeForceMute opção (para true) ao criar a conexão SIP, para que ela reconheça um evento de moderação com silenciamento forçado.

Propriedades JSON dos eventos de monitoramento SIP

O objeto JSON inclui as seguintes propriedades:

sessionId -- O ID da sessão associado a este evento
applicationId -- O ID do projeto associado a este evento
event -- callCreated | callUpdated | callDestroyed | muteForced
reason_code -- Para um callDestroyed evento, reason_code está definido como um dos seguintes valores:
- A código de resposta SIP padrão para detectar erros no handshake do SIP
- 700 — “Encerramento normal” — Esta causa indica que a chamada está sendo encerrada porque um dos usuários envolvidos na chamada solicitou o encerramento da mesma.
- 703 — “Encerramento inesperado” — Essa causa indica que a chamada está sendo encerrada inesperadamente.
- 704 — “Media Timeout” — Esse código indica que nossa ponte SIP não conseguiu receber nenhum tráfego RTP do outro terminal SIP.
- 705 — “Duração máxima” — A chamada atingiu a duração máxima.
- 706 — “Max Inactive” — A chamada atingiu o tempo máximo de inatividade.
reason_message -- Para um callDestroyed evento, reason_message é uma sequência de caracteres que descreve o motivo pelo qual a chamada foi cancelada.
state -- Para um callUpdated evento, state está definido como um dos seguintes valores:
- DIALING -- A chamada SIP foi iniciada
- RINGING -- A chamada SIP está tocando no momento
- ON_HOLD -- A chamada SIP está em espera
- ACTIVE -- Uma chamada SIP foi atendida e está em andamento
- HANGUP -- Uma chamada SIP concluída
timestamp -- O carimbo de data e hora do evento, em milissegundos desde a época Unix
call -- Um objeto que define a conexão, contendo as seguintes propriedades:
- id —- O ID da conferência
- connectionId —- O ID de conexão do cliente SIP
- createdAt —- O valor do carimbo de data/hora, em milissegundos desde a época Unix, correspondente ao momento em que a chamada foi criada

Considerações sobre segurança

Existem algumas práticas recomendadas pela Vonage para o uso da interface SIP com seus servidores SIP. Elas visam mitigar possíveis ataques, fornecendo mecanismos para autenticar e autorizar que as chamadas SIP recebidas em seu servidor sejam legítimas e para criptografar toda a sinalização e mídia:

Utilize o TLS e habilite chamadas seguras (SRTP) para a sinalização, a fim de evitar a possibilidade de interceptação das comunicações.
Habilite a autenticação SIP no seu servidor. Caso contrário, qualquer pessoa que conheça seu URI SIP poderá enviar chamadas para o seu servidor.

Entre em contato conosco caso tenha mais perguntas.

Detalhes técnicos

Suporte ao RFC 3550 (RTP/RTCP): O tráfego de mídia pode ser criptografado (SRTP) ou não criptografado (RTP simples). No caso de criptografia, os protocolos DTLS e SDES são compatíveis.

Suporte a codecs: O gateway SIP da Vonage é compatível com os codecs de áudio OPUS, G.711 e G.722, além dos codecs de vídeo H.264 e VP8. O vídeo SIP está limitado a 480p a 800 kbps.

Sinalização: O gateway SIP da Vonage é compatível com a norma RFC 3261 (SIP) sobre UDP, TCP e TLS. Entre em contato com a Vonage caso precise de informações ou suporte para qualquer ramal específico.

O gateway SIP da Vonage rejeitará qualquer mensagem SIP proveniente de uma plataforma SIP de terceiros, a menos que faça parte de um diálogo SIP iniciado pelo próprio gateway SIP da Vonage. As chamadas iniciadas pelo gateway SIP da Vonage podem ser colocadas em espera usando um re-INVITE com o sendonly/inactive direção no SDP ou um re-INVITE com a porta 0 no SDP.

Outras considerações: A mídia inicial está desativada.

Perguntas frequentes

O que é o SIP? Por que o SIP é importante?

O Protocolo de Iniciação de Sessão (SIP) é um protocolo de comunicação destinado à sinalização e ao controle de sessões de comunicação multimídia. As aplicações mais comuns do SIP são na telefonia pela Internet para chamadas de voz e vídeo, bem como em mensagens instantâneas, em redes de Protocolo de Internet (IP).

No nosso caso, ele é usado para estabelecer uma chamada a partir do Sessions para um servidor SIP de terceiros. Assim que a chamada é estabelecida, o áudio (e o vídeo, se houver) é enviado usando o protocolo RTP.

Qual é a diferença entre SIP e PSTN? A Vonage oferece um gateway PSTN?

A PSTN é a rede telefônica tradicional. A PSTN não é uma rede IP e não utiliza o protocolo SIP, mas muitos provedores, como a Nexmo, dispõem de gateways para converter protocolos SIP em protocolos PSTN. Dessa forma, uma chamada SIP por IP é convertida em uma chamada telefônica.

Na prática, mesmo que a Video API da Vonage não ofereça suporte a chamadas PSTN, conseguimos fazer isso ao oferecer suporte a chamadas SIP. A partir daí, basta encontrar um provedor que converta as chamadas SIP em chamadas PSTN.

Posso ligar para telefones comuns usando o recurso de interconexão SIP?

A interconexão SIP da Vonage permite que os parceiros iniciem chamadas para qualquer terminal SIP. Para fazer ou receber chamadas de um telefone comum, os clientes precisam de um gateway para converter a chamada SIP nos protocolos utilizados nas redes de telefonia móvel ou fixa.

Existe alguma maneira de lidar com chamadas feitas para ou recebidas de um número de telefone comum (PSTN)?

Com a interconexão SIP, os clientes podem fazer chamadas externas a partir de uma sessão para qualquer destino SIP. Além disso, os clientes podem configurar um gateway SIP (próprio ou de terceiros) para fazer chamadas externas para um número de telefone comum.

Embora a API de interconexão SIP não ofereça suporte a chamadas SIP recebidas, os clientes podem implementar a discagem a partir de um telefone comum (PSTN) utilizando um gateway SIP (próprio ou de terceiros) para conectar a chamada recebida de telefones comuns à chamada SIP de saída proveniente da Vonage.

O SIP Interconnect suporta o envio de vídeo?

Sim. Defina o video bandeira para true ao iniciar a chamada SIP usando o Método da API REST. O vídeo SIP está limitado a 480p a 800 kbps.

Existe uma diferença perceptível na qualidade de áudio percebida entre o terminal WebRTC e o terminal SIP?

A expectativa é que a qualidade seja a mesma, embora haja uma latência adicional no terminal SIP.

Como funciona o recurso de arquivamento com o SIP Interconnect?

O recurso de arquivamento funciona exatamente da mesma forma que funciona hoje para uma sessão WebRTC. Até 16 fluxos de vídeo e os primeiros 50 fluxos de áudio, incluindo fluxos de áudio e vídeo SIP, farão parte do arquivo.

Como o usuário navega pelo IVR? Haverá um teclado numérico no aplicativo web/móvel?

É possível usar a API REST para enviar sinais DTMF a clientes SIP, a fim de oferecer suporte a sistemas de Resposta Interativa de Voz (IVR). Consulte Envio de sinais DTMF.

Com quais servidores SIP o SIP Interconnect é compatível?

Testamos a interoperabilidade com alguns dos equipamentos de telecomunicações mais populares (ACME Packet, Broadsoft), algumas plataformas SIP populares (Nexmo e outras) e o servidor SIP de código aberto mais popular (Freeswitch). É impossível garantir a interoperabilidade com todos os servidores SIP, mas tentamos limitar o uso de extensões/recursos SIP para reduzir as chances de falha. Até o momento, nunca precisamos alterar nossa solução para garantir a interoperabilidade com nenhum novo servidor SIP.

Como é possível encerrar uma chamada para um cliente SIP conectado a uma sessão?

Utilizando a API do cliente existente — Um cliente Web (JavaScript) conectado a uma sessão com privilégios de moderador pode forçar outros clientes, incluindo clientes SIP, a se desconectarem da sessão.

Utilização da API REST para moderação do lado do servidor — Se os clientes WebRTC estiverem em dispositivos móveis ou se o cliente não quiser conceder privilégios de moderador aos clientes, os servidores de aplicativos podem enviar uma solicitação HTTP DELETE a um cliente conectado para forçar o desligamento do lado do servidor.