Developer reference
WBIZ.IN API
Build third-party WhatsApp integrations on top of WBIZ. Send messages, templates and (soon) read inbox state from your own backend with a Bearer API key. v1 is stable — backward-incompatible changes ship as a new version, never as a break to existing routes.
Quick start
Three steps to your first WhatsApp send.
- 1
Issue an API key
Sign in and head to Settings → API keys. Create a key for your integration. The secret is shown once — store it securely.
- 2
Set the base URL + auth header
All requests go to and must include .
- 3
Make your first call
Send a freeform text inside the active 24-hour window, or a template message any time. Responses return a Meta
wamidyou can correlate with delivery webhooks.
Authentication
Every request must include a Bearer API key in the Authorization header. Each key is scoped per WhatsApp Business Account, so an integration only sees the WABA you bind it to.
curl https://api.wbiz.in/v1/messages/text \
-H "Authorization: Bearer wbiz_live_xxx..." \
-H "Content-Type: application/json"messages:sendactiveSend text, template, media, interactive and location messages on the bound WABA.
templates:readactiveList approved templates with their components and variables.
contacts:readactiveRead contacts in the workspace, by id or filtered list.
contacts:writeactiveCreate and update contacts. Idempotent on phone number.
inbox:readactiveList conversations and read message history per thread.
webhooks:manageplannedConfigure outbound delivery / status webhooks programmatically.
Rate limits
Each API key is rate-limited per minute. Limits scale with your plan. Every response includes the standard rate-limit headers so you can back off cleanly.
| Plan | Requests / minute | Burst (10s window) |
|---|---|---|
| Starter | 60 | 15 |
| Growth | 600 | 120 |
| Scale | 6 000 | 1 200 |
X-RateLimit-LimitMax requests in the current window.
X-RateLimit-RemainingRequests left in the current window.
X-RateLimit-ResetUnix timestamp when the window resets.
Hitting the cap returns HTTP 429 with Retry-After in seconds. Build exponential back-off into your client.
Resource
Messages
Programmatically send WhatsApp messages from your backend. All endpoints are scoped to the WABA your API key is bound to.
Send a text message
Send a freeform text message inside the active 24-hour service window. Use for support replies after the customer has messaged you. For first-touch outreach, use the template endpoint.
https://api.wbiz.in/v1/messages/textRequest body
tostringRequiredRecipient phone number in E.164 format. Must be WhatsApp-registered.
min 8, max 20 charsExample:+919812345678bodystringRequiredThe text body of the message. URLs auto-link in the WhatsApp client. Use \n for line breaks.
min 1, max 4096 charsExample:Your order #4827 has shipped!phoneNumberIdstringOptionalPin the send to a specific phone number on your WABA. Required if your WABA has more than one phone — otherwise the first phone is used.
Example:107394529103847
Request example
curl -X POST https://api.wbiz.in/v1/messages/text \
-H "Authorization: Bearer wbiz_live_xxx..." \
-H "Content-Type: application/json" \
-d '{
"to": "+919812345678",
"body": "Hi! Your order #4827 has shipped.",
"phoneNumberId": "107394529103847"
}'Response — 200 OK
{
"wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQjg5RTk0NDM2NjE2RDM3RkU0AA=="
}Errors
- 400
VALIDATION_FAILEDBody failed validation — invalid E.164, body over 4096 chars, or missing required field.
- 400
OUTSIDE_24H_WINDOWRecipient hasn’t messaged you in the last 24 hours. Use a template message.
- 401
INVALID_API_KEYMissing, malformed, or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key is valid but lacks the messages:send scope.
- 404
PHONE_NOT_FOUNDphoneNumberId does not belong to the WABA tied to this API key.
- 429
RATE_LIMITEDPlan rate limit exceeded. Retry after X-RateLimit-Reset.
- 502
META_UPSTREAM_ERRORMeta’s Cloud API rejected the send. Body includes the upstream error code.
Send a template message
Send an approved WhatsApp template. Works any time — including outside the 24-hour service window — and supports body variables, header media, buttons and Flow attachments.
https://api.wbiz.in/v1/messages/templateRequest body
tostringRequiredRecipient phone number in E.164 format.
min 8, max 20 charsExample:+919812345678templatestringRequiredName (slug) of the approved template. Must already be Meta-approved on the WABA tied to this API key.
max 120 charsExample:order_shipped_v2languagestringRequiredLocale code (en, en_US, hi_IN, …). Must match the language Meta approved the template in.
max 8 charsExample:en_USvariablesstring[]OptionalPositional substitutions for {{1}}, {{2}}, … placeholders in the template body. Pass them in order.
Example:["Aarav", "4827", "tomorrow"]phoneNumberIdstringOptionalPin the send to a specific phone number on your WABA.
Example:107394529103847componentsobject[]OptionalPre-built Meta-shaped components array. Use this when positional variables are not enough — header media, named variables, buttons with URL parameters, Flow attachments.
flowAction"navigate" | "data_exchange"OptionalAction verb for templates that include a Flow button. "navigate" jumps to a static screen; "data_exchange" calls your encrypted Flow data endpoint.
Request example
curl -X POST https://api.wbiz.in/v1/messages/template \
-H "Authorization: Bearer wbiz_live_xxx..." \
-H "Content-Type: application/json" \
-d '{
"to": "+919812345678",
"template": "order_shipped_v2",
"language": "en_US",
"variables": ["Aarav", "4827", "tomorrow"],
"phoneNumberId": "107394529103847"
}'Response — 200 OK
{
"wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQjg5RTk0NDM2NjE2RDM3RkU0AA=="
}Errors
- 400
VALIDATION_FAILEDBody failed validation — invalid E.164, missing template name, unsupported language.
- 400
TEMPLATE_NOT_APPROVEDTemplate exists but is in Draft / Pending / Rejected. Only APPROVED templates send.
- 400
TEMPLATE_LANGUAGE_MISMATCHLanguage does not match Meta’s approved locale for this template.
- 400
TEMPLATE_VARIABLE_COUNT_MISMATCHNumber of variables does not match the {{1}}…{{n}} placeholders.
- 401
INVALID_API_KEYMissing, malformed, or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key is valid but lacks the messages:send scope.
- 404
TEMPLATE_NOT_FOUNDNo template with that name exists on the WABA tied to this API key.
- 404
PHONE_NOT_FOUNDphoneNumberId does not belong to the WABA tied to this API key.
- 429
RATE_LIMITEDPlan rate limit exceeded. Retry after X-RateLimit-Reset.
- 502
META_UPSTREAM_ERRORMeta’s Cloud API rejected the send. Body includes the upstream error code.
Send a media message
Send an image, video, document, audio or sticker. Provide the media either by Meta-hosted media handle (mediaId) or by HTTPS URL (link) — exactly one of the two is required.
https://api.wbiz.in/v1/messages/mediamediaId OR link, never both. The link variant must be HTTPS, publicly fetchable by Meta, and within Meta’s per-type size limits.Request body
tostringRequiredRecipient in E.164 format.
min 8, max 20 charsExample:+919812345678type"image" | "video" | "document" | "audio" | "sticker"RequiredMedia type. Determines which Meta size + format limits apply.
Example:imagemediaIdstringOptionalMeta media handle from a prior upload (preferred — survives multiple sends).
Example:1042817329043...linkstringOptionalPublic HTTPS URL Meta will fetch the media from. Used when mediaId is absent.
Example:https://cdn.example.com/invoice.pdfcaptionstringOptionalOptional caption — supported on image / video / document.
Example:Your invoice for April.filenamestringOptionalOverride the displayed filename (document only).
Example:invoice-april.pdfphoneNumberIdstringOptionalPin the send to a specific phone number on your WABA.
Request example
curl -X POST https://api.wbiz.in/v1/messages/media \
-H "Authorization: Bearer wbiz_live_xxx..." \
-H "Content-Type: application/json" \
-d '{
"to": "+919812345678",
"type": "image",
"link": "https://cdn.example.com/promo.jpg",
"caption": "Spring sale starts now!"
}'Response — 200 OK
{ "wamid": "wamid.HBgM..." }Errors
- 400
VALIDATION_FAILEDBody failed validation — invalid E.164, unsupported type, both/neither of mediaId+link supplied.
- 400
MEDIA_FETCH_FAILEDMeta could not fetch the link URL — non-HTTPS, 404, blocked content-type, or > size limit for the type.
- 400
OUTSIDE_24H_WINDOWRecipient hasn’t messaged you in 24h. Use a media template instead.
- 401
INVALID_API_KEYMissing, malformed or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key lacks the messages:send scope.
- 404
PHONE_NOT_FOUNDphoneNumberId does not belong to the bound WABA.
- 429
RATE_LIMITEDPlan rate limit exceeded.
- 502
META_UPSTREAM_ERRORMeta rejected the send — body includes the upstream Meta error.
Send an interactive message
Send reply buttons (up to 3) or a list menu (up to 10 sections × 10 rows). The recipient taps a choice and the response arrives on your inbound webhook tied to the same conversation.
https://api.wbiz.in/v1/messages/interactivekind=list, the WhatsApp button that opens the menu is labelled “Choose” and is not customisable through the v1 API. If you need a custom label, send the same payload as a template instead.Request body
tostringRequiredRecipient in E.164 format.
Example:+919812345678kind"buttons" | "list"RequiredWhich interactive variant to render.
Example:buttonsbodystringRequiredMain body text shown above the buttons / list.
max 1024 charsheaderTextstringOptionalOptional header text rendered above the body.
max 60 charsfooterstringOptionalOptional footer rendered below the buttons.
max 60 charsbuttonsArray<{id, title}>OptionalRequired when kind=buttons. Up to 3 reply buttons.
Example:[{"id":"yes","title":"Yes"},{"id":"no","title":"No"}]listSectionsArray<{title, rows: Array<{id, title, description?}>}>OptionalRequired when kind=list. Up to 10 sections, each with up to 10 rows.
phoneNumberIdstringOptionalPin to a specific phone number.
Request example
# Reply buttons
curl -X POST https://api.wbiz.in/v1/messages/interactive \
-H "Authorization: Bearer wbiz_live_xxx..." \
-H "Content-Type: application/json" \
-d '{
"to": "+919812345678",
"kind": "buttons",
"body": "Did your order arrive in good condition?",
"buttons": [
{ "id": "yes", "title": "Yes, all good" },
{ "id": "no", "title": "Report an issue" }
]
}'Response — 200 OK
{ "wamid": "wamid.HBgM..." }Errors
- 400
VALIDATION_FAILEDInvalid kind, buttons > 3, listSections > 10, or rows > 10 per section.
- 400
INTERACTIVE_LIMITSTitle text exceeds 20 chars or button id exceeds 256 chars (Meta limits).
- 400
OUTSIDE_24H_WINDOWInteractive messages must be inside the 24h window.
- 401
INVALID_API_KEYMissing, malformed or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key lacks the messages:send scope.
- 429
RATE_LIMITEDPlan rate limit exceeded.
- 502
META_UPSTREAM_ERRORMeta rejected the send.
Send a location pin
Send a tappable location pin to the recipient — useful for store directions, delivery rendezvous points or service areas.
https://api.wbiz.in/v1/messages/locationRequest body
tostringRequiredRecipient in E.164 format.
Example:+919812345678latitudenumberRequiredDecimal degrees, between -90 and 90.
Example:12.9716longitudenumberRequiredDecimal degrees, between -180 and 180.
Example:77.5946namestringOptionalDisplay name shown above the pin (e.g. business name).
Example:WBIZ HQaddressstringOptionalFull address shown below the name.
Example:Indiranagar, Bengaluru 560038phoneNumberIdstringOptionalPin to a specific phone number.
Request example
curl -X POST https://api.wbiz.in/v1/messages/location \
-H "Authorization: Bearer wbiz_live_xxx..." \
-H "Content-Type: application/json" \
-d '{
"to": "+919812345678",
"latitude": 12.9716,
"longitude": 77.5946,
"name": "WBIZ HQ",
"address": "Indiranagar, Bengaluru 560038"
}'Response — 200 OK
{ "wamid": "wamid.HBgM..." }Errors
- 400
VALIDATION_FAILEDlatitude/longitude out of range, or invalid E.164.
- 400
OUTSIDE_24H_WINDOWLocation messages require the 24h window.
- 401
INVALID_API_KEYMissing, malformed or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key lacks the messages:send scope.
- 429
RATE_LIMITEDPlan rate limit exceeded.
- 502
META_UPSTREAM_ERRORMeta rejected the send.
Resource
Templates
Read approved WhatsApp templates so your integration knows what it can send. The template body, variables and language come from Meta — your code mirrors that contract.
List templates
Cursor-paginated list of templates on the WABA bound to your API key. Filter by approval status, category or language.
https://api.wbiz.in/v1/templatesQuery parameters
status"approved" | "pending" | "rejected"OptionalFilter by Meta-approval state. Default returns all.
categorystringOptionalFilter by template category (utility, marketing, authentication).
languagestringOptionalLocale code filter — exact match on Meta-approved language.
Example:en_USlimitnumberOptionalPage size. Default 25, max 100.
cursorstringOptionalCursor returned by the previous page (template id).
Request example
curl -G https://api.wbiz.in/v1/templates \
-H "Authorization: Bearer wbiz_live_xxx..." \
--data-urlencode "status=approved" \
--data-urlencode "language=en_US" \
--data-urlencode "limit=25"Response — 200 OK
{
"data": [
{
"name": "order_shipped_v2",
"language": "en_US",
"category": "UTILITY",
"status": "APPROVED",
"components": [
{ "type": "BODY", "text": "Hi {{1}}! Order #{{2}} ships {{3}}." }
]
}
],
"nextCursor": "65fc2e1b9a8b..."
}Errors
- 401
INVALID_API_KEYMissing, malformed or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key lacks the templates:read scope.
- 429
RATE_LIMITEDPlan rate limit exceeded.
Resource
Contacts
Manage the contacts your WhatsApp campaigns can reach. Create, list, fetch and update — including custom fields, tags and opt-in state.
List contacts
Cursor-paginated contact list with optional search, tag and opt-in filters.
https://api.wbiz.in/v1/contactsQuery parameters
searchstringOptionalSearch by name or phone (substring).
tagstringOptionalFilter to contacts tagged with this label.
optedInbooleanOptionalFilter by opt-in state. Omit to include both.
limitnumberOptionalPage size. Default 25, max 100.
cursorstringOptionalCursor returned by the previous page (last contact id).
Request example
curl -G https://api.wbiz.in/v1/contacts \
-H "Authorization: Bearer wbiz_live_xxx..." \
--data-urlencode "tag=vip" \
--data-urlencode "optedIn=true" \
--data-urlencode "limit=50"Response — 200 OK
{
"data": [
{
"id": "65fc2e1b9a8b1c...",
"phone": "+919812345678",
"name": "Aarav Sharma",
"email": "aarav@example.com",
"tags": ["vip", "delhi"],
"customFields": { "city": "Delhi", "tier": "gold" },
"optedIn": true,
"createdAt": "2026-04-12T08:32:11.420Z"
}
],
"nextCursor": "65fc2e1b9a8b..."
}Errors
- 401
INVALID_API_KEYMissing, malformed or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key lacks the contacts:read scope.
- 429
RATE_LIMITEDPlan rate limit exceeded.
Create a contact
Create a contact — or, on phone collision, return the existing contact (idempotent upsert by phone).
https://api.wbiz.in/v1/contactsPATCH /v1/contacts/:id to update fields after.Request body
phonestringRequiredE.164 phone number — primary identifier.
Example:+919812345678namestringOptionalDisplay name.
Example:Aarav SharmaemailstringOptionalEmail address — must be a valid email format if provided.
tagsstring[]OptionalInitial tags. Tags are created on the fly if they don’t exist.
Example:["vip","delhi"]customFieldsRecord<string, string>OptionalFree-form key/value metadata. Both key and value are strings.
Example:{"city":"Delhi","tier":"gold"}optedInbooleanOptionalMarketing opt-in state. Defaults to true on create.
Request example
curl -X POST https://api.wbiz.in/v1/contacts \
-H "Authorization: Bearer wbiz_live_xxx..." \
-H "Content-Type: application/json" \
-d '{
"phone": "+919812345678",
"name": "Aarav Sharma",
"email": "aarav@example.com",
"tags": ["vip","delhi"],
"customFields": { "city": "Delhi", "tier": "gold" },
"optedIn": true
}'Response — 200 OK
{
"id": "65fc2e1b9a8b1c...",
"phone": "+919812345678",
"name": "Aarav Sharma",
"email": "aarav@example.com",
"tags": ["vip", "delhi"],
"customFields": { "city": "Delhi", "tier": "gold" },
"optedIn": true,
"createdAt": "2026-04-28T17:42:12.108Z"
}Errors
- 400
VALIDATION_FAILEDPhone failed E.164 validation, or email failed format check.
- 401
INVALID_API_KEYMissing, malformed or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key lacks the contacts:write scope.
- 429
RATE_LIMITEDPlan rate limit exceeded.
Get a contact
Fetch one contact by id. Cross-WABA contact ids return 404 (not 403) so probing for foreign ids leaks nothing.
https://api.wbiz.in/v1/contacts/:idPath parameters
idstringContact id from list / create.
Example:65fc2e1b9a8b1c...
Request example
curl https://api.wbiz.in/v1/contacts/65fc2e1b9a8b1c... \
-H "Authorization: Bearer wbiz_live_xxx..."Response — 200 OK
{
"id": "65fc2e1b9a8b1c...",
"phone": "+919812345678",
"name": "Aarav Sharma",
"email": "aarav@example.com",
"tags": ["vip"],
"customFields": { "city": "Delhi" },
"optedIn": true,
"createdAt": "2026-04-12T08:32:11.420Z"
}Errors
- 401
INVALID_API_KEYMissing, malformed or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key lacks the contacts:read scope.
- 404
NOT_FOUNDContact does not exist OR belongs to a different WABA.
Update a contact
Partial update — supply only the fields you want to change. Tags fully replace the current set; customFields shallow-merge.
https://api.wbiz.in/v1/contacts/:idPath parameters
idstringContact id.
Example:65fc2e1b9a8b1c...
Request body
namestringOptionalNew display name.
emailstringOptionalNew email address.
tagsstring[]OptionalReplaces the contact’s tag set entirely.
Example:["vip","gold"]customFieldsRecord<string, string>OptionalShallow-merged into the existing custom fields.
optedInbooleanOptionalUpdate marketing opt-in state.
Request example
curl -X PATCH https://api.wbiz.in/v1/contacts/65fc2e1b9a8b1c... \
-H "Authorization: Bearer wbiz_live_xxx..." \
-H "Content-Type: application/json" \
-d '{
"tags": ["vip","gold"],
"customFields": { "tier": "platinum" }
}'Response — 200 OK
{
"id": "65fc2e1b9a8b1c...",
"phone": "+919812345678",
"name": "Aarav Sharma",
"tags": ["vip", "gold"],
"customFields": { "city": "Delhi", "tier": "platinum" },
"optedIn": true
}Errors
- 400
VALIDATION_FAILEDField type mismatch or invalid email format.
- 401
INVALID_API_KEYMissing, malformed or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key lacks the contacts:write scope.
- 404
NOT_FOUNDContact does not exist OR belongs to a different WABA.
Resource
Conversations & messages
Read inbox state. Use this to surface ongoing chats inside your CRM, or to backfill message history for analytics.
List conversations
Cursor-paginated conversation list. Cursor is the lastMessageAt ISO timestamp of the last item — pass it as the next-page boundary.
https://api.wbiz.in/v1/conversationsQuery parameters
status"open" | "closed"OptionalFilter by conversation status.
channel"whatsapp" | "messenger" | "instagram"OptionalFilter by channel.
limitnumberOptionalPage size. Default 25, max 100.
cursorstring (ISO date)OptionallastMessageAt of the last conversation on the previous page.
Request example
curl -G https://api.wbiz.in/v1/conversations \
-H "Authorization: Bearer wbiz_live_xxx..." \
--data-urlencode "status=open" \
--data-urlencode "channel=whatsapp" \
--data-urlencode "limit=25"Response — 200 OK
{
"data": [
{
"id": "65fc2e1b9a8b1c...",
"contact": {
"phone": "+919812345678",
"name": "Aarav Sharma"
},
"channel": "whatsapp",
"status": "open",
"lastMessageAt": "2026-04-28T17:42:12.108Z",
"unreadCount": 2
}
],
"nextCursor": "2026-04-28T17:42:12.108Z"
}Errors
- 401
INVALID_API_KEYMissing, malformed or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key lacks the inbox:read scope.
- 429
RATE_LIMITEDPlan rate limit exceeded.
List messages in a conversation
Paginated message history for a single conversation. Pagination uses beforeId — pass the id of the oldest message you have to get older messages.
https://api.wbiz.in/v1/conversations/:id/messagesPath parameters
idstringConversation id.
Query parameters
limitnumberOptionalPage size. Default 50, max 200.
beforeIdstringOptionalMessage id — fetches messages strictly older than this one.
Request example
curl -G https://api.wbiz.in/v1/conversations/65fc2e1b9a8b/messages \
-H "Authorization: Bearer wbiz_live_xxx..." \
--data-urlencode "limit=50"Response — 200 OK
{
"data": [
{
"wamid": "wamid.HBgM...",
"direction": "inbound",
"kind": "text",
"body": "Has my order shipped?",
"createdAt": "2026-04-28T17:38:01.220Z",
"status": "delivered"
},
{
"wamid": "wamid.HBgM...",
"direction": "outbound",
"kind": "template",
"body": "Hi Aarav! Your order #4827 has shipped.",
"createdAt": "2026-04-28T17:42:12.108Z",
"status": "read"
}
],
"nextCursor": "65fc2e1b9a8b1c..."
}Errors
- 401
INVALID_API_KEYMissing, malformed or revoked API key.
- 403
INSUFFICIENT_SCOPEAPI key lacks the inbox:read scope.
- 404
NOT_FOUNDConversation does not exist OR belongs to a different WABA.
Delivery webhooks
Every send returns a wamid. Delivery, read and reply events arrive on the same wamid through your configured webhook so you can correlate them with the original request.
Programmatic webhook configuration via the API ships in v1.1 alongside the webhooks:manage scope. Until then, configure delivery webhooks from /app/channels.
Real engineers reply.
Stuck on a Meta error code, modelling a complex template, or looking for an SDK in your favourite language? Drop us a note — every API question routes to a real engineer, average reply under 4 business hours.