Integração com a Exotel | ElevenLabs Documentation

Visão geral

Este guia explica como conectar seus números de telefone da Exotel diretamente ao ElevenAgents. Essa integração permite usar seus números e infraestrutura Exotel existentes, enquanto aproveita os recursos avançados de voz IA da ElevenLabs, tanto para chamadas recebidas quanto para chamadas efetuadas.

Como a integração funciona

A integração com a Exotel usa dois recursos da Exotel:

Applet Voicebot (mídia de entrada + saída): Um applet ExoML na Exotel que abre um WebSocket para a ElevenLabs e transmite o áudio da chamada nos dois sentidos.
API Connect (discagem de saída): Para chamadas efetuadas, a ElevenLabs chama o endpoint Calls/connect.json da Exotel usando sua API Key e API Token. A Exotel disca para o destino e, quando a chamada é atendida, encaminha o áudio pelo mesmo applet Voicebot para a ElevenLabs.

Para chamadas recebidas, a Exotel encaminha as chamadas de entrada para o applet Voicebot atribuído ao número de telefone, que abre o WebSocket para a ElevenLabs.

Para chamadas efetuadas, a ElevenLabs inicia a chamada pela API Connect, e a Exotel conecta a chamada novamente pelo applet Voicebot.

Requisitos

Antes de configurar a integração com a Exotel, verifique se você tem:

Uma conta Exotel ativa com pelo menos um número de telefone provisionado.
Acesso de administrador ao painel da Exotel em my.exotel.com (Singapura) ou my.exotel.in (Mumbai).
Uma conta da ElevenLabs e um agente ao qual você quer vincular o número de telefone.

Atualmente, a Exotel é compatível com os clusters de Singapura (api.exotel.com) e Mumbai (api.in.exotel.com). Escolha o cluster no qual sua conta Exotel foi provisionada. Usar a região errada causará falhas de autenticação.

Como habilitar o Voicebot na sua conta Exotel

Antes de mais nada, entre em contato com o suporte da Exotel e peça para:

Habilitar o applet Voicebot na sua conta. Ele é bloqueado por padrão e não aparecerá no App Bazaar até que sua conta seja provisionada para usá-lo.
Provisionar o número de canais (chamadas simultâneas) de que você precisa. Esse é o limite de chamadas simultâneas do Voicebot que a Exotel permitirá que sua conta execute. Dimensione-o para o pico de tráfego esperado.

Esta etapa normalmente leva de 1 a 2 dias úteis. Comece antes de iniciar o restante da configuração.

Endpoint WebSocket da ElevenLabs

Você configurará seu applet Voicebot da Exotel para transmitir áudio ao seguinte URL do WebSocket.

Ambiente	URL do WebSocket
Padrão (EUA/Internacional)	`wss://api.elevenlabs.io/v1/convai/conversation/exotel`
Residência na UE	`wss://api.eu.residency.elevenlabs.io/v1/convai/conversation/exotel`
Residência na Índia	`wss://api.in.residency.elevenlabs.io/v1/convai/conversation/exotel`

Se sua conta ElevenLabs estiver em um ambiente isolado de residência de dados (UE ou Índia), use o URL de residência correspondente. Saiba mais sobre residência de dados.

Configuração na Exotel

Obtenha suas credenciais da Exotel

No painel da Exotel, abra o menu Monitor à esquerda e clique em Developer. Isso abre a página de credenciais da API, onde você pode consultar o Account SID, a API Key e o API Token.

Você precisará de quatro valores:

Account SID: O SID da sua conta Exotel.
API Key: A parte de nome de usuário das credenciais de API da Exotel.
API Token: A parte de senha das credenciais de API da Exotel. Mantenha-o em segredo.
Região (subdomínio da API): O cluster em que sua conta Exotel está. É api.exotel.com (Singapura) ou api.in.exotel.com (Mumbai). Você pode confirmar qual deles é verificando o host de qualquer URL de API exibido na página Developer.

A ElevenLabs usa a API Key + API Token para autenticação HTTP Basic ao chamar a API Connect da Exotel para discagem de saída.

Crie um applet Voicebot no App Bazaar

No painel da Exotel, abra o menu Manage à esquerda e clique em App Bazaar.
Clique em Create / Add New Flow, dê ao app um nome descritivo (por exemplo, ElevenLabs) e clique em OK.
Na paleta de applets à direita, arraste o applet Voicebot para a tela Call Start.
Abra a configuração do applet Voicebot e cole no campo URL o URL do WebSocket da ElevenLabs para sua residência de dados (o campo “Which bot you want to connect the enduser?”):
```
wss://api.elevenlabs.io/v1/convai/conversation/exotel
```
Se sua conta ElevenLabs estiver na residência de dados da UE ou da Índia, use o URL de residência correspondente da tabela acima (por exemplo, wss://api.in.residency.elevenlabs.io/v1/convai/conversation/exotel) em vez do padrão api.elevenlabs.io.

As demais opções do Voicebot (“Record this?”, “Recording Channels”, “Recording Format”, “Encrypt DTMF”) podem permanecer com os valores padrão, a menos que você tenha uma necessidade específica de gravação ou conformidade.

(Opcional) Encadeie um applet Connect para transferências a atendentes. Ignore esta etapa se você não precisar que o agente possa transferir a chamada para uma pessoa. Se quiser usar a ferramenta Transfer to number do agente, adicione um applet Connect imediatamente após o applet Voicebot no fluxo.

Na paleta Voice Applets à direita, arraste o applet Connect para o slot Next → Continue to the next applet do Voicebot.

Paleta Voice Applets com o Connect
destacado

Na configuração do applet Connect, escolha Configure parameters dynamically by providing a URL e cole o endpoint do applet Connect da ElevenLabs para sua residência de dados em Primary URL:

https://api.elevenlabs.io/v1/convai/exotel/connect-applet

Applet Connect configurado com o URL dinâmico
da ElevenLabs

Os URLs de residência correspondentes são:

Ambiente	URL do applet Connect
Padrão (EUA/Internacional)	`https://api.elevenlabs.io/v1/convai/exotel/connect-applet`
Residência na UE	`https://api.eu.residency.elevenlabs.io/v1/convai/exotel/connect-applet`
Residência na Índia	`https://api.in.residency.elevenlabs.io/v1/convai/exotel/connect-applet`

Quando o agente aciona sua ferramenta Transfer to number, a ElevenLabs devolve o controle à Exotel, e a Exotel busca este URL para obter o número de destino para discagem. Deixe o Fallback URL vazio e mantenha todos os outros valores padrão.

Salve e publique o applet.
Anote o Applet ID (às vezes chamado de App ID). Você o encontrará no URL do editor ExoML (por exemplo, .../exoml/start_voice/12345) ou na lista de apps. Você precisará dele ao importar o número para a ElevenLabs.

O applet Voicebot processa as chamadas recebidas e efetuadas. Você precisa de apenas um applet por conta. Todos os números de telefone importados para a ElevenLabs podem compartilhá-lo.

Atribua o fluxo a um número de telefone (somente chamadas recebidas)

Salve e publique o fluxo ExoML da etapa anterior. Em seguida, encaminhe um número de telefone da Exotel para ele, para que as chamadas recebidas cheguem ao seu applet Voicebot.

No painel da Exotel, abra o menu Manage à esquerda e clique em ExoPhones (logo abaixo de App Bazaar).
Se você ainda não tiver um número de telefone, clique em Buy a number e compre um no país / área de que precisa antes de continuar.
Encontre o número que deseja usar com seu agente da ElevenLabs. Na coluna Installed App, abra o menu suspenso e selecione o fluxo criado na etapa anterior (por exemplo, ElevenLabs).
Salve a configuração. As chamadas recebidas para esse número agora serão encaminhadas diretamente ao applet Voicebot e transmitidas para a ElevenLabs.

Se o número for usado apenas para chamadas efetuadas, você pode ignorar esta etapa. As chamadas efetuadas são discadas pela API Connect da ElevenLabs e não dependem da atribuição de Installed App.

Configuração na ElevenLabs

Importe o número de telefone da Exotel

No painel do ElevenAgents, acesse a aba Phone Numbers. Clique em + Import number e selecione From Exotel no menu suspenso.

ElevenAgents: menu suspenso Import number com From Exotel
selecionado

Preencha os campos a seguir:

Label: Um nome descritivo (por exemplo, Support Line).
Phone number: O número da Exotel no formato E.164 (por exemplo, +918048961234).
Exotel Account SID: Da etapa 1 acima.
Exotel API Key: Da etapa 1 acima.
Exotel API Token: Da etapa 1 acima (armazenado como um segredo do workspace).
Region: Escolha Singapore (api.exotel.com) ou Mumbai (api.in.exotel.com) de acordo com seu cluster da Exotel.
Voicebot Applet ID: O App ID da etapa 2 acima.

Clique em Import para salvar o número. A ElevenLabs verificará as credenciais com a Exotel e armazenará o token da API como um segredo do workspace.

Atribua seu agente

Depois que o número for importado, abra-o na lista Phone Numbers e escolha o agente que deve atender às chamadas recebidas no menu suspenso Assigned agent.

As chamadas recebidas exigem que o applet Voicebot esteja atribuído ao número no lado da Exotel (veja a seção anterior). Configurações somente para chamadas efetuadas não precisam de uma atribuição para chamadas recebidas.

Teste uma chamada recebida

Ligue para seu número da Exotel de qualquer telefone. A Exotel encaminhará a chamada para o applet Voicebot, que abre um WebSocket para a ElevenLabs. Seu agente atenderá e iniciará a conversa.

Monitore a chamada no painel de histórico de chamadas para verificar se tudo está funcionando como esperado.

Como fazer chamadas efetuadas

Números Exotel importados também podem iniciar chamadas efetuadas. Seu agente disca um número de telefone e inicia a conversa quando o destinatário atende.

Inicie uma chamada efetuada

Na aba Phone Numbers, localize seu número Exotel e clique no botão Outbound call.

Configure a chamada

No modal Outbound Call:

Selecione o agente que atenderá a conversa.
Insira o número de telefone do destinatário no formato E.164.
Clique em Send Test Call para iniciar a chamada.

A ElevenLabs chama a API Connect da Exotel com suas credenciais armazenadas. A Exotel disca para o destinatário e encaminha o áudio de volta pelo applet Voicebot quando a chamada é atendida.

Ao fazer chamadas efetuadas, seu agente inicia a conversa; por isso, verifique se ele tem uma primeira mensagem adequada configurada.

Para acionar chamadas efetuadas programaticamente, em vez de pelo painel, use o endpoint Chamada efetuada pela Exotel. A referência da API inclui o esquema da solicitação e snippets de SDK prontos para uso.

Requisitos de configuração do agente

O applet Voicebot transmite áudio em PCM de 8 kHz. A plataforma ElevenLabs processa automaticamente a conversão de formato de áudio. Você não precisa alterar as configurações de TTS ou de áudio de entrada do agente.

Formatos de número de telefone

Os números de telefone são armazenados no formato E.164 (por exemplo, +918048961234). Ao importar um número indiano da Exotel que você poderia escrever localmente como 08048961234 ou 8048961234, informe-o como +918048961234. A ElevenLabs rejeitará importações duplicadas do mesmo número em formatos diferentes.

Transferências de chamadas

Você pode transferir chamadas do seu agente de volta para a Exotel configurando uma ferramenta Transfer to number no agente. Quando a ferramenta é acionada, a ElevenLabs encerra a etapa do Voicebot, e a Exotel busca o número de destino no URL dinâmico do applet Connect encadeado e, em seguida, disca para o destino.

Para que isso funcione, você precisa dos dois itens:

O applet Connect opcional configurado imediatamente após o applet Voicebot no seu fluxo ExoML (veja a etapa 5 em Configuração na Exotel).
A ferramenta Transfer to number configurada no seu agente. Veja o guia de transferência de agente.

Sem o applet Connect no fluxo, as tentativas de transferência do agente falharão, pois a Exotel não terá para onde encaminhar a chamada depois que o Voicebot terminar.

Solução de problemas

Erro exotel_connect_failed ao iniciar uma chamada efetuada

A ElevenLabs recebeu uma resposta diferente de 200 da API Connect da Exotel. As causas mais comuns são:

Region incorreta. Verifique se a região escolhida no momento da importação corresponde ao cluster da Exotel em que sua conta está (Singapore ou Mumbai).
API Key ou API Token inválidos. Verifique novamente as credenciais na página API Settings da Exotel e importe o número novamente com os valores corretos.
O Account SID não corresponde ao par API Key / Token.
O número de destino não está no formato E.164.

As chamadas recebidas não chegam ao meu agente

Confirme que o campo URL do applet Voicebot corresponde exatamente ao endpoint WebSocket da ElevenLabs para sua residência de dados (incluindo wss://).
Confirme que o número de telefone da Exotel está encaminhado ao app ExoML que contém o applet Voicebot (painel da Exotel, ExoPhones, o número, Installed App).
Na ElevenLabs, confirme que o número de telefone tem um agente atribuído na aba Phone Numbers.

Erros de incompatibilidade de Applet ID durante a importação

O campo Voicebot Applet ID espera o App ID numérico do URL do editor ExoML (por exemplo, em .../exoml/start_voice/12345, o ID é 12345). Não cole o URL completo. Use apenas o ID.

Número de telefone importado duas vezes em formatos diferentes

A ElevenLabs normaliza os números da Exotel para E.164 antes de armazená-los e garante a exclusividade em (provider, phone_number). Se você já importou o mesmo número em um formato diferente de E.164, exclua primeiro a entrada antiga e depois importe-o novamente no formato E.164.