Kampagne anlegen
const url = 'https://api.speakki.de/v1/campaigns';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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}'};
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/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.
Authorizations
Abschnitt betitelt „Authorizations“Request Bodyrequired
Abschnitt betitelt „Request Bodyrequired“Neue Kampagne mit Empfängern.
object
Name der Kampagne, höchstens 80 Zeichen.
Assistent, der anruft (aus GET /v1/assistants).
Ohne Angabe gilt die Absendernummer des Assistenten.
Empfänger in der Reihenfolge der Anrufe, höchstens 2000. Entweder recipients oder contact_list_id.
object
Zielnummer, am besten in E.164.
Werte für die Platzhalter des Assistenten.
object
Kontaktliste aus dem Dashboard. Die Kontakte werden beim Anlegen kopiert, Variablen sind name, firma und email.
Anrufzeiten der Kampagne. Nur innerhalb von Montag bis Samstag, 8 bis 20 Uhr, und innerhalb der Anrufzeiten der Organisation.
object
Wochentage, 1 = Montag bis 6 = Samstag.
Beginn in deutscher Zeit, frühestens 08:00.
Ende in deutscher Zeit, spätestens 20:00.
Pause zwischen zwei Empfängern in Sekunden, Standard 30.
Versuche je Empfänger, Standard 1.
Abstand zwischen zwei Versuchen in Minuten, Standard 120.
Herkunft der Kontakte, zum Beispiel „Bestandskunden“.
Muss true sein: Sie bestätigen, dass alle Empfänger dem Anruf zugestimmt haben.
true startet die Kampagne sofort nach dem Anlegen, sonst bleibt sie ein Entwurf.
Responses
Abschnitt betitelt „Responses“Kampagne angelegt.
Die angelegte Kampagne, dazu die Empfänger, die nicht übernommen wurden.
object
ID der Kampagne.
Name der Kampagne.
draft Entwurf, scheduled Start geplant, running läuft, paused pausiert, completed alle Empfänger erledigt, canceled abgebrochen.
Absender in E.164.
Namen der Variablen, die die Empfänger mitbringen.
Platzhalter des Assistenten, für die die Empfänger keinen Wert haben. Solche Empfänger werden übersprungen.
Anrufzeiten der Kampagne. Nur innerhalb von Montag bis Samstag, 8 bis 20 Uhr, und innerhalb der Anrufzeiten der Organisation.
object
Wochentage, 1 = Montag bis 6 = Samstag.
Beginn in deutscher Zeit, frühestens 08:00.
Ende in deutscher Zeit, spätestens 20:00.
Pause zwischen zwei Empfängern in Sekunden.
Versuche je Empfänger.
Abstand zwischen zwei Versuchen in Minuten.
Herkunft der Kontakte, wie beim Anlegen angegeben.
Angelegt am.
Empfänger nach Stand.
object
Alle Empfänger der Kampagne.
Noch nicht angerufen.
Anruf läuft oder wartet auf den nächsten Versuch.
Gespräch geführt.
Anruf beendet ohne Gespräch.
Nie angerufen (Sperrliste, gesperrter Kontakt, ungültig oder Kampagne abgebrochen).
Empfänger, die nicht übernommen wurden (ungültige Nummer, anderes Land, Sondernummer).
object
Position in recipients (ab 1) bzw. in der Kontaktliste.
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.
Der beanstandete Wert, gekürzt.
Einträge mit einer Nummer, die schon vorkam.
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.
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": "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.
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." }}