# WATI API Reference

WATI API for WhatsApp business messaging. Base URL depends on the tenant's `api_endpoint` (e.g. `https://live-mt-server.wati.io`).

Full docs: https://docs.wati.io/reference/introduction

## Authentication

All requests require `Authorization: Bearer <token>` header. The bearer token is obtained when creating a WATI connection via `create_integration_auth(platform="wati", bearer_token=..., api_endpoint=...)`.

## Contacts

### List Contacts

```
GET /api/ext/v3/contacts?page_number=1&page_size=20
```

Response:
```json
{
  "contact_list": [
    {
      "id": "507f1f77bcf86cd799439011",
      "wa_id": "1234567890",
      "name": "John Doe",
      "phone": "+1234567890",
      "contact_status": "active",
      "source": "manual",
      "opted_in": true,
      "allow_broadcast": true,
      "teams": ["Team A"],
      "custom_params": [{"name": "city", "value": "New York"}],
      "channel_type": "whatsapp"
    }
  ],
  "page_number": 1,
  "page_size": 20
}
```

### Add Contact

```
POST /api/ext/v3/contacts
Content-Type: application/json

{
  "whatsapp_number": "1234567890",
  "name": "John Doe",
  "custom_params": [
    {"name": "age", "value": "30"},
    {"name": "city", "value": "New York"}
  ]
}
```

Required fields: `whatsapp_number`, `name`.

### Update Contacts (Batch)

```
PUT /api/ext/v3/contacts
Content-Type: application/json

{
  "contacts": [
    {
      "target": "507f1f77bcf86cd799439011",
      "customParams": [{"name": "city", "value": "London"}]
    }
  ]
}
```

`target` can be: ContactId, PhoneNumber, or `Channel:PhoneNumber` format.

### Get Contact Detail

```
GET /api/ext/v3/contacts/{contact_id}
```

## Conversations

### Get Messages

```
GET /api/ext/v3/conversations/{target}/messages?page_number=1&page_size=20
```

`target` can be:
- **ConversationId** — unique conversation ID
- **PhoneNumber** — e.g. `14155552671`
- **Channel:PhoneNumber** — e.g. `MyChannel:14155552671`

Response:
```json
{
  "message_list": [
    {
      "id": "507f1f77bcf86cd799439011",
      "text": "Hello!",
      "type": "text",
      "timestamp": "2026-01-06T02:50:13Z",
      "owner": true,
      "status": "delivered",
      "operator_name": "John Doe",
      "conversation_id": "685bd235e6119686e693a093",
      "event_type": "message"
    }
  ],
  "page_number": 1,
  "page_size": 20
}
```

### Send Text Message

```
POST /api/ext/v3/conversations/{target}/messages/text
Content-Type: application/json

{
  "text": "Hello, how can I help you?"
}
```

### Send File Message (via URL)

```
POST /api/ext/v3/conversations/{target}/messages/file/url
Content-Type: application/json

{
  "url": "https://example.com/document.pdf",
  "caption": "Here is your document"
}
```

### Send Interactive Message

```
POST /api/ext/v3/conversations/{target}/messages/interactive
```

### Assign Operator

```
PUT /api/ext/v3/conversations/{target}/assign
Content-Type: application/json

{
  "assigned_id": "<operator_id>"
}
```

### Update Conversation Status

```
PUT /api/ext/v3/conversations/{target}/status
Content-Type: application/json

{
  "status": "resolved"
}
```

## Template Messages (V1)

### Send Template Message

```
POST /api/v1/sendTemplateMessage?whatsappNumber=85264318721
Content-Type: application/json

{
  "template_name": "new_chat_v1",
  "broadcast_name": "my_broadcast",
  "channel_number": "85264318721",
  "parameters": [
    {"name": "name", "value": "Matthew"}
  ]
}
```

Required fields: `template_name`, `broadcast_name`, `channel_number`, `parameters`.

### Get Templates

```
GET /api/v1/getMessageTemplates
```

## Campaigns (V3)

```
GET /api/ext/v3/campaigns?page_number=1&page_size=20
GET /api/ext/v3/campaigns/{campaign_id}
GET /api/ext/v3/campaigns/{campaign_id}/recipients
GET /api/ext/v3/campaigns/{campaign_id}/overview
```

## Chatbots (V3, Pro Plan)

```
GET /api/ext/v3/chatbots
POST /api/ext/v3/chatbots/start
```

## Error Handling

| Code | Meaning |
|------|---------|
| 400 | Invalid request — check required fields |
| 401 | Unauthorized — invalid or expired bearer token |
| 403 | Forbidden — insufficient permissions |
| 429 | Rate limit exceeded |
| 500 | Server error — retry |

Error response format:
```json
{"code": 400, "message": "Description", "timestamp": "2026-01-01T00:00:00Z"}
```

## Astra ↔ WATI Mapping

| Astra Tool | WATI Equivalent |
|------------|-----------------|
| `get_contacts_and_leads` | `GET /api/ext/v3/contacts` |
| `get_contact` | `GET /api/ext/v3/contacts/{id}` |
| `list_conversations` | N/A (Astra gateway conversations) |
| `get_conversation_messages` | `GET /api/ext/v3/conversations/{target}/messages` |

WATI-specific operations not available through Astra gateway:
- `POST /api/ext/v3/contacts` — add contact directly
- `PUT /api/ext/v3/contacts` — batch update contacts
- `POST /api/ext/v3/conversations/{target}/messages/text` — send message
- `POST /api/v1/sendTemplateMessage` — send template message
- `GET /api/ext/v3/campaigns` — campaign management
