Kampagnen-API-Auslöser (Nur für Administratoren)

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.

Ü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
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": {
    "goal": "Benutzerdefiniertes Ziel für diesen spezifischen Kontakt",
    "company": "Spezifischer Firmenname",
    "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

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.

Verwendung von Template-Überschreibungen

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

json

{
  "templateOverwrite": {
    "goal": "Lead für Premium-Produktangebot qualifizieren",
    "company": "Acme Corporation",
    "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:

goal: Das spezifische Ziel für diesen Anruf
company: Firmenname, der während des Anrufs erwähnt werden soll
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": {
      "goal": "Produktdemo vereinbaren",
      "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: {
      goal: 'Produktdemo vereinbaren',
      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': {
        'goal': 'Produktdemo vereinbaren',
        '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 Kontakte basierend auf Telefonnummern

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 (Nur für Administratoren) ​

Ü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 (Nur für Administratoren)

Ü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