API für ausgehende Anrufe

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 <Ihr-API-Token>

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.
`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

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.

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:

"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:

"destinations": [
  { "phone": "+491761234567" },
  { "phone": "+491769876543" }
]

Um für alle Zielrufnummern dieselben Werte zu verwenden, senden Sie stattdessen ein einzelnes prompt_variables auf oberster Ebene:

{
  "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

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). Die Ergebnisse der Anrufe erscheinen zudem in Ihrem Dashboard — siehe Ergebnisse verfolgen.

Ergebnisse verfolgen

Die Ergebnisse der Anrufe finden Sie in Ihrem Dashboard — im Verlauf ausgehender Anrufe oder in den Konversationen: 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:

{
  "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:

{
  "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:

curl -X POST https://aipro.placetel.de/api/v1/outbound/calls \
  -H "Authorization: Bearer <Ihr-API-Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+491761234567",
    "agent_number": "+4921186942846"
  }'

Personalisierte Sammelanrufe:

curl -X POST https://aipro.placetel.de/api/v1/outbound/calls/bulk \
  -H "Authorization: Bearer <Ihr-API-Token>" \
  -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.

Startseite

AI-Assistenten

KI Inhalte & Kontext

Erweiterte Funktionen

Chat-Kanäle

Tickets

Team

Agent-Vorlagen

Authentifizierung

Rufnummernformat

Endpunkte

Einzelnen Anruf auslösen

Anfrage-Body (JSON)

Antwort

Mehrere Anrufe auf einmal auslösen

Anfrage-Body (JSON)

Format der Zielrufnummern

Antwort

Ergebnisse verfolgen

Prompt personalisieren

Regeln

Fehler

HTTP-Statuscodes

Häufige Validierungsfehler (400)

Schnellstart

​Authentifizierung

​Rufnummernformat

​Endpunkte

​Einzelnen Anruf auslösen

​Anfrage-Body (JSON)

​Antwort

​Mehrere Anrufe auf einmal auslösen

​Anfrage-Body (JSON)

​Format der Zielrufnummern

​Antwort

​Ergebnisse verfolgen

​Prompt personalisieren

​Regeln

​Fehler

​HTTP-Statuscodes

​Häufige Validierungsfehler (400)

​Schnellstart

Authentifizierung

Rufnummernformat

Endpunkte

Einzelnen Anruf auslösen

Anfrage-Body (JSON)

Antwort

Mehrere Anrufe auf einmal auslösen

Anfrage-Body (JSON)

Format der Zielrufnummern

Antwort

Ergebnisse verfolgen

Prompt personalisieren

Regeln

Fehler

HTTP-Statuscodes

Häufige Validierungsfehler (400)

Schnellstart