# 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](../broadcasts/broadcasts.md). - **Basis-URL** — `https://api.youraiconnector.com/v1` - **Authentifizierung** — Ihr API-Schlüssel (siehe [Authentifizierung](authentication.md)) - **Fehler & Paginierung** — siehe [Fehler & Paginierung](errors-and-pagination.md) 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](reference.md) 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 ```json { "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 | Feld | Beschreibung | |---|---| | `name` | Wie der Broadcast im Dashboard genannt wird. | | `channel` | Der eine Kanal, über den dieser Broadcast sendet: `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `messenger`, `facebook`, `telegram`, `instagram_private`, `line`, `viber`, `imessage`, `email`, `chat_widget`, `custom_channel`. Ein Broadcast hat genau einen Kanal – um dasselbe woanders zu senden, [duplizieren Sie ihn auf einen anderen Kanal](#duplicate-a-broadcast). `tiktok` und `skool` sind reine Antwortkanäle und können niemals für Broadcasts verwendet werden. | | `agent_id` | Der KI-Agent, der Antworten beantwortet. Lassen Sie es `null`, damit Antworten stattdessen in Ihrem Team-Posteingang landen. | | `list_id` | Die Kontaktliste, an die gesendet werden soll. So legen Sie die Zielgruppe über die API fest – siehe [Kontakte](contacts.md) zum Erstellen und Befüllen von Listen. | | `list_name` | Anzeigename, der neben dem Broadcast angezeigt wird. Kosmetisch. | | `send_to_new_list_members` | `true` hält den Broadcast aktiv, sodass jeder, der später zur Liste hinzugefügt wird, ebenfalls die Eröffnungsnachricht erhält. | | `whats_app_template` | Die Eröffnungsnachricht. Bei WhatsApp Business ist es eine echte genehmigte Vorlage; auf jedem anderen Kanal wird ihr `body` als einfacher Eröffnungstext verwendet. Legen Sie dies über die [Vorlagen-Endpunkte](#the-opening-message) fest, nicht manuell. | | `opener_media` | Ein Bild oder Video, das mit der Eröffnungsnachricht gesendet wird. Senden Sie immer das gesamte Objekt (oder `null`, um es zu entfernen) – das Schreiben einzelner Schlüssel darin wird abgelehnt. Nicht unterstützt bei SMS. | | `execution_date` | Wann gesendet werden soll. Senden Sie einen ISO 8601-Zeitstempel oder Epochen-Millisekunden. Ein zukünftiges Datum plant den Versand; lassen Sie es weg (oder verwenden Sie ein vergangenes Datum), um sofort beim Start zu senden. | | `drip_mode` | `true` taktet den Versand in Batches über die Zeit, anstatt alles auf einmal zu senden. | | `time_critical` | `true` deaktiviert die automatische Taktung, die ab 50 Kontakten einsetzt – für eine warme Zielgruppe, die die Nachricht sofort benötigt. Dies hebt nicht das tägliche Sendelimit des Kanals selbst auf. | | `batch_size` | Wie viele Kontakte pro Batch beim schrittweisen Versand. | | `follow_up_config` | Die Follow-up-Kette für Kontakte, die niemals antworten. | 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 | Status | Bedeutung | |---|---| | `Draft` | Wird erstellt. Es ist nichts geplant. | | `Pending Approval` | Gestartet, aber die WhatsApp-Vorlage wartet noch auf eine Entscheidung. Der Versand beginnt automatisch, sobald die Vorlage genehmigt wurde – Sie müssen den Vorgang nicht erneut starten. | | `Scheduled` | Gestartet mit einem zukünftigen `execution_date`. | | `Sending` | Aktiv im Versand (ein Broadcast, der für neue Listenmitglieder bereitgestellt wurde, verbleibt hier, während er auf diese wartet). | | `Paused` | Angehalten – von Ihnen oder automatisch durch eine Sicherheitsprüfung. | | `Sent` | Abgeschlossen. | | `Failed` | Abgeschlossen, wobei mehr als die Hälfte der Versendungen fehlgeschlagen ist. | --- ## Broadcast erstellen `POST /broadcasts` — erstellt einen `Draft`. **cURL** ```bash 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** ```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** ```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`) ```json { "success": true, "broadcast_id": "bcd123abc456" } ``` --- ## Broadcasts auflisten `GET /broadcasts` — jeder Broadcast im Konto, beginnend mit dem neuesten. **Abfrageparameter** | Parameter | Erforderlich | Beschreibung | |---|---|---| | `status` | Nein | Gibt nur Broadcasts mit einem bestimmten Status zurück, z. B. `Sending`. Die Schreibweise muss exakt mit der [Statustabelle](#statuses) übereinstimmen. | ```bash curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending" ``` ```javascript const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const { broadcasts } = await res.json(); ``` ```python 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`) ```json { "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. ```bash 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"`. ```bash 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" }' ``` ```javascript 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](#launch-a-broadcast), [anhalten](#pause-and-resume) und [fortsetzen](#pause-and-resume). --- ## 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` | Feld | Erforderlich | Beschreibung | |---|---|---| | `body` | Ja | Der Nachrichtentext, bis zu 1024 Zeichen. Verwenden Sie `{{variable}}` Platzhalter zur Personalisierung. | | `name` | Nein | Vorlagenname. Standardmäßig der Name des Broadcasts. | | `language` | Nein | Sprachcode. Standardmäßig `en`. | | `category` | Nein | `marketing` (Standard), `utility`, `authentication` oder `authentication-international`. Dies bestimmt den Preis des Versands, also geben Sie es wahrheitsgemäß an. | | `variables` | Nein | Die Platzhalternamen in der Reihenfolge ihres Erscheinens. Wenn Sie dies weglassen, werden sie aus dem Textkörper gelesen — was meistens gewünscht ist, da der Versand sie für jeden Kontakt ausfüllt. | ```bash 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`) ```json { "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](templates.md) in den Broadcast, sodass Sie auf nichts warten müssen. | Feld | Erforderlich | Beschreibung | |---|---|---| | `template_id` | Ja | Die ID einer genehmigten Vorlage in Ihrem Konto. | ```bash 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`) ```json { "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. ```bash curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY" ``` **WhatsApp-Antwort** (`200`) — Guthaben, aufgeschlüsselt nach Zielland: ```json { "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: ```json { "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: | `billing_mode` | Wer zahlt | Was die Zahlen bedeuten | |---|---|---| | `credits` | Ihr Your AI Connector-Konto | `totalTemplateCost` und die Zahlen pro Land sind Credits. | | `twilio_direct` | Ihr eigenes Twilio-Konto | `estimatedCostUsd` ist der Betrag, den Twilio Ihnen in Rechnung stellt. | | `meta_waba_direct` | Ihr eigenes WhatsApp Business-Konto, abgerechnet durch Meta | Jeder Credit-Wert wird als `null` zurückgegeben — absichtlich, damit er niemals mit „kostenlos“ verwechselt wird. Die Länder- und Kontaktzahlen sind weiterhin korrekt. | 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** ```bash curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```python res = requests.post( "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", headers={"X-API-Key": "YOUR_API_KEY"}, ) print(res.json()) ``` **Antwort** (`200`) ```json { "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: | Problem | Was zu beheben ist | |---|---| | Kein Publikum | Legen Sie `list_id` fest (oder fügen Sie Kontakte hinzu), bevor Sie starten. | | Keine Eröffnungsnachricht | Legen Sie den Opener fest — siehe [Die Eröffnungsnachricht](#the-opening-message). | | Anhang bei SMS | SMS können keine Bilder oder Videos enthalten. Entfernen Sie den Anhang oder verschieben Sie den Broadcast auf WhatsApp. | | Anhang stimmt nicht mit der genehmigten Vorlage überein | Bei WhatsApp befinden sich die Medien innerhalb der genehmigten Vorlage. Ein nachträglicher Austausch des Anhangs erfordert daher eine erneute Einreichung der Vorlage. | | Vorlage abgelehnt | Schreiben Sie die Nachricht um und reichen Sie sie erneut ein. | | Vorlage nie eingereicht | Reichen Sie sie zuerst ein (oder wählen Sie eine genehmigte aus). | | Vorlage genehmigt, aber fehlt in Ihrem WhatsApp-Konto | Normalerweise eine Vorlage, die genehmigt wurde, bevor die Nummer vollständig verbunden war. Reichen Sie sie erneut ein. | | Kein verbundener Absender für den Kanal | Verbinden Sie zuerst den Kanal — siehe [Kanäle](channels.md). | | Nur-Antwort-Kanal | TikTok und Skool erlauben es Unternehmen nicht, eine Konversation zu initiieren, daher können sie nicht für Broadcasts verwendet werden. | | Bereits scharfgeschaltet | Für den Broadcast ist bereits ein Versand geplant. Halten Sie ihn an, bevor Sie ihn erneut starten. | | Wartet noch auf Genehmigung | Er wird automatisch versendet, sobald die Vorlage genehmigt ist. | | WhatsApp Business-Konto von Meta blockiert | Meta hat unternehmensinitiierte Konversationen auf Ihrem eigenen WhatsApp Business-Konto gestoppt — normalerweise ein Problem mit der Zahlungsmethode. Beheben Sie dies im Meta Business Manager. | | Aus einer klassischen Kampagne gestartet | Starten Sie ihn stattdessen aus dem Kampagnen-Editor. Siehe [Klassische Kampagnen in Broadcasts](#broadcasts-that-mirror-a-classic-campaign). | --- ## Anhalten und Fortsetzen `POST /broadcasts/{broadcastId}/pause` stoppt einen `Sending`- oder `Scheduled`-Broadcast und verwirft alle in der Warteschlange befindlichen Elemente. ```bash 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: ```bash curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY" ``` **Antwort** (`200`) ```json { "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](#pause-and-resume) 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. ```bash curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY" ``` **Antwort** (`200`) ```json { "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. | Feld | Erforderlich | Beschreibung | |---|---|---| | `to_channel` | Nein | Erstellen Sie die Kopie auf einem anderen Kanal. So senden Sie dasselbe auf zwei Kanälen – eine Übertragung hat immer nur einen. | ```bash 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`) ```json { "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}` ```bash 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": ""}` mit den folgenden Status zurück: | Status | Bedeutung | |---|---| | `400` | Etwas an der Anfrage oder dem Status des Broadcasts ist falsch — ein fehlendes Feld, ein ungültiger Anhang oder ein Starten/Pausieren/Fortsetzen/Löschen, das im aktuellen Status des Broadcasts nicht zulässig ist. Die `error`-Nachricht nennt den Grund. | | `401` | Fehlender oder ungültiger API-Schlüssel. | | `403` | Ihr Plan beinhaltet keinen API-Zugriff. | | `404` | Kein solcher Broadcast in Ihrem Konto vorhanden (oder bei der Vorlagenauswahl: keine solche Vorlage). | | `429` | Ratenbegrenzung erreicht. Warten Sie kurz und versuchen Sie es erneut. | | `500` | Auf unserer Seite ist etwas schiefgelaufen. Versuchen Sie es nach einer kurzen Wartezeit erneut. | --- ## Nächste Schritte - [Broadcasts-Leitfaden](../broadcasts/broadcasts.md) — das Produkt hinter diesen Endpunkten, einschließlich Pacing und Sicherheitsverhalten - [Kontakte-API](contacts.md) — erstellen Sie die Liste, an die ein Broadcast gesendet wird - [Vorlagen-API](templates.md) — verwalten Sie die genehmigten WhatsApp-Vorlagen, aus denen Sie wählen können - [Webhooks-API](webhooks.md) — abonnieren Sie `Broadcast Started` und `Broadcast Completed`, anstatt abzufragen (Polling)