Guias

Agente próprio

Quer ligar a um número volai a sua própria plataforma de voz - o ElevenLabs Conversational AI no seu próprio workspace, o Vapi, o Retell ou até um IVR próprio em Asterisk/FreeSWITCH - em vez do agente integrado do volai? Esta página é um guia para os dois sentidos: chamadas recebidas e efetuadas. Nas chamadas efetuadas não paga ainda a sobretaxa de agente de 2,50 kr/min (≈ 0,10 EUR) - o agente é operado (e pago) por si, na sua plataforma.

1Quando usar agente próprio e quando o integrado

Os dois caminhos funcionam no mesmo número e com o mesmo saldo - diferem apenas em QUEM opera a lógica da conversa e no custo adicional:

2Chamadas recebidas no agente próprio

Nenhuma mecânica nova - basta o encaminhamento existente mode: "sip" (igual ao de um softphone próprio, ver SIP) com o sipUri da sua plataforma. Para um número SIP-trunk do ElevenLabs registado no SEU próprio workspace, trata-se do endereço com o mesmo número que tem a sua linha volai:

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"}}'

E na sua conta ElevenLabs (Settings → Phone Numbers → Import → SIP trunk) registe este 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"
  }
}

allowed_addresses acima é o nosso intervalo de sinalização (81.31.45.0/24) - mais seguro do que o universal 0.0.0.0/0, que deixa entrar um INVITE de qualquer lado. Ambos deixam passar a chamada, mas numa importação sem credenciais a allowlist é a ÚNICA verificação - por isso indique o intervalo, não 0.0.0.0/0.

Utiliza uma plataforma diferente do ElevenLabs? O princípio é o mesmo - descubra nela o endereço SIP para onde deve chegar a chamada do seu número e indique-o em sipUri. No Vapi, o mesmo intervalo vai para o BYO trunk como gateways.

No Vapi, o endereço de encaminhamento é sip:<E164>@<credentialId>.sip.vapi.ai - o <credentialId> encontra-se no seu BYO SIP trunk no Vapi; uma organização na região da UE tem, em vez de sip.vapi.ai, o domínio sip.eu.vapi.ai. O sip.vapi.ai simples pertence aos números nativos do Vapi e não funciona para um número nosso. Deixe o nome de utilizador e a palavra-passe vazios no BYO trunk, o Vapi reconhece as nossas chamadas pelo IP nos gateways.

Em gateways, indique o intervalo como IP 81.31.45.0 e a máscara (netmask) 24 em separado. Com a máscara por omissão 32, o Vapi deixaria passar apenas um endereço e rejeitaria as nossas chamadas.

3Chamadas efetuadas a partir do agente próprio (relay)

Este é o sentido contrário - a sua plataforma efetua a chamada para fora. A maioria das plataformas de IA de voz (incluindo o ElevenLabs) não consegue registar de forma permanente uma linha telefónica como cliente SIP - limita-se a enviar uma chamada autenticada com as credenciais da sua linha. A rede telefónica não deixa passar essa chamada diretamente para o número de destino e, por isso, encaminha-a através de uma ligação de relay de curta duração:

1. Configure a sua plataforma para a sua linha

Obtenha as credenciais SIP da sua linha:

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"]
}

A resposta devolve server (para o REGISTER de um softphone, ver SIP) e outboundTrunkAddress SEPARADAMENTE - não são intermutáveis.

E defina outboundTrunkAddress - NÃO server - como trunk de saída da sua plataforma. No ElevenLabs trata-se do campo outbound_trunk_config do número de telefone em causa (Settings → Phone Numbers → o seu número → Outbound calling), exatamente neste formato:

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

2. Crie a ligação de relay

Imediatamente antes da chamada (a ligação tem uma duração curta, ver os limites 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"
}

O número de destino indica-o a NÓS em to - a plataforma nunca o vê, recebe apenas o sipName simples da resposta.

3. Peça à plataforma que ligue para o sipName

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

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

agent_id encontra-se no seu agente no ElevenLabs, agent_phone_number_id é o phone_number_id do número importado - devolve-o a resposta da importação ou pode lê-lo na lista Phone numbers.

Tem um cliente SIP próprio ou uma central em vez do ElevenLabs? Marque diretamente o sipUri completo, como uma chamada SIP normal - esta restrição aplica-se apenas às plataformas que querem um nome simples sem o prefixo sip: .

4. O que acontece a seguir

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

A resposta sobre a marcação da chamada só chega depois de todo o toque (facilmente dezenas de segundos) - não é um erro, mas um timeout curto do seu lado pareceria nesse momento uma falha, embora a chamada esteja em curso.

4Resolução de problemas

As mensagens mais frequentes com um agente próprio e o que fazer:

5Faturação

Uma chamada efetuada através do relay é faturada ao mesmo preço de uma chamada efetuada normal - 0,92 kr/min (≈ 0,04 EUR) - sem qualquer sobretaxa de agente. Os preços são sem IVA, como toda a tabela de preços.

A simultaneidade é limitada (ver os limites abaixo): no máximo 1 chamada ativa por cada um dos seus números e no máximo 2 em simultâneo por conta.

Quem recebe só vê a sua linha volai se o número tiver nomes de relay (relayNames) próprios - o número recebe-os logo após a compra. Enquanto não os tiver, o lease passa para o pool partilhado e quem recebe vê o número de demonstração do volai. Se isto durar mais de uma hora, escreva ao suporte.

6Limites, quotas e segurança

O limite é de 1 lease ativo por cada um dos seus números e no máximo 2 por conta - uma salvaguarda deliberada para que um único cliente não ocupe todo o pool partilhado de slots de relay:

• 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 (caller ID spoofing).
• As mesmas barreiras de uma chamada normal - lista de não chamar (vale apenas para chamadas, não para SMS), bloqueio automático de 30 dias após 3 tentativas falhadas para o mesmo número em 24 horas, linhas de tarifa especial, proteção contra ciclos entre números volai, bloqueio do número de destino e o limite geral de frequência de chamadas. Nada disto se pode contornar através do relay.
• Pool cheio -> 503 capacity_busy - os slots de relay são um limite de simultaneidade partilhado por TODA a plataforma, não apenas pela sua conta. Em caso de capacity_busy nada é cobrado, tente novamente daí a pouco.
• A referência REST completa (códigos de erro, GET/DELETE sobre os leases) encontra-se em REST API.

Cada erro da API inclui cause (quem o resolve) e action (o que fazer) - ver Formato dos erros na referência da REST API.