Zum Inhalt springen
Hilfe-Center
Support kontaktierenApp öffnen

Anruf starten

POST
/v1/calls
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.

Idempotency-Key
string
>= 1 characters <= 128 characters

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.

Media typeapplication/json

Auftrag für einen ausgehenden Anruf.

object
assistant_id
required

Assistent, der anruft (aus GET /v1/assistants).

string format: uuid
to
required

Zielnummer, am besten in E.164 (+49…). Nur Deutschland, Österreich und Schweiz, keine Sonder- und Mehrwertnummern.

string
>= 1 characters <= 32 characters
from_number_id

Absender aus GET /v1/phone-numbers. Ohne Angabe gilt die Absendernummer des Assistenten.

string format: uuid
variables

Werte für die Platzhalter des Assistenten, z. B. {"name": "Frau Meier"}. Höchstens 30 Einträge.

object
key
additional properties
string
<= 500 characters
metadata

Freie Daten, höchstens 4096 Bytes als JSON. Sie kommen im Call-Objekt und im Webhook zurück.

object
key
additional properties
scheduled_at
Any of:
string format: date-time
max_attempts

Versuche insgesamt, Standard 1.

integer
>= 1 <= 3
retry_delay_minutes

Abstand zwischen zwei Versuchen in Minuten, Standard 120.

integer
>= 120 <= 10080

Es gab schon einen Anruf mit diesem Idempotency-Key. Er wird unverändert zurückgegeben.

Media typeapplication/json

Ein ausgehender Anruf (Auftrag) mit seinen Versuchen.

object
id
required

ID des Anrufs.

string format: uuid
status
required

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.

string
Allowed values: queued dialing in_progress completed not_reached canceled blocked
block_reason
required
Any of:
string
Allowed values: plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
to
required

Zielnummer in E.164.

string
from
required

Absendernummer in E.164.

string
assistant_id
required
Any of:
string format: uuid
campaign_id
required
Any of:
string format: uuid
variables
required

Werte für die Platzhalter in Begrüßung und Auftrag.

object
key
additional properties
string
metadata
required

Ihre freien Daten, unverändert zurückgegeben.

object
key
additional properties
scheduled_at
required
Any of:
string format: date-time
next_attempt_at
required
Any of:
string format: date-time
max_attempts
required

Versuche insgesamt, die für diesen Anruf erlaubt sind.

integer
attempt_count
required

Bisherige Wählversuche.

integer
last_result
required
Any of:
string
Allowed values: answered no_answer busy voicemail failed
created_at
required

Auftrag angelegt am.

string format: date-time
finished_at
required
Any of:
string format: date-time
attempts
required

Alle Wählversuche in ihrer Reihenfolge.

Array<object>

Ein Wählversuch.

object
number
required

Nummer des Versuchs, beginnend bei 1.

integer
result
required
Any of:
string
Allowed values: answered no_answer busy voicemail failed
started_at
required

Beginn des Wählens.

string format: date-time
ended_at
required
Any of:
string format: date-time
duration_seconds
required
Any of:
integer

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.

Media typeapplication/json

Ein ausgehender Anruf (Auftrag) mit seinen Versuchen.

object
id
required

ID des Anrufs.

string format: uuid
status
required

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.

string
Allowed values: queued dialing in_progress completed not_reached canceled blocked
block_reason
required
Any of:
string
Allowed values: plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
to
required

Zielnummer in E.164.

string
from
required

Absendernummer in E.164.

string
assistant_id
required
Any of:
string format: uuid
campaign_id
required
Any of:
string format: uuid
variables
required

Werte für die Platzhalter in Begrüßung und Auftrag.

object
key
additional properties
string
metadata
required

Ihre freien Daten, unverändert zurückgegeben.

object
key
additional properties
scheduled_at
required
Any of:
string format: date-time
next_attempt_at
required
Any of:
string format: date-time
max_attempts
required

Versuche insgesamt, die für diesen Anruf erlaubt sind.

integer
attempt_count
required

Bisherige Wählversuche.

integer
last_result
required
Any of:
string
Allowed values: answered no_answer busy voicemail failed
created_at
required

Auftrag angelegt am.

string format: date-time
finished_at
required
Any of:
string format: date-time
attempts
required

Alle Wählversuche in ihrer Reihenfolge.

Array<object>

Ein Wählversuch.

object
number
required

Nummer des Versuchs, beginnend bei 1.

integer
result
required
Any of:
string
Allowed values: answered no_answer busy voicemail failed
started_at
required

Beginn des Wählens.

string format: date-time
ended_at
required
Any of:
string format: date-time
duration_seconds
required
Any of:
integer

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.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleinvalid_request
{
"error": {
"code": "invalid_request",
"message": "Die Anfrage ist ungültig."
}
}

API-Schlüssel fehlt oder ist ungültig.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleunauthorized
{
"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.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

{
"error": {
"code": "insufficient_scope",
"message": "Diesem API-Schlüssel fehlt die Berechtigung für diese Anfrage."
}
}

Nicht gefunden.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleassistant_not_found
{
"error": {
"code": "assistant_not_found",
"message": "Dieser Assistent wurde nicht gefunden."
}
}

Passt nicht zum aktuellen Zustand.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleconflict
{
"error": {
"code": "conflict",
"message": "Die Anfrage passt nicht zum aktuellen Zustand."
}
}

Die Anfrage ist zu groß (Body über 1 MB). Code invalid_request.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleinvalid_request
{
"error": {
"code": "invalid_request",
"message": "Die Anfrage ist ungültig."
}
}

Falscher Content-Type. Senden Sie JSON als application/json. Code invalid_request.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleinvalid_request
{
"error": {
"code": "invalid_request",
"message": "Die Anfrage ist ungültig."
}
}

Fachlich abgelehnt. Der Code nennt den Grund.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

{
"error": {
"code": "billing_blocked",
"message": "Anrufe sind gerade nicht möglich. Bitte prüfen Sie Tarif und Zahlung."
}
}

Zu viele Anfragen. retry-after und x-ratelimit-reset nennen die Sekunden, bis wieder Anfragen möglich sind.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Examplerate_limited
{
"error": {
"code": "rate_limited",
"message": "Zu viele Anfragen. Bitte versuchen Sie es gleich noch einmal."
}
}

Interner Fehler.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleinternal_error
{
"error": {
"code": "internal_error",
"message": "Interner Fehler. Bitte versuchen Sie es später noch einmal."
}
}