SIP de entrada

O SIP de entrada permite que um cliente SIP, como um softphone ou um tronco SIP, ligue para um dos seus números Turn.io. O Turn atende essas chamadas da mesma forma que atende as chamadas de WhatsApp desse número: com o agente de IA, a sala de espera ou um operador na caixa de entrada.

Esta página é para quem configura clientes SIP. Ela cobre o servidor, as credenciais, o TLS, o SRTP e os codecs que o Turn espera, e como uma chamada se comporta depois de conectada.

Versão alfa

O SIP de entrada está em fase alfa e sujeito a alterações. Requisitos, limites e comportamento podem mudar em versões futuras.

info

O SIP de entrada é liberado por um sinalizador de recurso (feature flag). Para usá-lo nos seus números, peça acesso em support@turn.io.

Resumo

Configuração	Valor
Servidor	sip.turn.io, porta 5061
Transporte	TLS 1.2 ou superior, com uma cifra ECDHE. Sem UDP nem TCP sem criptografia
Autenticação	Digest SIP, MD5, qop=auth, realm turn.io
Nome de usuário	O endereço do número, como +15551230000
Endereço para discar	sip:+15551230000@sip.turn.io;transport=tls
Mídia	SRTP com chaves SDES (a=crypto), perfil RTP/SAVP
Codecs	G.711 μ-law (PCMU, payload type 0) ou A-law (PCMA, payload type 8)
DTMF	RFC 4733 telephone-event, payload type 101
Portas de mídia	UDP 30000 a 30096, no endereço da resposta SDP do Turn
Direção	Somente chamadas de entrada

Como ativar

1. No Turn, abra Configurações do número, depois Chamadas, e encontre a seção SIP de entrada. Somente administradores podem alterá-la.
2. Ative Ativar SIP de entrada.
3. Em Senha SIP, clique em Gerar e copie a senha. Ela é exibida uma única vez: o Turn guarda apenas um hash digest dela, por isso não consegue exibi-la de novo. Você também pode digitar a sua própria senha. Uma senha nova substitui a antiga imediatamente.
4. Copie o Nome de usuário SIP. Ele é o endereço do número, incluindo o + inicial.

Enquanto o número não tiver uma senha SIP, o Turn recusa as chamadas para ele com 403 Forbidden.

O restante da página Chamadas decide quem atende: atendimento por IA, sala de espera, agendamentos e operadores. As chamadas SIP seguem as mesmas configurações das chamadas de WhatsApp do número.

Sinalização

Servidor e TLS

Conecte-se a sip.turn.io na porta 5061 por TLS. O Turn não aceita SIP por UDP nem por TCP sem criptografia.

• O Turn aceita TLS 1.2 e superior, somente com cifras com sigilo direto (ECDHE).
• O certificado é de uma autoridade pública e emitido para sip.turn.io. Verifique-o como faria com qualquer outro. Ele é apresentado com ou sem SNI.
• O Turn não pede certificado de cliente.
• Mantenha a conexão TLS aberta durante toda a chamada. O Turn envia as requisições da chamada, como o BYE quando o agente de IA encerra a chamada, pela conexão em que o seu INVITE chegou. Ele nunca abre uma conexão até você, então o seu cliente não precisa ser acessível pela internet.
• Uma conexão sem sinalização por uma hora é fechada. Se as suas chamadas puderem durar mais do que isso, envie OPTIONS como keep-alive. O Turn responde OPTIONS com 200 OK sem pedir credenciais.

Autenticação

O Turn desafia todo INVITE com 401 Unauthorized:

WWW-Authenticate: Digest realm="turn.io", nonce="…", qop="auth"

Responda ao desafio com estas credenciais:

Campo	Valor
Nome de usuário	O Nome de usuário SIP do Turn, como +15551230000
Senha	A Senha SIP que você gerou ou definiu
Realm	turn.io

O Turn não autentica por endereço IP, então não precisa saber de onde vêm as suas chamadas. Num tronco SIP, configure o Turn como um peer no qual você se autentica com essas credenciais.

O registro é opcional. O Turn aceita um REGISTER para o endereço do número (o nome de usuário SIP como address of record) com as mesmas credenciais e responde 200 OK. Ele nunca faz chamadas para um cliente registrado, então registre apenas se o seu cliente exigir.

Endereçamento

Duas partes do INVITE importam:

• A parte de usuário da Request-URI escolhe o número do Turn. Ela precisa ser exatamente igual ao nome de usuário SIP do número, incluindo o +: sip:+15551230000@sip.turn.io;transport=tls. Um endereço que não corresponde a nenhum número recebe 404 Not Found. Um número com o SIP de entrada desativado recebe 403 Forbidden.
• A parte de usuário do From é quem liga. Ela precisa ser um número de telefone: dígitos com um + inicial opcional, de preferência no formato E.164. O Turn registra a chamada no contato com esse número, e cria o contato se ele não existir, como faz com uma chamada de WhatsApp. Qualquer outra coisa, como alice, recebe 400 Bad Request.

Um tronco SIP normalmente coloca o número de quem liga (caller ID) no From, que é o que o Turn espera. Um softphone normalmente coloca ali o nome de usuário da conta. Com o nome de usuário SIP do Turn como nome de usuário da conta, as chamadas são registradas no próprio endereço do número. Para ligar como outro número de telefone, defina o nome de usuário da conta do softphone como esse número e o nome de usuário de autenticação (muitas vezes chamado "auth ID" ou "auth user") como o nome de usuário SIP do Turn. Deixe o registro desativado, porque só o próprio endereço do número pode se registrar.

Mídia

SRTP

O SRTP é obrigatório. Ofereça RTP/SAVP (ou RTP/SAVPF) com chaves SDES em linhas a=crypto (RFC 4568). As chaves trafegam dentro da sinalização protegida por TLS.

O Turn escolhe a primeira linha a=crypto da sua oferta que ele suporta e responde com uma linha, com a mesma tag e a mesma suíte e uma chave própria. Ele suporta estas suítes:

• AES_CM_128_HMAC_SHA1_80
• AES_CM_128_HMAC_SHA1_32
• AEAD_AES_128_GCM
• AEAD_AES_256_GCM

O Turn ignora linhas que não consegue honrar exatamente: uma suíte desconhecida, uma chave com MKI (|1:4) ou mais de uma chave, ou parâmetros de sessão como KDR ou UNENCRYPTED_SRTP. Um tempo de vida (lifetime) da chave é aceito. Ofereça pelo menos uma linha simples, como:

a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:<chave e salt em base64>

O Turn recusa estas ofertas com 488 Not Acceptable Here:

• RTP sem criptografia (RTP/AVP), mesmo com linhas a=crypto. O SRTP é negociado pelo perfil da linha m=.
• DTLS-SRTP (UDP/TLS/RTP/SAVP com fingerprint).
• RTP/SAVP sem nenhuma linha a=crypto que o Turn possa usar.

O Turn não envia nem lê RTCP.

Codecs

O Turn fala apenas G.711. Ele responde com o primeiro entre PCMU (payload type 0) e PCMA (payload type 8) na ordem da sua oferta, mais telephone-event (payload type 101). Outros codecs na oferta não atrapalham, mas o Turn não os escolhe. Uma oferta sem nenhuma das duas leis G.711, como apenas Opus ou G.722, recebe 488 Not Acceptable Here.

• Envie pacotes de 20 ms. O Turn envia pacotes de 20 ms.
• O INVITE precisa trazer a oferta SDP. Um INVITE sem ela (late offer) recebe 488 Not Acceptable Here.
• O Turn aceita DTMF RFC 4733, mas não age sobre as teclas pressionadas.

Aqui está uma oferta que o Turn aceita, e a resposta dele:

m=audio 40000 RTP/SAVP 8 0 101
a=rtpmap:8 PCMA/8000
a=rtpmap:0 PCMU/8000
a=rtpmap:101 telephone-event/8000
a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:<sua chave>
a=ptime:20
a=sendrecv

c=IN IP4 203.0.113.11
m=audio 30012 RTP/SAVP 8 101
a=rtpmap:8 PCMA/8000
a=rtpmap:101 telephone-event/8000
a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:<chave do Turn>
a=sendrecv

Portas, NAT e firewalls

• Envie o seu áudio para o endereço e a porta da resposta SDP do Turn. O endereço de mídia não é o endereço para o qual sip.turn.io resolve, então libere UDP de saída para o endereço do c= da resposta nas portas 30000 a 30096. Cada chamada recebe uma porta nessa faixa.
• O Turn usa RTP simétrico: ele envia o áudio dele para o endereço e a porta de onde vem o seu áudio, e não para os do seu SDP. Um cliente atrás de NAT funciona sem STUN nem ICE, desde que envie e receba pela mesma porta. O Turn não usa ICE.
• Envie RTP continuamente a partir do momento em que a chamada é atendida, inclusive durante o silêncio. O Turn desliga uma chamada quando não recebe áudio por 30 segundos. Desative a supressão de silêncio (VAD) e não coloque a chamada em espera de um jeito que interrompa o seu RTP, como a=inactive.

Fluxo da chamada

Cliente                                    Turn
  |------ INVITE (oferta SDP) --------------->|
  |<----- 401 Unauthorized -------------------|
  |------ ACK ------------------------------->|
  |------ INVITE (oferta SDP, credenciais) -->|
  |<----- 100 Trying -------------------------|
  |<----- 180 Ringing ------------------------|
  |                … tocando …                |
  |<----- 200 OK (resposta SDP) --------------|
  |------ ACK ------------------------------->|
  |<========== SRTP, nos dois sentidos ======>|
  |------ BYE (ou o Turn envia BYE) --------->|
  |<----- 200 OK -----------------------------|

• Tocando. Depois de autenticar a chamada, o Turn envia 180 Ringing sem SDP, então toque o ringback localmente. Não há early media.
• Atendimento. O Turn envia 200 OK com a resposta SDP assim que alguém atende: o agente de IA, um operador que aceita a chamada na caixa de entrada, ou a sala de espera. Na sala de espera, quem liga ouve a mensagem de boas-vindas e depois a música de espera até um operador entrar.
• Ninguém atende. O Turn encerra uma chamada que ninguém atende 30 a 40 segundos depois do INVITE, com 503 Service Unavailable.
• Cancelamento. Um CANCEL enquanto a chamada toca recebe 487 Request Terminated para o INVITE.
• Desligamento. Qualquer um dos lados pode enviar BYE. O Turn envia um quando o agente de IA ou o operador encerra a chamada, ou quando o seu áudio para por 30 segundos.
• Re-INVITE. O Turn aceita re-INVITEs que renovam a sessão, mudam o seu endereço de mídia ou trocam as chaves SRTP. O codec continua o mesmo. Se o Turn não puder aceitar uma nova oferta, ele responde 488 Not Acceptable Here e a chamada continua sem alterações.

Quem atende

As chamadas SIP são roteadas exatamente como as chamadas de WhatsApp do número, com as configurações da página Chamadas:

• Atendimento por IA: o agente de IA atende imediatamente, ou quando nenhum operador estiver disponível. Agentes de IA na OpenAI ou na ElevenLabs podem atender chamadas SIP. Um número cuja IA atende com um modelo Gemini recusa chamadas SIP com 503 Service Unavailable.
• Sala de espera: quem liga aguarda, com a mensagem de boas-vindas e a música de espera, até um operador entrar.
• Agendamentos: quem liga com um agendamento no horário da chamada aguarda na sala de espera até o responsável pelo agendamento entrar.
• Operadores: a chamada toca na caixa de entrada como uma chamada de WhatsApp, na conversa de quem liga. Se as chamadas vão para o operador atribuído à conversa, só esse operador é chamado.

A chamada aparece na conversa de quem liga como apareceria uma chamada de WhatsApp.

Códigos de resposta

Código	Significado
100 Trying	O Turn recebeu o INVITE.
180 Ringing	A chamada está autenticada e tocando. Sem SDP.
200 OK	A chamada foi atendida. Traz a resposta SDP do Turn. Também é a resposta a um REGISTER bem-sucedido.
400 Bad Request	A parte de usuário do From não é um número de telefone.
401 Unauthorized	Desafio digest. Envie a requisição de novo com as credenciais.
403 Forbidden	O SIP de entrada está desativado para o número, ou o número não tem senha SIP.
404 Not Found	Nenhum número do Turn tem o endereço discado.
487 Request Terminated	Você cancelou o INVITE enquanto ele tocava.
488 Not Acceptable Here	O Turn não consegue usar a sua oferta SDP: ela não existe, não tem codec G.711, não é SRTP, é DTLS-SRTP ou não tem nenhuma linha a=crypto utilizável. Em resposta a um re-INVITE, o Turn recusou a mudança e a chamada continua.
500 Server Internal Error	O Turn não conseguiu configurar a chamada.
503 Service Unavailable	Ninguém atendeu a tempo, não foi possível conectar a chamada, ou o número atende com um modelo de IA que não recebe chamadas SIP.
603 Decline	Um operador recusou a chamada.

Checklist do cliente

A maioria das chamadas que falham se deve a uma destas configurações:

Configuração	Valor
Servidor SIP ou proxy	sip.turn.io:5061
Transporte	TLS
Nome de usuário, ou nome de usuário de autenticação	O nome de usuário SIP do Turn, como +15551230000
Senha	A senha SIP do Turn
Realm	turn.io, ou deixe vazio para usar o do desafio
Número para discar	O nome de usuário SIP do Turn
Caller ID (usuário do From)	O número de telefone de quem liga
Criptografia de mídia	SRTP com SDES, obrigatório. Não DTLS-SRTP nem ZRTP
Codecs	PCMU e/ou PCMA ativados
Empacotamento	20 ms
DTMF	RFC 4733
Supressão de silêncio (VAD)	Desativada
Registro	Opcional

Limitações

• Somente chamadas de entrada: o Turn não faz chamadas SIP.
• Somente G.711. Sem codecs de banda larga como Opus ou G.722.
• Somente SRTP com chaves SDES. Sem RTP sem criptografia e sem DTLS-SRTP.
• As teclas pressionadas são recebidas, mas o Turn não age sobre elas.
• Sem early media, e sem configuração de quanto tempo uma chamada toca antes de o Turn encerrá-la.
• Um número cuja IA atende com um modelo Gemini não recebe chamadas SIP.
• A capacidade é limitada durante a fase alfa. Informe a support@turn.io o seu pico esperado de chamadas simultâneas antes de enviar tráfego de produção.