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.
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.
Variablen in Begrüßung und Auftrag
Abschnitt betitelt „Variablen in Begrüßung und Auftrag“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_variablesnennt 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.
Geplanter Zeitpunkt
Abschnitt betitelt „Geplanter Zeitpunkt“Mit scheduled_at legen Sie den Start fest:
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:00oder alsZfü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.
Wiederholversuche
Abschnitt betitelt „Wiederholversuche“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.
Idempotency-Key
Abschnitt betitelt „Idempotency-Key“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.
Zustände eines Anrufs
Abschnitt betitelt „Zustände eines Anrufs“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.
Ergebnisse eines Versuchs
Abschnitt betitelt „Ergebnisse eines Versuchs“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.
Anrufe abfragen
Abschnitt betitelt „Anrufe abfragen“# ein Anrufcurl https://api.speakki.de/v1/calls/0b1d7c2e-6a0f-4d0b-9a55-2f4f8f1c7e10 \ -H "Authorization: Bearer spk_live_IHR_SCHLUESSEL"
# alle Anrufe, die niemanden erreicht habencurl "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.
Anruf abbrechen
Abschnitt betitelt „Anruf abbrechen“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.