Vejledninger

Medbring egen agent

Skal en egen stemmeplatform - ElevenLabs Conversational AI i eget workspace, Vapi, Retell eller blot en almindelig Asterisk/FreeSWITCH-IVR - forbindes med et volai-nummer i stedet for den indbyggede agent? Denne side gennemgår begge retninger: indgående og udgående opkald. Ved udgående opkald undgås desuden agenttillægget på 2,50 kr/min (≈ 0,78 DKK), fordi agenten drives (og betales) direkte hos egen platform.

1Egen agent eller den indbyggede

Begge veje kører på samme nummer og samme saldo - de adskiller sig kun i, HVEM der driver samtalelogikken, og hvad det koster ekstra:

2Indgående opkald til egen agent

Ingen ny mekanik - den eksisterende mode: "sip" routing (som til en egen softphone, se SIP) med platformens sipUri adresse. For et ElevenLabs SIP-trunk-nummer registreret i EGET workspace er det en adresse med samme nummer som volai-linjen:

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

Og på ElevenLabs-kontoen (Settings → Phone Numbers → Import → SIP trunk) registreres nummeret med inbound_trunk_config:

{
  "provider": "sip_trunk",
  "phone_number": "+420601234567",
  "label": "Min egen agent",
  "inbound_trunk_config": {
    "allowed_addresses": ["81.31.45.0/24"],
    "media_encryption": "allowed"
  }
}

allowed_addresses ovenfor er vores signaleringsområde (81.31.45.0/24) - sikrere end det universelle 0.0.0.0/0, som lader en INVITE komme ind fra hvor som helst. Begge dele lader opkaldet passere, men ved import uden loginoplysninger er allowlisten den ENESTE kontrol - brug derfor området, ikke 0.0.0.0/0.

Bruges en anden platform end ElevenLabs? Samme princip - find ud af, hvilken SIP-adresse den forventer opkald til nummeret på, og angiv den i sipUri. Hos Vapi indsættes det samme område i BYO-trunkens gateways.

Hos Vapi er routingadressen sip:<E164>@<credentialId>.sip.vapi.ai - <credentialId> findes på den egen BYO SIP-trunk i Vapi; en organisation i EU-regionen bruger domænet sip.eu.vapi.ai i stedet for sip.vapi.ai. Den rene sip.vapi.ai tilhører Vapis native numre og virker ikke til et nummer fra os. Brugernavn og adgangskode lades tomme på BYO-trunken - Vapi genkender vores opkald på IP-adressen i gateways.

I gateways angives området som IP 81.31.45.0 og netmaske (netmask) 24 hver for sig. Med standardmasken 32 ville Vapi kun lade én adresse passere og afvise vores opkald.

3Udgående opkald fra egen agent (relay)

Det er den modsatte retning - platformen ringer selv ud. De fleste stemme-AI-platforme (ElevenLabs inklusive) kan dog ikke registrere en telefonlinje permanent som SIP-klient - de sender blot ét autentificeret opkald med linjens loginoplysninger. Telefonnettet lader ikke et sådant opkald gå direkte videre til destinationsnummeret, og derfor ledes det via en kortvarig relay-forbindelse:

1. Peg platformen på linjen

Hent linjens SIP-oplysninger:

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

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

Svaret returnerer server (til en softphones REGISTER, se SIP) og outboundTrunkAddress HVER FOR SIG - de kan ikke bruges i flæng.

Og angiv outboundTrunkAddress - IKKE server - som platformens udgående trunk. Hos ElevenLabs er det outbound_trunk_config for det pågældende telefonnummer (Settings → Phone Numbers → nummeret → Outbound calling), i præcis denne form:

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

2. Opret en relay-forbindelse

Lige før opkaldet (forbindelsen har kort levetid, se grænserne nedenfor) kaldes:

curl -X POST https://volai.cz/v1/relay \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -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"
}

Det kaldte nummer angives til OS i feltet to - platformen ser det aldrig, den får kun det rene sipName fra svaret.

3. Bed platformen ringe til sipName

Hos ElevenLabs betyder det at kalde /v1/convai/sip-trunk/outbound-call med to_number sat direkte til sipName:

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

agent_id findes på agenten i ElevenLabs, agent_phone_number_id er phone_number_id for det importerede nummer - importsvaret returnerer den, eller den kan aflæses på listen Phone numbers.

Bruges en egen SIP-klient eller PBX i stedet for ElevenLabs? Ring direkte til hele sipUri som et almindeligt SIP-opkald - begrænsningen gælder kun platforme, der vil have et rent navn uden sip: præfikset.

4. Hvad der sker derefter

Telefonnettet modtager opkaldet på navnet volai_relay_2, stiller det videre til to og sætter det viste nummer for den, der ringer, til from - den kaldte ser volai-linjen på displayet, ikke relay-slottets interne navn (kun hvis nummeret har egne relay-navne - se Afregning nedenfor, ellers ser den kaldte volais demonummer). Når opkaldet slutter, frigives lease, og minutterne afregnes som et almindeligt udgående opkald - 0,92 kr/min (≈ 0,29 DKK), intet agenttillæg.

Svaret på opkaldet kommer først efter hele ringetiden (nemt et halvt minut eller mere) - det er ikke en fejl, men en kort timeout hos platformen kunne se sådan ud, mens opkaldet stadig ringer.

4Fejlfinding

De hyppigste meldinger med egen agent og hvad der kan gøres ved dem:

5Afregning

Et udgående opkald via relay afregnes til samme takst som et almindeligt udgående opkald - 0,92 kr/min (≈ 0,29 DKK) - uden noget som helst agenttillæg. Priserne er uden moms, ligesom hele prislisten.

Samtidigheden er begrænset (se grænserne nedenfor): højst 1 aktivt opkald pr. nummer og højst 2 pr. konto på samme tid.

Den kaldte ser kun volai-linjen, hvis nummeret har egne relay-navne (relayNames) - nummeret får dem straks efter købet. Indtil da falder lease'en tilbage på den delte pulje, og den kaldte ser volais demonummer. Hvis det varer længere end en time, kontaktes support.

6Grænser, kvoter og sikkerhed

Loftet er 1 aktiv lease pr. nummer og højst 2 pr. konto - en bevidst sikring mod, at én kunde optager hele den delte pulje af relay-slots:

• from skal være et volai-nummer, som kontoen selv ejer - ellers from_number_not_owned. Uden denne kontrol kunne man udgive sig for en andens linje (caller ID spoofing).
• Samme spærrer som et almindeligt opkald - ring-ikke-listen (gælder kun opkald, ikke SMS), automatisk 30-dages blokering efter 3 mislykkede forsøg til samme nummer inden for 24 timer, premium-linjer, beskyttelse mod sløjfer mellem volai-numre, lås på det kaldte nummer og den generelle ratebegrænsning for opkald. Intet af dette kan omgås via relay.
• Fuld pulje -> 503 capacity_busy - relay-slots er et fælles samtidighedsloft for HELE platformen, ikke kun for kontoen. Ved capacity_busy afregnes der ikke noget, prøv igen om lidt.
• Den fulde REST-reference (fejlkoder, GET/DELETE på leases) findes i REST API-referencen.

Hver API-fejl indeholder cause (hvem der løser den) og action (hvad der skal gøres) - se Fejlformat i REST API-referencen.