Siirry sisältöön

Oppaat

Oma agentti

Haluatko yhdistää volai-numeroon oman ääniympäristösi - ElevenLabs Conversational AI:n omassa workspacessasi, Vapin, Retellin tai vaikka oman Asterisk- tai FreeSWITCH-IVR:n - sisäänrakennetun agentin sijaan? Tällä sivulla kuvataan molemmat suunnat: saapuvat ja lähtevät puhelut. Lähtevissä puheluissa vältät lisäksi agenttilisän 0,105 €/min - agentin ajat (ja maksat) itse omalla alustallasi.

Pikakatsaus

Saapuvat puhelut asetetaan reitittämällä numero alustan SIP-osoitteeseen - ei uutta mekaniikkaa. Lähtevät puhelut kulkevat lyhytikäisen relay-yhteyden kautta, koska alusta ei itse pysty pitämään linjaa pysyvästi rekisteröitynä SIP-asiakkaana.

Tarvitset: volai-numeron, API-avaimen (vk_...) ja tilin alustalla (ElevenLabs, Vapi, oma puhelinvaihde...).

1Oma agentti vai sisäänrakennettu

Molemmat tiet kulkevat saman numeron ja saman saldon kautta - ne eroavat vain siinä, KUKA ajaa keskustelun logiikkaa ja mitä se maksaa lisää:

KriteeriSisäänrakennettu agenttiOma agentti
Kuka ohjaa puheluaMe - yksi systemPrompt, meidän äänemme ja meidän ElevenLabs-workspacemme.Sinä - mikä tahansa alusta, oma kehote, oma ääni, omat työkalut.
AsetusYksi POST /v1/agents-kutsu.Numeron SIP-tunnukset + alustasi määritys (tämä sivu).
Puhelun hinta0,0384 €/min lähtevä, 0,0209 €/min saapuvasama - 0,0384 €/min lähtevä, 0,0209 €/min saapuva
Agenttilisä+ 0,105 €/minei mitään - maksat vain puheluminuutit
Litterointi, yhteenveto, puhelinvastaajan tunnistusKyllä, automaattisesti.Ei - hoitaa (tai ei hoida) oma alustasi.

Vältät agenttilisän, mutta emme anna sinulle mitään ylimääräistä ilmaiseksikaan - oman alustasi (ElevenLabs, Vapi...) maksat suoraan sen oman hinnaston mukaan. Veloitamme vain puheluminuutit volai-linjalla, aivan kuten SIP-asiakkaasta tai sisäänrakennetusta agentista. Hinnat ovat ilman arvonlisäveroa, kuten koko hinnasto.

2Saapuvat puhelut omalle agentille

Ei uutta mekaniikkaa - vain nykyinen reititys tilassa mode: "sip" (sama kuin omalla softphonella, ks. SIP) ), ja kenttään sipUri annetaan alustan SIP-osoite. ElevenLabsin SIP-trunk-numerolle, joka on rekisteröity OMAAN workspaceesi, se on osoite, jossa on sama numero kuin volai-linjallasi:

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

Ja ElevenLabs-tililläsi (Settings → Phone Numbers → Import → SIP trunk) numero rekisteröidään kentällä inbound_trunk_config:

json
{
  "provider": "sip_trunk",
  "phone_number": "+420601234567",
  "label": "Oma agenttini",
  "inbound_trunk_config": {
    "allowed_addresses": ["81.31.45.0/24"],
    "media_encryption": "allowed"
  }
}

allowed_addresses yllä on meidän signalointialueemme (81.31.45.0/24) - turvallisempi kuin yleinen 0.0.0.0/0, joka päästää INVITE-pyynnön sisään mistä tahansa. Molemmat päästävät puhelun läpi, mutta tuonnissa ilman tunnuksia sallittujen osoitteiden lista on AINOA tarkistus - anna siksi alue, ei 0.0.0.0/0.

Käytätkö muuta alustaa kuin ElevenLabsia? Sama periaate - selvitä, mihin SIP-osoitteeseen se odottaa numerosi puheluita, ja anna se kenttään sipUri. Vapin kohdalla sama alue annetaan BYO-trunkin kentässä gateways.

Vapin reititysosoite on sip:<E164>@<credentialId>.sip.vapi.ai - <credentialId> löytyy Vapista BYO SIP -trunkiltasi, ja EU-alueen organisaatio käyttää verkkotunnusta sip.eu.vapi.ai verkkotunnuksen sip.vapi.ai sijaan. Pelkkä sip.vapi.ai kuuluu Vapin omille numeroille eikä toimi meiltä tulevalle numerolle. Jätä BYO-trunkin käyttäjätunnus ja salasana tyhjiksi, Vapi tunnistaa puhelumme gatewaysin IP-osoitteesta.

Anna alue gatewaysissa erikseen IP-osoitteena 81.31.45.0 ja verkkomaskina (netmask) 24. Oletusmaskilla 32 Vapi päästäisi läpi vain yhden osoitteen ja hylkäisi puhelumme.

3Lähtevät puhelut omalta agentilta (relay)

Tämä on vastakkainen suunta - alustasi soittaa itse ulos. Useimmat ääni-AI-alustat (ElevenLabs mukaan lukien) eivät kuitenkaan pysty rekisteröimään puhelinlinjaa pysyvästi SIP-asiakkaana - ne lähettävät vain yhden todennetun puhelun linjasi tunnuksilla. Puhelinverkko ei päästä tällaista puhelua suoraan kohdenumeroon, ja siksi se ohjataan lyhytikäisen relay-yhteyden kautta:

Miksi relay eikä suora soitto

Kohdenumeroon soittaminen suoraan trunkin kautta ei toimi kumpaankaan suuntaan: verkkomme ulkopuoliseen numeroon puhelu ei synny lainkaan (alusta ilmoittaa virheestä, eikä siitä jää jälkeä mihinkään), ja toiseen volai-numeroon verkossamme se yhdistyy vain SISÄISESTI nimettömänä puheluna - se ei koskaan poistu verkostamme, vaikka näyttää yhdistyneeltä. Relay on ainoa tapa saada puhelu todella ulos.

1. Aseta alustasi linjallesi

Hae linjasi SIP-tunnukset:

bash
curl "https://volai.cz/v1/numbers/+420601234567/sip" \
  -H "Authorization: Bearer vk_SINUN_AVAIN"
json
{
  "server": "sip.volai.cz",
  "username": "123456",
  "password": "a1b2c3d4e5f6",
  "outboundTrunkAddress": "sip.volai.cz",
  "port": 5060,
  "transport": "tcp",
  "inboundSignallingCidrs": ["81.31.45.0/24"]
}

Vastaus palauttaa kentän server (softphonen REGISTERiä varten, ks. SIP) ja kentän outboundTrunkAddress ERIKSEEN - ne eivät ole keskenään vaihdettavissa.

Ja anna outboundTrunkAddress - EI server - alustan lähtevän trunkin osoitteeksi. ElevenLabsissa se on kentässä outbound_trunk_config kyseiselle puhelinnumerolle (Settings → Phone Numbers → numerosi → Outbound calling), täsmälleen tässä muodossa:

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

Anna täsmälleen outboundTrunkAddress

Lähtevän trunkin osoitteen on oltava täsmälleen vastauksen arvo outboundTrunkAddress - riippumatta siitä, onko se sama kuin server. Toinen osoite tarkoittaa, ettei puhelua reititetä verkossa, ja alusta ilmoittaa sen virheenä 1011 sip request timed out - puheluhistoriaan ei jää mitään.

2. Luo relay-yhteys

Heti ennen puhelua (yhteys on lyhytikäinen, ks. rajat alla) kutsu:

bash
curl -X POST https://volai.cz/v1/relay \
  -H "Authorization: Bearer vk_SINUN_AVAIN" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "from": "+420601234567"}'
json
{
  "id": "rl_4f2a91cd",
  "sipName": "volai_relay_2",
  "sipUri": "sip:volai_relay_2@sip.volai.cz",
  "expiresAt": 1756111760000,
  "callId": "c_9d4e2b7f"
}

Soitettavan numeron annat MEILLE kentässä to - alusta ei näe sitä koskaan, vaan saa vastauksesta vain paljaan sipNamen.

3. Pyydä alustaa soittamaan sipNameen

Paljas nimi, ei koko SIP-URI

ElevenLabs to_number hylkää koko SIP-URI:n viestillä "SipCallTo should be a phone number or SIP user, not a full SIP URI" - siksi yllä oleva vastaus palauttaa kentät sipName (paljas volai_relay_2) ja sipUri (koko sip:volai_relay_2@sip.volai.cz) ERIKSEEN. Vain edellinen kuuluu kenttään to_number - ei koskaan koko URI.

ElevenLabsissa tämä tarkoittaa kutsua /v1/convai/sip-trunk/outbound-call kentällä to_number asetettuna suoraan arvoon sipName:

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

agent_id löytyy agentiltasi ElevenLabsissa, agent_phone_number_id on tuodun numeron phone_number_id - tuontivastaus palauttaa sen, tai sen voi lukea Phone numbers -listasta.

Käytätkö ElevenLabsin sijaan omaa SIP-asiakasta tai puhelinvaihdetta? Soita koko sipUri suoraan, kuten tavallinen SIP-puhelu - rajoitus koskee vain alustoja, jotka haluavat pelkän nimen ilman etuliitettä sip: lainkaan.

4. Mitä tapahtuu seuraavaksi

Puhelinverkko ottaa puhelun vastaan nimellä volai_relay_2, ohjaa sen eteenpäin kentän to mukaan ja asettaa soitetulle näkyvän numeron kentän from mukaiseksi - soitettu näkee näytöllään volai-linjasi, ei relay-paikan sisäistä nimeä (jos numerolla on omat relay-nimet - ks. Laskutus alla, muuten soitettu näkee volain demonumeron). Kun puhelu päättyy, lease vapautetaan ja minuutit veloitetaan kuten tavallisesta lähtevästä puhelusta - 0,0384 €/min, ei agenttilisää.

Vastaus soittopyyntöön tulee vasta koko soittoäänen jälkeen (helposti kymmeniä sekunteja) - se ei ole virhe, mutta lyhyt aikakatkaisu sinun päässäsi voi näyttää epäonnistumiselta, vaikka puhelu on käynnissä.

4Vianmääritys

Yleisimmät viestit oman agentin kanssa ja mitä niille tehdään:

ViestiSyyKorjaus
1011 sip request timed outLähtevän trunkin osoite ei ole outboundTrunkAddress.Anna ElevenLabsissa outbound_trunk_config.address-arvoksi outboundTrunkAddress SIP-tunnusten vastauksesta, ei server.
SipCallTo should be a phone number or SIP user, not a full SIP URIto_number sisältää koko sipUrin paljaan nimen sijaan.Kenttään to_number kuuluu vain sipName vastauksesta POST /v1/relay.
Puhelu päättyy heti alustalla (failed ElevenLabsissa), meillä ei näy mitäänPuhelinnumeroon soitettiin suoraan, ei relayn kautta.Luo relay-yhteys (POST /v1/relay) ja soita palautettuun sipNameen.
max auth retry attempts reached for SIP inviteAlusta ei läpäissyt kirjautumista: joko lähtevän trunkin käyttäjätunnus tai salasana ei täsmää, tai puhelu tuli puhelinnumerona sipNamen sijaan - verkko vaatii silloin uuden kirjautumisen, jota alusta ei osaa tehdä.Kopioi käyttäjätunnus ja salasana täsmälleen numeron SIP-tunnuksista (username, password). Anna kenttään to_number vain sipName vastauksesta POST /v1/relay ja käynnistä puhelu API:n kautta (POST /v1/convai/sip-trunk/outbound-call) tai ElevenLabsin MCP-työkalulla make_outbound_call, ei lomakkeella, joka hyväksyy vain puhelinnumeroita. Lease odottaa puhelua vain ttlSecs (oletus 120 s).
404 from_number_not_ownedfrom pyynnössä POST /v1/relay ei ole sinun volai-numerosi.Anna kenttään from täsmälleen se volai-numero, josta soitat.
400 relay_lease_limitTällä numerolla (1) tai tilillä (2) on jo aktiivinen lease.Odota, kunnes lease vapautuu, tai peruuta käyttämätön (DELETE /v1/relay/{id}).
503 capacity_busyJaettu relay-paikkojen joukko on tilapäisesti täynnä.Mitään ei veloiteta - yritä hetken kuluttua uudelleen.
Saapuva puhelu ei soiNumeroa ei ole tuotu ElevenLabsiin, allowed_addresses ei päästä meidän aluettamme sisään tai reititystä ei ole tallennettu volaihin.Tarkista kaikki kolme yllä olevaa vaihetta; jos vaihde vastaa 401, täytä reitityksen käyttäjätunnus ja salasana.
Soitettu näkee volai-numeron sinun numerosi sijaanNumerolla ei vielä ole omia relay-nimiä. Ne luodaan heti oston jälkeen, mutta tällä kertaa se ei onnistunut.Seuraava puhelu yrittää luoda ne uudelleen itsestään. Jos soitettu näkee volai-numeron vielä tunnin kuluttuakin, ota yhteyttä tukeen.
Toistettu puhelu hylätään heti (SIP 603)Alusta soitti samaan sipNameen uudelleen, yleensä vastaamatta jääneen puhelun jälkeen. Yksi lease yhdistää vain yhden puhelun.Luo uusi lease (POST /v1/relay) ennen jokaista yritystä, myös toistettaessa vastaamatta jääneen puhelun jälkeen, ja sammuta alustasta automaattinen uudelleensoitto.

5Laskutus

Relayn kautta tehty lähtevä puhelu veloitetaan samalla hinnalla kuin tavallinen lähtevä puhelu - 0,0384 €/min - ilman minkäänlaista agenttilisää. Hinnat ovat ilman arvonlisäveroa, kuten koko hinnasto.

Samanaikaisten puhelujen määrä on rajattu (ks. rajat alla): enintään 1 aktiivinen puhelu yhtä numeroasi kohden ja enintään 2 tiliä kohden yhtä aikaa.

Soitettu näkee volai-linjasi vain, jos numerolla on omat relay-nimet (relayNames) - numero saa ne heti oston jälkeen. Kunnes sillä ne ovat, lease palaa jaettuun joukkoon ja soitettu näkee volain demonumeron. Jos se kestää yli tunnin, ota yhteyttä tukeen.

6Rajat, kiintiöt ja turvallisuus

Katto on 1 aktiivinen lease numeroa kohden ja enintään 2 tiliä kohden - tietoinen suoja sitä vastaan, että yksi asiakas varaa koko jaetun relay-paikkojen joukon:

MitäArvo
Lease odottaa ensimmäistä puhelua (pending)oletus 120 s, ttlSecs 15-300 s
Puhelu käynnissä (active)15 minuuttia
Aktiivinen lease yhtä numeroasi kohdenenintään 1
Aktiivisia leasejä tiliä kohdenenintään 2
Leasen käyttökertakäyttöinen - toinen puhelu samalla leasella hylätään, ja myös uusi yritys vastaamatta jääneen puhelun jälkeen vaatii uuden leasen
  • from on oltava sinun oma volai-numerosi - muuten from_number_not_owned. Ilman tätä tarkistusta voisi esiintyä toisen linjana (väärennetty soittajan numero).
  • Samat esteet kuin tavallisessa puhelussa - soittokieltolista (koskee vain puheluita, ei tekstiviestejä), automaattinen 30 päivän esto 3 epäonnistuneen yrityksen jälkeen samaan numeroon 24 tunnin sisällä, palvelunumerot, suoja volai-numeroiden välisiä silmukoita vastaan, soitetun numeron esto ja yleinen puhelumäärien raja. Mitään näistä ei voi kiertää relayn kautta.
  • Joukko täynnä -> 503 capacity_busy - relay-paikat ovat jaettu samanaikaisuuden katto KOKO alustalle, ei vain tilillesi. Virheen capacity_busy yhteydessä mitään ei veloiteta, yritä hetken kuluttua uudelleen.
  • Täydellinen REST-viite (virhekoodit, GET/DELETE leaseille) löytyy sivulta REST API.

Jokaisessa API-virheessä on cause (kuka korjaa asian) ja action (mitä tehdä) - ks. Virheen muoto REST API -viitteessä.