Zum Inhalt springen
50 kr sichern
REST API

SMS und Anrufe direkt aus Ihrem n8n-Workflow

n8n ruft die REST-API von volai über den HTTP-Request-Node auf - ohne Code senden Sie eine SMS, starten einen Anruf über einen Sprachagenten und erhalten das Ergebnis per Webhook zurück.

1Schlüssel als Credential speichern

Legen Sie in n8n ein neues Credential vom Typ HTTP Header Auth an: Headername Authorization, Wert Bearer vk_IHR_SCHLUESSEL (den Schlüssel finden Sie im Portal im Bereich KI-Assistent). Weisen Sie es jedem HTTP-Request-Node zu, der volai.cz/v1/* aufruft - derselbe Schlüssel gilt für SMS, Anrufe und den Webhook.

2SMS aus dem Workflow senden

Fügen Sie einen HTTP-Request-Node hinzu: Methode POST, URL https://volai.cz/v1/messages, JSON-Body mit den Feldern to und body. Die Antwort enthält priceHal (den Preis in Hundertsteln der Abrechnungswährung für alle Segmente der Nachricht) und segments - ein Text mit Sonderzeichen belegt mehr Segmente als eine reine ASCII-Nachricht. Im Beispiel unten steht der Nachrichtentext deshalb bewusst ohne Umlaute, damit er in einem Segment bleibt - mit Umlauten funktioniert es genauso, verbraucht aber mehr Segmente.

bash
curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_IHR_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "body": "Ihre Bestellung liegt zur Abholung bereit."}'

3Kunden über Ihren Agenten anrufen

Ein zweiter HTTP-Request-Node: POST https://volai.cz/v1/calls mit to und der agentId eines vorhandenen Sprachagenten (Sie legen ihn im Portal oder per POST /v1/agents an) - dem Agenten muss eine eigene Nummer zugewiesen sein, sonst endet die Anfrage mit dem Fehler agent_no_number. Die Anfrage startet den Anruf nur und liefert seine id zurück - das tatsächliche Ergebnis (abgeschlossen, nicht abgenommen, fehlgeschlagen) erfahren Sie über den Webhook im nächsten Schritt.

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

4Webhook einrichten, damit sich der Workflow zurückmeldet

Fügen Sie einen Webhook-Trigger hinzu (n8n generiert Ihnen die URL) und speichern Sie genau diese Adresse per PUT /v1/webhook zusammen mit der Liste der Ereignisse, die Sie interessieren. Achtung: Ein leeres Feld events bedeutet nicht kein Ereignis, sondern ausnahmslos alle - zählen Sie sie daher lieber immer auf. Die Antwort liefert auch das secret - speichern Sie es sofort, GET /v1/webhook gibt es nicht mehr zurück.

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

5Signatur prüfen und erst dann den Body verarbeiten

Jede Anfrage trägt den Header Volai-Signature in der Form t=<unix>,v1=<hex>. Berechnen Sie in einem Code-Node den HMAC-SHA256 über {t}.{rawBody} mit Ihrem secret und vergleichen Sie ihn mit v1 - verarbeiten Sie den Body erst, wenn beide übereinstimmen. Aktivieren Sie im Webhook-Node unter Add Options die Option Raw Body - ohne sie parst n8n den Body sofort, und die Bytes, über die die Signatur berechnet wurde, gehen verloren. Bei aktivierter Option kommt er jedoch als Binärdaten an (Eigenschaft data), nicht in json.body - der Code unten liest den Body daher über getBinaryDataBuffer, das unabhängig davon funktioniert, ob n8n Binärdaten im Arbeitsspeicher, auf der Festplatte oder in S3 hält. Das integrierte crypto lässt sich im Code-Node nur bei self-hosted n8n mit aktiviertem NODE_FUNCTION_ALLOW_BUILTIN=crypto verwenden - n8n Cloud unterstützt den Import von Modulen gar nicht, die Prüfung passt dort also nicht in einen einzigen Node. In der Cloud verlängern Sie die Kette daher um einen Extract From File-Node (Operation Extract From Text File) - er wandelt die Binärdaten zunächst in Text in einem gewählten Feld um (zum Beispiel rawBody) - und erst dann berechnet ein Crypto-Node (Aktion Hmac, Typ SHA256, Kodierung HEX, als Wert ein Ausdruck, der den Zeitstempel aus dem Header mit dem Feld rawBody verbindet, das Secret über ein Crypto-Credential statt über ein gewöhnliches Textfeld) den Hash ohne Code; den Vergleich mit v1 schließt ein IF-Node ab.

javascript
// Eingabe aus dem Webhook-Node mit aktivierter Option Raw Body: Der Header ist der Wert
// "Volai-Signature", z. B. "t=1756111640,v1=8f2ac1d4..."; der rohe Body
// kommt als Binärdaten an (Standardname der Eigenschaft "data"), nicht in json.body.
const header = $input.first().json.headers['volai-signature'];

// getBinaryDataBuffer funktioniert in allen Speichermodi für Binärdaten in n8n
// (Standard im Arbeitsspeicher sowie Dateisystem/S3) - das direkte Lesen von
// $input.first().binary.data.data würde nur im Arbeitsspeichermodus klappen.
const rawBody = (await this.helpers.getBinaryDataBuffer(0, 'data')).toString('utf8');

// secret ist der Wert aus Schritt 4 (PUT /v1/webhook) - in der Produktion lesen Sie ihn
// aus einem n8n-Credential oder einer Umgebungsvariable und schreiben ihn nie fest in den Code
const secret = 'whsec_ersetzen_sie_durch_ihren';

const crypto = require('crypto'); // nur self-hosted n8n, siehe Text des Schritts

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('Ungültige Signatur Volai-Signature');
}

Was Sie damit tun können

Bestätigungs-SMS nach einer Bestellung

Ihr Onlineshop oder Reservierungssystem schickt bei einer neuen Bestellung einen Webhook an n8n - der Workflow versendet sofort eine SMS mit der Bestätigung und der voraussichtlichen Abholzeit.

Ausgehende Anrufe aus Planer oder Tabelle

Eine Zeile in Google Sheets, Airtable oder Ihrem CRM löst einen HTTP-Request-Node aus, der den Kunden über Ihren Sprachagenten anruft - Terminerinnerung, Aufforderung zum Abschluss einer Bestellung, kurze Umfrage.

Anrufergebnis zurück ins System schreiben

Der Webhook call.completed liefert das Transkript, die Zusammenfassung und die erfassten Angaben aus dem Anruf (data) - der Workflow schreibt sie ins CRM, in eine Tabelle oder sendet sie an Slack, ganz ohne manuelles Anhören der Aufzeichnung.

Häufige Fragen

Gibt es einen offiziellen n8n-Node für volai?
Noch nicht - heute genügen die allgemeinen Nodes HTTP Request und Webhook, die n8n immer mitbringt. Ein verifizierter Community-Node müsste das Review im n8n Creator Portal durchlaufen - wir bereiten ihn derzeit nicht vor.
Woran erkenne ich, dass der Webhook wirklich von volai kommt und nicht von jemand anderem?
Am Header Volai-Signature - einer HMAC-SHA256-Signatur mit dem secret, das Ihnen jedes PUT /v1/webhook zurückgibt (speichern Sie es sofort, GET gibt es nicht mehr zurück). Die genaue Formel samt Beispielen in Python und TypeScript finden Sie unter /docs/webhooky.
Was ist, wenn der HTTP Request in einen Timeout läuft und n8n ihn wiederholt?
Fügen Sie den Header Idempotency-Key mit einem beliebigen stabilen Wert hinzu (zum Beispiel der Bestell-ID). Innerhalb von 24 Stunden erhalten Sie auf eine wiederholte Anfrage mit demselben Schlüssel exakt dieselbe Antwort zurück - SMS und Anruf werden nicht ein zweites Mal ausgelöst.
Was kostet die Automatisierung im Vergleich zum manuellen Aufruf der API zusätzlich?
Nichts - für n8n fällt kein Aufpreis an. Es gelten dieselben Preise wie in der Preisübersicht: SMS 1,36 kr (≈ 0,06 EUR), ausgehender Anruf 0,92 kr/min (≈ 0,04 EUR), Sprachagent zusätzlich 2,50 kr/min (≈ 0,10 EUR). Die genauen Preise stehen unter /cenik.

Probieren Sie es gleich aus

Registrieren Sie sich und die ersten 50 kr gehen auf uns.

50 kr Guthaben erhaltenDokumentation öffnen