Trunking SIP

Visão geral

O trunking SIP (Session Initiation Protocol) permite conectar sua infraestrutura de telefonia existente diretamente ao ElevenLabs Agents. Essa integração permite que todos os clientes usem seus sistemas telefônicos existentes e aproveitem 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
• Rotear chamadas para agentes de IA sem alterar sua infraestrutura telefônica existente
• Gerenciar chamadas de entrada e de saída
• Usar transporte TLS criptografado e criptografia de mídia para mais segurança

Como o trunking SIP funciona

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

1. Chamadas de entrada: as chamadas do seu trunk SIP são roteadas para a plataforma da ElevenLabs usando seu endereço SIP INVITE configurado.
2. Chamadas de saída: as chamadas iniciadas pela ElevenLabs são roteadas para seu trunk SIP usando seu nome de host configurado, permitindo que seus agentes façam chamadas de saída.
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 Access Control List (ACL) com base no IP de origem da sinalização.
4. Sinalização e mídia: a configuração inicial da chamada (sinalização) oferece suporte a vários protocolos de transporte, incluindo TLS para comunicação criptografada. Depois que a chamada é estabelecida, 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 transporte TLS, ambos os lados realizam um handshake TLS antes de qualquer sinalização SIP ser 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 de entrada para a 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 de saída da ElevenLabs: A ElevenLabs abre a conexão para 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 dentro do diálogo, como BYE ou REFER, podem exigir uma nova conexão TLS quando a conexão original já foi encerrada. O comportamento do certificado nessas conexões subsequentes é diferente da configuração inicial da chamada:

• Conexões subsequentes para 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 acima, que geralmente é um endereço IP. Normalmente, seu sistema retorna um certificado válido para um nome de domínio totalmente qualificado (FQDN), e não para esse 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 é 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 correto de URI SIP. A URI do tronco SIP da ElevenLabs depende do transporte que você deseja usar para a 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, construa 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

Onde:

• +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 tronco SIP, verifique se você tem:

1. Um PBX ou sistema de telefonia compatível com SIP
2. Números de telefone que você 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 maior segurança, verifique se seu provedor de tronco SIP oferece suporte a transporte TLS
6. Compatibilidade com codecs de áudio: Seu sistema precisa 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 tronco 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 entrada

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

• Criptografia de mídia: Configure a criptografia dos 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 em branco 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 que têm permissão para enviar chamadas a 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 para validação de certificados TLS. Deixe esse campo em branco se não usar TLS.
• Autenticação (Opcional): Forneça credenciais de autenticação digest que serão usadas para autenticar chamadas de entrada.
  • 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 saída

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

• Endereço: Nome de host ou endereço IP para onde 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 um certificado válido.

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

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

• Criptografia de mídia: Configure a criptografia dos 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 oferecer no SDP para chamadas de saída (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 de saída. 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. Os cabeçalhos personalizados podem ser usados para roteamento e identificação de chamadas, faturamento 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 deixar em branco, será usada a autenticação por Lista de Controle de Acesso (ACL), que exige que você inclua endereços IP da ElevenLabs na lista de permissões nas configurações do seu provedor.

Boa prática de segurança: Use transporte TLS com criptografia de mídia Obrigatória para ter o máximo de segurança. Isso garante que a sinalização e 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 lista de permissões de endereços IP para controle de acesso

A autenticação digest é altamente recomendada, pois oferece melhor segurança sem depender de listas de permissões de IP, que podem ser complexas de gerenciar com endereços IP dinâmicos.

O campo Endereço especifica para onde a ElevenLabs enviará chamadas de saída dos 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 da chamada, 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 está fazendo 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 procurará automaticamente o cabeçalho SIP específico da Twilio:

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

Essa alternativa garante compatibilidade com o Elastic SIP Trunking da Twilio sem exigir alterações de configuração.

Fluxo de processamento

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

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

Cabeçalhos SIP personalizados X- de chamadas de entrada do tronco SIP 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 letras minúsculas, substituindo hífens 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 pelo chamador. 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çalhos 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ê pode 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 deve atender às 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 plano de assinatura. Ative a fila de chamadas para manter os chamadores de entrada em espera quando o limite for atingido, em vez de rejeitá-los
• Recursos de gravação e análise de chamadas 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 precisa oferecer suporte nativo a um desses codecs ou realizar reamostragem para corresponder aos requisitos do seu sistema

Perguntas frequentes

Próximas etapas

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