Skip to content
WbizTool

Messaging API

Send Message API

Send a WhatsApp text, image or document to one phone number from your connected WhatsApp number. Use it for order confirmations, payment reminders, alerts and support replies.

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

Body: JSON, form fields, or multipart/form-data when uploading a file

The message is queued and sent from your WhatsApp number within moments. The response gives you a msg_id you can use to check its status.

Quick example#

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

Replace YOUR_API_KEY and 678 with your own key and number ID. See Authentication for where to find them. The key goes in the Authorization: Bearer header (recommended); client_id and api_key in the body, as JSON or form fields, work too – the examples further down use them.

Request parameters#

Authentication

AuthorizationheaderRecommended

Bearer YOUR_API_KEY: your API key from Settings → API keys. With the header, client_id and api_key can be left out of the body; if both are sent, a valid key in the header is used. See Send the key in a header.

client_idintegerWithout the Authorization header

Your API Client ID from Settings → API keys. Optional with the header; if you send it, it must be the key's workspace.

api_keystringWithout the Authorization header

Your API key from the same page, when you don't send it in the header.

whatsapp_clientintegerRequired if you have more than one number

ID of the WhatsApp number or Telegram account to send from, from WhatsApp settings. If you leave it out, the only connected number is used, WhatsApp first: one connected WhatsApp number is used even if a Telegram account is also connected, and a Telegram account only when no WhatsApp number is connected. An @username uses the only connected Telegram account. With no WhatsApp number connected, the only Chrome extension number whose browser is closed is used, so the message waits instead of failing.

Recipient and message

phonestringrequired

The recipient's WhatsApp number. Spaces, +, -, ., brackets and a leading 00 are removed for you, so +91 98765-43210 works. Spreadsheet values such as 919876543210.0 and 9.19876543210E+11 are read as their digits, but a rounded one such as 9.19877E+11 is refused, because digits are missing. Send the number either with its country code (919876543210) or without it (9876543210) together with country_code. A local number written with its leading 0 works too: 09876543210 with country_code 91 goes to 919876543210, and 0612345678 with 39 (Italy, where the 0 is part of the number) goes to 390612345678. A number written with + or 00 carries its country code: country_code isn't added to it, and a bracketed (0) after the code is dropped, so +44 (0)20 7946 0018 goes to 442079460018. From a Telegram account, phone can also be an @username, a t.me/username link or tg:<id>.

country_codestringoptional

Country calling code without +, for example 91 for India or 1 for the USA. It's added in front of phone unless the number already starts with it or is written with + or 00. Exception: with 91, a 10-digit number always gets the prefix. With other codes, a local number that starts with the same digits isn't prefixed, so send it with the country code included.

msg_typeintegeroptional

0 text (default), 1 image, 2 file or document.

msgstringRequired when msg_type is 0

Message text, up to 3,000 characters. For images and files it's the caption and can be empty. WhatsApp formatting works: *bold*, _italic_, ~strikethrough~. message is accepted as an alias.

Images and files

img_urlstringRequired when msg_type is 1 and no file is uploaded

Public http or https URL of the image.

file_urlstringRequired when msg_type is 2 and no file is uploaded

Public http or https URL the file can be downloaded from directly.

filefileoptional

Upload the image or file instead of giving a URL. Send the request as multipart/form-data with the field named file.

file_namestringoptional

File name the recipient sees, such as invoice-4821.pdf. Its extension decides how the file is sent, so include one. It's sent in lower case, characters such as & : ? * $ ; are replaced with _, and it's cut to 150 characters. If you leave it out, the name comes from the URL or the uploaded file.

Delivery options

expire_after_secondsintegeroptional

Mark the message as expired (status 4) if it hasn't been sent within this many seconds, for example 3600 for one hour. Useful for time-sensitive messages such as delivery ETAs. A background job does this at least 30 seconds after the deadline, so don't rely on it for deadlines shorter than a minute.

webhookstringoptional

URL that receives a POST when the message is sent, fails, is cancelled or expires. See Webhook.

idempotency_keystringoptional

Optional, up to 255 characters. Retry with the same value and you get the first answer back instead of a second message, for 24 hours. You can send it as an Idempotency-Key header instead. See Retry safely.

Retry safely#

After a timeout or a lost connection you can't tell whether your request got through, and sending it again could message the customer twice. To retry safely, send an idempotency_key field or an Idempotency-Key header with a value of your own that's unique to this message, such as your order ID or a UUID, and use the same value and the same request when you retry.

It works on Send message, Send to group, Send to multiple numbers and Schedule message. Each API key has its own values, kept for 24 hours. Without one, or with a blank one, every request sends as usual.

What happensAnswer
The first request with this valueThe normal answer.
A retry after it succeededThe first answer again, with the header Idempotent-Replayed: true. No new message.
A retry after a refusal (status 0)Runs again: refusals aren't remembered, so you can fix the request and retry with the same value.
A retry while the first request is still runningHTTP 409, code idempotency_in_progress, with Retry-After: 1.
The same value with a different requestHTTP 409, code idempotency_key_reused.
A value over 255 characters, or with line breaksHTTP 400, code invalid_idempotency_key.

The idempotency key only stops the same request making a second message. It doesn't tell you whether the message reached WhatsApp: use a webhook or Message status for that.

Sending images and files#

Download limits for img_url and file_url:

  • The URL must be public: http or https, reachable from the internet. Up to 5 redirects are followed, and each one must also lead to a public address.
  • Linked files can be up to 100 MB. The server must start responding within 45 seconds and not stall for longer than that.
  • The file is fetched when you call the API, so a broken link fails straight away with Invalid file url.

Files sent with msg_type 2 keep these extensions:

CategoryExtensions
Images.jpg, .jpeg, .jpe, .png, .gif, .webp, .bmp
Documents.pdf, .doc, .docx, .docm, .xls, .xlsx, .xlsm, .xlsb, .ppt, .pptx, .pptm, .txt, .csv
Audio.mp3, .mpga, .m4a, .aac, .wav, .ogg, .oga
Video.mp4, .mov, .avi, .webm
Archives.zip, .rar

These checks run when the message is sent, not when you call the API, so the failures only show up in Message status and the webhook:

Problemerror in Message status
An image (msg_type 1) over 16 MBFile exceeds WhatsApp size limit (16MB max)
A video (.mp4, .webm) over 64 MB, including one sent as an image (msg_type 1)File exceeds WhatsApp size limit (64MB max)
Any other file (msg_type 2) over 100 MBFile exceeds WhatsApp size limit (100MB max)
An empty file (0 bytes)The file is empty
A .wav or .ogg file sent as an image (msg_type 1)File type not supported

WAV and OGG audio can't be sent as an image (msg_type 1). Sent as a file (msg_type 2), they arrive as a document under their own name, such as recording.wav. .mp3, .mpga, .m4a and .aac files arrive as audio that plays in the chat, and msg follows as a separate text message (audio has no caption).

Image from a 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 🎉"
  }'
Upload a file
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

Using the official clients#

The Python and Node.js clients call this endpoint for you.

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)

Errors raise requests.HTTPError. Read the reason with e.response.json()["message"].

Response#

A successful request returns HTTP 200:

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}
FieldTypeDescription
statusinteger1 if the message was queued, 0 if the request failed.
messagestringCreated on success, otherwise the error.
msg_idintegerID of the queued message. Save it to check the status later. Only present on success.

"status": 1 means the message was queued, not that it reached the recipient yet. Use a webhook or Message status to confirm it was sent.

Errors#

Errors return HTTP 400 with status set to 0 (Account Disabled has no status field):

{ "status": 0, "message": "Msg cant be null" }
MessageHow to fix it
Auth Error - Please send correct API key and Client idSend a non-empty api_key.
Invalid client id.Send client_id as a number.
Auth Error: invalid api keyCheck the key exists, hasn't been deleted and belongs to this client_id.
Either phone or group_name parameter is requiredAdd phone.
Please provide either phone OR group_name, not bothRemove one of them.
Invalid phone numberphone must be a number of 6–17 digits. Letters and other symbols aren't allowed, and neither is a rounded spreadsheet value such as 9.19877E+11.
Invalid Contact Number "…"With the country code added, the number must be 7–15 digits long.
Msg cant be nullText messages (msg_type 0) need msg.
Message length is too longKeep msg to 3,000 characters or fewer.
Image Url Can't be nullFor msg_type 1, send img_url or upload a file.
File Url Can't be nullFor msg_type 2, send file_url or upload a file.
Invalid file url, Can't download / Invalid file urlThe URL isn't public, timed out, or the file is over 100 MB.
Invalid whatsapp clientThat whatsapp_client ID isn't in your workspace.
Invalid whatsapp client id.Send whatsapp_client. It's required when your workspace has more than one connected number.
Telegram usernames can only be sent to from a Telegram account: pass its id as whatsapp_clientAn @username, t.me link or tg:<id> in phone needs a Telegram account as whatsapp_client.
Not enough creditsThe workspace is on the free plan and has no messages left: paid plans send unlimited messages. See When you run out of messages.
Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow. (HTTP 429, "code": "daily_limit_reached")This number took 1,000 messages in the last 24 hours (fair use). The response still has the msg_id of the refused message, which shows as failed. Send the rest later or from another number.
Demo Account can not access apisUse a regular account.
Account DisabledYour account is disabled. Contact support.
Invalid JSON format: …The JSON body isn't valid, often because of a trailing comma or an unescaped line break in msg. Use \n for new lines.

A queued message can still fail when it's sent, for example with File exceeds WhatsApp size limit (…). Those errors never appear in this response. See Sending images and files and check Message status.

Webhook#

If you pass webhook, WbizTool sends a POST to that URL when the message is sent or fails, and when it's cancelled or expires before it was sent. The body is form-encoded (application/x-www-form-urlencoded), not JSON:

msg_id=9817263&status=SENT
FieldValues
msg_idThe msg_id returned when you sent the message.
statusSENT, FAILED, CANCELLED (cancelled before it was sent: with Cancel message, from the dashboard, or because its WhatsApp number or campaign was removed) or EXPIRED (not sent before expire_after_seconds ran out, or still waiting on a disconnected number 48 hours after it was due)

Each webhook is signed: the headers WbizTool-Timestamp and WbizTool-Signature (v1= and an HMAC-SHA256 of <timestamp>.<raw body> with your workspace's signing secret) let you check it came from WbizTool. Get the secret and the Python and Node.js check in Webhook signatures; receivers that ignore the headers keep working.

Respond with any 2xx code; a redirect is followed, at most 3 times. If your endpoint doesn't answer within 10 seconds, can't be reached, or returns 429 or 5xx, WbizTool tries again after 30 seconds, 1 minute and 2 minutes (4 tries in all). Other 4xx responses aren't retried. The URL must be a public internet address: a webhook to a private or local address (such as 192.168.x.x or localhost) isn't sent.

Tips#

  • Phone numbers: store numbers in international format and send them with country_code to avoid ambiguity.
  • New lines in JSON: write them as \n inside msg. A raw line break makes the JSON invalid.
  • Keep your number connected: messages are sent from your WhatsApp number, so it must stay connected in WhatsApp settings.
  • Many recipients: to send the same message to several numbers in one request, use Send to multiple numbers. For large campaigns, upload a spreadsheet from the Campaigns page instead.