Zum Inhalt springen
Wbiztool

Messaging-API

Nachricht senden (Send Message API)

Senden Sie einen WhatsApp-Text, ein Bild oder ein Dokument von Ihrer verbundenen WhatsApp-Nummer an eine Telefonnummer. Nutzen Sie die API für Bestellbestätigungen, Zahlungserinnerungen, Benachrichtigungen und Antworten im Support.

POSThttps://wbiztool.com/api/v1/send_msg/

Body: JSON, Formularfelder oder multipart/form-data beim Hochladen einer Datei

Die Nachricht wird in die Warteschlange gestellt und innerhalb kurzer Zeit von Ihrer WhatsApp-Nummer gesendet. Die Antwort enthält eine msg_id, mit der Sie ihren Status prüfen können.

Kurzes Beispiel#

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

Ersetzen Sie 12345, YOUR_API_KEY und 678 durch Ihre eigenen Werte. Wo Sie diese finden, steht unter Authentifizierung.

Request-Parameter#

Authentifizierung

client_idintegererforderlich

Ihre API-Client-ID aus Einstellungen → API-Schlüssel.

api_keystringerforderlich

Ihr API-Schlüssel von derselben Seite.

whatsapp_clientintegerErforderlich, wenn Sie mehr als eine Nummer haben

ID der WhatsApp-Nummer, von der gesendet wird, aus den WhatsApp-Einstellungen. Wenn Sie den Parameter weglassen und Ihr Arbeitsbereich genau eine verbundene Nummer hat, wird diese Nummer verwendet.

Empfänger und Nachricht

phonestringerforderlich

Die WhatsApp-Nummer des Empfängers, nur Ziffern. Leerzeichen, +, -, . und Klammern werden automatisch entfernt. Senden Sie die Nummer entweder mit Ländervorwahl (919876543210) oder ohne (9876543210) zusammen mit country_code. Lassen Sie bei Formularfeldern die führende nationale 0 weg (09876543210): Sie wird nicht entfernt, bevor country_code vorangestellt wird, sodass die Nachricht an die falsche Nummer geht. JSON-Requests entfernen sie automatisch.

country_codestringoptional

Internationale Vorwahl ohne +, zum Beispiel 91 für Indien oder 1 für die USA. Sie wird vor phone gesetzt, sofern die Nummer nicht bereits damit beginnt. Ausnahme: Bei 91 erhält eine 10-stellige Nummer immer das Präfix. Bei anderen Vorwahlen erhält eine lokale Nummer, die mit denselben Ziffern beginnt, kein Präfix. Senden Sie sie daher mit enthaltener Ländervorwahl.

msg_typeintegeroptional

0 Text (Standard), 1 Bild, 2 Datei oder Dokument.

msgstringErforderlich, wenn msg_type 0 ist

Nachrichtentext, bis zu 3.000 Zeichen. Bei Bildern und Dateien ist es die Bildunterschrift, die leer sein darf. WhatsApp-Formatierung funktioniert: *bold*, _italic_, ~strikethrough~. message wird als Alias akzeptiert.

Bilder und Dateien

img_urlstringErforderlich, wenn msg_type 1 ist und keine Datei hochgeladen wird

Öffentliche http- oder https-URL des Bildes.

file_urlstringErforderlich, wenn msg_type 2 ist und keine Datei hochgeladen wird

Öffentliche http- oder https-URL, von der die Datei direkt heruntergeladen werden kann.

filefileoptional

Laden Sie das Bild oder die Datei hoch, statt eine URL anzugeben. Senden Sie den Request als multipart/form-data mit einem Feld namens file.

file_namestringoptional

Dateiname, den der Empfänger sieht, zum Beispiel invoice-4821.pdf. Die Dateiendung bestimmt, wie die Datei gesendet wird, geben Sie also eine an. Er wird in Kleinbuchstaben gesendet, Zeichen wie & : ? * $ ; werden durch _ ersetzt, und er wird auf 150 Zeichen gekürzt. Wenn Sie den Parameter weglassen, wird der Name aus der URL oder der hochgeladenen Datei übernommen.

Zustelloptionen

expire_after_secondsintegeroptional

Markiert die Nachricht als abgelaufen (Status 4), wenn sie nicht innerhalb dieser Anzahl Sekunden gesendet wurde, zum Beispiel 3600 für eine Stunde. Nützlich für zeitkritische Nachrichten wie voraussichtliche Lieferzeiten. Ein Hintergrundjob erledigt das frühestens 30 Sekunden nach Fristablauf. Verlassen Sie sich daher bei Fristen unter einer Minute nicht darauf.

webhookstringoptional

URL, die einen POST erhält, wenn die Nachricht gesendet wird oder fehlschlägt. Siehe Webhook.

Bilder und Dateien senden#

Download-Limits für img_url und file_url:

  • Die URL muss öffentlich sein: http oder https, aus dem Internet erreichbar. Bis zu 5 Weiterleitungen werden verfolgt, und jede muss ebenfalls zu einer öffentlichen Adresse führen.
  • Verlinkte Dateien dürfen bis zu 100 MB groß sein. Der Server muss innerhalb von 45 Sekunden zu antworten beginnen und darf nicht länger als diese Zeit ins Stocken geraten.
  • Die Datei wird abgerufen, wenn Sie die API aufrufen. Ein defekter Link schlägt daher sofort mit Invalid file url fehl.

Unterstützte Dateiendungen: .pdf, .xlsx, .xls, .txt, .docx, .png, .jpg, .jpeg, .webp, .mp3, .mpga, .m4a, .mp4, .webm.

Diese Prüfungen laufen beim Senden der Nachricht, nicht beim Aufruf der API. Die Fehler erscheinen daher nur in Nachrichtenstatus und im Webhook:

Problemerror in Nachrichtenstatus
Ein Bild (msg_type 1) über 16 MBFile exceeds WhatsApp size limit (16MB max)
Ein Video (.mp4, .webm) über 64 MB oder eine leere DateiFile exceeds WhatsApp size limit (…)
Eine .ogg-Datei oder eine als Bild (msg_type 1) gesendete .wav-DateiFile type not supported

WAV- und OGG-Audio werden nicht unterstützt. Eine als Datei (msg_type 2) gesendete .wav-Datei wird nicht abgelehnt, kommt aber als recording.wav.pdf an. Konvertieren Sie Audio vorher in .mp3 oder .m4a.

Bild von einer URL
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 1,
    "country_code": "91",
    "phone": "9876543210",
    "img_url": "https://example.com/offers/diwali-sale.jpg",
    "msg": "Our Diwali sale starts today 🎉"
  }'
Datei hochladen
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -F client_id=12345 \
  -F api_key=YOUR_API_KEY \
  -F whatsapp_client=678 \
  -F msg_type=2 \
  -F country_code=91 \
  -F phone=9876543210 \
  -F "msg=Your invoice for order #4821 is attached." \
  -F file_name=invoice-4821.pdf \
  -F file=@./invoice-4821.pdf

Offizielle Clients verwenden#

Die Clients für Python und Node.js rufen diesen Endpoint für Sie auf.

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id="12345")

result = client.send_message(
    phone="9876543210",
    country_code="91",
    msg="Hi Aman, your order #4821 has shipped.",
    whatsapp_client=678,
)
print(result)

Fehler lösen requests.HTTPError aus. Den Grund lesen Sie mit e.response.json()["message"].

Antwort#

Ein erfolgreicher Request gibt HTTP 200 zurück:

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}
FeldTypBeschreibung
statusinteger1, wenn die Nachricht in die Warteschlange gestellt wurde, 0, wenn der Request fehlgeschlagen ist.
messagestringCreated bei Erfolg, andernfalls der Fehler.
msg_idintegerID der Nachricht in der Warteschlange. Speichern Sie sie, um später den Status zu prüfen. Nur bei Erfolg vorhanden.

"status": 1 bedeutet, dass die Nachricht in die Warteschlange gestellt wurde, nicht, dass sie den Empfänger bereits erreicht hat. Verwenden Sie einen Webhook oder Nachrichtenstatus, um den Versand zu bestätigen.

Fehler#

Fehler geben HTTP 400 mit status gleich 0 zurück (Account Disabled hat kein Feld status):

{ "status": 0, "message": "Msg cant be null" }
MeldungLösung
Auth Error - Please send correct API key and Client idSenden Sie einen nicht leeren api_key.
Invalid client id.Senden Sie client_id als Zahl.
Auth Error: invalid api keyPrüfen Sie, ob der Schlüssel existiert, nicht gelöscht wurde und zu dieser client_id gehört.
Either phone or group_name parameter is requiredFügen Sie phone hinzu.
Please provide either phone OR group_name, not bothEntfernen Sie einen der beiden Parameter.
Invalid phone numberphone darf nur Ziffern enthalten (6–17), optional mit einem + am Anfang.
Invalid Contact Number "…"Einschließlich Ländervorwahl muss die Nummer 6–15 Ziffern lang sein.
Msg cant be nullTextnachrichten (msg_type 0) benötigen msg.
Message length is too longBegrenzen Sie msg auf höchstens 3.000 Zeichen.
Image Url Can't be nullSenden Sie für msg_type 1 eine img_url oder laden Sie eine file hoch.
File Url Can't be nullSenden Sie für msg_type 2 eine file_url oder laden Sie eine file hoch.
Invalid file url, Can't download / Invalid file urlDie URL ist nicht öffentlich, das Zeitlimit wurde überschritten oder die Datei ist größer als 100 MB.
Invalid whatsapp clientDiese whatsapp_client-ID gehört nicht zu Ihrem Arbeitsbereich.
Invalid whatsapp client id.Senden Sie whatsapp_client. Der Parameter ist erforderlich, wenn Ihr Arbeitsbereich mehr als eine verbundene Nummer hat.
Not enough creditsIhr Plan hat keine Nachrichten mehr übrig.
Demo Account can not access apisVerwenden Sie ein reguläres Konto.
Account DisabledIhr Konto ist deaktiviert. Kontaktieren Sie den Support.
Invalid JSON format: …Der JSON-Body ist ungültig, oft wegen eines abschließenden Kommas oder eines nicht maskierten Zeilenumbruchs in msg. Verwenden Sie \n für neue Zeilen.

Eine Nachricht in der Warteschlange kann beim Senden trotzdem noch fehlschlagen, zum Beispiel mit File exceeds WhatsApp size limit (…). Solche Fehler erscheinen nie in dieser Antwort. Siehe Bilder und Dateien senden und prüfen Sie Nachrichtenstatus.

Webhook#

Wenn Sie webhook übergeben, sendet Wbiztool einen POST an diese URL, sobald die Nachricht gesendet wurde oder fehlgeschlagen ist. Der Body ist formularkodiert (application/x-www-form-urlencoded), nicht JSON:

msg_id=9817263&status=SENT
FeldWerte
msg_idDie msg_id, die Sie beim Senden der Nachricht erhalten haben.
statusSENT oder FAILED

Antworten Sie mit einem beliebigen 2xx-Code. Wenn Ihr Endpoint nicht rechtzeitig antwortet (nach 3 Sekunden) oder 5xx zurückgibt, wird der Aufruf insgesamt bis zu 3-mal versucht. Eine 4xx-Antwort wird nicht wiederholt. Für stornierte oder abgelaufene Nachrichten wird kein Webhook gesendet; verwenden Sie dafür Nachrichtenstatus.

Tipps#

  • Telefonnummern: Speichern Sie Nummern im internationalen Format und senden Sie sie mit country_code, um Mehrdeutigkeiten zu vermeiden.
  • Zeilenumbrüche in JSON: Schreiben Sie sie in msg als \n. Ein echter Zeilenumbruch macht das JSON ungültig.
  • Halten Sie Ihre Nummer verbunden: Nachrichten werden von Ihrer WhatsApp-Nummer gesendet, daher muss sie in den WhatsApp-Einstellungen verbunden bleiben.
  • Viele Empfänger: Um dieselbe Nachricht in einem Request an mehrere Nummern zu senden, verwenden Sie An mehrere Nummern senden. Für große Kampagnen laden Sie stattdessen eine Tabelle auf der Seite Kampagnen hoch.