Handleidingen

Eigen agent

Wilt u in plaats van de ingebouwde agent van volai uw eigen spraakplatform op een volai-nummer aansluiten - ElevenLabs Conversational AI in uw eigen workspace, Vapi, Retell, of gewoon een eigen Asterisk/FreeSWITCH-IVR? Deze pagina beschrijft beide richtingen: inkomende en uitgaande gesprekken. Bij uitgaande gesprekken betaalt u bovendien geen toeslag voor de agent van 2,50 kr/min (≈ 0,10 EUR) - de agent draait (en betaalt) u zelf bij uw eigen platform.

1Wanneer een eigen agent, wanneer de ingebouwde

Beide wegen lopen via hetzelfde nummer en hetzelfde tegoed - ze verschillen alleen in WIE de gesprekslogica draait en wat dat extra kost:

2Inkomende gesprekken naar uw eigen agent

Geen nieuwe mechanica - gewoon de bestaande mode: "sip" -routering (hetzelfde als voor uw eigen softphone, zie SIP) ) met het sipUri van uw platform. Voor een ElevenLabs SIP-trunknummer dat in UW EIGEN workspace is geregistreerd is dat een adres met hetzelfde nummer als uw volai-lijn:

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

En in uw ElevenLabs-account (Settings → Phone Numbers → Import → SIP trunk) registreert u dit nummer met inbound_trunk_config:

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

allowed_addresses hierboven is ons signaleringsbereik (81.31.45.0/24) - veiliger dan het algemene 0.0.0.0/0, dat een INVITE van overal toelaat. Beide laten het gesprek door, maar bij een import zonder inloggegevens is de allowlist de ENIGE controle - gebruik dus het bereik, niet 0.0.0.0/0.

Gebruikt u een ander platform dan ElevenLabs? Hetzelfde principe - zoek bij dat platform het SIP-adres op waarnaar het gesprek voor uw nummer moet worden gestuurd en zet dat in sipUri. Bij Vapi komt hetzelfde bereik in de gateways van de BYO-trunk.

Bij Vapi is het routeringsadres sip:<E164>@<credentialId>.sip.vapi.ai - <credentialId> vindt u bij uw BYO SIP-trunk in Vapi; een organisatie in de EU-regio gebruikt in plaats van sip.vapi.ai het domein sip.eu.vapi.ai. Het kale sip.vapi.ai hoort bij native Vapi-nummers en werkt niet voor een nummer van ons. Laat de gebruikersnaam en het wachtwoord bij de BYO-trunk leeg, Vapi herkent onze gesprekken aan het IP-adres in de gateways.

Voer in de gateways het bereik apart in als IP 81.31.45.0 en netmask 24. Met het standaardmasker 32 zou Vapi maar één adres toelaten en onze gesprekken weigeren.

3Uitgaande gesprekken van uw eigen agent (relay)

Dit is de omgekeerde richting - uw platform belt zelf naar buiten. De meeste spraak-AI-platforms (ook ElevenLabs) kunnen een telefoonlijn echter niet permanent als SIP-client registreren - ze sturen alleen één geauthenticeerd gesprek met de inloggegevens van uw lijn. Het telefoonnetwerk laat zo'n gesprek niet rechtstreeks door naar het doelnummer, daarom leidt u het via een kortstondige relayverbinding:

1. Stel uw platform in op uw lijn

Haal de SIP-gegevens van uw lijn op:

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

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

Het antwoord bevat server (voor de REGISTER van een softphone, zie SIP) en outboundTrunkAddress APART - ze zijn niet uitwisselbaar.

En stel outboundTrunkAddress - NIET server - in als uitgaande trunk van uw platform. Bij ElevenLabs gaat het om het outbound_trunk_config van het betreffende telefoonnummer (Settings → Phone Numbers → uw nummer → Outbound calling), precies in deze vorm:

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

2. Maak een relayverbinding aan

Vlak voor het gesprek (de verbinding heeft een korte levensduur, zie de limieten hieronder) roept u aan:

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

Het nummer dat u wilt bellen geeft u aan ONS door in to - het platform ziet het nooit, het krijgt alleen de kale sipName uit het antwoord.

3. Laat uw platform de sipName bellen

Bij ElevenLabs betekent dit bellen via /v1/convai/sip-trunk/outbound-call met to_number rechtstreeks ingesteld op de sipName:

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

agent_id vindt u bij uw agent in ElevenLabs, agent_phone_number_id is de phone_number_id van het geïmporteerde nummer - die staat in het antwoord van de import of in de lijst Phone numbers.

Gebruikt u een eigen SIP-client of PBX in plaats van ElevenLabs? Bel dan rechtstreeks de volledige sipUri als een gewoon SIP-gesprek - die beperking geldt alleen voor platforms die een kale naam willen zonder het voorvoegsel sip: .

4. Wat er daarna gebeurt

Het telefoonnetwerk neemt het gesprek aan onder de naam volai_relay_2, schakelt het door naar uw to en stelt het zichtbare nummer van de beller in op uw from - de gebelde ziet op het display uw volai-lijn en niet de interne naam van de relayslot (als het nummer eigen relaynamen heeft - zie Facturering hieronder, anders ziet de gebelde het demonummer van volai). Na afloop van het gesprek komt de lease vrij en worden de minuten aangerekend zoals bij een gewoon uitgaand gesprek - 0,92 kr/min (≈ 0,04 EUR), geen toeslag voor de agent.

Het antwoord op het belverzoek komt pas na de volledige beltijd (gerust tientallen seconden) - dat is geen fout, ook al zou een korte timeout aan uw kant op dat moment als een mislukking overkomen terwijl het gesprek loopt.

4Problemen oplossen

De meest voorkomende meldingen bij een eigen agent en wat u eraan kunt doen:

5Facturering

Een uitgaand gesprek via relay wordt tegen hetzelfde tarief aangerekend als een gewoon uitgaand gesprek - 0,92 kr/min (≈ 0,04 EUR) - zonder enige toeslag voor de agent. De tarieven zijn exclusief btw, net als de hele prijslijst.

Het aantal gelijktijdige gesprekken is beperkt (zie de limieten hieronder): maximaal 1 actief gesprek per nummer van u en maximaal 2 per account tegelijk.

De gebelde ziet uw volai-lijn ALLEEN als het nummer eigen relaynamen (relayNames) heeft - het nummer krijgt ze direct na de aankoop. Zolang het ze niet heeft, valt de lease terug op de gedeelde pool en ziet de gebelde het demonummer van volai. Duurt dat langer dan een uur, schrijf dan naar de support.

6Limieten, quota en beveiliging

Het maximum is 1 actieve lease per nummer van u en maximaal 2 per account - een bewuste beveiliging die voorkomt dat één klant de hele gedeelde pool met relayslots bezet:

• from moet uw eigen volai-nummer zijn - anders from_number_not_owned. Zonder deze controle zou men zich kunnen voordoen als de lijn van een ander (caller ID spoofing).
• Dezelfde poorten als bij een gewoon gesprek - bel-me-niet-lijst (geldt alleen voor gesprekken, niet voor sms), automatische blokkade van 30 dagen na 3 mislukte pogingen naar hetzelfde nummer binnen 24 uur, premium-nummers, bescherming tegen lussen tussen volai-nummers, vergrendeling van het gebelde nummer en de algemene limiet op het aantal gesprekken. Niets hiervan is via relay te omzeilen.
• Volle pool -> 503 capacity_busy - relayslots vormen een gedeeld plafond voor gelijktijdigheid van het HELE platform, niet alleen van uw account. Bij capacity_busy wordt er niets in rekening gebracht, probeer het zo meteen opnieuw.
• De volledige REST-referentie (foutcodes, GET/DELETE bij leases) vindt u in de REST API.

Elke API-fout bevat cause (wie het oplost) en action (wat u moet doen) - zie Foutformaat in de REST API-referentie.