Zum Inhalt springen
Hilfe-Center
Support kontaktierenApp öffnen

Kampagne anlegen

POST
/v1/campaigns
curl --request POST \
--url https://api.speakki.de/v1/campaigns \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "Terminerinnerung November", "assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44", "recipients": [ { "to": "+4915228817386", "variables": { "name": "Frau Meier", "termin": "Dienstag" } }, { "to": "+491729925904", "variables": { "name": "Herr Kurz", "termin": "Mittwoch" } } ], "call_window": { "days": [ 1, 2, 3, 4, 5 ], "from": "09:00", "to": "17:00" }, "max_attempts": 2, "contact_source": "Bestandskunden mit Einwilligung aus dem Kundenportal", "consent_confirmed": true, "start": true }'

Legt eine Kampagne mit einer festen Empfängerliste an: entweder recipients oder eine Kontaktliste aus dem Dashboard. Ungültige Empfänger werden nicht übernommen und in rejected_recipients gemeldet, doppelte Nummern nur einmal. Mit start: true läuft die Kampagne sofort los, sonst bleibt sie ein Entwurf. Der Assistent ruft die Empfänger nacheinander an, mit der eingestellten Pause dazwischen. Für jeden Empfänger gelten dieselben Grenzen wie für einen einzelnen Anruf. Höchstens 5 Kampagnen laufen gleichzeitig.

Berechtigung: campaigns:write.

Media typeapplication/json

Neue Kampagne mit Empfängern.

object
name
required

Name der Kampagne, höchstens 80 Zeichen.

string
>= 1 characters <= 80 characters
assistant_id
required

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

string format: uuid
from_number_id

Ohne Angabe gilt die Absendernummer des Assistenten.

string format: uuid
recipients

Empfänger in der Reihenfolge der Anrufe, höchstens 2000. Entweder recipients oder contact_list_id.

Array<object>
>= 1 items <= 2000 items
object
to
required

Zielnummer, am besten in E.164.

string
variables

Werte für die Platzhalter des Assistenten.

object
key
additional properties
string
contact_list_id

Kontaktliste aus dem Dashboard. Die Kontakte werden beim Anlegen kopiert, Variablen sind name, firma und email.

string format: uuid
start_at
Any of:
string format: date-time
call_window

Anrufzeiten der Kampagne. Nur innerhalb von Montag bis Samstag, 8 bis 20 Uhr, und innerhalb der Anrufzeiten der Organisation.

object
days
required

Wochentage, 1 = Montag bis 6 = Samstag.

Array<integer>
>= 1 items
from
required

Beginn in deutscher Zeit, frühestens 08:00.

string
/^([01]\d|2[0-3]):[0-5]\d$/
to
required

Ende in deutscher Zeit, spätestens 20:00.

string
/^([01]\d|2[0-3]):[0-5]\d$/
pause_seconds

Pause zwischen zwei Empfängern in Sekunden, Standard 30.

integer
>= 10 <= 600
max_attempts

Versuche je Empfänger, Standard 1.

integer
>= 1 <= 3
retry_delay_minutes

Abstand zwischen zwei Versuchen in Minuten, Standard 120.

integer
>= 120 <= 10080
contact_source
required

Herkunft der Kontakte, zum Beispiel „Bestandskunden“.

string
>= 10 characters <= 500 characters
consent_confirmed
required

Muss true sein: Sie bestätigen, dass alle Empfänger dem Anruf zugestimmt haben.

boolean
start

true startet die Kampagne sofort nach dem Anlegen, sonst bleibt sie ein Entwurf.

boolean

Kampagne angelegt.

Media typeapplication/json

Die angelegte Kampagne, dazu die Empfänger, die nicht übernommen wurden.

object
id
required

ID der Kampagne.

string format: uuid
name
required

Name der Kampagne.

string
status
required

draft Entwurf, scheduled Start geplant, running läuft, paused pausiert, completed alle Empfänger erledigt, canceled abgebrochen.

string
Allowed values: draft scheduled running paused completed canceled
assistant_id
required
Any of:
string format: uuid
from_number_id
required
Any of:
string format: uuid
from_number
required

Absender in E.164.

string | null
contact_list_id
required
Any of:
string format: uuid
variables
required

Namen der Variablen, die die Empfänger mitbringen.

Array<string>
missing_variables
required

Platzhalter des Assistenten, für die die Empfänger keinen Wert haben. Solche Empfänger werden übersprungen.

Array<string>
start_at
required
Any of:
string format: date-time
call_window
required

Anrufzeiten der Kampagne. Nur innerhalb von Montag bis Samstag, 8 bis 20 Uhr, und innerhalb der Anrufzeiten der Organisation.

object
days
required

Wochentage, 1 = Montag bis 6 = Samstag.

Array<integer>
>= 1 items
from
required

Beginn in deutscher Zeit, frühestens 08:00.

string
/^([01]\d|2[0-3]):[0-5]\d$/
to
required

Ende in deutscher Zeit, spätestens 20:00.

string
/^([01]\d|2[0-3]):[0-5]\d$/
pause_seconds
required

Pause zwischen zwei Empfängern in Sekunden.

integer
max_attempts
required

Versuche je Empfänger.

integer
retry_delay_minutes
required

Abstand zwischen zwei Versuchen in Minuten.

integer
contact_source
required

Herkunft der Kontakte, wie beim Anlegen angegeben.

string
consent_confirmed_at
required
Any of:
string format: date-time
next_dispatch_at
required
Any of:
string format: date-time
started_at
required
Any of:
string format: date-time
completed_at
required
Any of:
string format: date-time
created_at
required

Angelegt am.

string format: date-time
counts
required

Empfänger nach Stand.

object
total
required

Alle Empfänger der Kampagne.

integer
pending
required

Noch nicht angerufen.

integer
queued
required

Anruf läuft oder wartet auf den nächsten Versuch.

integer
reached
required

Gespräch geführt.

integer
not_reached
required

Anruf beendet ohne Gespräch.

integer
skipped
required

Nie angerufen (Sperrliste, gesperrter Kontakt, ungültig oder Kampagne abgebrochen).

integer
rejected_recipients
required

Empfänger, die nicht übernommen wurden (ungültige Nummer, anderes Land, Sondernummer).

Array<object>
object
line
required

Position in recipients (ab 1) bzw. in der Kontaktliste.

integer
reason
required

missing_number Nummer fehlt, invalid_number keine gültige Nummer, country_not_allowed nicht Deutschland, Österreich oder Schweiz, special_number Sonder- oder Mehrwertnummer, value_too_long ein Wert über 500 Zeichen, invalid_variables ungültiger Variablenname.

string
Allowed values: missing_number invalid_number country_not_allowed special_number value_too_long invalid_variables
value
required

Der beanstandete Wert, gekürzt.

string
duplicate_recipients
required

Einträge mit einer Nummer, die schon vorkam.

integer

Example

{
"status": "draft",
"call_window": {
"days": [
1,
2,
3,
4,
5
],
"from": "09:00",
"to": "17:00"
},
"rejected_recipients": [
{
"reason": "missing_number"
}
]
}

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

Examplefrom_number_not_allowed
{
"error": {
"code": "from_number_not_allowed",
"message": "Als Absender sind nur eigene, aktive Rufnummern möglich."
}
}

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."
}
}