Trunking SIP

Visão geral

O trunking SIP (Session Initiation Protocol) permite conectar sua infraestrutura de telefonia atual diretamente ao ElevenLabs Agents. Essa integração permite que todos os clientes usem seus sistemas telefônicos atuais enquanto aproveitam os recursos avançados de voz IA da ElevenLabs.

Com o trunking SIP, você pode:

• Conectar seu Private Branch Exchange (PBX) ou sistema telefônico compatível com SIP à plataforma de voz IA da ElevenLabs
• Encaminhar chamadas para agentes de IA sem alterar sua infraestrutura telefônica atual
• Gerenciar chamadas recebidas e realizadas
• Usar transporte TLS criptografado e criptografia de mídia para mais segurança

Como funciona o trunking SIP

O trunking SIP estabelece uma conexão direta entre sua infraestrutura de telefonia e a plataforma ElevenLabs:

1. Chamadas recebidas: As chamadas do seu tronco SIP são encaminhadas para a plataforma ElevenLabs usando seu endereço SIP INVITE configurado.
2. Chamadas realizadas: As chamadas iniciadas pela ElevenLabs são encaminhadas para seu tronco SIP usando seu nome de host configurado, permitindo que seus agentes façam chamadas externas.
3. Autenticação: A segurança da conexão para a sinalização é mantida por autenticação digest (nome de usuário/senha) ou autenticação por Lista de Controle de Acesso (ACL) com base no IP de origem da sinalização.
4. Sinalização e mídia: A configuração inicial da chamada (sinalização) é compatível com vários protocolos de transporte, incluindo TLS para comunicação criptografada. Após o estabelecimento da chamada, os dados de áudio reais (fluxo RTP) podem ser criptografados de acordo com suas configurações de criptografia de mídia.

Segurança de transporte: certificados e conjuntos de cifras

Ao usar o transporte TLS, ambos os lados executam um handshake TLS antes que qualquer sinalização SIP seja trocada. Durante o handshake, eles validam um certificado e negociam um conjunto de cifras. O lado que aceita a conexão atua como servidor TLS e apresenta o certificado; o lado que abre a conexão atua como cliente TLS e o valida. A ElevenLabs exige TLS 1.2 ou superior.

As funções dependem da direção da chamada:

• Chamadas recebidas pela ElevenLabs: Seu sistema abre a conexão, portanto a ElevenLabs atua como servidor TLS. A ElevenLabs apresenta um certificado válido para sip.rtc.elevenlabs.io, e seu sistema o valida como cliente TLS.
• Chamadas realizadas pela ElevenLabs: A ElevenLabs abre a conexão com o endereço que você configurou, portanto seu servidor SIP ou SBC atua como servidor TLS. Seu sistema deve apresentar um certificado válido e confiável, que a ElevenLabs valida como cliente TLS.

Garanta que ambos os lados confiem nos certificados um do outro e compartilhem pelo menos um conjunto de cifras em comum. Caso contrário, o handshake TLS falhará antes que a chamada seja estabelecida. Consulte a referência de SIP para ver as definições desses termos.

Conexões subsequentes

Algumas solicitações durante o diálogo, como BYE ou REFER, podem exigir uma nova conexão TLS quando a conexão original já tiver sido encerrada. O comportamento do certificado nessas conexões subsequentes é diferente da configuração inicial da chamada:

• Conexões subsequentes com a ElevenLabs: Seu sistema estabelece a conexão com o endereço do cabeçalho Contact retornado na resposta, que é resolvido para um servidor SIP específico no formato <ip>.hosts.rtc.elevenlabs.io. Esse servidor apresenta um certificado válido para *.hosts.rtc.elevenlabs.io, que seu sistema valida como cliente TLS.
• Conexões subsequentes da ElevenLabs: Quando a ElevenLabs inicia uma conexão TLS para um BYE ou REFER, ela se conecta ao endereço no cabeçalho Via mais alto, que geralmente é um endereço IP. Normalmente, seu sistema retorna um certificado válido para um nome de domínio totalmente qualificado (FQDN), em vez desse endereço IP. Para validar esse certificado, configure o campo Domínios remotos nas configurações do seu número de telefone. Se qualquer domínio para o qual o certificado recebido seja válido corresponder a um domínio remoto configurado, a validação será bem-sucedida; caso contrário, falhará.

Fazendo chamadas para o tronco SIP da ElevenLabs

Ao iniciar chamadas para a plataforma ElevenLabs, você precisa usar o formato de URI SIP correto. A URI do tronco SIP da ElevenLabs depende do transporte que você quer usar para sinalização:

• TCP: sip:sip.rtc.elevenlabs.io:5060;transport=tcp
• TLS: sip:sip.rtc.elevenlabs.io:5061;transport=tls
• UDP: sip:sip.rtc.elevenlabs.io:5060;transport=udp (experimental; use apenas para testes, não em produção)

Para fazer uma chamada, crie uma URI SIP completa que inclua um identificador. Por exemplo, para ligar para o número de telefone +19991234567 por TCP:

sip:+19991234567@sip.rtc.elevenlabs.io:5060

Em que:

• +19991234567 é o identificador (normalmente um número de telefone no formato E.164)
• O identificador também pode ser qualquer valor de string, como 1000 ou john

Requisitos

Antes de configurar o trunking SIP, verifique se você tem:

1. Um PBX ou sistema de telefonia compatível com SIP
2. Números de telefone que deseja conectar à ElevenLabs
3. Acesso de administrador à configuração do seu tronco SIP
4. Configurações de firewall adequadas para permitir tráfego SIP
5. Suporte a TLS: Para mais segurança, verifique se seu provedor de tronco SIP oferece suporte ao transporte TLS
6. Compatibilidade com codecs de áudio: Seu sistema deve oferecer suporte a pelo menos um dos codecs de áudio G.722 ou G.711 (PCMU ou PCMA), ou ser capaz de reamostrar o áudio do seu lado. Isso é independente de qualquer formato de áudio configurado no agente para conexões websocket diretas.

Configurando o trunking SIP

1

Acesse Números de telefone

Acesse a seção Números de telefone no painel do ElevenLabs Agents.

2

Importe o tronco SIP

Clique no botão “Importar número” e selecione “Do tronco SIP” para abrir a caixa de diálogo de configuração.

3

Insira a configuração básica

Preencha a configuração básica com as seguintes informações:

• Rótulo: Um nome descritivo para o número de telefone
• Número de telefone: O número de telefone no formato E.164 a ser conectado (por exemplo, +15551234567)

4

Configure as definições de chamadas recebidas

Configure como a ElevenLabs processa chamadas que chegam ao seu tronco SIP, incluindo criptografia de mídia e controles de acesso:

• Criptografia de mídia: Configure a criptografia para fluxos de mídia RTP:
  • Desativada: Sem criptografia de mídia
  • Permitida: Permite fluxos de mídia criptografados
  • Obrigatória: Exige fluxos de mídia criptografados
• Números permitidos (Opcional): Números de telefone autorizados a ligar para este número. Deixe vazio para permitir todos os números.
• Endereços IP de origem permitidos (Opcional): Funciona apenas para transporte TCP/TLS, não UDP. Endereços IP ou intervalos CIDR autorizados a enviar chamadas para este tronco. Deixe como 0.0.0.0/0 para permitir todos os endereços.
• Domínios remotos (Opcional): Especifique os domínios FQDN dos seus servidores SIP dos quais as chamadas são originadas, por exemplo, example.pstn.twilio.com. Esses domínios são usados na validação de certificados TLS. Deixe este campo vazio se não usar TLS.
• Autenticação (Opcional): Forneça credenciais de autenticação digest que serão usadas para autenticar chamadas recebidas.
  • Nome de usuário do tronco SIP: Nome de usuário para autenticação SIP digest
  • Senha do tronco SIP: Senha para autenticação SIP digest

5

Configure as definições de chamadas realizadas

Configure para onde a ElevenLabs deve enviar chamadas do seu número de telefone:

• Endereço: Nome de host ou endereço IP para o qual o SIP INVITE é enviado (por exemplo, sip.telnyx.com). Deve ser apenas um nome de host ou endereço IP, não uma URI SIP completa. Se usar TLS, use um nome de host com certificado válido.

• Tipo de transporte: Selecione o protocolo de transporte para sinalização SIP:

  • TCP: Transporte TCP padrão
  • TLS: Transporte TLS criptografado para mais segurança
  • UDP: Transporte sem conexão (experimental; use TCP ou TLS em produção)

• Criptografia de mídia: Configure a criptografia para fluxos de mídia RTP:

  • Desativada: Sem criptografia de mídia
  • Permitida: Permite fluxos de mídia criptografados
  • Obrigatória: Exige fluxos de mídia criptografados

• Codecs ativados: Codecs a serem oferecidos no SDP para chamadas realizadas (G.722, PCMU, PCMA). Útil quando seu provedor SIP oferece suporte apenas a determinados codecs.

• Cabeçalhos personalizados (Opcional): Adicione cabeçalhos SIP personalizados a serem incluídos nas chamadas realizadas. Clique em “Adicionar cabeçalho” para inserir o nome e o valor do cabeçalho exigido pelo seu provedor; você pode adicionar vários cabeçalhos conforme necessário. Cabeçalhos personalizados podem ser usados para roteamento e identificação de chamadas, fins de cobrança e rastreamento, além de requisitos específicos do provedor.

• Autenticação (Opcional): Forneça credenciais de autenticação digest se exigido pelo seu provedor de tronco SIP.

  • Nome de usuário do tronco SIP: Nome de usuário para autenticação SIP digest
  • Senha do tronco SIP: Senha para autenticação SIP digest

  Se deixada vazia, será usada a autenticação por Lista de Controle de Acesso (ACL), que exige permitir os endereços IP da ElevenLabs nas configurações do seu provedor.

Boa prática de segurança: Use transporte TLS com criptografia de mídia Obrigatória para obter o máximo de segurança. Isso garante que tanto a sinalização quanto a mídia sejam criptografadas de ponta a ponta.

Métodos de autenticação:

• Autenticação digest: Usa credenciais de nome de usuário/senha para autenticação segura (recomendado)
• Autenticação ACL: Usa permissão de endereços IP para controle de acesso

A autenticação digest é altamente recomendada, pois oferece mais segurança sem depender da permissão de IPs, que pode ser complexa de gerenciar com endereços IP dinâmicos.

O campo Endereço especifica para onde a ElevenLabs enviará chamadas realizadas pelos seus agentes de IA. Insira apenas o nome de host ou endereço IP, sem o prefixo de protocolo sip:.

6

Conclua a configuração

Clique em “Importar” para finalizar a configuração.

Dados do cliente e personalização

Para garantir o encaminhamento e a rastreabilidade adequados dos metadados de chamadas, inclua os seguintes cabeçalhos SIP personalizados na carga do seu webhook e na solicitação SIP INVITE:

• X-CALL-ID: Identificador exclusivo da chamada
• X-CALLER-ID: Identificador da parte que fez a chamada

Esses cabeçalhos permitem que o sistema associe os metadados da chamada à conversa e forneça contexto para personalização.

Suporte a cabeçalho alternativo

Se os cabeçalhos padrão acima não estiverem presentes, o sistema buscará automaticamente o cabeçalho SIP específico da Twilio:

• sip.twilio.callSid: Identificador exclusivo da chamada da Twilio

Esse recurso alternativo garante compatibilidade com o Elastic SIP Trunking da Twilio sem exigir alterações na configuração.

Fluxo de processamento

Assim que os metadados relevantes forem recebidos por qualquer um dos cabeçalhos compatíveis, caller_id e/ou call_id estarão disponíveis no webhook de início da conversa e como variáveis dinâmicas do sistema.

Cabeçalhos personalizados de chamadas recebidas como variáveis dinâmicas

Os cabeçalhos SIP X- personalizados de chamadas de trunking SIP recebidas são expostos automaticamente como variáveis dinâmicas na conversa.

Os nomes dos cabeçalhos são normalizados removendo o prefixo X-, convertendo o nome para minúsculas, substituindo hifens por sublinhados e adicionando o prefixo sip_. Por exemplo, X-Contact-ID se torna {{sip_contact_id}}, e X-Campaign-ID se torna {{sip_campaign_id}}.

Use essas variáveis nos prompts do agente, nas primeiras mensagens e nas ferramentas para personalizar a conversa com o contexto fornecido por quem ligou. Os valores também ficam visíveis no histórico da conversa, na aba Chamada telefônica.

Cabeçalhos BYE de variáveis dinâmicas

Quando uma chamada termina, a ElevenLabs envia um SIP BYE para encerrar o diálogo. Você pode anexar cabeçalhos personalizados a esse BYE mapeando variáveis dinâmicas para nomes de cabeçalho na configuração do seu tronco SIP.

Defina attributes_to_headers em inbound_trunk_config ou outbound_trunk_config ao criar ou atualizar um número de telefone de tronco SIP pela API. Cada entrada mapeia um nome de variável dinâmica para o nome do cabeçalho SIP a ser incluído no BYE:

"inbound_trunk_config": {
  "attributes_to_headers": {
    "dynamic_variable_name": "bye_header_name"
  }
}

O valor do cabeçalho é o valor final da variável dinâmica ao término da conversa. Valores definidos durante a chamada — por ferramentas do agente, substituições de webhook ou outras atualizações em tempo de execução — são refletidos no BYE.

Por exemplo, se attributes_to_headers contiver "disposition_code": "X-Disposition" e a variável dinâmica disposition_code for resolved quando a conversa terminar, o BYE incluirá X-Disposition: resolved.

Atribuindo agentes a números de telefone

Depois de importar o número de telefone do seu tronco SIP, você poderá atribuí-lo a um agente da ElevenLabs:

1. Acesse a seção Números de telefone no painel do ElevenAgents
2. Selecione o número de telefone do tronco SIP que você importou
3. Clique em “Atribuir agente”
4. Selecione o agente que deseja usar para atender chamadas para esse número

Solução de problemas

Limitações e considerações

• O suporte a várias chamadas simultâneas depende do seu nível de assinatura. Ative a fila de chamadas para manter os chamadores recebidos em espera quando o limite for atingido, em vez de rejeitá-los
• Os recursos de gravação de chamadas e análise estão disponíveis, mas podem exigir configuração adicional
• Os recursos de chamadas de saída podem ser limitados pelo seu provedor de tronco SIP
• Suporte a TLS: verifique se seu provedor de tronco SIP oferece suporte a TLS 1.2 ou superior para transporte criptografado
• Criptografia de mídia: o suporte a SRTP varia conforme o provedor; verifique a compatibilidade antes de exigir criptografia
• Formato de áudio: a implementação SIP da ElevenLabs envia e recebe áudio usando os codecs PCMU ou PCMA (G.711, 8 kHz) ou G.722 (16 kHz). Isso é independente de qualquer formato de áudio configurado no agente para conexões websocket diretas. Seu sistema de tronco SIP deve oferecer suporte nativo a um desses codecs ou realizar reamostragem para atender aos requisitos do seu sistema

Perguntas frequentes

Próximas etapas

• Referência de SIP: glossário de termos de SIP e redes
• Saiba como criar agentes da ElevenLabs