> ## Documentation Index > Fetch the complete documentation index at: https://aipro.placetel.de/docs/llms.txt > Use this file to discover all available pages before exploring further. # API für ausgehende Anrufe > REST-API zum Auslösen KI-gestützter ausgehender Anrufe an Ihre Kontakte. REST-API zum Auslösen KI-gestützter ausgehender Anrufe an Ihre Kontakte. Lösen Sie einen einzelnen Anruf oder mehrere Anrufe auf einmal aus, personalisieren Sie den Prompt pro Anruf und verfolgen Sie die Ergebnisse. **Basis-URL:** `https://aipro.placetel.de/api/v1/outbound` ## Authentifizierung Jede Anfrage muss ein Bearer-Token im `Authorization`-Header senden: ``` Authorization: Bearer ``` Erzeugen (oder erneuern) Sie Ihr Token auf der Seite **Ausgehende Anrufe** in Ihrem Dashboard („API-Token generieren"). Das Token wird nur einmal angezeigt — bewahren Sie es sicher auf; beim Erneuern wird das vorherige Token ungültig. Jedes Token erreicht nur Ihre eigenen Assistenten und Daten. ## Rufnummernformat Alle Rufnummern müssen im **E.164-Format** vorliegen — ein `+`, gefolgt von Ziffern. Senden Sie das exakte Format; Nummern werden nicht für Sie umformatiert. ``` ✅ +491761234567 ✅ +442071234567 ❌ 0176 1234567 ❌ +49 176 123 4567 ❌ 491761234567 ``` ## Endpunkte ### Einzelnen Anruf auslösen ``` POST /api/v1/outbound/calls ``` Löst einen einzelnen ausgehenden Anruf aus. Der Anruf wird sofort gewählt. #### Anfrage-Body (JSON) | Parameter | Typ | Erforderlich | Beschreibung | | ------------------ | ------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `destination` | string | Ja | Anzurufende Nummer (E.164) | | `agent_number` | string | Ja | Die Rufnummer Ihres Assistenten (ein führendes `+` ist optional) oder dessen SIP-ID (ein Wert, der mit `t` beginnt) | | `prompt_variables` | object | Nein | Werte, die in den Prompt des Assistenten eingesetzt werden. Siehe [Prompt personalisieren](#prompt-personalisieren). | | `caller_number` | string | Nur SIP-Assistenten | Beim Angerufenen angezeigte Rufnummer (E.164). Erforderlich, wenn `agent_number` eine SIP-ID ist, und muss eine in Ihrem Placetel-Konto registrierte Rufnummer sein. | #### Antwort ```json theme={null} HTTP 201 Created { "success": true, "call_id": "outb_...", "status": "dialing", "destination": "+491761234567" } ``` Verwenden Sie `call_id`, um den Anruf zu referenzieren. Ergebnis und Transkript des Anrufs erscheinen in Ihrem Dashboard — siehe [Ergebnisse verfolgen](#ergebnisse-verfolgen). ### Mehrere Anrufe auf einmal auslösen ``` POST /api/v1/outbound/calls/bulk ``` Löst Anrufe an mehrere Zielrufnummern in einer Anfrage aus. Bis zu **10 Zielrufnummern**. #### Anfrage-Body (JSON) | Parameter | Typ | Erforderlich | Beschreibung | | ------------------ | ------ | ------------------- | -------------------------------------------------------------------------------------------------------- | | `destinations` | array | Ja | Bis zu 10 Zielrufnummern. Formate siehe unten. | | `agent_number` | string | Ja | Rufnummer oder SIP-ID Ihres Assistenten | | `prompt_variables` | object | Nein | Gemeinsame Werte für alle Zielrufnummern (siehe die Regel zum Kombinieren unten) | | `caller_number` | string | Nur SIP-Assistenten | Angezeigte Rufnummer für SIP-Assistenten; muss eine in Ihrem Placetel-Konto registrierte Rufnummer sein. | #### Format der Zielrufnummern Jede Zielrufnummer ist ein Objekt mit einem Feld `phone` und optionalen `prompt_variables` pro Zielrufnummer: ```json theme={null} "destinations": [ { "phone": "+491761234567", "prompt_variables": { "customer_name": "Max" } }, { "phone": "+491769876543", "prompt_variables": { "customer_name": "Anna" } } ] ``` Wenn Sie keine Werte pro Zielrufnummer benötigen, lassen Sie `prompt_variables` weg: ```json theme={null} "destinations": [ { "phone": "+491761234567" }, { "phone": "+491769876543" } ] ``` Um für **alle** Zielrufnummern dieselben Werte zu verwenden, senden Sie stattdessen ein einzelnes `prompt_variables` auf oberster Ebene: ```json theme={null} { "agent_number": "+4921186942846", "destinations": [ { "phone": "+491761234567" }, { "phone": "+491769876543" } ], "prompt_variables": { "campaign": "Spring 2026" } } ``` `prompt_variables` auf oberster Ebene und pro Zielrufnummer **können nicht kombiniert** werden — nutzen Sie das eine oder das andere. **Die gesamte Anfrage wird validiert, bevor ein Anruf ausgelöst wird.** Schlägt die Validierung fehl — etwa ein ungültiges Rufnummernformat, mehr als 10 Zielrufnummern oder eine fehlende bzw. ungültige Prompt-Variable — wird die **gesamte** Anfrage mit einem `400` abgelehnt, und es werden **keine** Anrufe ausgelöst. **Nach bestandener Validierung wird jede Zielrufnummer unabhängig gewählt.** Schlägt bei einer Nummer der Anruf auf Telefonieebene fehl, werden die übrigen trotzdem ausgeführt — ein Sammelauftrag kann also je Zielrufnummer eine Mischung aus Erfolgen und Fehlern zurückgeben (siehe die Antwort unten). Doppelte Zielrufnummern (identische Nummern) werden entfernt — jede eindeutige Nummer wird einmal angerufen. #### Antwort ```json theme={null} HTTP 201 Created { "success": true, "total": 3, "succeeded": 2, "failed": 1, "results": [ { "destination": "+491761234567", "success": true, "status": "dialing", "error": null }, { "destination": "+491760000000", "success": false, "status": "failed", "error": "Something went wrong. Please try again or contact support." } ] } ``` Ein Sammelauftrag liefert `201` zurück, auch wenn einzelne — oder alle — Anrufe fehlschlagen: Prüfen Sie `success` und `status` je Eintrag in `results[]`; die Zähler `succeeded` / `failed` auf oberster Ebene fassen den Sammelauftrag zusammen. Ein anderer Status als `201` bedeutet, dass die gesamte Anfrage abgelehnt wurde (siehe [Fehler](#fehler)). Die Ergebnisse der Anrufe erscheinen zudem in Ihrem Dashboard — siehe [Ergebnisse verfolgen](#ergebnisse-verfolgen). ### Ergebnisse verfolgen Die Ergebnisse der Anrufe finden Sie in Ihrem Dashboard — im [Verlauf ausgehender Anrufe](https://aipro.placetel.de/outbound/history) oder in den [Konversationen](https://aipro.placetel.de/conversations): ob der jeweilige Anruf zustande kam, samt vollständigem Gespräch und Transkript. Filtern Sie nach dem Assistenten, mit dem Sie die Anrufe ausgelöst haben, um sie zu finden. ## Prompt personalisieren Setzen Sie zur Anrufzeit dynamische Werte in den Prompt Ihres Assistenten ein, damit jeder Empfänger eine individuell zugeschnittene Nachricht hört. **1. Platzhalter hinzufügen** — im Prompt des Assistenten mit der `{{name}}`-Syntax: ``` Guten Tag {{customer_name}}, ich rufe wegen Ihrer Bestellung {{order_id}} an. ``` **2. Werte übergeben** — in `prompt_variables` beim Auslösen des Anrufs: ```json theme={null} { "destination": "+491761234567", "agent_number": "+4921186942846", "prompt_variables": { "customer_name": "Max Mustermann", "order_id": "ORD-2026-0042" } } ``` Der Prompt wird vor dem Anruf mit Ihren Werten aufgelöst. #### Regeln * Jeder `{{Platzhalter}}` im Prompt muss übergeben werden, sonst wird die Anfrage mit `400` abgelehnt. * Nicht im Prompt verwendete Schlüssel werden akzeptiert und ignoriert. * Schlüsselnamen sollten in Kleinbuchstaben und `snake_case` sein (Buchstaben, Ziffern, Unterstriche), z. B. `customer_name`. * Werte müssen Zeichenketten sein (senden Sie Zahlen und boolesche Werte als Zeichenketten, z. B. `"3"`, `"true"`). * Bis zu 25 Schlüssel; jeder Wert bis zu 500 Zeichen. * Nutzen Sie im Sammelauftrag entweder `prompt_variables` pro Zielrufnummer oder gemeinsam auf oberster Ebene, nicht beides. ## Fehler Alle Fehler haben dieselbe Form: ```json theme={null} { "success": false, "error": "Description of the issue" } ``` #### HTTP-Statuscodes | Code | Bedeutung | | ----- | ------------------------------------------------------------------------------- | | `201` | Erfolg — Anruf(e) ausgelöst | | `400` | Ungültige Anfrage — fehlende oder ungültige Parameter | | `401` | Nicht autorisiert — fehlendes oder ungültiges API-Token | | `403` | Verboten — ausgehende Anrufe sind für Ihr Konto nicht aktiviert | | `404` | Nicht gefunden — Assistent nicht gefunden | | `422` | Ihr Tageslimit für Anrufe ist erreicht — kontaktieren Sie uns, um es zu erhöhen | #### Häufige Validierungsfehler (400) | Fehlermeldung | Ursache | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `Missing parameter: destination` | `destination` nicht angegeben | | `Missing parameter: agent_number` | `agent_number` nicht angegeben | | `Invalid destination format. Must be E.164 international format starting with '+', e.g. '+491761234567'.` | Nummer nicht im E.164-Format | | `Agent not found or not accessible` | Assistent existiert nicht | | `Maximum 10 destinations allowed per request` | Sammelauftrag über dem Limit | | `Missing prompt_variables keys: customer_name, order_id` | Prompt enthält Platzhalter, die nicht durch die übergebenen Variablen abgedeckt sind | | `prompt_variables values must be strings` | Ein Variablenwert ist keine Zeichenkette | | `Cannot combine top-level prompt_variables with per-destination prompt_variables` | Gemischte Variablenmodi in einem Sammelauftrag | ## Schnellstart **Ein Anruf:** ```bash theme={null} curl -X POST https://aipro.placetel.de/api/v1/outbound/calls \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "destination": "+491761234567", "agent_number": "+4921186942846" }' ``` **Personalisierte Sammelanrufe:** ```bash theme={null} curl -X POST https://aipro.placetel.de/api/v1/outbound/calls/bulk \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "agent_number": "+4921186942846", "destinations": [ { "phone": "+491761111111", "prompt_variables": { "customer_name": "Max Müller" } }, { "phone": "+491762222222", "prompt_variables": { "customer_name": "Anna Schmidt" } } ] }' ``` **Ergebnisse prüfen** — Ergebnisse und Transkripte der Anrufe erscheinen in Ihrem Dashboard; siehe [Ergebnisse verfolgen](#ergebnisse-verfolgen).