WhatsApp Business

# WhatsApp Business

Access the WhatsApp Business API with managed OAuth authentication. Send messages, manage message templates, handle media, and interact with customers through WhatsApp.

## Quick Start

```bash
# 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))
EOF
```

## Base URL

```
https://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.

## Authentication

All requests require the Maton API key in the Authorization header:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your WhatsApp Business OAuth connections at `https://ctrl.maton.ai`.

### List Connections

```bash
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))
EOF
```

### Create Connection

```bash
python <<'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))
EOF
```

### Get Connection

```bash
python <<'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))
EOF
```

**Response:**
```json
{
 "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.

### Delete Connection

```bash
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))
EOF
```

### Specifying Connection

If you have multiple WhatsApp Business connections, specify which one to use with the `Maton-Connection` header:

```bash
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))
EOF
```

If omitted, the gateway uses the default (oldest) active connection.

## API Reference

### Messages

#### Send Text Message

```bash
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"
 }
}
```

#### Send Template Message

```bash
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"}
 ]
 }
 ]
 }
}
```

#### Send Image Message

```bash
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!"
 }
}
```

#### Send Document Message

```bash
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"
 }
}
```

#### Send Video Message

```bash
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"
 }
}
```

#### Send Audio Message

```bash
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"
 }
}
```

#### Send Location Message

```bash
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"
 }
}
```

#### Send Contact Message

```bash
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"}
 ]
 }
 ]
}
```

#### Send Interactive Button Message

```bash
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"}}
 ]
 }
 }
}
```

#### Send Interactive List Message

```bash
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"}
 ]
 }
 ]
 }
 }
}
```

#### Mark Message as Read

```bash
POST /whatsapp-business/v21.0/{phone_number_id}/messages
Content-Type: application/json

{
 "messaging_product": "whatsapp",
 "status": "read",
 "message_id": "wamid.xxxxx"
}
```

### Media

#### Upload Media

```bash
POST /whatsapp-business/v21.0/{phone_number_id}/media
Content-Type: multipart/form-data

file=@/path/to/file.jpg
type=image/jpeg
messaging_product=whatsapp
```

#### Get Media URL

```bash
GET /whatsapp-business/v21.0/{media_id}
```

#### Delete Media

```bash
DELETE /whatsapp-business/v21.0/{media_id}
```

### Message Templates

#### List Templates

```bash
GET /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templates
```

Query parameters:
- `limit` - Number of templates to return
- `status` - Filter by status: `APPROVED`, `PENDING`, `REJECTED`

#### Create Template

```bash
POST /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 Template

```bash
DELETE /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templates?name=template_name
```

### Phone Numbers

#### Get Phone Number

```bash
GET /whatsapp-business/v21.0/{phone_number_id}
```

#### List Phone Numbers

```bash
GET /whatsapp-business/v21.0/{whatsapp_business_account_id}/phone_numbers
```

### Business Profile

#### Get Business Profile

```bash
GET /whatsapp-business/v21.0/{phone_number_id}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical
```

#### Update Business Profile

```bash
POST /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": "[email protected]",
 "websites": ["https://example.com"],
 "vertical": "RETAIL"
}
```

## Code Examples

### JavaScript

```javascript
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' }
 }
 })
 }
);
```

### Python

```python
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://g

[Truncated for public library preview]