# MEATBALL Gateway - WhatsApp API Documentation

## Overview
MEATBALL Gateway is a powerful WhatsApp API service that enables businesses to send and receive WhatsApp messages programmatically. Unlike other APIs, MEATBALL Gateway allows you to start conversations with customers without waiting for them to message you first.

## Base URL
- Production: https://api.meatball.social

## Authentication
All API requests require authentication using Bearer tokens in the Authorization header:
```
Authorization: Bearer YOUR_API_KEY
```

API keys follow the format: `mg_live_sk_[64-character-hex-string]`

## API Endpoints

### 1. Health Check
**GET** `/health`
- **Description**: Check if the API is running
- **Authentication**: None required
- **Response**: `{"ok": true}`

### 2. Send WhatsApp Message
**POST** `/send_message`
- **Description**: Send a WhatsApp message to any phone number
- **Authentication**: Required (Bearer token)
- **Request Body**:
```json
{
  "from_phone": "+15551234567",
  "to_phone": "+15559876543", 
  "message": "Hello from MEATBALL Gateway!"
}
```
- **Response**:
```json
{
  "message_id": "msg_123456789",
  "created_at": "2024-01-15T10:30:00Z",
  "from_phone": "+15551234567",
  "to_phone": "+15559876543",
  "message": "Hello from MEATBALL Gateway!",
  "status": "sent"
}
```

## Webhooks

MEATBALL Gateway supports webhooks for receiving incoming messages. When someone sends a message to your WhatsApp number, the webhook will be triggered.

### Webhook Events
- **message**: Triggered when a new message is received

### Webhook Payload Format
```json
{
  "message_id": "msg_123456789",
  "created_at": "2024-01-15T10:30:00Z",
  "from_phone": "+15559876543",
  "to_phone": "+15551234567",
  "message": "Hello! I need help with my order.",
  "status": "received",
  "webhook_id": "webhook_123",
  "event": "message"
}
```

### Webhook Configuration
Webhooks are configured through the MEATBALL Gateway dashboard:
1. Navigate to the Webhooks section
2. Create a new webhook with your endpoint URL
3. Select the event types you want to receive
4. The webhook will be triggered for incoming messages

## Key Features

### 1. Start Conversations
Unlike other WhatsApp APIs, MEATBALL Gateway allows you to initiate conversations with customers. You don't need to wait for them to message you first.

### 2. Lightning Fast Delivery
Sub-second message delivery with 99.9% uptime guarantee. Faster than Twilio and other competitors.

### 3. AI-Friendly Messages
Support for longer text messages perfect for AI agents and automated systems.

### 4. Group Messaging
Group messaging support coming soon - send messages to multiple recipients simultaneously.

### 5. Enterprise Security
Bank-level security with end-to-end encryption and compliance with international standards.

## Usage Examples

### cURL Example
```bash
curl -X POST https://api.meatball.social/send_message \
  -H "Authorization: Bearer mg_live_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from_phone": "+15551234567",
    "to_phone": "+15559876543",
    "message": "Hello from MEATBALL Gateway!"
  }'
```

### JavaScript Example
```javascript
const response = await fetch('https://api.meatball.social/send_message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mg_live_sk_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from_phone: '+15551234567',
    to_phone: '+15559876543',
    message: 'Hello from MEATBALL Gateway!'
  })
});

const data = await response.json();
console.log(data);
```

### Python Example
```python
import requests

url = 'https://api.meatball.social/send_message'
headers = {
    'Authorization': 'Bearer mg_live_sk_your_api_key_here',
    'Content-Type': 'application/json'
}
data = {
    'from_phone': '+15551234567',
    'to_phone': '+15559876543',
    'message': 'Hello from MEATBALL Gateway!'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

## Error Handling

### Common HTTP Status Codes
- **200**: Success
- **400**: Bad Request - Invalid request body or parameters
- **401**: Unauthorized - Invalid or missing API key
- **403**: Forbidden - Phone number not associated with your account
- **500**: Internal Server Error - Server-side error

### Error Response Format
```json
{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": "Additional error details if available"
}
```

## Rate Limits
- No rate limits currently enforced
- Fair usage policy applies
- Contact support for high-volume usage

## Support
- **Email**: tech@meatball.social
- **Documentation**: https://meatball.social/api/docs
- **Website**: https://meatball.social

## Getting Started
1. Sign up at https://meatball.social
2. Contact support to get your WhatsApp phone number assigned
3. Create your first API key in the dashboard
4. Configure webhooks for incoming messages
5. Start sending messages!

## SDKs
Official SDKs for popular programming languages are coming soon:
- Node.js
- Python
- PHP
- Go
- Ruby
- Java

## Changelog
- v0.1.0: Initial release with basic messaging functionality
- Webhook support for incoming messages
- Multi-user phone number management
- API key authentication system

---
Generated by MEATBALL Gateway API
Last updated: 2025-09-24