API Reference

The WazBot REST API allows you to programmatically manage agents, send messages, retrieve conversations, and integrate WazBot into your existing systems.

Base URL

https://api.wazbot.io/v1

Authentication

All API requests require a Bearer token in the Authorization header:

Authentication Header

http

Authorization: Bearer YOUR_API_KEY

Generate API keys in Settings → API Keys. Each key can be scoped to specific permissions (read, write, admin).

Security

Never expose API keys in client-side code. Always make API calls from your backend server.

Rate Limits

Plan	Requests/min	Requests/day
Free	30	1,000
Pro	120	50,000
Enterprise	600	Unlimited

Endpoints

Send Message

Send a message to a WhatsApp number via your connected bot.

POST /messages/send

bash

curl -X POST https://api.wazbot.io/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "type": "text",
    "body": "Hello! Your order has been confirmed.",
    "agent_id": "agent_abc123"
  }'

Response:

{
  "success": true,
  "message_id": "msg_xyz789",
  "status": "sent",
  "timestamp": "2026-04-28T12:00:00Z"
}

List Conversations

Retrieve a paginated list of conversations.

GET /conversations

bash

curl https://api.wazbot.io/v1/conversations?page=1&limit=20 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "conv_001",
      "contact": "+1234567890",
      "contact_name": "John Doe",
      "last_message": "Thanks for your help!",
      "status": "resolved",
      "agent_id": "agent_abc123",
      "created_at": "2026-04-27T10:30:00Z",
      "updated_at": "2026-04-27T11:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156
  }
}

Get Conversation Messages

GET /conversations/:id/messages

bash

curl https://api.wazbot.io/v1/conversations/conv_001/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Agent

Programmatically create a new AI agent.

POST /agents

bash

curl -X POST https://api.wazbot.io/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Bot",
    "model": "gpt-4o",
    "system_prompt": "You are a helpful sales assistant...",
    "temperature": 0.7,
    "max_tokens": 1024,
    "welcome_message": "Hi! How can I help you today?"
  }'

Response:

{
  "id": "agent_new456",
  "name": "Sales Bot",
  "model": "gpt-4o",
  "status": "inactive",
  "created_at": "2026-04-28T12:00:00Z"
}

Update Agent

PATCH /agents/:id

bash

curl -X PATCH https://api.wazbot.io/v1/agents/agent_new456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "temperature": 0.5
  }'

Upload Knowledge Base Document

POST /knowledge-base/upload

bash

curl -X POST https://api.wazbot.io/v1/knowledge-base/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "agent_id=agent_abc123"

Get Usage Statistics

GET /usage

bash

curl https://api.wazbot.io/v1/usage?period=current_month \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "period": "2026-04",
  "messages_sent": 12450,
  "messages_limit": 25000,
  "conversations": 3200,
  "agents_active": 3,
  "tokens_used": 2450000,
  "cost_usd": 34.20
}

Webhooks

Webhook Event Payload

json

{
  "event": "message.received",
  "timestamp": "2026-04-28T12:05:00Z",
  "data": {
    "conversation_id": "conv_001",
    "message_id": "msg_incoming_123",
    "from": "+1234567890",
    "type": "text",
    "body": "What's my order status?",
    "contact_name": "John Doe"
  }
}

Available Events

Event	Description
`message.received`	New incoming message from a customer
`message.sent`	Bot sent a reply
`message.delivered`	Message delivered to the customer
`message.read`	Customer read the message
`conversation.created`	New conversation started
`conversation.resolved`	Conversation marked as resolved
`agent.handoff`	Conversation transferred to human agent

SDKs

Official SDKs are available for popular languages:

Install Node.js SDK

bash

npm install @wazbot/sdk

Node.js SDK Example

javascript

import { WazBot } from '@wazbot/sdk';

const client = new WazBot({ apiKey: 'YOUR_API_KEY' });

// Send a message
const result = await client.messages.send({
  to: '+1234567890',
  body: 'Hello from the SDK!',
  agentId: 'agent_abc123',
});

console.log(result.messageId); // msg_xyz789

Python SDK Example

python

from wazbot import WazBot

client = WazBot(api_key="YOUR_API_KEY")

# Send a message
result = client.messages.send(
    to="+1234567890",
    body="Hello from Python!",
    agent_id="agent_abc123"
)

print(result.message_id)  # msg_xyz789

Postman Collection

Download our Postman Collection to test all API endpoints interactively.

Affiliate Program

Troubleshooting