Zum Inhalt springen
Hilfe-Center
Support kontaktierenApp öffnen

Kampagnen über die API

Eine Kampagne ist eine feste Liste von Empfängern, die Ihr Assistent nacheinander anruft, mit einer Pause dazwischen. Jeder Empfänger wird ein normaler Anruf. Es gelten dieselben Regeln und Grenzen wie für einen einzelnen Anruf.

Nutzen Sie eine Kampagne, sobald Sie mehr als eine Handvoll Nummern anrufen. Sie brauchen dann keine eigene Warteschlange und stoßen nicht an das Rate-Limit.

Zum Anlegen und Steuern braucht der Schlüssel campaigns:write, zum Abfragen campaigns:read.

Terminal-Fenster
curl https://api.speakki.de/v1/campaigns \
-H "Authorization: Bearer spk_live_IHR_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"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
}'

Die API antwortet mit Status 201 und der Kampagne. Mit "start": true läuft sie sofort los. Ohne start bleibt sie ein Entwurf, den Sie später starten.

Feld Pflicht Bedeutung
name ja Name der Kampagne, höchstens 80 Zeichen.
assistant_id ja Assistent, der anruft.
recipients eines von beiden Empfänger in der Reihenfolge der Anrufe, höchstens 2000. Je Eintrag to und optional variables.
contact_list_id eines von beiden Kontaktliste aus dem Dashboard, siehe unten.
contact_source ja Woher die Kontakte stammen, 10 bis 500 Zeichen.
consent_confirmed ja Muss true sein. Sie bestätigen damit, dass alle Empfänger dem Anruf zugestimmt haben.
from_number_id nein Absender. Ohne Angabe gilt die Absendernummer des Assistenten.
start_at nein Geplanter Start als ISO 8601 mit Zeitzone.
call_window nein Anrufzeiten der Kampagne: days (1 = Montag bis 6 = Samstag), from und to als HH:MM in deutscher Zeit. Nur innerhalb von 08:00 bis 20:00.
pause_seconds nein Pause zwischen zwei Empfängern, 10 bis 600 Sekunden. Standard ist 30.
max_attempts nein Versuche je Empfänger, 1 bis 3. Standard ist 1.
retry_delay_minutes nein Abstand zwischen zwei Versuchen, 120 bis 10080 Minuten.
start nein true startet die Kampagne sofort nach dem Anlegen.

Geben Sie entweder recipients oder contact_list_id an, nicht beides. Alle Felder stehen in der API-Referenz.

Die Antwort nennt, was mit der Liste passiert ist:

  • rejected_recipients: Einträge mit ungültiger Nummer, einer Nummer außerhalb von Deutschland, Österreich und der Schweiz oder einer Sondernummer. Je Eintrag line (Position in recipients ab 1), reason und value.
  • duplicate_recipients: Anzahl der Einträge mit einer Nummer, die schon vorkam. Jede Nummer wird nur einmal angerufen.
  • missing_variables: Platzhalter des Assistenten, für die Empfänger keinen Wert haben. Solche Empfänger werden übersprungen.

Prüfen Sie diese drei Felder, bevor Sie einen Entwurf starten.

Statt recipients können Sie eine Kontaktliste aus dem Dashboard angeben. Die Kontakte werden beim Anlegen kopiert. Spätere Änderungen an der Liste wirken nicht auf die Kampagne. Als Variablen stehen name, firma und email bereit.

Terminal-Fenster
curl https://api.speakki.de/v1/campaigns \
-H "Authorization: Bearer spk_live_IHR_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"name": "Wartung Frühjahr",
"assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44",
"contact_list_id": "9d3f6b2a-4c1e-4f8a-b7d5-2e6a8c1f3b90",
"contact_source": "Bestandskunden mit Wartungsvertrag",
"consent_confirmed": true
}'
Terminal-Fenster
curl -X POST https://api.speakki.de/v1/campaigns/3f8a2b1c-9d4e-4a6f-8b2c-1e5d7f9a0b3c/start \
-H "Authorization: Bearer spk_live_IHR_SCHLUESSEL"
Anfrage Wirkung Möglich im Status
POST /v1/campaigns/{id}/start startet einen Entwurf, sofort oder zu start_at draft
POST /v1/campaigns/{id}/pause kein weiterer Empfänger wird angerufen, ein laufendes Gespräch läuft zu Ende running, scheduled
POST /v1/campaigns/{id}/resume setzt beim nächsten Empfänger fort paused
POST /v1/campaigns/{id}/cancel bricht endgültig ab, offene Empfänger werden übersprungen draft, scheduled, running, paused

Passt die Anfrage nicht zum Status, antwortet die API mit Status 409 und dem Code conflict. Dasselbe gilt, wenn schon 5 Kampagnen Ihrer Organisation laufen.

Terminal-Fenster
curl https://api.speakki.de/v1/campaigns/3f8a2b1c-9d4e-4a6f-8b2c-1e5d7f9a0b3c \
-H "Authorization: Bearer spk_live_IHR_SCHLUESSEL"
status Bedeutung
draft Entwurf, noch nicht gestartet
scheduled Start geplant
running läuft
paused pausiert
completed alle Empfänger erledigt
canceled abgebrochen

counts zählt die Empfänger nach Stand:

Feld Bedeutung
total alle Empfänger
pending noch nicht angerufen
queued Anruf läuft oder wartet auf den nächsten Versuch
reached Gespräch geführt
not_reached Anruf beendet ohne Gespräch
skipped nie angerufen: Sperrliste, gesperrter Kontakt, ungültig oder Kampagne abgebrochen

next_dispatch_at nennt den frühesten Zeitpunkt für den nächsten Empfänger. Liegt er außerhalb der Anrufzeiten oder ist das Tageslimit erreicht, wartet die Kampagne und macht zum nächsten erlaubten Zeitpunkt weiter. Anders als ein einzelner Anruf wird hier nichts abgelehnt.

GET /v1/campaigns listet alle Kampagnen, neueste zuerst, auf Wunsch gefiltert mit status.

Terminal-Fenster
curl "https://api.speakki.de/v1/campaigns/3f8a2b1c-9d4e-4a6f-8b2c-1e5d7f9a0b3c/recipients?status=skipped" \
-H "Authorization: Bearer spk_live_IHR_SCHLUESSEL"

Die Empfänger kommen in Listenreihenfolge, je Eintrag mit position, to, variables und:

Feld Bedeutung
status pending noch nicht angerufen, queued Anruf angelegt, done Anruf beendet, skipped nie angerufen
skip_reason Grund bei skipped, einer der Fehlercodes
last_result Ergebnis des letzten Versuchs, zum Beispiel answered oder no_answer
attempt_count Zahl der Versuche
call_id der Anruf dieses Empfängers für GET /v1/calls/{id}

Alle Anrufe einer Kampagne liefert auch GET /v1/calls?campaign_id=....

Ist die Kampagne abgeschlossen oder abgebrochen, sendet SpeakKI das Ereignis outbound_campaign.finished an den Webhook des Assistenten.

Ohne Programmierung legen Sie eine Kampagne im Dashboard an: Ausgehende Anrufe › Kampagnen › Kampagne anlegen. Im Schritt Empfänger wählen Sie mit CSV-Datei wählen Ihre Liste oder nehmen eine Kontaktliste:

phone_number;name;termin
+4915228817386;Frau Meier;Dienstag um 10 Uhr
+491729925904;Herr Kurz;Mittwoch um 14 Uhr
  • Die erste Zeile enthält die Spaltennamen.
  • Die Spalte phone_number ist Pflicht. Die Namen telefon, telefonnummer, phone und nummer gelten ebenfalls.
  • Jede weitere Spalte wird eine Variable für Begrüßung und Auftrag. Die Spalte termin füllt den Platzhalter {{termin}}.
  • Als Trennzeichen gelten Semikolon und Komma.
  • Spaltennamen bestehen aus Buchstaben, Ziffern und Unterstrich. Umlaute, Leerzeichen und Bindestriche schreibt SpeakKI um, aus „Straße Nr“ wird Strasse_Nr.
  • Die Datei darf höchstens 1 MB groß sein und höchstens 2000 Empfänger enthalten. Speichern Sie sie als CSV in UTF-8.

Das Dashboard zeigt vor dem Anlegen gültige Empfänger, fehlerhafte Zeilen und doppelte Nummern. Im letzten Schritt speichern Sie die Kampagne als Entwurf oder starten sie sofort. Im Detail der Kampagne stehen Pausieren, Fortsetzen und Abbrechen.

Kampagnen aus dem Dashboard und aus der API sind dieselben. Sie können eine im Dashboard angelegte Kampagne über die API abfragen und steuern.