WhatsApp API

WhatsApp Business messaging

Use the Ozibus WhatsApp API for authorised server-to-server business messaging. Ozibus resolves the WhatsApp sender from the authenticated merchant account; callers do not submit a Twilio Account SID, Auth Token, Messaging Service SID or sender number.

Endpoint

POST https://api.ozibus.com.au/v1/whatsapp

Authentication and source allowlist

The request must originate from an active IP address or CIDR range in Integration > Trusted IPs. Keep the secret API key on a trusted server. Do not call this endpoint directly from browser JavaScript or a public widget.

Common request properties

Text message

Use text for ordinary free-form conversation messages where the WhatsApp customer-service window and channel rules permit them.

{
  "type": "text",
  "to": "+61412345678",
  "message": "Your appointment is confirmed for tomorrow at 10:00."
}

Image message

Use image for a publicly retrievable image. The URL must be available to the provider without authentication, cookies or an expiring browser session.

{
  "type": "image",
  "to": "+61412345678",
  "media_url": "https://merchant.example.com/media/order-1842.jpg",
  "caption": "Your completed order is ready for collection."
}

Document message

Use document for a provider-supported document such as a PDF invoice, booking confirmation or account statement. Ozibus does not currently accept a separate filename property; use a meaningful filename in the media URL response.

{
  "type": "document",
  "to": "+61412345678",
  "media_url": "https://merchant.example.com/documents/invoice-INV-1842.pdf",
  "caption": "Invoice INV-1842"
}

Audio message

Use audio for a provider-supported audio file. Caption support depends on the WhatsApp/provider media rules applied to the file type.

{
  "type": "audio",
  "to": "+61412345678",
  "media_url": "https://merchant.example.com/media/voice-update.ogg"
}

Video message

Use video for a provider-supported video file. Host a stable file with the correct content type and a size accepted by WhatsApp and the configured provider account.

{
  "type": "video",
  "to": "+61412345678",
  "media_url": "https://merchant.example.com/media/product-demo.mp4",
  "caption": "A short demonstration of your new device."
}

Generic media message

Use generic media when the application selects the media classification dynamically. media_type is required in application practice and must resolve to image, document, audio or video. If omitted, the current service defaults it to image.

{
  "type": "media",
  "media_type": "document",
  "to": "+61412345678",
  "media_url": "https://merchant.example.com/documents/booking-6841.pdf",
  "caption": "Your booking confirmation"
}

Approved template message

Use template for business-initiated messages outside the customer-service window and for approved structured or interactive content. The Twilio Content Template must already exist, be approved where approval is required and be available to the merchant WhatsApp sender.

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HX0123456789abcdef0123456789abcdef",
  "content_variables": {
    "1": "Ada",
    "2": "27 August 2026",
    "3": "10:00 AM"
  }
}

The Content SID determines the language, body, buttons and structured layout. The send payload supplies only recipient data and the approved variable values; it does not redefine the template.

Template use case: order or appointment update

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HX11111111111111111111111111111111",
  "content_variables": {
    "1": "Ada",
    "2": "ORD-1842",
    "3": "Out for delivery"
  }
}

Template use case: quick-reply buttons

Create and approve a quick-reply Content Template first. The button labels and reply identifiers belong to that template.

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HX22222222222222222222222222222222",
  "content_variables": {
    "1": "Ada",
    "2": "BK-6841"
  }
}

Template use case: call-to-action buttons

Use an approved call-to-action template for actions such as visiting a booking page or calling a support number. Static and variable URL portions are defined by the Content Template.

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HX33333333333333333333333333333333",
  "content_variables": {
    "1": "Ada",
    "2": "booking/BK-6841"
  }
}

Template use case: rich card

A card template can combine approved text, media and actions. The actual card anatomy is configured in Twilio Content Template Builder.

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HX44444444444444444444444444444444",
  "content_variables": {
    "1": "Premium Support Plan",
    "2": "AUD 49.00",
    "3": "plans/premium"
  }
}

Template use case: carousel

Carousel cards, card count, actions and variable positions must be defined by a supported and approved Content Template. Availability depends on the merchant sender and current provider/channel capabilities.

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HX55555555555555555555555555555555",
  "content_variables": {
    "1": "Shared Hosting",
    "2": "Business Hosting",
    "3": "Managed VPS"
  }
}

Template use case: list picker

Use a list-picker template when the recipient should choose from structured options such as appointment locations, departments or service categories.

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HX66666666666666666666666666666666",
  "content_variables": {
    "1": "Ada",
    "2": "available appointment locations"
  }
}

Template use case: catalog or product

Catalog and product messages require the relevant Meta commerce assets, sender permissions and a compatible approved template. The payload below supplies variables only; it does not create or attach a catalog.

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HX77777777777777777777777777777777",
  "content_variables": {
    "1": "CATALOG-REFERENCE",
    "2": "PRODUCT-REFERENCE"
  }
}

Template use case: WhatsApp Flow

Flows must be created and approved in the relevant Meta/WhatsApp environment and referenced by a compatible Content Template. Flow state and sensitive form handling remain the integrator responsibility.

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HX88888888888888888888888888888888",
  "content_variables": {
    "1": "BOOKING-6841",
    "2": "Ada"
  }
}

Template use case: authentication or OTP

Use an approved authentication template when the merchant account, destination and current WhatsApp rules support it. Generate and verify codes server-side; do not place reusable secrets in template variables.

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HX99999999999999999999999999999999",
  "content_variables": {
    "1": "482731"
  }
}

Template use case: payment request

Payment templates are region-, account- and provider-dependent. Use them only where the merchant has the required payment configuration and Meta/WhatsApp approval. Ozibus does not create payment credentials from this send payload.

{
  "type": "template",
  "to": "+61412345678",
  "content_sid": "HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "content_variables": {
    "1": "INV-1842",
    "2": "49.00",
    "3": "AUD"
  }
}

Queue a message

Add use_queue: true to any supported direct or template payload when asynchronous processing is preferred.

{
  "type": "text",
  "to": "+61412345678",
  "message": "We have received your request and will update you shortly.",
  "use_queue": true
}

Successful direct-send response

{
  "response_code": 0,
  "response_message": "WhatsApp message accepted by Twilio.",
  "data": {
    "message_id": 1842,
    "provider_message_id": "SM0123456789abcdef0123456789abcdef",
    "status": "accepted"
  }
}

Accepted means the upstream provider accepted the submission. It does not mean the recipient received or read the message. Final delivery state is updated through provider status callbacks.

Successful queued response

{
  "response_code": 0,
  "response_message": "WhatsApp message queued successfully.",
  "data": {
    "message_id": 1842,
    "queue_id": 731
  }
}

Validation error response

{
  "response_code": 20,
  "response_message": "A publicly accessible HTTP or HTTPS media URL is required."
}

Other validation failures include an invalid merchant secret key, a source address outside the merchant allowlist, an invalid E.164 recipient, an empty message, an unsupported direct type or an invalid Content SID.

Media requirements

• Use a stable public HTTP or HTTPS URL. HTTPS is strongly recommended.
• The provider must be able to retrieve the URL without a login, cookie, browser session or private-network route.
• Return the correct media Content-Type and a provider-supported format.
• Keep the file within the current WhatsApp and provider size limits. These limits can vary by media type and provider capability.
• Do not use a short-lived signed URL that may expire before the queued message is processed.

Template and conversation rules

• Obtain and retain the recipient opt-in required by WhatsApp and applicable law before initiating messages.
• Use approved templates when required outside the customer-service window.
• Do not change approved template meaning through misleading variables.
• Honour block, stop, unsubscribe and other opt-out requests promptly.
• Template approval, quality status, messaging limits and feature availability are controlled by Meta/WhatsApp and the configured provider account.

Retry and delivery guidance

The current request body has no caller-supplied idempotency key. A blind retry after an uncertain network result can therefore produce a duplicate message. Record the Ozibus message_id, inspect the response and delivery state, and retry only when the failure is known to be safe.

API acceptance does not guarantee delivery, opening or reading. Provider filtering, template status, recipient blocking, sender quality, account limits, destination restrictions and outages may affect delivery.