Anruf starten
const url = 'https://api.speakki.de/v1/calls';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"assistant_id":"5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44","to":"+4915228817386","variables":{"name":"Frau Meier"},"metadata":{"kundennummer":"4711"},"max_attempts":2}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.speakki.de/v1/calls \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44", "to": "+4915228817386", "variables": { "name": "Frau Meier" }, "metadata": { "kundennummer": "4711" }, "max_attempts": 2 }'Legt einen ausgehenden Anruf an. Der Assistent ruft sofort an oder zum geplanten Zeitpunkt. Abgelehnte Anfragen legen keinen Anruf an, der Fehlercode nennt den Grund.
Geprüft wird: Tarif und Freischaltung, Abrechnung, Assistent und Absender, Zielnummer (nur Deutschland, Österreich, Schweiz, keine Sonder- und Mehrwertnummern), Sperrliste und gesperrte Kontakte, Werte für alle Platzhalter, Anrufzeiten (Montag bis Samstag, 8 bis 20 Uhr, in deutscher Zeit), Tageslimit und höchstens ein Anruf je Nummer und Tag.
Ein Anruf je Nummer und Tag (number_called_today): Gezählt werden andere Anrufe an dieselbe Nummer am selben Kalendertag, die nicht abgebrochen oder abgelehnt wurden. Wiederholversuche desselben Anrufs zählen nicht.
Tageslimit (daily_limit_reached): Gezählt werden die Wählversuche der Organisation am Kalendertag, also auch jede Wiederholung. Ist das Limit beim Anlegen erreicht, wird die Anfrage abgelehnt. Ist es erst beim Wählen erreicht, wird der Anruf auf den nächsten Tag verschoben.
Variablen: Alle variables gehen als Angaben an den Assistenten, auch solche ohne Platzhalter in Begrüßung oder Auftrag. Senden Sie nur, was der Assistent wissen darf.
Idempotency-Key: Mit dem Header Idempotency-Key legt eine wiederholte Anfrage keinen zweiten Anruf an. Der Schlüssel gilt je Organisation (über alle API-Schlüssel hinweg) und ohne zeitliche Grenze. Kommt derselbe Schlüssel mit derselben Anfrage erneut, liefert die API den schon angelegten Anruf mit Status 200 zurück. Kommt er mit einer anderen Anfrage (anderes Ziel, anderer Assistent, andere Variablen, Metadaten, Zeiten oder Versuche), antwortet die API mit 409 und dem Code conflict und legt nichts an. Verglichen wird der Inhalt, nicht die Schreibweise: die Reihenfolge der Felder und die Schreibweise der Nummer spielen keine Rolle. Eine abgelehnte Anfrage belegt den Schlüssel nicht.
Berechtigung: calls:write.
Authorizations
Abschnitt betitelt „Authorizations“Parameters
Abschnitt betitelt „Parameters“Header Parameters
Abschnitt betitelt „Header Parameters“Frei gewählter Schlüssel je Auftrag, gilt je Organisation und ohne zeitliche Grenze. Dieselbe Anfrage mit demselben Schlüssel legt keinen zweiten Anruf an, sondern liefert den vorhandenen (Status 200). Eine andere Anfrage mit demselben Schlüssel wird mit 409 conflict abgelehnt.
Request Bodyrequired
Abschnitt betitelt „Request Bodyrequired“Auftrag für einen ausgehenden Anruf.
object
Assistent, der anruft (aus GET /v1/assistants).
Zielnummer, am besten in E.164 (+49…). Nur Deutschland, Österreich und Schweiz, keine Sonder- und Mehrwertnummern.
Absender aus GET /v1/phone-numbers. Ohne Angabe gilt die Absendernummer des Assistenten.
Werte für die Platzhalter des Assistenten, z. B. {"name": "Frau Meier"}. Höchstens 30 Einträge.
object
Freie Daten, höchstens 4096 Bytes als JSON. Sie kommen im Call-Objekt und im Webhook zurück.
object
Versuche insgesamt, Standard 1.
Abstand zwischen zwei Versuchen in Minuten, Standard 120.
Responses
Abschnitt betitelt „Responses“Es gab schon einen Anruf mit diesem Idempotency-Key. Er wird unverändert zurückgegeben.
Ein ausgehender Anruf (Auftrag) mit seinen Versuchen.
object
ID des Anrufs.
queued wartet (auch zwischen zwei Versuchen), dialing klingelt, in_progress Gespräch läuft, completed Gespräch geführt, not_reached alle Versuche ohne Gespräch, canceled abgebrochen, blocked vor dem Wählen abgelehnt.
Zielnummer in E.164.
Absendernummer in E.164.
Werte für die Platzhalter in Begrüßung und Auftrag.
object
Ihre freien Daten, unverändert zurückgegeben.
object
Versuche insgesamt, die für diesen Anruf erlaubt sind.
Bisherige Wählversuche.
Auftrag angelegt am.
Alle Wählversuche in ihrer Reihenfolge.
Ein Wählversuch.
Example
{ "id": "0b1d7c2e-6a0f-4d0b-9a55-2f4f8f1c7e10", "status": "completed", "block_reason": null, "to": "+4915228817386", "from": "+493023125010", "assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44", "campaign_id": null, "variables": { "name": "Frau Meier" }, "metadata": { "kundennummer": "4711" }, "scheduled_at": null, "next_attempt_at": null, "max_attempts": 2, "attempt_count": 1, "last_result": "answered", "created_at": "2026-11-16T09:00:00.000Z", "finished_at": "2026-11-16T09:02:10.000Z", "attempts": [ { "number": 1, "result": "answered", "started_at": "2026-11-16T09:00:02.000Z", "ended_at": "2026-11-16T09:02:10.000Z", "duration_seconds": 118 } ]}Anruf angelegt.
Ein ausgehender Anruf (Auftrag) mit seinen Versuchen.
object
ID des Anrufs.
queued wartet (auch zwischen zwei Versuchen), dialing klingelt, in_progress Gespräch läuft, completed Gespräch geführt, not_reached alle Versuche ohne Gespräch, canceled abgebrochen, blocked vor dem Wählen abgelehnt.
Zielnummer in E.164.
Absendernummer in E.164.
Werte für die Platzhalter in Begrüßung und Auftrag.
object
Ihre freien Daten, unverändert zurückgegeben.
object
Versuche insgesamt, die für diesen Anruf erlaubt sind.
Bisherige Wählversuche.
Auftrag angelegt am.
Alle Wählversuche in ihrer Reihenfolge.
Ein Wählversuch.
Example
{ "id": "0b1d7c2e-6a0f-4d0b-9a55-2f4f8f1c7e10", "status": "completed", "block_reason": null, "to": "+4915228817386", "from": "+493023125010", "assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44", "campaign_id": null, "variables": { "name": "Frau Meier" }, "metadata": { "kundennummer": "4711" }, "scheduled_at": null, "next_attempt_at": null, "max_attempts": 2, "attempt_count": 1, "last_result": "answered", "created_at": "2026-11-16T09:00:00.000Z", "finished_at": "2026-11-16T09:02:10.000Z", "attempts": [ { "number": 1, "result": "answered", "started_at": "2026-11-16T09:00:02.000Z", "ended_at": "2026-11-16T09:02:10.000Z", "duration_seconds": 118 } ]}Ungültige Anfrage.
Einheitliches Fehlerformat aller Antworten unter /v1.
object
Der Fehler.
object
Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.
Meldung für Menschen, auf Deutsch.
Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.
object
Examples
{ "error": { "code": "invalid_request", "message": "Die Anfrage ist ungültig." }}API-Schlüssel fehlt oder ist ungültig.
Einheitliches Fehlerformat aller Antworten unter /v1.
object
Der Fehler.
object
Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.
Meldung für Menschen, auf Deutsch.
Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.
object
Examples
{ "error": { "code": "unauthorized", "message": "Der API-Schlüssel fehlt oder ist ungültig. Senden Sie ihn als „Authorization: Bearer spk_live_…“." }}Nicht erlaubt: Tarif, Freischaltung oder Berechtigung des Schlüssels.
Einheitliches Fehlerformat aller Antworten unter /v1.
object
Der Fehler.
object
Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.
Meldung für Menschen, auf Deutsch.
Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.
object
Examples
{ "error": { "code": "insufficient_scope", "message": "Diesem API-Schlüssel fehlt die Berechtigung für diese Anfrage." }}{ "error": { "code": "plan_required", "message": "Ausgehende Anrufe sind ab dem Tarif Professional enthalten." }}{ "error": { "code": "access_not_approved", "message": "Ausgehende Anrufe sind für diese Organisation noch nicht freigeschaltet." }}Nicht gefunden.
Einheitliches Fehlerformat aller Antworten unter /v1.
object
Der Fehler.
object
Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.
Meldung für Menschen, auf Deutsch.
Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.
object
Examples
{ "error": { "code": "assistant_not_found", "message": "Dieser Assistent wurde nicht gefunden." }}Passt nicht zum aktuellen Zustand.
Einheitliches Fehlerformat aller Antworten unter /v1.
object
Der Fehler.
object
Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.
Meldung für Menschen, auf Deutsch.
Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.
object
Examples
{ "error": { "code": "conflict", "message": "Die Anfrage passt nicht zum aktuellen Zustand." }}Die Anfrage ist zu groß (Body über 1 MB). Code invalid_request.
Einheitliches Fehlerformat aller Antworten unter /v1.
object
Der Fehler.
object
Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.
Meldung für Menschen, auf Deutsch.
Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.
object
Examples
{ "error": { "code": "invalid_request", "message": "Die Anfrage ist ungültig." }}Falscher Content-Type. Senden Sie JSON als application/json. Code invalid_request.
Einheitliches Fehlerformat aller Antworten unter /v1.
object
Der Fehler.
object
Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.
Meldung für Menschen, auf Deutsch.
Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.
object
Examples
{ "error": { "code": "invalid_request", "message": "Die Anfrage ist ungültig." }}Fachlich abgelehnt. Der Code nennt den Grund.
Einheitliches Fehlerformat aller Antworten unter /v1.
object
Der Fehler.
object
Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.
Meldung für Menschen, auf Deutsch.
Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.
object
Examples
{ "error": { "code": "billing_blocked", "message": "Anrufe sind gerade nicht möglich. Bitte prüfen Sie Tarif und Zahlung." }}{ "error": { "code": "assistant_outbound_disabled", "message": "Für diesen Assistenten sind ausgehende Anrufe nicht eingeschaltet." }}{ "error": { "code": "from_number_missing", "message": "Für diesen Assistenten ist keine Absendernummer hinterlegt." }}{ "error": { "code": "from_number_not_allowed", "message": "Als Absender sind nur eigene, aktive Rufnummern möglich." }}{ "error": { "code": "invalid_number", "message": "Bitte geben Sie eine gültige Telefonnummer an, zum Beispiel +49 171 2345678." }}{ "error": { "code": "country_not_allowed", "message": "Ausgehende Anrufe sind nur nach Deutschland, Österreich und in die Schweiz möglich." }}{ "error": { "code": "special_number", "message": "Sonder- und Mehrwertnummern können nicht angerufen werden." }}{ "error": { "code": "own_number", "message": "Eigene Rufnummern können nicht angerufen werden." }}{ "error": { "code": "suppressed", "message": "Diese Nummer steht auf der Sperrliste und wird nicht mehr angerufen." }}{ "error": { "code": "contact_blocked", "message": "Dieser Kontakt ist gesperrt." }}{ "error": { "code": "outside_call_hours", "message": "Außerhalb der Anrufzeiten sind keine Anrufe möglich." }}{ "error": { "code": "daily_limit_reached", "message": "Das Tageslimit für ausgehende Anrufe ist erreicht." }}{ "error": { "code": "number_called_today", "message": "Diese Nummer wurde heute bereits angerufen." }}{ "error": { "code": "missing_variables", "message": "Es fehlen Werte für Variablen in Begrüßung oder Auftrag." }}Zu viele Anfragen. retry-after und x-ratelimit-reset nennen die Sekunden, bis wieder Anfragen möglich sind.
Einheitliches Fehlerformat aller Antworten unter /v1.
object
Der Fehler.
object
Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.
Meldung für Menschen, auf Deutsch.
Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.
object
Examples
{ "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte versuchen Sie es gleich noch einmal." }}Interner Fehler.
Einheitliches Fehlerformat aller Antworten unter /v1.
object
Der Fehler.
object
Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.
Meldung für Menschen, auf Deutsch.
Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.
object
Examples
{ "error": { "code": "internal_error", "message": "Interner Fehler. Bitte versuchen Sie es später noch einmal." }}