WhatsApp Business connectors

Send template messages, text, media and manage conversations via the WhatsApp Business API from Bonita processes.

The Bonita WhatsApp Business Connectors are available for Bonita 10.2 Community (2024.3) version and above.

Overview

The WhatsApp Business connector allows Bonita processes to interact with the WhatsApp Business Cloud API. It provides six operations:

  • Send Template — Send a pre-approved WhatsApp template message

  • Send Text — Send a free-form text message within the 24-hour session window

  • Send Media — Send an image, document, audio, or video

  • Get Status — Retrieve the delivery status of a sent message

  • List Conversations — Retrieve conversation analytics for a WhatsApp Business Account

  • Get Messages — Retrieve messages exchanged with a contact

Getting started

  1. Download the connector JAR from the GitHub releases page

  2. In Bonita Studio, go to Development > Connector > Import connector…​

  3. Select the downloaded .jar file

  4. The connector is now available in the Messaging category

Connection configuration

All operations share these connection parameters:

Parameter Required Description Default

Token

Yes

Permanent System User Token from Meta Business Manager

Resolved from env var WHATSAPP_TOKEN if not set

Phone Number ID

Yes

WhatsApp Business phone number ID

Base URL

No

WhatsApp Cloud API base URL

https://graph.facebook.com/v21.0

Connect Timeout

No

Connection timeout in milliseconds

10000

Read Timeout

No

Read timeout in milliseconds

30000

Send Template

Sends a pre-approved WhatsApp template message. Template messages can be sent outside the 24-hour session window.

Parameter Required Description Default

To

Yes

Recipient phone number in international format (e.g., +34612345678)

Template Name

Yes

Name of the approved template

Language Code

Yes

Template language code (e.g., en_US, es)

en_US

Header Parameters

No

JSON array of header parameter values

Body Parameters

No

JSON array of body parameter values
Parameter Type Description

success

Boolean

Whether the operation succeeded

messageId

String

The WhatsApp message ID

errorMessage

String

Error description if failed

Send Text

Sends a free-form text message. Only available within the 24-hour session window after the customer initiates contact.

Parameter Required Description Default

To

Yes

Recipient phone number

Body

Yes

Message text content

Preview URL

No

Enable URL preview in the message

false
Parameter Type Description

success

Boolean

Whether the operation succeeded

messageId

String

The WhatsApp message ID

errorMessage

String

Error description if failed

Send Media

Sends a media file (image, document, audio, video) to a contact.

Parameter Required Description Default

To

Yes

Recipient phone number

Media URL

Yes

Public URL of the media file

Media Type

Yes

Type of media: image, document, audio, video

Caption

No

Media caption (images and documents only)
Parameter Type Description

success

Boolean

Whether the operation succeeded

messageId

String

The WhatsApp message ID

errorMessage

String

Error description if failed

Get Status

Retrieves the delivery status of a previously sent message.

Parameter Required Description Default

Message ID

Yes

The WhatsApp message ID to check
Parameter Type Description

success

Boolean

Whether the operation succeeded

status

String

Delivery status: sent, delivered, read, failed

timestamp

String

Timestamp of the status update

errorMessage

String

Error description if failed

List Conversations

Retrieves conversation analytics for a WhatsApp Business Account.

Parameter Required Description Default

WABA ID

Yes

WhatsApp Business Account ID

Start Date

No

Start date for analytics (ISO format)

End Date

No

End date for analytics (ISO format)
Parameter Type Description

success

Boolean

Whether the operation succeeded

conversations

String

JSON array of conversation analytics

totalCount

Integer

Total number of conversations

errorMessage

String

Error description if failed

Get Messages

Retrieves messages exchanged with contacts.

Parameter Required Description Default

Phone Number ID

Yes

Phone number ID to retrieve messages for

Since

No

Retrieve messages since this timestamp
Parameter Type Description

success

Boolean

Whether the operation succeeded

messages

String

JSON array of messages

totalCount

Integer

Total number of messages

errorMessage

String

Error description if failed

Error handling

HTTP Code Behavior

400 Bad Request

Immediate failure — check parameters

401 Unauthorized

Immediate failure — check token

403 Forbidden

Immediate failure — insufficient permissions

429 Rate Limited

Automatic retry with backoff

500+ Server Error

Automatic retry with exponential backoff

Use cases

Send appointment reminders

Use Send Template to send a pre-approved reminder 24 hours before an appointment:

{
  "token": "${WHATSAPP_TOKEN}",
  "phoneNumberId": "123456789012345",
  "to": "+34612345678",
  "templateName": "appointment_reminder",
  "languageCode": "es",
  "bodyParameters": ["Juan García", "25/03/2026", "10:00", "Dr. López"]
}
Template messages must be pre-approved by Meta. They are the only way to initiate conversations outside the 24-hour session window.

Send order confirmations

Use Send Text within a customer service conversation:

{
  "token": "${WHATSAPP_TOKEN}",
  "phoneNumberId": "123456789012345",
  "to": "+34612345678",
  "body": "Your order #12345 has been confirmed. Estimated delivery: March 28, 2026. Track at: https://example.com/track/12345",
  "previewUrl": true
}

Send invoices as PDF

Use Send Media to share a document:

{
  "token": "${WHATSAPP_TOKEN}",
  "phoneNumberId": "123456789012345",
  "to": "+34612345678",
  "mediaUrl": "https://your-server.com/invoices/INV-2026-001.pdf",
  "mediaType": "document",
  "caption": "Invoice INV-2026-001 - Total: 1,250.00€"
}

Monitor message delivery

Use Get Status to verify a critical notification was delivered:

{
  "token": "${WHATSAPP_TOKEN}",
  "phoneNumberId": "123456789012345",
  "messageId": "wamid.HBgLMzQ2MTIzNDU2NzgVAgASGBQzRUI..."
}

Response:

{
  "success": true,
  "status": "delivered",
  "timestamp": "2026-03-25T10:30:00Z"
}

Configuration tips

Getting a WhatsApp Business Token

  1. Go to Meta Business Manager

  2. Navigate to System Users > Create a system user

  3. Generate a Permanent Token with whatsapp_business_messaging permission

  4. Store it securely as a Bonita parameter

Template message parameters

Template parameters are positional arrays. If your template has:

Hello {{1}}, your appointment with {{2}} is on {{3}} at {{4}}.

Then bodyParameters should be: ["Juan", "Dr. López", "25/03/2026", "10:00"]

Phone number format

Always use international format with country code:

  • Spain: +34612345678

  • France: +33612345678

  • US: +12125551234

24-hour session window

  • Template messages can be sent anytime (pre-approved by Meta)

  • Text and media messages can only be sent within 24 hours after the customer’s last message

  • If the window expires, use a template message to re-engage

Source code

bonita-connector-whatsapp on GitHub