Zum Inhalt springen
Hilfe-Center
Support kontaktierenApp öffnen

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.

  1. 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:read und calls:write. Kopieren Sie den Schlüssel sofort, er wird nur einmal angezeigt.

    Terminal-Fenster
    export SPEAKKI_API_KEY="spk_live_IHR_SCHLUESSEL"
  2. 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"]
    }
    ]
    }

    name ist der Name aus dem Dashboard. Ist die Liste leer, schalten Sie am Assistenten Ausgehende Anrufe erlauben ein und hinterlegen Sie Begrüßung und Absender.

  3. Anruf starten

    Für jeden Platzhalter aus variables geben 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 201 und dem Anruf. Merken Sie sich die id.

    {
    "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": []
    }
  4. Stand abfragen

    Terminal-Fenster
    curl https://api.speakki.de/v1/calls/0b1d7c2e-6a0f-4d0b-9a55-2f4f8f1c7e10 \
    -H "Authorization: Bearer $SPEAKKI_API_KEY"

    status wechselt von queued über dialing und in_progress zu completed (Gespräch geführt) oder not_reached (niemand erreicht). Alle Zustände stehen unter Anrufe starten.

  5. 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ätzlich call.ended mit Zusammenfassung. Wie Sie die Signatur prüfen, steht unter Webhooks.

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.