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.
Kampagne anlegen
Abschnitt betitelt „Kampagne anlegen“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.
Empfänger, die nicht übernommen werden
Abschnitt betitelt „Empfänger, die nicht übernommen werden“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 Eintragline(Position inrecipientsab 1),reasonundvalue.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.
Mit einer Kontaktliste
Abschnitt betitelt „Mit einer Kontaktliste“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.
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 }'Starten, pausieren, fortsetzen, abbrechen
Abschnitt betitelt „Starten, pausieren, fortsetzen, abbrechen“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.
Verlauf abfragen
Abschnitt betitelt „Verlauf abfragen“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.
Empfänger abfragen
Abschnitt betitelt „Empfänger abfragen“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.
Kampagne im Dashboard mit CSV-Datei
Abschnitt betitelt „Kampagne im Dashboard mit CSV-Datei“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_numberist Pflicht. Die Namentelefon,telefonnummer,phoneundnummergelten ebenfalls. - Jede weitere Spalte wird eine Variable für Begrüßung und Auftrag. Die Spalte
terminfü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.