Kunden aus einem n8n-Workflow anrufen

Sie können einen Kunden aus n8n anrufen, ohne eine Zeile Code zu schreiben: Fügen Sie Ihrem Workflow einen HTTP-Request-Node hinzu, richten Sie ihn auf POST https://volai.cz/v1/calls mit einem Header Authorization: Bearer vk_... und einem Body aus {to, agentId} - und Ihr Sprachagent wählt die Nummer genau dann, wenn der Workflow es verlangt. Unten finden Sie die vollständige Einrichtung: Workflow-Daten in den Prompt des Agenten übernehmen, das Ergebnis des Anrufs zurück nach n8n holen und ganz ohne Agent anrufen, indem Sie zwei Nummern direkt verbinden.

Was Sie brauchen

• Eine n8n-Instanz - Cloud oder selbst gehostet, jede aktuelle Version.
• Ein volai-Konto und einen API-Schlüssel aus dem Portal (Einstellungen -> API & MCP) in der Form vk_.... Speichern Sie ihn in n8n als Header-Auth-Zugangsdaten (Header Authorization, Wert Bearer vk_...), damit Sie den Schlüssel nicht in jeden Node kopieren müssen.
• Eine eigene Nummer mit zugeordnetem Sprachagenten - legen Sie ihn im Portal an oder über /docs/agent. Noch kein Agent? Sie können trotzdem anrufen, indem Sie zwei Nummern direkt verbinden (die Variante mit from weiter unten).

1HTTP-Request-Node hinzufügen

Methode POST, URL https://volai.cz/v1/calls, Authentifizierung über Ihre gespeicherten Zugangsdaten, Body Content Type JSON. Der Body braucht to (die Nummer des Kunden) und agentId (die ID des Agenten aus dem Portal) - beide sind Pflicht, und zwar genau EINES von agentId/from/systemPrompt, nie mehr als eines.

{
  "to": "={{ $json.phone }}",
  "agentId": "ag_kx91fa2b",
  "variables": {
    "customer_name": "={{ $json.name }}",
    "order_number": "={{ $json.order }}"
  },
  "ringingTimeoutSecs": 30
}

Werte in der Form ={{...}} sind n8n-Ausdrücke - $json liest Felder aus dem vorherigen Node des Workflows (zum Beispiel aus einem Webhook „neue Bestellung“ oder einer Tabellenzeile).

2Workflow-Daten in den Prompt des Agenten übernehmen

variables ist ein Objekt von String zu String, das der Agent als dynamische Variablen erhält - in seinem Systemprompt verweisen Sie darauf als {{customer_name}}. Grenzen: höchstens 20 Schlüssel, Schlüssel bis 64 Zeichen, Werte bis 512 Zeichen. Die Namen attempt_id, caller_number und called_number sind reserviert - volai füllt sie selbst aus, und gleichnamige Werte aus Ihrem Workflow würden verworfen.

ringingTimeoutSecs (5 bis 60 Sekunden, Standard 25) legt fest, wie lange das Telefon klingeln darf, bevor ein unbeantworteter Anruf mit endReason: "no_answer" endet. Ein längeres Timeout erhöht die Chance, dass der Kunde abnimmt, belegt aber auch länger eine Leitung für ausgehende Anrufe.

3Antwort lesen und optional auf das Ergebnis warten

Eine erfolgreiche Antwort kommt sofort zurück, der Anruf hat aber gerade erst begonnen - status ist initiated, kein Endzustand:

{
  "id": "c_9d4e2b7f",
  "status": "initiated"
}

Möchten Sie das Ergebnis im selben Workflow-Lauf abwarten statt über einen separaten Webhook? Fügen Sie direkt nach dem HTTP-Request-Node einen zweiten Node hinzu, der GET /v1/calls/{id} mit dem Parameter waitSecs (0 bis 45 Sekunden) aufruft - der Server antwortet, sobald der Anruf endet oder das Timeout erreicht ist, je nachdem, was zuerst eintritt:

curl "https://volai.cz/v1/calls/c_9d4e2b7f?waitSecs=30" \
  -H "Authorization: Bearer vk_YOUR_KEY"

Das Ergebnis zurückholen: ein Webhook nach n8n

Für einen produktiven Workflow ist es meist praktischer, nicht inline zu warten, sondern das Ergebnis separat zustellen zu lassen: Fügen Sie in n8n einen Webhook-Node hinzu (ein neuer Workflow genügt), kopieren Sie seine Production URL und registrieren Sie sie einmalig bei volai:

curl -X PUT https://volai.cz/v1/webhook \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-instance.app.n8n.cloud/webhook/volai-calls",
    "events": ["call.completed", "call.failed", "call.no_answer"]
  }'

Die Antwort enthält ein secret (in der Form whsec_...) - speichern Sie es, Sie brauchen es, um die Signatur jeder eingehenden Anfrage zu prüfen. volai sendet einen Header Volai-Signature in der Form t=<unix>,v1=<hex> - den vollständigen Verifizierungscode in TypeScript und Python finden Sie auf /docs/webhooky. Er lässt sich nicht unverändert in einen n8n-Code-Node übernehmen: Der HMAC wird über den ROHEN Request-Body berechnet, deshalb müssen Sie im Webhook-Node die Option Raw Body aktivieren (ohne sie liefert n8n bereits geparstes JSON und die Signatur stimmt nie überein), und im Code-Node importieren Sie crypto mit require, nicht mit import. Verarbeiten Sie den Body nicht, bevor Sie die Signatur geprüft haben.

Das kommt an, sobald der Anruf beendet ist:

{
  "event": "call.completed",
  "ts": 1756111640000,
  "data": {
    "id": "c_9d4e2b7f",
    "direction": "out",
    "from": "+420601234567",
    "to": "+420777123456",
    "status": "completed",
    "durationSecs": 90,
    "priceHal": 513,
    "answeredBy": "human",
    "endReason": "completed",
    "transcript": [
      { "role": "agent", "message": "Guten Tag, ich rufe wegen der Bestellung A-42 an." },
      { "role": "caller", "message": "Ja, das weiß ich schon, danke für die Erinnerung." }
    ],
    "summary": "Der Kunde hat den Erhalt der Bestellung A-42 bestätigt.",
    "data": {
      "order_confirmed": true
    }
  }
}

Der Schlüssel data innerhalb von data ist optional und enthält genau die Felder, die Sie beim Agenten in dessen dataFields konfiguriert haben - das Beispiel oben (order_confirmed) ist nur zur Veranschaulichung, Ihre Felder werden anders heißen. Ein nachfolgender n8n-Node kann dann anhand dieser Felder verzweigen, etwa um einen CRM-Eintrag zu aktualisieren oder den Anruf neu zu planen.

Wie rufen Sie ohne Agent an?

Wenn Sie keinen Sprachagenten brauchen, sondern nur eine direkte Verbindung zwischen zwei Nummern (zum Beispiel einem Vertriebsmitarbeiter und einem Kunden), senden Sie from statt agentId:

{
  "to": "+420777123456",
  "from": "+420601234567"
}

volai ruft zuerst from an, und sobald jemand abnimmt, wählt es to. Beide Gesprächsabschnitte werden getrennt mit 0.92 CZK pro Minute abgerechnet (ohne Agent-Aufschlag). from ist die Nummer, unter der SIE abnehmen - typischerweise Ihr Handy - und kann jede tschechische oder slowakische Nummer sein, sie muss nicht zu Ihrem volai-Konto gehören. Die eigentliche Voraussetzung ist eine andere: Ihr Konto braucht mindestens eine eigene volai-Nummer, denn über sie wird der Anruf abgerechnet und sie sehen beide Seiten im Display (ohne sie gibt volai bridge_needs_number zurück). Tragen Sie nur keine volai-Nummer in from ein, die auf einen Agenten oder auf SIP geleitet wird - das Netz würde diesen ersten Abschnitt statt zu Ihnen zum Agenten verbinden, und Ihr Telefon würde nie klingeln.

Was kostet ein solcher Anruf?

Ein ausgehender Anruf über einen Agenten wird als Summe zweier Tarife abgerechnet: die ausgehende Minute (0.92 CZK) plus der Agent-Aufschlag OBENDRAUF (2.50 CZK), beide laut Preisliste vom 2. September 2026. Ein Anruf von 90 Sekunden kommt auf 5.13 CZK:

Abgerechnet wird sekundengenau, nicht pro angefangener Minute - ein kürzerer Anruf kostet entsprechend weniger. Die vollständige Preisliste (Nummern, Agent, SMS) finden Sie unter /cenik.

Sicher wiederholen (Idempotency-Key)

n8n kann einen Node bei einem Fehler automatisch wiederholen (Retry On Fail) - ohne Absicherung würde das zwei echte Anrufe beim selben Kunden bedeuten. Fügen Sie einen Header Idempotency-Key mit einem Wert hinzu, der für einen Workflow-Lauf stabil bleibt (n8n stellt dafür {{ $execution.id }} bereit, oder nutzen Sie Ihre eigene Bestell-ID) - mit demselben Schlüssel erhalten Sie innerhalb von 24 Stunden die Antwort des ersten Versuchs zurück, und der Anruf wird nicht doppelt ausgelöst:

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reminder-order-A-42" \
  -d '{"to": "+420777123456", "agentId": "ag_kx91fa2b"}'

Was tun, wenn die API einen Fehler zurückgibt?

Diese Tabelle deckt die Varianten agentId und from ab - die Zustände, die nur für einen Testanruf ohne eigene Nummer (systemPrompt) gelten, fehlen bewusst, das ist ein anderer Ablauf.

Wie es weitergeht

Eine vollständige Übersicht dessen, was Sie aus n8n tun können (SMS, Nummern, Do-not-call-Liste), finden Sie in der Anleitung zur n8n-Integration. Die vollständige REST-Referenz steht unter /docs/api, die vollständige Liste der Webhook-Ereignisse samt Signaturprüfung unter /docs/webhooky.

Wie es weitergeht