Schnellstart: der erste Anruf über die API
In fünf Schritten ruft Ihr Assistent zum ersten Mal über die API an. Sie brauchen den Tarif Professional, die Freischaltung für ausgehende Anrufe und einen Assistenten mit eingerichtetem Abschnitt Ausgehende Anrufe. Details stehen im Überblick.
Ein Anruf über die API ist ein echter Anruf. Testen Sie mit Ihrer eigenen Nummer, montags bis samstags zwischen 8 und 20 Uhr.
-
Schlüssel anlegen
Öffnen Sie im Dashboard KI einstellen › Verbindungen › Webhooks & API und klicken Sie unter API-Schlüssel auf Schlüssel anlegen. Wählen Sie die Berechtigungen
calls:readundcalls:write. Kopieren Sie den Schlüssel sofort, er wird nur einmal angezeigt.Terminal-Fenster export SPEAKKI_API_KEY="spk_live_IHR_SCHLUESSEL" -
Assistenten-ID holen
Terminal-Fenster curl https://api.speakki.de/v1/assistants \-H "Authorization: Bearer $SPEAKKI_API_KEY"Die Antwort nennt jeden Assistenten, der für ausgehende Anrufe bereit ist, mit Absendernummer und Platzhaltern:
{"data": [{"id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44","name": "Mia · Terminerinnerung","from_number": "+493023125010","variables": ["name"]}]}nameist der Name aus dem Dashboard. Ist die Liste leer, schalten Sie am Assistenten Ausgehende Anrufe erlauben ein und hinterlegen Sie Begrüßung und Absender. -
Anruf starten
Für jeden Platzhalter aus
variablesgeben Sie einen Wert mit.Terminal-Fenster curl https://api.speakki.de/v1/calls \-H "Authorization: Bearer $SPEAKKI_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: termin-4711-erinnerung" \-d '{"assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44","to": "+4915228817386","variables": { "name": "Frau Meier" }}'Die API antwortet mit Status
201und dem Anruf. Merken Sie sich dieid.{"id": "0b1d7c2e-6a0f-4d0b-9a55-2f4f8f1c7e10","status": "queued","block_reason": null,"to": "+4915228817386","from": "+493023125010","assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44","campaign_id": null,"variables": { "name": "Frau Meier" },"metadata": {},"scheduled_at": null,"next_attempt_at": null,"max_attempts": 1,"attempt_count": 0,"last_result": null,"created_at": "2026-11-16T09:00:00.000Z","finished_at": null,"attempts": []} -
Stand abfragen
Terminal-Fenster curl https://api.speakki.de/v1/calls/0b1d7c2e-6a0f-4d0b-9a55-2f4f8f1c7e10 \-H "Authorization: Bearer $SPEAKKI_API_KEY"statuswechselt vonqueuedüberdialingundin_progresszucompleted(Gespräch geführt) odernot_reached(niemand erreicht). Alle Zustände stehen unter Anrufe starten. -
Webhook empfangen
Statt den Stand abzufragen, lassen Sie sich benachrichtigen. Tragen Sie am Assistenten in der Stufe Feinjustierung unter Was er für Anrufer erledigt › Daten an Ihr System senden (Webhook) die Adresse Ihres Programms ein. Nach jedem Anruf sendet SpeakKI das Ereignis
outbound_call.finished, nach jedem Gespräch zusätzlichcall.endedmit Zusammenfassung. Wie Sie die Signatur prüfen, steht unter Webhooks.
Dasselbe in JavaScript
Abschnitt betitelt „Dasselbe in JavaScript“const response = await fetch("https://api.speakki.de/v1/calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.SPEAKKI_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "termin-4711-erinnerung", }, body: JSON.stringify({ assistant_id: "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44", to: "+4915228817386", variables: { name: "Frau Meier" }, }),});
const body = await response.json();if (!response.ok) { // Fehlerformat: { error: { code, message, details } } throw new Error(`${body.error.code}: ${body.error.message}`);}console.log(body.id, body.status);Verwenden Sie den Schlüssel nur auf Ihrem Server, nie im Browser oder in einer App.
Wie geht es weiter?
Abschnitt betitelt „Wie geht es weiter?“- Anrufe starten: planen, wiederholen, abbrechen.
- Kampagnen: viele Empfänger nacheinander anrufen.
- Regeln und Grenzen: Anrufzeiten, Limits und rechtlicher Rahmen.
- Fehler: alle Codes und was zu tun ist.