Zum Inhalt springen
WbizTool

API v2 (Beta)

Nachrichten

Senden Sie eine Nachricht sofort oder zu einem festgelegten Zeitpunkt, an eine Telefonnummer, eine WhatsApp-Gruppe, einen gespeicherten Kontakt oder einen Telegram-Benutzernamen. Senden Sie dieselbe Nachricht mit einem Request an bis zu 1.000 Empfänger, lesen Sie den Verlauf, verfolgen Sie den Status einer Nachricht und stornieren Sie sie, solange sie wartet.

VorgangEndpointScope
Nachricht sendenPOST /api/v2/messagesmessages:send
An viele Empfänger sendenPOST /api/v2/messages/batchmessages:send
Nachrichten auflistenGET /api/v2/messagesmessages:read
Nachricht abrufenGET /api/v2/messages/{id}messages:read
Nachricht stornierenDELETE /api/v2/messages/{id}messages:send

Schlüssel, Fehler, Idempotency-Key und Limits funktionieren wie im Überblick über API v2 beschrieben. Um ohne Abfragen zu erfahren, wann eine Nachricht gesendet wird oder fehlschlägt, fügen Sie einen Webhook-Endpunkt hinzu.

Nachricht senden#

POSThttps://wbiztool.com/api/v2/messages

Body: JSON (application/json)

Die Nachricht wird in die Warteschlange gestellt, und die Antwort kommt, bevor sie gesendet wird: mit HTTP 202 und der Message im Status queued (oder scheduled bei einem zukünftigen send_at). Verfolgen Sie sie mit Nachricht abrufen oder einem Webhook.

curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-ready" \
  -d '{
    "from": 101,
    "to": { "phone": "+919876543210" },
    "text": "Hi Asha, your order #1042 is ready."
  }'

Antwort (202):

{
  "id": 9817263,
  "status": "queued",
  "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
  "to": { "phone": "+919876543210", "contact_id": 991 },
  "text": "Hi Asha, your order #1042 is ready.",
  "media": null,
  "send_at": null,
  "expires_at": null,
  "created_at": "2026-10-18T10:15:02.311Z",
  "sent_at": null,
  "error": null
}

Body

toobjecterforderlich

Wer sie erhält: genau eines von phone, group, contact_id oder username. Siehe Empfänger.

frominteger or nullErforderlich, außer der Arbeitsbereich hat genau eine verbundene Nummer

Die id der Nummer, die sie sendet, aus Nummern auflisten. Wenn Sie das Feld weglassen, sendet die einzige verbundene Nummer: Eine verbundene WhatsApp-Nummer wird verwendet, auch wenn zusätzlich ein Telegram-Konto verbunden ist, und ein Telegram-Konto nur, wenn keine WhatsApp-Nummer verbunden ist. Eine abgemeldete Nummer wird akzeptiert: Ihre Nachrichten warten, bis sie wieder verbunden ist.

textstringErforderlich, außer es werden Medien gesendet

Die Nachricht, bis zu 3.000 Zeichen. Mit media ist es die Bildunterschrift und kann weggelassen werden. WhatsApp-Formatierung funktioniert: *bold*, _italic_, ~strikethrough~. Schreiben Sie Zeilenumbrüche in JSON als \n.

mediaobject or nulloptional

Ein Bild oder eine Datei zum Senden. Siehe Medien.

send_atstring or nulloptional

Zu diesem Zeitpunkt statt sofort senden: ISO 8601 mit Offset, zum Beispiel 2026-10-20T09:30:00+05:30. Der Zeitpunkt muss in der Zukunft liegen. Siehe Planung und Ablauf.

expires_atstring or nulloptional

Nach diesem Zeitpunkt nicht mehr senden: Die Nachricht wird stattdessen expired. ISO 8601 mit Offset, in der Zukunft und nach send_at.

Header

Authorizationheadererforderlich

Bearer wbz_live_…, ein Schlüssel mit dem Scope messages:send.

Idempotency-Keyheaderoptional

Eine beliebige eindeutige Zeichenfolge, damit eine Wiederholung nie eine zweite Nachricht sendet. Siehe Idempotency-Key.

Fehler beim Senden#

HTTPCodeWann
400validation_failedEin Feld fehlt, hat den falschen Typ oder ist unbekannt; to enthält keines oder mehrere seiner Felder; media enthält beide oder keines von url und media_id; expires_at liegt nicht nach send_at
400text_requiredWeder text noch media
400text_too_longtext ist länger als 3.000 Zeichen
400invalid_datetimesend_at oder expires_at ist nicht ISO 8601 mit Offset
402no_creditsDer Arbeitsbereich hat in seinem Plan keine Nachrichten mehr übrig
403number_not_allowedDer Schlüssel ist auf andere Nummern beschränkt
403account_disabledDas Konto des Inhabers des Arbeitsbereichs ist deaktiviert
422invalid_phoneto.phone ist keine Telefonnummer im internationalen Format mit +
422invalid_usernameto.username ist kein Telegram-Benutzername, Link oder keine tg:-ID
422username_needs_telegramto.username mit einer WhatsApp-Nummer als from
422contact_not_foundKein Kontakt mit dieser to.contact_id
422media_not_foundKeine Datei mit dieser media.media_id
422invalid_media_urlmedia.url ist kein öffentlicher http(s)-Link
422time_in_pastsend_at oder expires_at liegt bereits in der Vergangenheit
422number_not_foundfrom ist keine Nummer dieses Arbeitsbereichs
422from_requiredKein from, und der Arbeitsbereich hat keine oder mehrere verbundene Nummern
422message_rejectedDie Nachricht konnte nicht in die Warteschlange gestellt werden; message nennt den Grund
429number_daily_cap_reachedDie Nummer hat in den letzten 24 Stunden 1.000 Nachrichten gesendet

Ein abgelehntes Senden hinterlässt nichts: Es wird keine Nachricht gespeichert, es gibt also nichts zu stornieren. Fehler, die bei jedem Request auftreten können (Schlüssel, Scopes, Rate-Limits, Idempotency-Key), stehen auf der Fehlerseite.

An viele Empfänger senden#

POSThttps://wbiztool.com/api/v2/messages/batch

Body: JSON (application/json)

Sendet dieselbe Nachricht an bis zu 1.000 Empfänger. Der Body ist derselbe wie bei Nachricht senden, nur dass to eine Liste von Empfängern ist.

  • Alles oder nichts. Jeder Empfänger wird geprüft, bevor etwas in die Warteschlange kommt, und die gesamte Liste muss in die verbleibenden Nachrichten des Plans und in das Kontingent der sendenden Nummer für die nächsten 24 Stunden passen. Ist ein Empfänger fehlerhaft, wird nichts in die Warteschlange gestellt, und field nennt ihn, zum Beispiel to[3].phone.
  • Derselbe Empfänger doppelt erhält eine Nachricht.
  • Die Antwort ist 202 mit data: eine Message pro Empfänger, in der Reihenfolge von to.
curl -X POST https://wbiztool.com/api/v2/messages/batch \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: opening-hours-2026-10-20" \
  -d '{
    "from": 101,
    "to": [
      { "phone": "+919876543210" },
      { "phone": "+447700900123" },
      { "group": "Bakery staff" }
    ],
    "text": "We open at 10 tomorrow."
  }'

Antwort (202), eine Message pro Empfänger; die zweite und dritte sehen aus wie die erste, mit to gleich {"phone": "+447700900123", …} und {"group": "Bakery staff", …}:

{
  "data": [
    {
      "id": 9817264,
      "status": "queued",
      "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
      "to": { "phone": "+919876543210", "contact_id": 991 },
      "text": "We open at 10 tomorrow.",
      "media": null,
      "send_at": null,
      "expires_at": null,
      "created_at": "2026-10-19T16:02:40.118Z",
      "sent_at": null,
      "error": null
    }
  ]
}

Fehler beim Senden eines Batches#

Dieselben wie beim Senden einer Nachricht, mit der Position des Empfängers in field (to[0].phone), und zusätzlich:

HTTPCodeWann
400too_many_recipientsto hat mehr als 1.000 Einträge
400validation_failedto ist leer oder keine Liste
402no_creditsDie Liste passt nicht in die verbleibenden Nachrichten: requested und remaining nennen die Differenz
429number_daily_cap_reachedDie Liste passt nicht in das Kontingent der Nummer für die nächsten 24 Stunden: requested und room nennen die Anzahl

Nachrichten auflisten#

GEThttps://wbiztool.com/api/v2/messages

Die Nachrichten des Arbeitsbereichs aus den letzten 90 Tagen, die neuesten zuerst, in Seiten. Dazu gehören auch Nachrichten aus dem Dashboard, aus Kampagnen, Erinnerungen, Integrationen und API v1, nicht nur die von API v2. Ein auf einige Nummern beschränkter Schlüssel sieht nur deren Nachrichten.

Query-Parameter

numberintegeroptional

Nur Nachrichten von dieser Nummern-id.

statusstringoptional

Nur Nachrichten mit diesem Status: queued, scheduled, sent, delivered, read, failed, cancelled oder expired.

sincestringoptional

Nur Nachrichten, die zu oder nach diesem Zeitpunkt erstellt wurden (ISO 8601 mit Offset).

untilstringoptional

Nur Nachrichten, die vor diesem Zeitpunkt erstellt wurden (ISO 8601 mit Offset).

limitintegeroptional

Nachrichten pro Seite, 1 bis 100 (Standard 25).

cursorstringoptional

Der next_cursor der letzten Seite, mit denselben Filtern.

Filter lassen sich kombinieren. Schreiben Sie in einem Query-String das + eines Offsets als %2B (ein einfaches + kommt als Leerzeichen an, das ebenfalls als + gelesen wird), oder verwenden Sie Z.

curl -G https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  --data-urlencode "status=failed" \
  --data-urlencode "since=2026-10-01T00:00:00+05:30" \
  --data-urlencode "limit=100"

Die Antwort ist {"data": [Message, …], "next_cursor": "…" or null}.

Fehler beim Auflisten#

HTTPCodeWann
400validation_failednumber ist keine Nummern-ID, status ist keiner der Status, oder limit liegt nicht zwischen 1 und 100
400invalid_datetimesince oder until ist nicht ISO 8601 mit Offset
400invalid_cursorDer Cursor ist beschädigt oder wurde mit anderen Filtern erzeugt

Nachricht abrufen#

GEThttps://wbiztool.com/api/v2/messages/{id}

Eine Nachricht und ihr aktueller Status.

curl https://wbiztool.com/api/v2/messages/9817263 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

Antwort (200), eine zugestellte Nachricht:

{
  "id": 9817263,
  "status": "delivered",
  "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
  "to": { "phone": "+919876543210", "contact_id": 991 },
  "text": "Hi Asha, your order #1042 is ready.",
  "media": null,
  "send_at": null,
  "expires_at": null,
  "created_at": "2026-10-18T10:15:02.311Z",
  "sent_at": "2026-10-18T10:15:09.870Z",
  "error": null
}

Eine Nachricht, die es nicht gibt, die zu einem anderen Arbeitsbereich gehört oder (bei einem auf einige Nummern beschränkten Schlüssel) von einer anderen Nummer gesendet wurde, antwortet mit 404 message_not_found.

Nachricht stornieren#

DELETEhttps://wbiztool.com/api/v2/messages/{id}

Storniert eine Nachricht, die noch wartet (queued oder scheduled), egal wer sie erstellt hat. Die Antwort ist 200 mit der Message, jetzt im Status cancelled. Ein Webhook-Endpunkt erhält message.cancelled.

Eine bereits gesendete Nachricht lässt sich nicht zurückholen. Eine Nachricht, die die sendende Nummer gerade in diesem Moment übernimmt, kann trotzdem noch gesendet werden. Prüfen Sie daher anschließend ihren Status, wenn es darauf ankommt.

curl -X DELETE https://wbiztool.com/api/v2/messages/9817263 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

Fehler beim Stornieren#

HTTPCodeWann
404message_not_foundKeine solche Nachricht für diesen Schlüssel
409not_cancellableSie wartet nicht mehr; status im Fehler nennt ihren aktuellen Status, zum Beispiel sent

Das Message-Objekt#

Jeder Vorgang auf dieser Seite antwortet mit Message-Objekten, und Webhook-Ereignisse enthalten eines in data.message.

FeldTypBeschreibung
idintegerDie ID der Nachricht. Damit rufen Sie die Nachricht ab oder stornieren sie.
statusstringWo sie gerade steht. Siehe Status.
fromobjectDie sendende Nummer: id, phone (ihre Ziffern mit Ländervorwahl, ohne +) und platform (whatsapp oder telegram).
toobjectDer Empfänger: phone (mit +), group oder username sowie contact_id, der gespeicherte Kontakt, an den sie ging. Eine Telefonnummer oder Gruppe, an die zum ersten Mal gesendet wird, wird als Kontakt gespeichert. (contact_id ist nur bei einer Testnachricht an eine nicht gespeicherte Nummer null.)
textstringDer Text oder die Bildunterschrift; "", wenn es keinen gibt.
mediaobject or nulltype (image oder file), url und file_name (null bei Bildern). Die url kann ein Link sein, der nur begrenzte Zeit funktioniert; speichern Sie ihn nicht.
send_atstring or nullDer geplante Zeitpunkt oder null für „sofort“.
expires_atstring or nullDer Zeitpunkt, nach dem sie nicht mehr gesendet wird, oder null.
created_atstringWann sie erstellt wurde.
sent_atstring or nullWann sie gesendet wurde, sobald das geschehen ist (sent, delivered oder read).
errorobject or nullBei einer failed- oder expired-Nachricht nennt message den Grund, zum Beispiel File exceeds WhatsApp size limit (16MB max). Sonst null.

Status#

StatusBedeutung
queuedWartet auf den Versand.
scheduledWartet auf ihr send_at.
sentVon Ihrer Nummer gesendet (ein Haken in WhatsApp).
deliveredAuf dem Telefon des Empfängers zugestellt (zwei Haken).
readVom Empfänger gelesen (blaue Haken).
failedSie konnte nicht gesendet werden; error.message nennt den Grund.
cancelledVor dem Versand storniert: mit Nachricht stornieren, im Dashboard oder weil ihre Nummer oder Kampagne entfernt wurde.
expiredNicht vor ihrem expires_at gesendet.

queued und scheduled können storniert werden. sent kann noch zu delivered und dann zu read werden. failed, cancelled, expired und read sind endgültig. Webhooks melden sent, failed, cancelled und expired; um delivered und read zu sehen, rufen Sie die Nachricht ab.

Empfänger#

to nimmt genau eines dieser Felder an:

FeldBeispielWer sie erhält
phone{"phone": "+919876543210"}Eine Telefonnummer im internationalen Format mit + (E.164). Leerzeichen und Bindestriche sind erlaubt.
group{"group": "Bakery staff"}Eine WhatsApp-Gruppe, in der die sendende Nummer Mitglied ist, über ihren exakten Namen (bis zu 200 Zeichen).
contact_id{"contact_id": 991}Ein im Arbeitsbereich gespeicherter Kontakt, über seine ID (etwa die contact_id einer früheren Nachricht). Sie geht an die Nummer oder Gruppe dieses Kontakts.
username{"username": "@asha_bakes"}Ein Telegram-Benutzer: @name, ein Link t.me/name oder tg: und eine Benutzer-ID. Nur von einem Telegram-Konto aus, geben Sie also eines als from an (oder haben Sie genau eines verbunden).

Für das Senden an Gruppen und über Telegram muss die sendende Nummer in dieser Gruppe sein bzw. diesen Benutzer erreichen können; Probleme dabei zeigen sich als failed-Nachricht, nicht als Fehler beim Senden.

Medien#

media sendet ein Bild oder eine Datei, mit text als Bildunterschrift. Geben Sie genau eines von url oder media_id an:

media.urlstringEntweder url oder media_id

Ein öffentlicher http- oder https-Link zur Datei, bis zu 1.000 Zeichen. Links zu privaten oder lokalen Adressen werden mit invalid_media_url abgelehnt.

media.media_idintegerEntweder url oder media_id

Eine Datei im Medienverzeichnis des Arbeitsbereichs, aus Datei hochladen. Laden Sie eine Datei einmal hoch und senden Sie sie so oft Sie möchten.

media.typestringoptional

image oder file. Ohne Angabe wird ein Link, der auf .jpg, .jpeg, .png, .gif oder .webp endet, als Bild gesendet und alles andere als Datei; eine media_id verwendet den Typ, mit dem die Datei hochgeladen wurde.

media.file_namestringoptional

Für eine file: der Name, den der Empfänger sieht, zum Beispiel invoice-1042.pdf (bis zu 100 Zeichen). Ohne Angabe wird der Name aus dem Link oder der hochgeladenen Datei übernommen. Die Dateiendung bestimmt, wie die Datei gesendet wird, geben Sie also eine an. Bei Bildern ignoriert.

{
  "to": { "phone": "+919876543210" },
  "text": "Your invoice for order #1042",
  "media": { "url": "https://example.com/invoices/1042.pdf", "type": "file", "file_name": "invoice-1042.pdf" }
}

Die Datei wird beim Senden der Nachricht abgerufen, nicht beim Aufruf der API. Ein defekter Link oder eine zu große Datei zeigt sich daher als failed-Nachricht mit dem Grund in error.message. Es gelten die Größen- und Typregeln von v1: siehe Bilder und Dateien senden.

Planung und Ablauf#

  • send_at plant die Nachricht. Sie bleibt bis dahin scheduled und kann storniert werden, bis sie gesendet wird. Schreiben Sie die Zeit mit Offset, 2026-10-20T09:30:00+05:30 bedeutet also 09:30 Uhr in Indien. Für wiederkehrende Nachrichten verwenden Sie Erinnerungen.
  • expires_at ist eine Frist: Wurde die Nachricht bis dahin nicht gesendet (etwa weil die Nummer abgemeldet war), wird sie expired, statt verspätet gesendet zu werden. Nutzen Sie das für Einmalcodes, Lieferzeiten und Angebote. Ein Hintergrundjob markiert sie frühestens 30 Sekunden nach Fristablauf als abgelaufen. Verlassen Sie sich daher nicht auf Fristen unter einer Minute.
  • Beide müssen in der Zukunft liegen, und expires_at muss nach send_at liegen.

Verwandte Themen#

  • Webhooks: message.sent und message.failed erhalten, statt abzufragen.
  • Medien: Dateien hochladen, um sie per media_id zu senden.
  • Nummern: die id, die Sie als from verwenden.
  • Fehler