Kampagnen-API-Auslöser

Der Kampagnen-API-Auslöser ermöglicht es Ihnen, Kontakte programmgesteuert zu Kampagnen hinzuzufügen und automatisierte Anrufe über eine REST-API zu starten. Dies ist ideal für die Integration mit bestehenden Systemen, Workflows oder benutzerdefinierten Anwendungen.

Zugriff auf den API-Auslöser

So greifen Sie auf die API-Auslöser-Einstellungen zu:

Navigieren Sie zur Detailseite Ihrer Kampagne
Klicken Sie auf den Tab Quellen in der Hauptnavigation
Wählen Sie API aus dem vertikalen Menü auf der linken Seite

Der Quellen-Tab organisiert alle Auslöser-Methoden (E-Mail, API und Integrationen) an einem praktischen Ort mit einfach zu navigierenden vertikalen Tabs.

Übersicht

Der API-Auslöser bietet einen einfachen REST-Endpunkt, der Kontaktinformationen akzeptiert und automatisch:

Den Kontakt im System erstellt oder aktualisiert
Den Kontakt zur angegebenen Kampagne hinzufügt, ohne doppelte Kampagnen-Einträge zu erstellen. Ist der Kontakt in dieser Kampagne bereits archiviert, wird der archivierte Eintrag wiederhergestellt und wie ein neuer Kampagnenkontakt neu gestartet. Eine aktive E-Mail- oder WhatsApp-Unterhaltung aus dem vorherigen Durchlauf wird beendet, wenn sie nicht von einem anderen Kampagnenkontakt genutzt wird. Die nächste Kontaktaufnahme beginnt dann eine neue Unterhaltung.
Optional den Anruf mit Template-Überschreibungen anpasst
Den automatisierten Anruf gemäß den Kampagneneinstellungen plant

API-Endpunkt

Methode: POST

URL: https://api.plugandplai.ai/campaign/{kampagnen-id}/trigger-contact

Authentifizierung: Bearer-Token (Ihr Service-API-Schlüssel)

Anfrage-Format

Content-Type: application/json
Authorization: Bearer YOUR_SERVICE_API_KEY

Anfrage-Body

Der Anfrage-Body muss ein JSON-Objekt mit der folgenden Struktur sein:

json

{
  "email": "kontakt@beispiel.de",
  "firstName": "Max",
  "lastName": "Mustermann",
  "phone": "+49 123 456789",
  "tags": ["tag1", "tag2"],
  "metadata": {
    "benutzerdefiniertesFeld1": "wert1",
    "benutzerdefiniertesFeld2": "wert2"
  },
  "templateOverwrite": {
    "variables.goal": "Benutzerdefiniertes Ziel für diesen spezifischen Kontakt",
    "variables.company": "Spezifischer Firmenname",
    "background-information.product": "Spezifische Produktinformationen"
  }
}

Feldbeschreibungen

Pflichtfelder

phone (string): Telefonnummer des Kontakts im internationalen Format (z.B. "+49 123 456789")

Optionale Felder

email (string): E-Mail-Adresse des Kontakts
firstName (string): Vorname des Kontakts
lastName (string): Nachname des Kontakts
tags (array von strings): Tags zur Organisation und Filterung des Kontakts
metadata (object): Benutzerdefinierte Schlüssel-Wert-Paare für zusätzliche Kontaktinformationen
templateOverwrite (object): Benutzerdefinierte Werte zum Überschreiben von Assistenten-Template-Variablen für diesen Kontakt. Verwenden Sie den vollständigen Variablenschlüssel aus Ihrer Kampagne, zum Beispiel variables.goal.

Template-Überschreibungen

Template-Überschreibungen ermöglichen es Ihnen, die Prompt-Variablen des Assistenten für jeden Kontakt individuell anzupassen. Dies macht Ihre Anrufe persönlicher und relevanter.

Was sind Template-Überschreibungen?

Wenn Sie Ihren Assistenten konfigurieren, können Sie Template-Variablen (auch "zusätzliche Variablen" genannt) definieren, die im Prompt des Assistenten erscheinen. Diese Variablen können beinhalten:

Firmenname
Produktinformationen
Kampagnenziele
Sonderangebote
Termindetails

Standardmäßig verwenden diese Variablen die in Ihrer Assistentenkonfiguration festgelegten Werte. Mit Template-Überschreibungen können Sie beim Auslösen der Kampagne über die API unterschiedliche Werte für spezifische Kontakte angeben.

Wenn Sie einen Kontakt auslösen, der in derselben Kampagne bereits archiviert ist, wird der archivierte Kampagneneintrag wiederhergestellt und neu gestartet. Alte Überschreibungswerte aus dem vorherigen Durchlauf werden zuerst entfernt. Die Werte aus der neuen Anfrage sind dann die aktiven Überschreibungen für diesen Kontakt.

Verwendung von Template-Überschreibungen

Im templateOverwrite-Objekt geben Sie die Variablennamen als Schlüssel und Ihre benutzerdefinierten Werte als Strings an:

json

{
  "templateOverwrite": {
    "variables.goal": "Lead für Premium-Produktangebot qualifizieren",
    "variables.company": "Acme Corporation",
    "background-information.product": "Enterprise Software Paket"
  }
}

Welche Variablen können überschrieben werden?

Die verfügbaren Template-Variablen hängen von der Schema-Konfiguration Ihres Assistenten ab. Häufige Beispiele sind:

variables.goal: Das spezifische Ziel für diesen Anruf
variables.company: Firmenname, der während des Anrufs erwähnt werden soll
background-information.product: Produkt oder Dienstleistung, die besprochen werden soll
Benutzerdefinierte Variablen, die im Schema Ihres Assistenten definiert sind

Um zu sehen, welche Variablen für Ihre Kampagne verfügbar sind, überprüfen Sie das API-Dokumentationsbeispiel im Tab "API-Auslöser" der Kampagne.

API-Schlüssel erhalten

Navigieren Sie zu Ihren Kontoeinstellungen
Finden Sie den Bereich Service-API-Schlüssel
Kopieren Sie Ihren API-Schlüssel
Bewahren Sie diesen Schlüssel sicher auf - er ermöglicht Zugriff auf Ihr Konto

Verwendung der API

Beispiel mit cURL

bash

curl -X POST https://api.plugandplai.ai/campaign/abc123/trigger-contact \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SERVICE_API_KEY" \
  -d '{
    "email": "max.mustermann@beispiel.de",
    "firstName": "Max",
    "lastName": "Mustermann",
    "phone": "+49 123 456789",
    "tags": ["qualifizierter-lead", "enterprise"],
    "metadata": {
      "quelle": "website-formular",
      "interesse": "premium-plan"
    },
    "templateOverwrite": {
      "variables.goal": "Produktdemo vereinbaren",
      "variables.company": "Acme GmbH"
    }
  }'

Beispiel mit JavaScript

javascript

const response = await fetch('https://api.plugandplai.ai/campaign/abc123/trigger-contact', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_SERVICE_API_KEY'
  },
  body: JSON.stringify({
    email: 'max.mustermann@beispiel.de',
    firstName: 'Max',
    lastName: 'Mustermann',
    phone: '+49 123 456789',
    tags: ['qualifizierter-lead', 'enterprise'],
    metadata: {
      quelle: 'website-formular',
      interesse: 'premium-plan'
    },
    templateOverwrite: {
      'variables.goal': 'Produktdemo vereinbaren',
      'variables.company': 'Acme GmbH'
    }
  })
});

const result = await response.json();

Beispiel mit Python

python

import requests

url = 'https://api.plugandplai.ai/campaign/abc123/trigger-contact'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_SERVICE_API_KEY'
}
data = {
    'email': 'max.mustermann@beispiel.de',
    'firstName': 'Max',
    'lastName': 'Mustermann',
    'phone': '+49 123 456789',
    'tags': ['qualifizierter-lead', 'enterprise'],
    'metadata': {
        'quelle': 'website-formular',
        'interesse': 'premium-plan'
    },
    'templateOverwrite': {
        'variables.goal': 'Produktdemo vereinbaren',
        'variables.company': 'Acme GmbH'
    }
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

Antwort-Format

Erfolgsantwort

Statuscode: 200 OK

json

[
  {
    "id": "kampagnen-anruf-id",
    "campaignId": "abc123",
    "contactId": "kontakt-id",
    "status": "pending",
    "retries": 0,
    "createdAt": "2026-01-22T10:30:00Z"
  }
]

Fehlerantworten

Statuscode: 400 Bad Request

Fehlende Pflichtfelder
Ungültiges Telefonnummernformat
Ungültiger Anfrage-Body

Statuscode: 401 Unauthorized

Fehlender oder ungültiger API-Schlüssel

Statuscode: 404 Not Found

Kampagne nicht gefunden

Best Practices

Sicherheit

API-Schlüssel sicher aufbewahren: Teilen Sie ihn niemals öffentlich oder speichern Sie ihn in Versionskontrollsystemen
HTTPS verwenden: Verwenden Sie immer den sicheren HTTPS-Endpunkt
Schlüssel regelmäßig rotieren: Aktualisieren Sie Ihre API-Schlüssel regelmäßig aus Sicherheitsgründen

Telefonnummern

Internationales Format verwenden: Ländercode einschließen (z.B. "+49 123 456789")
Vor dem Senden validieren: Stellen Sie sicher, dass Telefonnummern gültig und korrekt formatiert sind
Duplikate vermeiden: Das System verhindert doppelte Kampagnen-Einträge für denselben Kontakt in derselben Kampagne

Template-Überschreibungen

Spezifisch sein: Geben Sie klare, relevante Informationen in Template-Überschreibungen an
Zuerst testen: Probieren Sie es mit wenigen Kontakten aus, bevor Sie Massenoperationen durchführen
Schema abgleichen: Verwenden Sie nur Variablennamen, die im Schema Ihres Assistenten definiert sind
Werte prägnant halten: Template-Werte sollten klar und nicht zu lang sein

Integrations-Tipps

Fehler elegant behandeln: Implementieren Sie eine ordnungsgemäße Fehlerbehandlung in Ihrer Integration
Ergebnisse überwachen: Überprüfen Sie die Kampagnenergebnisse regelmäßig, um sicherzustellen, dass Kontakte korrekt hinzugefügt werden
Rate-Limiting beachten: Seien Sie sich der API-Rate-Limits bei Massen-Anfragen bewusst
Metadata nutzen: Verwenden Sie das Metadata-Feld, um nachzuverfolgen, woher Kontakte stammen, für bessere Analysen

Anwendungsfälle

CRM-Integration

Kampagnen automatisch auslösen, wenn:

Ein Lead einen bestimmten Score erreicht
Ein Deal in eine bestimmte Phase eintritt
Ein Kontakt Interesse an einem Produkt zeigt

Website-Formulare

Kontakte aus folgenden Quellen zu Kampagnen hinzufügen:

Kontaktformulare
Newsletter-Anmeldungen
Demo-Anfragen
Lead-Magnete

Marketing-Automatisierung

Integration mit Tools wie:

E-Mail-Marketing-Plattformen
Landing-Page-Builder
Webinar-Plattformen
E-Commerce-Systeme

Benutzerdefinierte Anwendungen

Eigene Workflows erstellen:

Nachverfolgung von Anfragen außerhalb der Geschäftszeiten
Wiederherstellung abgebrochener Warenkörbe
Nachverfolgung von Event-Registrierungen
Kundenzufriedenheitsumfragen

Fehlerbehebung

Kontakt nicht hinzugefügt

Überprüfen Sie, ob die Kampagnen-ID korrekt ist
Prüfen Sie, ob die Telefonnummer im gültigen internationalen Format vorliegt
Stellen Sie sicher, dass Ihr API-Schlüssel die erforderlichen Berechtigungen hat
Bestätigen Sie, dass die Kampagne nicht pausiert oder beendet ist

Template-Überschreibungen funktionieren nicht

Überprüfen Sie, ob die Variablennamen mit dem Schema Ihres Assistenten übereinstimmen
Prüfen Sie, ob Template-Werte Strings sind, keine Objekte oder Arrays
Stellen Sie sicher, dass Ihr Assistent Template-Parts konfiguriert hat

Authentifizierungsfehler

Überprüfen Sie, ob Ihr API-Schlüssel korrekt ist und nicht abgelaufen ist
Prüfen Sie, ob der Authorization-Header korrekt formatiert ist
Stellen Sie sicher, dass Sie das Präfix "Bearer" vor dem API-Schlüssel verwenden

Hilfe erhalten

Wenn Sie Probleme mit dem API-Auslöser haben:

Überprüfen Sie die API-Dokumentation im Tab "API-Auslöser" Ihrer Kampagne
Überprüfen Sie, ob Ihr Anfrage-Format mit den Beispielen übereinstimmt
Überprüfen Sie Fehlermeldungen auf spezifische Probleme
Kontaktieren Sie den Support für technische Unterstützung

Weitere Informationen zu Kampagnen finden Sie in der Kampagnen-Übersicht.

Kampagnen-API-Auslöser ​

Zugriff auf den API-Auslöser ​

Übersicht ​

API-Endpunkt ​

Anfrage-Format ​

Header ​

Anfrage-Body ​

Feldbeschreibungen ​

Pflichtfelder ​

Optionale Felder ​

Template-Überschreibungen ​

Was sind Template-Überschreibungen? ​

Verwendung von Template-Überschreibungen ​

Welche Variablen können überschrieben werden? ​

API-Schlüssel erhalten ​

Verwendung der API ​

Beispiel mit cURL ​

Beispiel mit JavaScript ​

Beispiel mit Python ​

Antwort-Format ​

Erfolgsantwort ​

Fehlerantworten ​

Best Practices ​

Sicherheit ​

Telefonnummern ​

Template-Überschreibungen ​

Integrations-Tipps ​

Anwendungsfälle ​

CRM-Integration ​

Website-Formulare ​

Marketing-Automatisierung ​

Benutzerdefinierte Anwendungen ​

Fehlerbehebung ​

Kontakt nicht hinzugefügt ​

Template-Überschreibungen funktionieren nicht ​

Authentifizierungsfehler ​

Hilfe erhalten ​

Kampagnen-API-Auslöser

Zugriff auf den API-Auslöser

Übersicht

API-Endpunkt

Anfrage-Format

Header

Anfrage-Body

Feldbeschreibungen

Pflichtfelder

Optionale Felder

Template-Überschreibungen

Was sind Template-Überschreibungen?

Verwendung von Template-Überschreibungen

Welche Variablen können überschrieben werden?

API-Schlüssel erhalten

Verwendung der API

Beispiel mit cURL

Beispiel mit JavaScript

Beispiel mit Python

Antwort-Format

Erfolgsantwort

Fehlerantworten

Best Practices

Sicherheit

Telefonnummern

Template-Überschreibungen

Integrations-Tipps

Anwendungsfälle

CRM-Integration

Website-Formulare

Marketing-Automatisierung

Benutzerdefinierte Anwendungen

Fehlerbehebung

Kontakt nicht hinzugefügt

Template-Überschreibungen funktionieren nicht

Authentifizierungsfehler

Hilfe erhalten