whatsapp-businessWhatsApp Business API integration with managed OAuth. Send messages, manage templates, and handle conversations. Use this skill when users want to interact with WhatsApp Business. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
Install via ClawdBot CLI:
clawdbot install byungkyu/whatsapp-businessAccess the WhatsApp Business API with managed OAuth authentication. Send messages, manage message templates, handle media, and interact with customers through WhatsApp.
# Send a text message
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'messaging_product': 'whatsapp', 'to': '1234567890', 'type': 'text', 'text': {'body': 'Hello from WhatsApp Business!'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFhttps://gateway.maton.ai/whatsapp-business/{native-api-path}Replace {native-api-path} with the actual WhatsApp Business API endpoint path. The gateway proxies requests to graph.facebook.com and automatically injects your OAuth token.
All requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEYEnvironment Variable: Set your API key as MATON_API_KEY:
export MATON_API_KEY="YOUR_API_KEY"Manage your WhatsApp Business OAuth connections at https://ctrl.maton.ai.
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=whatsapp-business&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFpython <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'whatsapp-business'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFpython <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFResponse:
{
"connection": {
"connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
"status": "ACTIVE",
"creation_time": "2025-12-08T07:20:53.488460Z",
"last_updated_time": "2026-01-31T20:03:32.593153Z",
"url": "https://connect.maton.ai/?session_token=...",
"app": "whatsapp-business",
"metadata": {}
}
}Open the returned url in a browser to complete OAuth authorization.
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFIf you have multiple WhatsApp Business connections, specify which one to use with the Maton-Connection header:
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'messaging_product': 'whatsapp', 'to': '1234567890', 'type': 'text', 'text': {'body': 'Hello!'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFIf omitted, the gateway uses the default (oldest) active connection.
POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "1234567890",
"type": "text",
"text": {
"preview_url": true,
"body": "Hello! Check out https://example.com"
}
}POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "1234567890",
"type": "template",
"template": {
"name": "hello_world",
"language": {
"code": "en_US"
},
"components": [
{
"type": "body",
"parameters": [
{"type": "text", "text": "John"}
]
}
]
}
}POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "1234567890",
"type": "image",
"image": {
"link": "https://example.com/image.jpg",
"caption": "Check out this image!"
}
}POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "1234567890",
"type": "document",
"document": {
"link": "https://example.com/document.pdf",
"caption": "Here's the document",
"filename": "report.pdf"
}
}POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "1234567890",
"type": "video",
"video": {
"link": "https://example.com/video.mp4",
"caption": "Watch this video"
}
}POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "1234567890",
"type": "audio",
"audio": {
"link": "https://example.com/audio.mp3"
}
}POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "1234567890",
"type": "location",
"location": {
"latitude": 37.7749,
"longitude": -122.4194,
"name": "San Francisco",
"address": "San Francisco, CA, USA"
}
}POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "1234567890",
"type": "contacts",
"contacts": [
{
"name": {
"formatted_name": "John Doe",
"first_name": "John",
"last_name": "Doe"
},
"phones": [
{"phone": "+1234567890", "type": "MOBILE"}
]
}
]
}POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "1234567890",
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "Would you like to proceed?"
},
"action": {
"buttons": [
{"type": "reply", "reply": {"id": "yes", "title": "Yes"}},
{"type": "reply", "reply": {"id": "no", "title": "No"}}
]
}
}
}POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "1234567890",
"type": "interactive",
"interactive": {
"type": "list",
"header": {"type": "text", "text": "Select an option"},
"body": {"text": "Choose from the list below"},
"action": {
"button": "View Options",
"sections": [
{
"title": "Products",
"rows": [
{"id": "prod1", "title": "Product 1", "description": "First product"},
{"id": "prod2", "title": "Product 2", "description": "Second product"}
]
}
]
}
}
}POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json
{
"messaging_product": "whatsapp",
"status": "read",
"message_id": "wamid.xxxxx"
}POST /whatsapp-business/v21.0/{phone_number_id}/media
Content-Type: multipart/form-data
file=@/path/to/file.jpg
type=image/jpeg
messaging_product=whatsappGET /whatsapp-business/v21.0/{media_id}DELETE /whatsapp-business/v21.0/{media_id}GET /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templatesQuery parameters:
limit - Number of templates to returnstatus - Filter by status: APPROVED, PENDING, REJECTEDPOST /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templates
Content-Type: application/json
{
"name": "order_confirmation",
"language": "en_US",
"category": "UTILITY",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "Order Confirmation"
},
{
"type": "BODY",
"text": "Hi {{1}}, your order #{{2}} has been confirmed!"
},
{
"type": "FOOTER",
"text": "Thank you for your purchase"
}
]
}Template categories: AUTHENTICATION, MARKETING, UTILITY
DELETE /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templates?name=template_nameGET /whatsapp-business/v21.0/{phone_number_id}GET /whatsapp-business/v21.0/{whatsapp_business_account_id}/phone_numbersGET /whatsapp-business/v21.0/{phone_number_id}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,verticalPOST /whatsapp-business/v21.0/{phone_number_id}/whatsapp_business_profile
Content-Type: application/json
{
"messaging_product": "whatsapp",
"about": "Your trusted partner",
"address": "123 Business St",
"description": "We provide excellent services",
"email": "contact@example.com",
"websites": ["https://example.com"],
"vertical": "RETAIL"
}const headers = {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
'Content-Type': 'application/json'
};
// Send text message
await fetch(
'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',
{
method: 'POST',
headers,
body: JSON.stringify({
messaging_product: 'whatsapp',
to: '1234567890',
type: 'text',
text: { body: 'Hello from WhatsApp!' }
})
}
);
// Send template message
await fetch(
'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',
{
method: 'POST',
headers,
body: JSON.stringify({
messaging_product: 'whatsapp',
to: '1234567890',
type: 'template',
template: {
name: 'hello_world',
language: { code: 'en_US' }
}
})
}
);import os
import requests
headers = {
'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
'Content-Type': 'application/json'
}
# Send text message
response = requests.post(
'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',
headers=headers,
json={
'messaging_product': 'whatsapp',
'to': '1234567890',
'type': 'text',
'text': {'body': 'Hello from WhatsApp!'}
}
)
# Send template message
response = requests.post(
'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',
headers=headers,
json={
'messaging_product': 'whatsapp',
'to': '1234567890',
'type': 'template',
'template': {
'name': 'hello_world',
'language': {'code': 'en_US'}
}
}
)+ or leading zeros (e.g., 1234567890)messaging_product must always be set to whatsappwamid) are used to track message status and repliesv21.0 is current; check Meta docs for latest versioncurl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsingjq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.| Status | Meaning |
|--------|---------|
| 400 | Missing WhatsApp Business connection or invalid request |
| 401 | Invalid or missing Maton API key |
| 404 | Phone number or resource not found |
| 429 | Rate limited (10 req/sec per account) |
| 4xx/5xx | Passthrough error from WhatsApp Business API |
Common error codes from WhatsApp:
131030 - Phone number not registered131031 - Message failed to send132000 - Template not found or not approved133010 - Phone number rate limit reachedMATON_API_KEY environment variable is set:echo $MATON_API_KEYpython <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFwhatsapp-business. For example:https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messageshttps://gateway.maton.ai/v21.0/PHONE_NUMBER_ID/messagesGenerated Mar 1, 2026
Businesses can automate responses to common customer inquiries, send order confirmations, and provide shipping updates via WhatsApp. This reduces response times and frees up human agents for complex issues, enhancing customer satisfaction and operational efficiency.
Healthcare clinics or service providers can send automated appointment reminders, confirmations, and follow-up messages to patients or clients. This minimizes no-shows, improves scheduling accuracy, and streamlines communication, leading to better resource management.
Companies can send personalized marketing messages, promotional offers, and product updates to opted-in customers. This enables targeted outreach, increases engagement rates, and drives sales through direct communication on a widely used platform.
Logistics and delivery services can provide real-time updates on order status, delivery times, and pickup instructions via WhatsApp. This keeps customers informed, reduces support calls, and improves transparency throughout the delivery process.
Event organizers can send invitations, collect RSVPs, and share event details or changes through WhatsApp. This simplifies attendee management, increases participation rates, and ensures timely communication for conferences, workshops, or social gatherings.
Offer a subscription-based service where businesses pay a monthly or annual fee to access the WhatsApp Business API integration. Revenue is generated through tiered pricing based on message volume, features, or number of connections, providing predictable recurring income.
Charge customers based on usage, such as per message sent or per API call. This model appeals to businesses with fluctuating messaging needs, allowing them to scale costs with usage while generating revenue from high-volume senders.
Resell the WhatsApp Business skill as part of a larger platform or service, branding it under your own name. Revenue comes from licensing fees or markups on the underlying service, enabling agencies or developers to offer integrated solutions to their clients.
💬 Integration Tip
Start by setting up a single connection via the control panel to test authentication, then gradually implement message types like text and templates before handling media or multiple connections.
iMessage/SMS CLI for listing chats, history, watch, and sending.
Use when you need to control Discord from Clawdbot via the discord tool: send messages, react, post or upload stickers, upload emojis, run polls, manage threads/pins/search, fetch permissions or member/role/channel info, or handle moderation actions in Discord DMs or channels.
Use when you need to control Slack from Clawdbot via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.
Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI (not for normal user chats).
Build or update the BlueBubbles external channel plugin for Clawdbot (extension package, REST send/probe, webhook inbound).
OpenClaw skill for designing Telegram Bot API workflows and command-driven conversations using direct HTTPS requests (no SDKs).