Zum Inhalt springen
Hilfe-Center
Support kontaktierenApp öffnen

Anrufe über die API starten

Mit POST /v1/calls legen Sie einen ausgehenden Anruf an. Ihr Assistent ruft sofort an oder zum geplanten Zeitpunkt, begrüßt die Person und führt den Auftrag aus, den Sie am Assistenten hinterlegt haben. Der Schlüssel braucht die Berechtigung calls:write.

Terminal-Fenster
curl https://api.speakki.de/v1/calls \
-H "Authorization: Bearer spk_live_IHR_SCHLUESSEL" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: termin-4711-erinnerung" \
-d '{
"assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44",
"to": "+4915228817386",
"variables": { "name": "Frau Meier", "termin": "Dienstag um 10 Uhr" },
"metadata": { "kundennummer": "4711" },
"max_attempts": 2
}'

Die API prüft vor dem Anlegen alle Regeln und Grenzen. Ist alles in Ordnung, antwortet sie mit Status 201 und dem Anruf. Wird die Anfrage abgelehnt, entsteht kein Anruf und die Antwort nennt den Grund als Fehlercode.

Feld Pflicht Bedeutung
assistant_id ja Assistent, der anruft. Die ID liefert GET /v1/assistants.
to ja Zielnummer, am besten in E.164 (+49...). Deutsche Schreibweisen wie 0152... rechnet die API um.
from_number_id nein Absender aus GET /v1/phone-numbers. Ohne Angabe gilt die Absendernummer des Assistenten.
variables nein Werte für die Platzhalter des Assistenten. Höchstens 30 Einträge, je Wert höchstens 500 Zeichen.
metadata nein Ihre freien Daten, höchstens 4096 Bytes als JSON. Sie kommen im Anruf und im Webhook unverändert zurück.
scheduled_at nein Geplanter Start als ISO 8601 mit Zeitzone. Ohne Angabe startet der Anruf sofort.
max_attempts nein Versuche insgesamt, 1 bis 3. Standard ist 1.
retry_delay_minutes nein Abstand zwischen zwei Versuchen in Minuten, 120 bis 10080 (7 Tage). Standard ist 120.

Alle Felder mit Typen und Beispielen stehen in der API-Referenz.

Am Assistenten schreiben Sie im Abschnitt Ausgehende Anrufe eine Begrüßung und einen Auftrag. Beide dürfen Platzhalter in doppelten geschweiften Klammern enthalten:

Guten Tag {{name}}, hier ist die digitale Assistentin der Mustermann Haustechnik.
Ich rufe wegen Ihres Termins am {{termin}} an.

Beim Anruf setzen Sie die Werte über variables ein. GET /v1/assistants nennt je Assistent die Namen der Platzhalter im Feld variables.

  • Für jeden Platzhalter ist ein Wert nötig. Fehlt einer, antwortet die API mit dem Code missing_variables. details.missing_variables nennt die fehlenden Namen.
  • Namen bestehen aus Buchstaben, Ziffern und Unterstrich, beginnen nicht mit einer Ziffer und sind höchstens 40 Zeichen lang.
  • Werte ohne Platzhalter sind erlaubt. Ihr Assistent bekommt alle Werte als Angaben zum Anruf mit und kann sie im Gespräch nutzen.

Geben Sie über variables nur mit, was Ihr Assistent im Gespräch wissen darf. metadata ist dagegen nur für Ihr eigenes Programm gedacht, der Assistent sieht diese Daten nicht.

Mit scheduled_at legen Sie den Start fest:

Terminal-Fenster
curl https://api.speakki.de/v1/calls \
-H "Authorization: Bearer spk_live_IHR_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44",
"to": "+4915228817386",
"variables": { "name": "Frau Meier", "termin": "Dienstag um 10 Uhr" },
"scheduled_at": "2026-11-17T09:30:00+01:00"
}'
  • Der Zeitpunkt braucht eine Zeitzone, entweder als Abstand wie +01:00 oder als Z für UTC.
  • Er darf höchstens 30 Tage in der Zukunft liegen.
  • Er muss in den Anrufzeiten liegen (Montag bis Samstag, 8 bis 20 Uhr deutscher Zeit, oder enger, wenn Ihre Organisation das eingestellt hat). Sonst antwortet die API mit outside_call_hours.

Auch ein sofortiger Anruf außerhalb der Anrufzeiten wird mit outside_call_hours abgelehnt. Die API verschiebt ihn nicht von selbst.

Mit max_attempts versucht Ihr Assistent es erneut, wenn er niemanden erreicht: nicht abgenommen, besetzt, Mailbox oder fehlgeschlagen. Zwischen zwei Versuchen liegen mindestens retry_delay_minutes Minuten. Fällt der nächste Versuch aus den Anrufzeiten, startet er zum nächsten erlaubten Zeitpunkt.

Solange ein weiterer Versuch aussteht, bleibt der Anruf queued und next_attempt_at nennt den frühesten Zeitpunkt. Nach einem geführten Gespräch gibt es keinen weiteren Versuch.

Ihr Assistent lässt es 30 Sekunden klingeln. Erkennt er eine Mailbox, legt er auf, ohne eine Nachricht zu hinterlassen. Ein Gespräch dauert höchstens 30 Minuten.

Senden Sie mit jedem Anruf den Header Idempotency-Key mit einem Wert, der in Ihrem System für genau diesen Auftrag steht, zum Beispiel termin-4711-erinnerung. Höchstens 128 Zeichen.

Schicken Sie dieselbe Anfrage noch einmal, etwa nach einem Netzwerkfehler, legt die API keinen zweiten Anruf an. So ruft Ihr Assistent niemanden doppelt an.

Wiederholte Anfrage Antwort
gleicher Schlüssel, gleicher Body Status 200 und der vorhandene Anruf, unverändert
gleicher Schlüssel, anderer Body Status 409 und der Code conflict

Der Schlüssel gilt je Organisation, über alle API-Schlüssel hinweg und ohne zeitliche Grenze. Verwenden Sie für einen neuen Auftrag einen neuen Wert. Eine abgelehnte Anfrage belegt den Schlüssel nicht.

Das Feld status zeigt, wo der Anruf steht.

status Bedeutung Abgeschlossen
queued wartet auf den Start oder auf den nächsten Versuch nein
dialing es klingelt nein
in_progress das Gespräch läuft nein
completed Gespräch geführt ja
not_reached alle Versuche ohne Gespräch ja
canceled abgebrochen ja
blocked vor dem Wählen abgelehnt, block_reason nennt den Grund ja

blocked entsteht, wenn sich zwischen Anlegen und Wählen etwas ändert, zum Beispiel landet die Nummer inzwischen auf der Sperrliste. block_reason trägt dann einen der Fehlercodes.

Jeder Wählversuch steht in attempts mit number, Zeiten und result. last_result am Anruf ist das Ergebnis des letzten Versuchs.

result Bedeutung Zählt auf Ihre Minuten
answered Gespräch geführt, duration_seconds nennt die Dauer ja
no_answer nicht abgenommen nein
busy besetzt nein
voicemail Mailbox erkannt und aufgelegt nein
failed der Anruf kam technisch nicht zustande nein

Solange ein Versuch läuft, ist result gleich null.

Terminal-Fenster
# ein Anruf
curl https://api.speakki.de/v1/calls/0b1d7c2e-6a0f-4d0b-9a55-2f4f8f1c7e10 \
-H "Authorization: Bearer spk_live_IHR_SCHLUESSEL"
# alle Anrufe, die niemanden erreicht haben
curl "https://api.speakki.de/v1/calls?status=not_reached&limit=50" \
-H "Authorization: Bearer spk_live_IHR_SCHLUESSEL"

GET /v1/calls liefert die Anrufe Ihrer Organisation, neueste zuerst. Filtern Sie mit status oder mit campaign_id nach einer Kampagne. Beide Anfragen brauchen die Berechtigung calls:read.

Das Gespräch selbst, mit Zusammenfassung und erfassten Angaben, finden Sie unter Gespräche. Dort verweist outbound_call_id auf den Anruf.

Terminal-Fenster
curl -X POST https://api.speakki.de/v1/calls/0b1d7c2e-6a0f-4d0b-9a55-2f4f8f1c7e10/cancel \
-H "Authorization: Bearer spk_live_IHR_SCHLUESSEL"

Abbrechen lässt sich ein Anruf nur, solange er queued ist, also vor dem Start oder zwischen zwei Versuchen. Die Antwort ist der Anruf mit status gleich canceled. Klingelt es schon, läuft das Gespräch oder ist der Anruf abgeschlossen, antwortet die API mit Status 409 und dem Code conflict.