Agente ElevenLabs num número checo através de SIP

Já tem um agente ElevenLabs Conversational AI e quer atribuir-lhe um número de telefone checo? Não há truque nenhum: basta ligar um número volai ao SIP trunk da plataforma do seu agente. As chamadas recebidas são a parte fácil - um único pedido PATCH ao encaminhamento do número. As chamadas efetuadas funcionam de forma ligeiramente diferente, porque a ElevenLabs (como a maioria das plataformas de voz com IA) não consegue registar permanentemente uma linha telefónica como cliente SIP - limita-se a enviar uma única chamada autenticada, pelo que esta segue por uma ligação relay de curta duração. A grande diferença em relação ao agente integrado da volai: nas chamadas efetuadas não paga de todo o acréscimo do agente de 2,50 kr/min (≈ 0,10 EUR) - o agente é operado (e pago) por si, no seu próprio workspace da ElevenLabs.

Quando faz mais sentido um agente próprio do que o integrado?

Ambos funcionam no mesmo número da volai e consomem o mesmo saldo - a diferença está em quem conduz a conversa e no que paga a mais por isso:

Dito de outro modo: um agente próprio compensa quando já tem um agente ElevenLabs em funcionamento, com prompt, ferramentas e voz próprios, e só precisa de lhe ligar um número checo. Se está a começar do zero e lhe basta um prompt de sistema, sem administração própria da ElevenLabs, o caminho mais rápido é o agente integrado da volai - cria-se com uma única chamada à API e a transcrição com o resumo chegam automaticamente.

De que vai precisar?

• Uma conta volai com um número checo já adquirido e uma chave de API (vk_...) - encontra-a no portal, na secção API e MCP.
• Um agente ElevenLabs Conversational AI já criado no SEU PRÓPRIO workspace - este guia não o cria, apenas o liga ao número.
• Saldo na conta volai - as chamadas são debitadas dele da mesma forma que com o agente integrado.

Passo 1: Ligar as chamadas recebidas

Defina o encaminhamento do número para mode: "sip" e, como sipUri, indique o endereço SIP em que a ElevenLabs espera receber as chamadas na importação de um SIP trunk:

curl -X PATCH "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_A_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "sip", "sipUri": "sip:+420601234567@sip.rtc.elevenlabs.io"}}'

Na conta ElevenLabs (Settings → Phone Numbers → Import → SIP trunk) registe depois o número com inbound_trunk_config:

{
  "provider": "sip_trunk",
  "phone_number": "+420601234567",
  "label": "O meu agente",
  "inbound_trunk_config": {
    "allowed_addresses": ["81.31.45.0/24"],
    "media_encryption": "allowed"
  }
}

Cobra-se apenas o minuto de chamada recebida (0,50 kr/min (≈ 0,02 EUR)), sem agente adicional - a mesma regra do agente integrado ou de um softphone normal.

Passo 2: Ligar as chamadas efetuadas através do relay

Este sentido é o inverso - o agente marca por si próprio. Mas a rede telefónica não encaminha diretamente para o número de destino uma chamada com um endereço SIP alheio, pelo que esta segue por uma ligação relay de curta duração: um slot SIP pontual que a volai cria imediatamente antes da chamada e elimina por si quando esta termina. A mecânica detalhada (porque é assim e como se apresenta noutras plataformas que não a ElevenLabs) encontra-a na página Agente próprio - aqui ficam apenas os três passos que tem de dar.

2.1 Configurar a ElevenLabs para a sua linha

Obtenha as credenciais SIP do número:

curl "https://volai.cz/v1/numbers/+420601234567/sip" \
  -H "Authorization: Bearer vk_A_SUA_CHAVE"

{
  "server": "sip.volai.cz",
  "username": "123456",
  "password": "a1b2c3d4e5f6",
  "outboundTrunkAddress": "sip.volai.cz",
  "port": 5060,
  "transport": "tcp",
  "inboundSignallingCidrs": ["81.31.45.0/24"]
}

O campo server serve para um softphone normal (ver a página SIP), mas na ElevenLabs deve usar o campo outboundTrunkAddress (sip.volai.cz), e não server - a troca termina com o erro 1011 sip request timed out - o endereço do trunk de chamadas efetuadas tem de ser exatamente este valor, caso contrário a chamada não é encaminhada na rede.

Defina-o como outbound_trunk_config desse número na ElevenLabs (Settings → Phone Numbers → o seu número → Outbound calling), exatamente assim:

{
  "outbound_trunk_config": {
    "address": "sip.volai.cz",
    "transport": "tcp",
    "media_encryption": "allowed",
    "credentials": {
      "username": "123456",
      "password": "a1b2c3d4e5f6"
    }
  }
}

2.2 Criar a ligação relay

Imediatamente antes da chamada (a ligação vive pouco tempo, os limites estão mais abaixo), chame:

curl -X POST https://volai.cz/v1/relay \
  -H "Authorization: Bearer vk_A_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "from": "+420601234567"}'

{
  "id": "rl_4f2a91cd",
  "sipName": "volai_relay_2",
  "sipUri": "sip:volai_relay_2@sip.volai.cz",
  "expiresAt": 1756111760000,
  "callId": "c_9d4e2b7f"
}

2.3 Indicar ao agente o sipName, e não o SIP URI completo

Na ElevenLabs, isto significa chamar /v1/convai/sip-trunk/outbound-call com to_number definido diretamente como sipName:

{
  "agent_id": "agent_...",
  "agent_phone_number_id": "phnum_...",
  "to_number": "volai_relay_2"
}

O que acontece depois de ligar

A rede telefónica atende a chamada com o nome volai_relay_2, transfere-a para o seu to e define o número visível de quem liga como o seu from - quem atende vê no ecrã a sua linha volai, e não o nome interno do slot relay (se o número tiver nomes relay próprios - caso contrário, quem atende vê o número de demonstração da volai; contacte o apoio). Quando a chamada termina, o lease é libertado e os minutos são cobrados como uma chamada efetuada normal - 0,92 kr/min (≈ 0,04 EUR), sem acréscimo do agente.

Limites e segurança

• from tem de ser um número volai seu - caso contrário, from_number_not_owned. Sem esta verificação, seria possível fazer-se passar por uma linha alheia.
• As mesmas barreiras de uma chamada normal - a lista de não ligar (apenas para chamadas, não para SMS), o bloqueio automático de 30 dias após três tentativas falhadas para o mesmo número em 24 horas e o limite geral de chamadas. O relay não contorna nada disto.
• O lease é de utilização única - uma segunda chamada no mesmo lease é recusada; para a seguinte, crie um novo.
• Um pool de slots relay cheio devolve 503 capacity_busy - é um limite de simultaneidade partilhado por TODA a plataforma volai, não apenas pela sua conta. Nada é cobrado nesse caso; basta tentar de novo daqui a pouco.

A referência REST completa (códigos de erro, GET/DELETE sobre os leases) encontra-a na referência da API REST; o procedimento completo - incluindo chamadas recebidas e efetuadas para qualquer plataforma, e não apenas a ElevenLabs - está na página Agente próprio.

Quando ficar com o agente integrado?

Com franqueza: um agente próprio significa mais peças em movimento - uma conta e uma fatura separadas na ElevenLabs, nenhuma transcrição nem resumo automáticos diretamente no portal da volai e um passo adicional antes de cada chamada efetuada (criar um lease relay). Se lhe basta um bom prompt de sistema e quer ter tudo pronto em poucos minutos, sem uma segunda conta noutra plataforma, o agente integrado da volai consegue o mesmo com uma única chamada à API - e o acréscimo do agente de 2,50 kr/min (≈ 0,10 EUR) devolve-se-lhe sob a forma de transcrição automática, resumo e deteção de atendedor em cada chamada.

A comparação completa de preços com a Twilio e outros fornecedores encontra-a em Preços; a integração com a ElevenLabs passo a passo, com ligações para a documentação deles, está na página Integrações.

O que se segue