Broadcasts-API #

Ein Broadcast ist ein ausgehender Versand: eine Zielgruppe, eine Eröffnungsnachricht, ein Kanal und ein Zeitplan. Optional wird auch der KI-Agent benannt, der die darauf eingehenden Antworten bearbeitet. Mit der Broadcasts-API können Sie diese Sendungen direkt aus Ihrem eigenen Code erstellen, bepreisen, starten und überwachen, anstatt das Dashboard zu verwenden. Informationen zum Produkt selbst finden Sie im Broadcasts-Leitfaden.

• Basis-URL — https://api.youraiconnector.com/v1
• Authentifizierung — Ihr API-Schlüssel (siehe Authentifizierung)
• Fehler & Paginierung — siehe Fehler & Paginierung

Alle nachstehenden Beispiele zeigen die ?apiKey=-Abfrageform in cURL und den X-API-Key-Header in JavaScript und Python – beides funktioniert an jedem Endpunkt.

Im API-Explorer. Jeder Endpunkt auf dieser Seite ist in der veröffentlichten OpenAPI-Spezifikation enthalten, sodass Sie die genauen Felder durchsuchen und Live-Anfragen im API-Explorer ausführen können.

Wie ein Versand zusammengestellt wird #

Das Senden eines Broadcasts erfolgt in vier Aufrufen, nicht in einem:

1. Erstellen Sie den Broadcast mit Zielgruppe, Kanal und Zeitplan – er beginnt als Draft.
2. Legen Sie die Eröffnungsnachricht fest. Bei WhatsApp Business bedeutet dies, eine Vorlage zur Genehmigung einzureichen (oder eine bereits genehmigte auszuwählen). Auf jedem anderen Kanal ist es einfacher Text.
3. Schätzen Sie die Kosten, wenn Sie den Preis prüfen möchten, bevor Sie etwas ausgeben (optional).
4. Starten Sie den Versand. Beim Start wird eine vollständige Prüfung durchgeführt – Zielgruppe, Nachricht, Vorlagengenehmigung, verbundener Absender – und der Versand entweder gestartet oder Sie werden genau darüber informiert, was fehlt.

Es wird nichts gesendet, bis Sie den Start-Aufruf tätigen.

Das Broadcast-Objekt #

{
  "id": "bcd123abc456",
  "name": "June promo",
  "status": "Draft",
  "channel": "whatsapp",
  "agent_id": "agt_789",
  "list_id": "lst_456",
  "list_name": "Newsletter subscribers",
  "total_contacts": 240,
  "send_to_new_list_members": false,
  "whats_app_template": {
    "body": "Hi {{first_name}}, our June offer is live.",
    "status": "approved",
    "sid": "HX0123...",
    "language": "en",
    "category": "marketing",
    "variables": ["first_name"]
  },
  "execution_date": 1781000000000,
  "drip_mode": true,
  "time_critical": false,
  "total_contacts_sent": 0,
  "credits_used": 0,
  "created_at": 1780900000000,
  "last_modified_at": 1780900000000
}

Zeitstempel werden als Epochen-Millisekunden zurückgegeben (execution_date, created_at, last_modified_at, …), und jede Kontakt-Referenz wird als Pfad-String wie contacts/uid_whatsapp_15551234567 zurückgegeben.

Felder, die Sie festlegen #

Alles, was Sie als user_id, id, status oder source_campaign_id senden, wird beim Erstellen ignoriert und beim Aktualisieren verworfen – der Status ändert sich nur über die unten aufgeführten Start-, Pause- und Fortsetzen-Endpunkte.

Felder, die die Plattform verwaltet #

status, total_contacts_sent, unique_contacts_replied, overall_reply_rate, credits_used, paused_reason, completion_summary, die Batch-Zähler und contacts (die einzelnen Kontakte, die vom Dashboard aus angehängt wurden, als Pfad-Strings ausgelesen). Lesen Sie diese, schreiben Sie sie nicht.

Statusse #

Broadcast erstellen #

POST /broadcasts — erstellt einen Draft.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "June promo",
    "channel": "whatsapp",
    "list_id": "lst_456",
    "agent_id": "agt_789",
    "drip_mode": true,
    "execution_date": "2026-06-15T09:00:00.000Z"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "June promo",
    channel: "whatsapp",
    list_id: "lst_456",
    agent_id: "agt_789",
    drip_mode: true,
    execution_date: "2026-06-15T09:00:00.000Z",
  }),
});
const { broadcast_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "June promo",
        "channel": "whatsapp",
        "list_id": "lst_456",
        "agent_id": "agt_789",
        "drip_mode": True,
        "execution_date": "2026-06-15T09:00:00.000Z",
    },
)
print(res.json()["broadcast_id"])

Antwort (201)

{ "success": true, "broadcast_id": "bcd123abc456" }

Broadcasts auflisten #

GET /broadcasts — jeder Broadcast im Konto, beginnend mit dem neuesten.

Abfrageparameter

curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();

res = requests.get(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]

Antwort (200)

{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }

Broadcast abrufen #

GET /broadcasts/{broadcastId} — gibt { "success": true, "broadcast": { ... } } zurück. Verwenden Sie dies, um einen laufenden Sendevorgang abzufragen: total_contacts_sent, unique_contacts_replied, overall_reply_rate und credits_used werden während des Vorgangs aktualisiert.

curl "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

Ein Broadcast, der in Ihrem Konto nicht existiert, gibt 404 zurück.

Broadcast aktualisieren #

PUT /broadcasts/{broadcastId} — senden Sie nur die Felder, die Sie ändern möchten. Sie können auch einen einzelnen Schlüssel innerhalb eines verschachtelten Objekts über einen Punktpfad ansprechen, z. B. "whats_app_template.body".

curl -X PUT "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "June promo (v2)", "execution_date": "2026-06-16T09:00:00.000Z" }'

await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "June promo (v2)", execution_date: "2026-06-16T09:00:00.000Z" }),
});

Ein leerer Body gibt 400 zurück. Zwei Regeln sind dabei zu beachten:

• opener_media ist ein Alles-oder-Nichts-Vorgang. Senden Sie das vollständige Objekt oder null, um den Anhang zu entfernen. Ein Punktpfad darauf (opener_media.name) wird mit 400 abgelehnt, da ein teilweise aktualisierter Anhang eine Datei beschreiben würde, die nicht vorhanden ist.
• Der Status ist nicht bearbeitbar. Verwenden Sie starten, anhalten und fortsetzen.

Die Eröffnungsnachricht #

Jede Broadcast-Nachricht enthält ihren Opener in whats_app_template. Was das bedeutet, hängt vom Kanal ab:

• WhatsApp Business — es muss eine Vorlage sein, die von WhatsApp genehmigt wurde. Verwenden Sie einen der beiden unten aufgeführten Endpunkte.
• Jeder andere Kanal (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — das body desselben Feldes ist einfach der Text, der gesendet wird. Das Übermitteln über den unten stehenden Endpunkt speichert ihn und markiert ihn als bereit, ohne dass WhatsApp involviert ist.

Vorlage zur Genehmigung einreichen #

POST /broadcasts/{broadcastId}/template

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, our June offer is live until Friday.",
    "language": "en",
    "category": "marketing"
  }'

Antwort (200)

{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }

template_status ist das, was WhatsApp angibt: pending während der Überprüfung, approved wenn sie verwendbar ist, rejected wenn sie abgelehnt wurde. Bei einem Nicht-WhatsApp-Kanal kommt es direkt als approved mit template_sid: null zurück — es gibt nichts zu überprüfen.

Dinge, die Sie aufhalten werden:

• Das Einreichen, während eine vorherige Vorlage noch geprüft wird, führt zu 400. Warten Sie zuerst die Entscheidung ab.
• Das Bearbeiten einer bereits genehmigten Vorlage lässt die genehmigte Version aktiv, bis die neue zurückkommt, sodass ein laufender Broadcast nie seinen Opener verliert.
• Bei einer WhatsApp-Nummer, die direkt über Meta verbunden ist, kann ein Broadcast mit angehängtem Bild oder Video nicht eingereicht werden (400) — Anhänge werden auf dem verwalteten WhatsApp Business-Weg und auf WhatsApp Web unterstützt.

Verwenden Sie eine bereits genehmigte Vorlage #

POST /broadcasts/{broadcastId}/template/select — kopiert eine bereits genehmigte Vorlage aus Ihrer Vorlagenbibliothek in den Broadcast, sodass Sie auf nichts warten müssen.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template/select?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "tpl_abc123" }'

Antwort (200)

{
  "success": true,
  "broadcast_id": "bcd123abc456",
  "template_status": "approved",
  "template_sid": "HX0123...",
  "body": "Hi {{first_name}}, our June offer is live until Friday.",
  "name": "june_promo",
  "language": "en",
  "variables": ["first_name"],
  "category": "marketing"
}

Die Genehmigung wird unsererseits anhand des Bibliothekseintrags überprüft — Sie senden immer nur die ID. Sie erhalten ein 400, wenn der Broadcast kein WhatsApp-Entwurf ist, wenn die Vorlage nicht genehmigt wurde, wenn es sich um eine Follow-up-Vorlage statt eines Openers handelt oder wenn der Broadcast einen Anhang hat (Bibliotheksvorlagen sind nur Text). Eine Vorlagen-ID, die nicht in Ihrem Konto vorhanden ist, führt zu 404.

Kosten schätzen #

POST /broadcasts/{broadcastId}/estimate-cost — berechnet den Preis für den Versand, bevor Sie sich festlegen. Verfügbar für whatsapp und sms Broadcasts; jeder andere Kanal gibt 400 zurück. Der Broadcast benötigt ein list_id, da die Schätzung die Zielgruppe zählt.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"

WhatsApp-Antwort (200) — Guthaben, aufgeschlüsselt nach Zielland:

{
  "success": true,
  "channel": "whatsapp",
  "billing_mode": "credits",
  "data": {
    "countries": [
      { "countryCode": "31", "name": "Netherlands", "iso": "NL", "flag": "🇳🇱", "contactCount": 180, "costPerContact": 1.2, "subtotal": 216 },
      { "countryCode": "1", "name": "United States", "iso": "US", "flag": "🇺🇸", "contactCount": 60, "costPerContact": 0.9, "subtotal": 54 }
    ],
    "totalContacts": 240,
    "totalTemplateCost": 270,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

SMS-Antwort (200) — US-Dollar, basierend auf den aktuellen Twilio-Preisen für Ihr eigenes Twilio-Konto:

{
  "success": true,
  "channel": "sms",
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 240,
    "messageLength": 118,
    "segmentsPerMessage": 1,
    "totalSegments": 240,
    "estimatedCostUsd": 1.788,
    "priceUnit": "USD",
    "billedByTwilio": true,
    "billing_mode": "twilio_direct",
    "service_messages_billable_soon": false
  }
}

Lesen Sie billing_mode, bevor Sie eine Nummer anzeigen. Hier erfahren Sie, wer die Kosten trägt:

SMS ohne verbundene Twilio-Anmeldedaten geben weiterhin die Segmentanzahl mit estimatedCostUsd: 0 zurück — es gibt keine Preisinformationen zum Abrufen.

Einen Broadcast starten #

POST /broadcasts/{broadcastId}/launch

Beim Starten wird alles überprüft und erst dann wird der Broadcast fortgesetzt. Es gibt keinen teilweisen Start: Entweder er beginnt, oder es ändert sich nichts und Sie erhalten eine Fehlermeldung mit dem Grund.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
if (!data.success) console.error(data.error);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

Antwort (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }

status ist der Ort, an dem der Broadcast gelandet ist:

• Scheduled — execution_date liegt in der Zukunft.
• Sending — er wurde jetzt gestartet.
• Pending Approval — die WhatsApp-Vorlage wird noch geprüft. Sie wird automatisch versendet, sobald die Vorlage genehmigt ist; rufen Sie den Start-Befehl nicht erneut auf.

Nur ein Draft (oder ein Pending Approval-Broadcast, dessen Vorlage inzwischen genehmigt wurde) kann gestartet werden — alles andere gibt 400 zurück.

Warum ein Start verweigert wird #

Jeder dieser Fehler wird als 400 mit einer verständlichen error-Nachricht zurückgegeben:

Anhalten und Fortsetzen #

POST /broadcasts/{broadcastId}/pause stoppt einen Sending- oder Scheduled-Broadcast und verwirft alle in der Warteschlange befindlichen Elemente.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"

Das Anhalten einer Pending Approval-Übertragung versetzt sie stattdessen zurück in den Status Draft – es war noch nichts geplant, also gibt es nichts, worauf man sie fortsetzen könnte. Jeder andere Status führt zu 400.

POST /broadcasts/{broadcastId}/resume startet eine Paused-Übertragung neu:

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"

Antwort (200)

{ "success": true, "broadcast_id": "bcd123abc456" }

Sie wird in Sending fortgesetzt oder zurück in Scheduled, falls der execution_date noch in der Zukunft liegt. Nur eine Paused-Übertragung kann fortgesetzt werden.

Weiterversand nach einer Pause wegen geringer Interaktion #

POST /broadcasts/{broadcastId}/override-engagement-guard

Während eine Übertragung in Batches versendet wird, messen wir, wie viele Personen auf jeden Batch geantwortet haben, bevor der nächste gestartet wird. Wenn fast niemand antwortet, hält die Übertragung automatisch an – ein Versand, der weiterhin in die Stille sendet, ist der schnellste Weg, um eine Nummer filtern oder blockieren zu lassen. Dafür gibt es die Schaltfläche Trotzdem fortfahren im Dashboard.

Da sich die Antwortrate, die die Pause verursacht hat, nicht ändern kann, während die Übertragung gestoppt ist, würde ein einfaches Fortsetzen bei der nächsten Prüfung nur erneut angehalten werden. Dieser Endpunkt ist die Entscheidung, trotzdem weiterzumachen: Er protokolliert die Außerkraftsetzung für diese eine Übertragung und hebt die Pause im selben Aufruf auf, falls die Übertragung wegen geringer Interaktion angehalten wurde.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"

Antwort (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }

• resumed: true – die Übertragung wurde wegen geringer Interaktion angehalten und läuft nun wieder; status ist der Status, in dem sie fortgesetzt wurde.
• resumed: false – es wurde nichts aufgehoben, die Außerkraftsetzung wird lediglich für zukünftige Prüfungen protokolliert. Das erhalten Sie, wenn die Übertragung nie angehalten wurde oder aus einem anderen Grund angehalten wurde (Sie haben sie manuell angehalten, ein Versandlimit wurde erreicht oder zu viele Sendungen sind fehlgeschlagen). Diese Pausen werden hier nicht aufgehoben – setzen Sie sie selbst fort, sobald Sie die Ursache behoben haben.

Die Außerkraftsetzung gilt nur für diese Übertragung. Es handelt sich nicht um eine Kontoeinstellung, und es ist sicher, sie zweimal aufzurufen.

Übertragung duplizieren #

POST /broadcasts/{broadcastId}/duplicate – kopiert das Publikum, die Nachricht und die Einstellungen in eine neue Draft. Alles, was den vorherigen Durchlauf betrifft (Zähler, Batches, Zeitplan, Antwortstatistiken), beginnt von vorn.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_channel": "sms" }'

Antwort (201)

{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }

Eine Kopie übernimmt niemals eine aktive WhatsApp-Genehmigung: Bei einer WhatsApp-Kopie muss die Vorlage von Ihnen bestätigt werden, und bei einer Kopie auf einen anderen Kanal wird sie verworfen und der Text wird zum einfachen Öffner. Das Kopieren auf SMS verwirft auch alle Anhänge, da SMS keine versenden kann.

Übertragung löschen #

DELETE /broadcasts/{broadcastId}

curl -X DELETE "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

Ein Sending oder Scheduled Broadcast wird mit 400 abgelehnt — pausieren Sie ihn zuerst.

Broadcasts, die eine klassische Kampagne spiegeln #

Klassische Kampagnen, die Nachrichten versenden, erscheinen ebenfalls in den Broadcasts, und die API gibt sie zusammen mit nativen Broadcasts zurück (sie tragen ein source_campaign_id). Sie verhalten sich etwas anders, da die Kampagne weiterhin die Kontrolle behält:

• Das Bearbeiten der Zielgruppe, der Nachricht oder des Zeitplans funktioniert und wird in die Kampagne übernommen.
• Kanal, Antwort-Agent, Anhang und alle Ausführungszähler sind hier schreibgeschützt — 400, wenn Sie versuchen, diese zu ändern. Ändern Sie diese in der Kampagne.
• Starten gibt 400 zurück, was Sie auf den Kampagnen-Editor verweist.
• Pausieren und Fortsetzen funktionieren und wirken sich auf die Kampagne aus.
• Löschen gibt 400 zurück — löschen Sie stattdessen die Kampagne, dann wird auch deren Broadcast-Eintrag entfernt.
• Duplizieren erstellt einen unabhängigen nativen Broadcast; dies ist der unterstützte Weg, um eine bewährte Kampagne zu übertragen.

Fehler #

Fehlgeschlagene Anfragen geben {"success": false, "error": "<message>"} mit den folgenden Status zurück:

Nächste Schritte #

• Broadcasts-Leitfaden — das Produkt hinter diesen Endpunkten, einschließlich Pacing und Sicherheitsverhalten
• Kontakte-API — erstellen Sie die Liste, an die ein Broadcast gesendet wird
• Vorlagen-API — verwalten Sie die genehmigten WhatsApp-Vorlagen, aus denen Sie wählen können
• Webhooks-API — abonnieren Sie Broadcast Started und Broadcast Completed, anstatt abzufragen (Polling)