Siirry sisältöön
REST API

Tekstiviestit ja puhelut suoraan n8n-työnkulusta

n8n kutsuu volain REST API:a HTTP Request -solmun kautta - ilman koodia työnkulku voi lähettää tekstiviestin, käynnistää puhelun puheagentin kautta ja saada tuloksen takaisin webhookina.

Alla olevat vaiheet kuvaavat manuaalisen yhteyden yleisillä HTTP Request- ja Webhook-solmuilla. Yhteisöliittymän lähdekoodi, nykyinen saatavuus sekä asennus- ja julkaisuohjeet löytyvät GitHubin README-tiedostosta.

1Tallenna avain credentialiksi

Luo n8n:ssä uusi HTTP Header Auth -tyyppinen credential: otsakkeen nimi Authorization, arvo Bearer vk_SINUN_AVAIMESI (avain löytyy portaalista kohdasta tekoälyavustaja). Liitä se jokaiseen HTTP Request -solmuun, joka kutsuu osoitetta /v1/* - sama avain kelpaa tekstiviesteille, puheluille ja webhookille.

2Lähetä tekstiviesti työnkulusta

Lisää HTTP Request -solmu: metodi POST, osoite https://volai.cz/v1/messages, JSON-runko kentillä to ja body. Vastauksessa on priceHal (hinta saldoyksikön sadasosina, viestin kaikista segmenteistä) ja segments - erikoismerkkejä, kuten å, ä ja ö, sisältävä teksti vie useamman segmentin kuin pelkkä ASCII-viesti. Alla oleva esimerkki jättää viestin tekstin siksi tarkoituksella ilman erikoismerkkejä, jotta se mahtuu yhteen segmenttiin - erikoismerkeillä se toimii samoin, mutta segmenttejä kuluu enemmän.

bash
curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_SINUN_AVAIMESI" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "body": "Tilaus on valmis noudettavaksi."}'

3Soita asiakkaalle agentin kautta

Toinen HTTP Request -solmu: POST https://volai.cz/v1/calls kentillä to ja agentId olemassa olevalle puheagentille (luodaan portaalissa tai kutsulla POST /v1/agents) - agentilla on oltava oma numero liitettynä, muuten kutsu päättyy virheeseen agent_no_number. Kutsu vain käynnistää puhelun ja palauttaa sen id:n - varsinainen lopputulos (onnistui, ei vastattu, epäonnistui) tulee seuraavan vaiheen webhookista.

bash
curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_SINUN_AVAIMESI" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "agentId": "ag_kx91fa2b"}'

4Määritä webhook, jotta työnkulku saa vastauksen

Lisää Webhook-tyyppinen trigger (n8n luo sille URL-osoitteen) ja tallenna sama osoite kutsulla PUT /v1/webhook yhdessä niiden tapahtumien luettelon kanssa, jotka sinua kiinnostavat. Huomaa: tyhjä events-taulukko ei tarkoita ei yhtään tapahtumaa vaan kaikki - luettele ne siksi aina erikseen. Vastaus palauttaa myös secret-arvon - tallenna se heti, GET /v1/webhook ei palauta sitä enää koskaan.

bash
curl -X PUT https://volai.cz/v1/webhook \
  -H "Authorization: Bearer vk_SINUN_AVAIMESI" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://oma-n8n.app.n8n.cloud/webhook/volai", "events": ["call.completed", "message.sent"]}'

5Tarkista allekirjoitus ennen rungon käsittelyä

Jokaisessa kutsussa on otsake Volai-Signature muodossa t=<unix>,v1=<hex>. Laske Code-solmussa HMAC-SHA256 arvosta {t}.{rawBody} omalla secret-arvollasi ja vertaa sitä arvoon v1 - käsittele runko vasta, kun ne täsmäävät. Ota Webhook-solmun kohdassa Add Options käyttöön asetus Raw Body - ilman sitä n8n jäsentää rungon suoraan ja tarkat tavut, joista allekirjoitus laskettiin, katoavat. Kun asetus on päällä, runko tulee binääridatana (ominaisuus data), ei kentässä json.body - alla oleva koodi lukee sen siksi funktiolla getBinaryDataBuffer, joka toimii riippumatta siitä, tallentaako n8n binääridatan muistiin, levylle vai S3:een. Sisäänrakennettua crypto-moduulia voi käyttää Code-solmussa vain itse ylläpidetyssä n8n:ssä, jossa NODE_FUNCTION_ALLOW_BUILTIN=crypto on päällä - n8n Cloud ei tue moduulien tuontia lainkaan, joten tarkistus ei mahdu siellä yhteen solmuun. Cloudissa ketjua pidennetäänkin Extract From File -solmulla (toiminto Extract From Text File) - se muuttaa ensin binääridatan tekstiksi vapaavalintaiseen kenttään (esimerkiksi rawBody) - ja vasta sen jälkeen Crypto-solmu (toiminto Hmac, tyyppi SHA256, koodaus HEX, arvona lauseke, joka yhdistää otsakkeen aikaleiman ja kentän rawBody, salaisuus annettuna Crypto-credentialilla eikä tavallisessa tekstikentässä) laskee tunnisteen ilman koodia; vertailun arvoon v1 päättää IF-solmu.

javascript
// Syöte Webhook-solmusta, jossa Raw Body -asetus on päällä: otsake on arvo
// "Volai-Signature", esim. "t=1756111640,v1=8f2ac1d4..."; raakasisältö
// tulee binääridatana (oletusominaisuus "data"), ei kentässä json.body.
const header = $input.first().json.headers['volai-signature'];

// getBinaryDataBuffer toimii kaikissa n8n:n binääridatan tallennustiloissa
// (oletuksena muisti sekä filesystem/S3) - suora luku
// $input.first().binary.data.data toimii vain muistitilassa.
const rawBody = (await this.helpers.getBinaryDataBuffer(0, 'data')).toString('utf8');

// secret on vaiheen 4 arvo (PUT /v1/webhook) - lue se tuotannossa
// n8n-credentialista tai ympäristömuuttujasta, älä kirjoita sitä koskaan suoraan koodiin
const secret = 'whsec_korvaa_omallasi';

const crypto = require('crypto'); // vain itse ylläpidetty n8n, ks. vaiheen teksti

const [tPart, v1Part] = header.split(',');
const t = tPart.replace('t=', '');
const v1 = v1Part.replace('v1=', '');

const expected = crypto
  .createHmac('sha256', secret)
  .update(`${t}.${rawBody}`)
  .digest('hex');

if (expected !== v1) {
  throw new Error('Virheellinen allekirjoitus otsakkeessa Volai-Signature');
}

Mitä sillä voi tehdä

Tekstiviestivahvistus tilauksen jälkeen

Verkkokauppa tai ajanvarausjärjestelmä lähettää n8n:lle webhookin, kun uusi tilaus saapuu - työnkulku lähettää heti vahvistustekstiviestin arvioidulla noutoajalla.

Lähtevät puhelut suunnittelijasta tai taulukosta

Rivi Google Sheetsissä, Airtablessa tai CRM:ssä käynnistää HTTP Request -solmun, joka soittaa asiakkaalle puheagentin kautta - muistutus ajasta, kehotus viimeistellä tilaus tai lyhyt kysely.

Puhelun tulos takaisin järjestelmään

Webhook call.completed toimittaa litteroinnin, yhteenvedon ja agentin puhelun aikana keräämät tiedot (data) - työnkulku kirjaa ne CRM:ään, taulukkoon tai Slackiin ilman, että kukaan kuuntelee tallennetta käsin.

Usein kysyttyä

Onko volaille olemassa virallinen n8n-solmu?
volain yhteisöliittymän n8n-nodes-volai lähdekoodipaketti on saatavilla. Se tukee tekstiviestejä, puheluita, ääniviestejä ja automaattisia webhook-triggereitä. GitHubin README-tiedostossa kuvataan nykyinen saatavuus sekä asennus ja julkaisu. Käyttö n8n Cloudissa edellyttää alustan vahvistusta, jota ei ole vielä saatu.
Mistä tiedän, että webhook tuli todella volaista eikä joltain muulta?
Otsakkeen Volai-Signature allekirjoituksesta (HMAC-SHA256 kutsun PUT /v1/webhook antamalla secret-arvolla, tallenna se heti). Kaava esimerkkeineen löytyy sivulta /docs/webhooky.
Mitä tapahtuu, jos HTTP Request aikakatkeaa ja n8n yrittää uudelleen?
Lisää otsake Idempotency-Key valitsemallasi pysyvällä arvolla, esimerkiksi tilauksen tunnuksella. 24 tunnin sisällä toistettu kutsu samalla avaimella palauttaa täsmälleen saman vastauksen - toista tekstiviestiä tai toista puhelua ei lähetetä.
Maksaako automatisointi n8n:llä extraa?
Ei - n8n ei lisää hintaan mitään. Hinnat ovat samat kuin hinnastossa: tekstiviesti 0,0567 €, lähtevä puhelu 0,0384 €/min, puheagentista peritään lisäksi 0,105 €/min. Koko hinnasto löytyy sivulta /cenik.

Kokeile heti

Rekisteröidy, niin saat ensimmäiset 2 € meiltä.