WhatsApp Business: Send Messages, Templates, and Media via Managed OAuth Gateway

16,709 downloads, 38 stars. The WhatsApp Business skill by @byungkyu gives your AI agent access to the WhatsApp Business API through Maton's managed OAuth gateway. Send messages, manage conversation templates, and handle rich media — without touching Meta's developer console directly.

If you've ever tried to set up WhatsApp Business API yourself, you know the pain: business verification, phone number provisioning, webhook configuration, token refresh. Maton handles all of that. You get one API key and a consistent interface.

The Problem It Solves

The official WhatsApp Business API requires a Meta Business account, phone number verification, a Facebook app, webhook endpoints, and token management. That's a significant setup burden before you send a single message.

The WhatsApp Business skill routes everything through Maton's gateway at https://gateway.maton.ai/whatsapp-business/. Maton manages the OAuth lifecycle, token refresh, and connection to graph.facebook.com. Your agent uses a single MATON_API_KEY — nothing else.

Setup

# Set your Maton API key
export MATON_API_KEY="YOUR_API_KEY"

Get your API key at maton.ai/settings. All requests use this header:

Authorization: Bearer $MATON_API_KEY

The base URL for all API calls:

https://gateway.maton.ai/whatsapp-business/{native-api-path}

Where {native-api-path} is the standard WhatsApp Business API path (e.g., v21.0/PHONE_NUMBER_ID/messages).

Sending Messages

Text Message

import urllib.request, os, json
 
data = json.dumps({
    'messaging_product': 'whatsapp',
    'to': '1234567890',
    'type': 'text',
    'text': {'body': 'Hello from WhatsApp Business!', 'preview_url': True}
}).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.load(urllib.request.urlopen(req)))

Template Message

Templates are pre-approved message formats required for outbound messages to users who haven't messaged you first:

data = json.dumps({
    'messaging_product': 'whatsapp',
    'to': '1234567890',
    'type': 'template',
    'template': {
        'name': 'hello_world',
        'language': {'code': 'en_US'},
        'components': [
            {'type': 'body', 'parameters': [{'type': 'text', 'text': 'John'}]}
        ]
    }
}).encode()

Media Messages

Image:

{'type': 'image', 'image': {'link': 'https://example.com/image.jpg', 'caption': 'Caption text'}}

Document (with filename):

{'type': 'document', 'document': {'link': 'https://example.com/file.pdf', 'caption': 'Here is the report', 'filename': 'report.pdf'}}

Audio:

{'type': 'audio', 'audio': {'link': 'https://example.com/audio.mp3'}}

Video:

{'type': 'video', 'video': {'link': 'https://example.com/video.mp4', 'caption': 'Watch this'}}

Location:

{
    'type': 'location',
    'location': {
        'latitude': 37.7749,
        'longitude': -122.4194,
        'name': 'San Francisco',
        'address': 'San Francisco, CA, USA'
    }
}

Contact card:

{
    'type': 'contacts',
    'contacts': [{
        'name': {'formatted_name': 'John Doe', 'first_name': 'John', 'last_name': 'Doe'},
        'phones': [{'phone': '+1234567890', 'type': 'MOBILE'}]
    }]
}

Connection Management

Maton manages the OAuth connection to WhatsApp Business. Connections are managed via https://ctrl.maton.ai.

List Active Connections

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"]}')

Create a Connection

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')
response = json.load(urllib.request.urlopen(req))
# Open response['connection']['url'] in a browser to complete OAuth

The response includes a url field — open it in a browser to authorize the WhatsApp Business account.

Multiple Connections

If you have multiple WhatsApp Business numbers, specify which to use:

req.add_header('Maton-Connection', 'connection_id_here')

Without this header, Maton uses the default (oldest active) connection.

Real-World Use Cases

Customer notification pipeline — Agent monitors order status changes and sends template messages to customers when their order ships, arrives, or needs attention.

Support ticket updates — When a support ticket is resolved, the agent sends a summary and resolution via WhatsApp.

Lead follow-up — CRM-integrated agent sends personalized template messages to new leads within minutes of sign-up.

Document delivery — Send invoices, reports, or contracts as PDF documents directly to a contact's WhatsApp.

Location sharing — Agent shares meeting location or store address as a native WhatsApp location pin.

Internal team notifications — Route alerts from monitoring systems to a WhatsApp group via the Business API.

Comparison

The key distinction: WhatsApp Business uses the official Meta Business API and requires a business account. WaCLI uses personal WhatsApp accounts via the whatsmeow library — different use case entirely.

Practical Tips

Use templates for outbound messages. WhatsApp Business API requires pre-approved templates for messages to users who haven't messaged you first in the last 24 hours. Keep your template library current.

Store the phone_number_id. Every message needs your WhatsApp Business phone_number_id in the URL. Retrieve it from your Maton connection details and store it as an environment variable.

Validate phone numbers. Numbers must be in international format without + (e.g., 14155238886 not +1 (415) 523-8886). Invalid formats will return an error silently in some cases.

Use Maton-Connection explicitly if you manage multiple numbers. Relying on the default connection works but is fragile if connection order changes.

Considerations

• Maton dependency — You're routing through a third-party gateway. Maton's uptime and pricing affect your workflow reliability and cost.
• Template approval time — WhatsApp template approval can take 24-72 hours. Plan template creation well ahead of launch.
• Recipient opt-in — WhatsApp Business API requires that recipients have opted in to receive messages from your business for template messages. No opt-in = policy violation.
• Phone number provisioning — Maton manages this, but you still need a phone number not already registered with WhatsApp.
• Rate limits — WhatsApp imposes per-number rate limits that increase as you build a good quality rating. New numbers start with lower limits.

The Bigger Picture

WhatsApp has 2+ billion users, and most businesses interact with customers through it in markets where it's the dominant messaging platform. The WhatsApp Business API provides the right tools for that — templates, media, conversations — but the barrier to entry has always been high.

The WhatsApp Business skill, via Maton's gateway, makes it an agent capability rather than an infrastructure project. 16,000+ downloads suggests a real workflow gap being filled: agents that need to reach people where they actually are.

View the skill on ClawHub: whatsapp-business