Oppaat
SIP
Kun puheagentti tai yksinkertainen soitonsiirto ei riitä ja numero halutaan yhdistää omaan softphoneen tai puhelinvaihteeseen (PBX), tarvitaan SIP-trunk-palveluntarjoaja - volai on sellainen. Tämä sivu on vaiheittainen opas.
1Saapuvat puhelut omalle SIP-palvelimellesi
Aseta numeron reititykseksi mode: "sip" ja anna sipUri -osoitteesi - sieltä puhelu menee suoraan sinulle, ei agentillemme eikä soitonsiirtoon:
curl -X PATCH "https://volai.eu/v1/numbers/+420601234567" \
-H "Authorization: Bearer vk_SINUN_AVAIN" \
-H "Content-Type: application/json" \
-d '{"routing": {"mode": "sip", "sipUri": "sip:reception@oma-palvelin.fi"}}'Veloitetaan vain saapuva minuutti (0,0209 €/min), agenttia ei lisätä - pyynnön täydellinen muoto ja muut reititystilat löytyvät sivulta REST API -viite.
Todennus omassa vaihteessasi
Puhelun omalle SIP-palvelimellesi lähetämme ensin todentamattomana INVITE-viestinä osoitteeseen sipUri. Vaihde, joka vastaa siihen kirjautumishaasteella (401/407) ja ilman lisätietoja hylkää puhelun, ei saa puhelua tässä muodossa - haasteeseen ei ole kukaan vastaamassa. Täytä siksi reititykseen myös sipUsername ja sipPassword - kun molemmat on täytetty, verkkomme kirjautuu kohteeseen (SIP digest) ja valitsee kutsutun numeron. Varmennettu live-puhelulla Vapin sisäiseen SIP-numeroon, joka hyväksyy tunnukset sisällöstä riippumatta. Se, yhdistyykö puhelu myös sinun vaihteessasi, riippuu vaihteesta - sen on todella vastattava INVITE-viestiin haasteella ja hyväksyttävä annettu nimi ja salasana; sitä emme takaa jokaiselle vaihteelle (testissä se ei onnistunut esimerkiksi Twilion SIP-toimialuetta vastaan). Ilman sipUsername- ja sipPassword-kenttiä reititys pysyy nykyisessä todentamattomassa muodossa. Tunnukset lisätään reititykseen näin:
curl -X PATCH "https://volai.eu/v1/numbers/+420601234567" \
-H "Authorization: Bearer vk_SINUN_AVAIN" \
-H "Content-Type: application/json" \
-d '{"routing": {"mode": "sip", "sipUri": "sip:reception@oma-palvelin.fi", "sipUsername": "reception", "sipPassword": "salainensalasana123"}}'Kutsutun numeron lähetämme aina täsmälleen siinä muodossa, kuin se on sipUrissa ennen @-merkkiä - emme lisää emmekä poista suuntanumeroa tai nollaa, joten kohdevaihteen on osattava käsitellä juuri se, mitä siihen kirjoitetaan.
sipUsername ja sipPassword eivät saa sisältää kaksoispistettä, @-merkkiä, välilyöntiä, lainausmerkkiä tai kenoviivaa, ja kumpikin saa olla enintään 64 merkkiä pitkä.
Vain toisen kentän täyttäminen ei onnistu - API palauttaa virheen ”Please fill in both username and password, or leave both empty.”.
Kaksoispiste sipUrin käyttäjäosassa (ennen @-merkkiä) ja portti isännässä (palvelimen jälkeisen kaksoispisteen jälkeen, esim. :5060) eivät vielä toimi yhdessä täytettyjen sipUsername- ja sipPassword-kenttien kanssa - molemmat antavat saman kovan virheen. Ilman tunnuksia molemmat toimivat muuttumattomina.
Poikkeus: Vapin BYO SIP -trunk (osoite <credentialId>.sip.vapi.ai, EU-alueen organisaatiolle <credentialId>.sip.eu.vapi.ai) ei käytä tunnuksia. Vapi tunnistaa puhelumme trunkin gatewayiden IP-osoitteesta, ja täytettyjen sipUsername- ja sipPassword-kenttien kanssa puhelu ei yhdistyisi, joten API hylkää tällaisen reitityksen koodilla validation. Tämä ei koske Vapin sisäistä SIP-numeroa (sip:<nimi>@sip.vapi.ai).
Kuka muu näkee nimen ja salasanan
Nimi ja salasana kulkevat puhelun mukana verkkoomme ja säilyvät reitityksen teknisissä lokeissa - et ole ainoa, joka ne näkee. Luo siksi vaihteeseen erillinen tili vain meitä varten, älä käytä pääylläpitäjän salasanaa.
Osittainen päivitys: pois jätetty kenttä pysyy ennallaan
Jos PATCH-pyynnössä lähetät vain sipUri ja jätät pois sipUsername sekä sipPassword , molemmat kentät pysyvät muuttumattomina - niitä ei tarvitse antaa uudelleen jokaisen sipUrin muutoksen yhteydessä. Pois jätetty kenttä (puuttuu kokonaan bodystä) säilyttää aina tallennetun arvon; tunnukset poistetaan vain nimenomaisella tyhjällä merkkijonolla MOLEMMISSA kentissä samanaikaisesti. Ainoa poikkeus on palvelimen vaihto: jos muutat myös sipUrin @-merkin jälkeistä osaa, salasana on lähetettävä uudelleen - tallennettua salasanaa emme lähetä toiselle palvelimelle kuin sille, jota varten se annettiin. Nykyinen tila tarkistetaan vastauksen kentästä hasSipPassword .
Eikö puhelu yhdistynyt? Salli meidät IP-osoitteella
SIP-kirjautuminen toimii vain kohteessa, joka antaa INVITE-viestille haasteen ja hyväksyy tunnukset (varmennettu Vapin sisäisellä SIP-numerolla) - muuten puhelu ei pääse perille riippumatta siitä, onko tunnukset täytetty. Signalointimme tulee alueelta 81.31.45.0/24, käytännössä useimmiten osoitteista 81.31.45.51 ja 81.31.45.56. Salli koko alue vaihteessa - silloin puhelu tunnistetaan lähdeosoitteesta, ei nimestä ja salasanasta, eikä tunnuksia tarvita lainkaan.
2Numeron SIP-tunnukset
Linjan kirjautumistiedot haetaan yhdellä kutsulla:
curl "https://volai.eu/v1/numbers/+420601234567/sip" \
-H "Authorization: Bearer vk_SINUN_AVAIN"{
"server": "sip.volai.cz",
"username": "123456",
"password": "a1b2c3d4e5f6",
"outboundTrunkAddress": "sip.volai.cz",
"port": 5060,
"transport": "tcp",
"inboundSignallingCidrs": ["81.31.45.0/24"]
}Määritys softphonessa (Zoiper, Linphone)
Molemmissa sovelluksissa annetaan periaatteessa samat tiedot, vain eri nimillä - etsi ”Lisää tili” / ”SIP-tili”:
| Kenttä | Arvo |
|---|---|
| Palvelin / Toimialue | sip.volai.cz |
| Käyttäjätunnus | yllä olevasta vastauksesta (username) |
| Salasana | yllä olevasta vastauksesta (password) |
| Siirto | TCP |
| Portti | 5060 (SIP:n oletusportti - jos kenttä tarjoaa tyhjän vaihtoehdon, jätä se tyhjäksi) |
Vaatiiko asiakasohjelma realmin täyttämistä?
Jätä kenttä tyhjäksi - useimmat asiakasohjelmat saavat realmin palvelimen haasteesta. Asiakasohjelman lokissa saattaa näkyä verkkomme tekninen toimialue, mikä on täysin normaalia. Jos asiakasohjelma vaatii realmin pakollisena, ota yhteyttä tukeen.
Asetusten tallentamisen jälkeen softphonen pitäisi rekisteröityä (tilakuvake ”online”/”rekisteröity”), ja numeroon soitetut puhelut alkavat soida siinä heti.
3Lähtevät puhelut SIP-asiakasohjelmasta
Kun softphone on rekisteröity, se voi soittaa ulos tämän linjan kautta itse - mitään API:amme ei tarvitse kutsua, puhelut soitetaan suoraan asiakasohjelmasta kuin tavalliselta puhelinlinjalta.
Minuutit veloitetaan volai-saldosta
SIP-asiakasohjelmasta soitetut lähtevät puhelut veloitetaan samalla hinnalla kuin API:n kautta soitettu lähtevä puhelu (0,0384 €/min) ja ne vähennetään saldosta - ei mistään erillisestä SIP-tilistä. Hinnat ovat ilman ALV:tä, kuten koko hinnasto.
Yhteys kulkee suoraan asiakasohjelman ja palvelimen välillä sip.volai.cz, ei API:mme kautta, joten minuutteja ei voida estää täsmälleen valinnan hetkellä. Suoraan SIP-asiakasohjelmasta soitettu puhelu veloitetaan jälkikäteen verkon tietueiden perusteella - aikaisintaan 10 minuuttia sen päättymisestä, yleensä puolen tunnin kuluessa - eikä se näy saldossa valinnan hetkellä. Päivittäinen puheluraja ja saldon tarkistus valinnan yhteydessä eivät koske näitä puheluita, koska ne valvovat vain API:n kautta soitettuja puheluita - saldo voi siis laskea alle nollan. Kun saldo laskee nollaan, uudet maksulliset toimet API:n/MCP:n kautta aletaan hylätä (puhelu vaatii vähintään pienimmän puhelusumman suuruisen saldon). Kun saldo laskee alle nollan, linjan SIP-yhteys katkaistaan muutaman minuutin kuluessa, soitonsiirto irrotetaan ja lähetetään sähköposti; kun saldoa on ladattu vähintään pienimmän puhelusumman verran, kaikki jatkuu itsestään eikä salasana muutu. Jos velkaa ei maksa viikon kuluessa, numero vapautetaan takaisin varastoon (jolloin SIP-yhteys päättyy lopullisesti). Seuraa siksi saldoa hyvissä ajoin, älä vasta nollassa.
Onko sinulla tekoälypuheagentti eikä softphonea?
Tämä vaihe edellyttää asiakasohjelmaa, joka voi rekisteröityä linjalle (SIP REGISTER) - softphone, PBX. Alusta, joka vain lähettää puhelun todennettuna kerran ilman pysyvää rekisteröintiä (tyypillisesti tekoälypuheagentit kuten ElevenLabs), tarvitsee toisenlaisen tavan - katso Oma agentti.
Alustan lähtevän trunkin osoite haetaan kentästä outboundTrunkAddress, ei yllä olevasta server-kentästä - lisää tuolla sivulla.
4Rajoitukset
- Yksi rekisteröinti linjaa kohden - yksi tunnuspari tukee kerrallaan yhtä rekisteröityä laitetta. Jos toinen asiakasohjelma kirjautuu sisään, ensimmäinen menettää todennäköisesti rekisteröintinsä - älä luota useaan laitteeseen yhtä aikaa samalla linjalla.
- Lähtevät omalta agentilta kyllä, täysi trunk-peering ei - linjan tunnukset on tarkoitettu siihen, että SINUN asiakasohjelmasi rekisteröityy meille puhelimena. Lähtevät puhelut omalta puheagentilta (ElevenLabs tai muu alusta) TOIMIVAT kuitenkin nykyisin - releen kautta, katso Oma agentti. Vaihdettasi ei silti voi yhdistää tasavertaiseksi operaattoriksi, jolla on oma reititys ulkoa tuleville SAAPUVILLE puheluille - käytä siihen reititystä
forwardnumerosta vaihteesi numeroon. - Vain ääni - ei videota eikä muita SIP-laajennuksia.
Liittyvää
REST API
Täydellinen kuvaus jokaisesta päätepisteestä: numerot, puhelut, tekstiviestit, tekstiviestien matkapuhelinnumerot, agentit ja niiden luonnokset, työkalut, tallenteet, webhookit, soittokieltolista, välitys, tili, tehtävät, saldo, asiakirjat, kalenterit ja integraatiot.
Puheagentti
Järjestelmäkehote, työkalut, siirto ihmiselle, tallenteet ja jäsennelty puhelutieto.
Tuo oma agenttisi
Yhdistä kolmannen osapuolen alusta (ElevenLabs, Asterisk...) ilman agenttilisää.