Actions

The ballerinax/whatsapp.business package exposes the following client:

Client	Purpose
Client	Send text, media, location, contact, and template messages, and manage media on WhatsApp Business Cloud.

Client

Configuration

Field	Type	Default	Description
auth	http:BearerTokenConfig	Required	Bearer-token authentication using a system-user or temporary access token.
apiVersion	string	"v23.0"	The Meta Graph API version path segment used for every request.
httpVersion	http:HttpVersion	http:HTTP_2_0	The HTTP version understood by the client.
timeout	decimal	30	The maximum time to wait (in seconds) for a response.
forwarded	string	"disable"	The choice of setting forwarded/x-forwarded header.
poolConfig	http:PoolConfiguration	()	Configurations associated with request pooling.
cache	http:CacheConfig		HTTP caching-related configurations.
compression	http:Compression	http:COMPRESSION_AUTO	The way of handling the accept-encoding header.
circuitBreaker	http:CircuitBreakerConfig	()	Configurations associated with the behavior of the circuit breaker.

Initializing the client

import ballerinax/whatsapp.business as business;

configurable string accessToken = ?;
configurable string phoneNumberId = ?;

business:Client whatsappClient = check new ({auth: {token: accessToken}});

Operations

Messaging

sendMessage

Sends a text, image, audio, video, document, location, or contact message.

Parameters:

Name	Type	Required	Description
phoneNumberId	string	Yes	The business phone number ID to send from.
payload	Message	Yes	The message to send. A union of TextMessage, ImageMessage, AudioMessage, VideoMessage, DocumentMessage, LocationMessage, and ContactMessage.

Returns: MessageResponsePayload|Error

Sample code:

business:TextMessage message = {
    to: "1XXXXXXXXXX",
    text: {body: "Hello from Ballerina!"}
};

business:MessageResponsePayload response = check whatsappClient->sendMessage(phoneNumberId, message);

Sample response:

{
    "messaging_product": "whatsapp",
    "contacts": [{"input": "1XXXXXXXXXX", "wa_id": "1XXXXXXXXXX"}],
    "messages": [{"id": "wamid.HBgLMTX..."}]
}

sendTemplateMessage

Sends a pre-approved message template.

Parameters:

Name	Type	Required	Description
phoneNumberId	string	Yes	The business phone number ID to send from.
payload	TemplateMessage	Yes	The template name, language, and component parameters.

Returns: MessageResponsePayload|Error

Sample code:

business:MessageResponsePayload response = check whatsappClient->sendTemplateMessage(phoneNumberId, {
    to: "1XXXXXXXXXX",
    template: {name: "hello_world", language: {code: "en_US"}}
});

Sample response:

{
    "messaging_product": "whatsapp",
    "contacts": [{"input": "1XXXXXXXXXX", "wa_id": "1XXXXXXXXXX"}],
    "messages": [{"id": "wamid.HBgLMTX..."}]
}

Media

uploadMedia

Uploads media to be referenced by ID in a subsequent message.

Parameters:

Name	Type	Required	Description
phoneNumberId	string	Yes	The business phone number ID to upload against.
payload	MediaUploadRequest	Yes	The file content, file name, and MIME type.

Returns: MediaUploadResponse|Error

Sample code:

import ballerina/io;

business:MediaUploadResponse uploaded = check whatsappClient->uploadMedia(phoneNumberId, {
    fileContent: check io:fileReadBytes("image.jpg"),
    fileName: "image.jpg",
    mimeType: "image/jpeg"
});

Sample response:

{
    "id": "1234567890"
}

retrieveMediaUrl

Retrieves the temporary download URL for a media object.

Parameters:

Name	Type	Required	Description
mediaId	string	Yes	The media object ID.

Returns: MediaUrlResponse|Error

Sample code:

business:MediaUrlResponse mediaInfo = check whatsappClient->retrieveMediaUrl(mediaId);

Sample response:

{
    "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/...",
    "id": "1234567890",
    "mime_type": "image/jpeg",
    "sha256": "...",
    "file_size": 12345
}

downloadMedia

Downloads a media object's bytes given its media ID.

Parameters:

Name	Type	Required	Description
mediaId	string	Yes	The media object ID.

Returns: byte[]|Error

Sample code:

byte[] mediaBytes = check whatsappClient->downloadMedia(mediaId);

downloadMediaFromUrl

Downloads a media object's bytes from its signed download URL (a MediaUrlResponse.url, as returned by retrieveMediaUrl), without re-fetching the media's metadata. Use this when you already have the URL (for example, after calling retrieveMediaUrl yourself to inspect the media's MIME type or size before deciding whether to download it), to avoid the redundant retrieveMediaUrl call that downloadMedia makes internally.

Parameters:

Name	Type	Required	Description
url	string	Yes	The signed download URL from a MediaUrlResponse.url.

Returns: byte[]|Error

Sample code:

business:MediaUrlResponse mediaInfo = check whatsappClient->retrieveMediaUrl(mediaId);
byte[] mediaBytes = check whatsappClient->downloadMediaFromUrl(mediaInfo.url);

deleteMedia

Deletes a previously uploaded media object.

Parameters:

Name	Type	Required	Description
mediaId	string	Yes	The media object ID.

Returns: MediaDeleteResponse|Error

Sample code:

business:MediaDeleteResponse deleted = check whatsappClient->deleteMedia(mediaId);

Sample response:

{
    "success": true
}

What's next

• Trigger Reference: react to inbound messages and status updates using the webhook listener.
• Example: complete example integrations for the WhatsApp Business connector and trigger.
• Setup Guide: create a Meta app and obtain credentials.