API Reference

The WazBot REST API lets you manage customers, leads, conversations, messages, and more programmatically. All requests operate within your authorized business context.

Base URL

All API requests are made to the following base URL:

https://app.wazbot.app/api/v1/

The API is versioned with /v1/. Development or staging environments, if provided, use a clearly labeled separate URL.

Authentication

Authenticate requests with an API key sent as a Bearer token in the Authorizationheader. Create and manage API keys from your account settings.

curl https://app.wazbot.app/api/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY"

Scopes & permissions

Where scopes are supported, each API key is granted a set of scopes that determine which resources and actions it can access. If a key lacks the required scope, the request is rejected with a permission error. Use the actual scope names shown in your account when assigning permissions.

Tenant isolation

Every request operates strictly within the authorized business (tenant) that owns the API key. You cannot access another business’s data, and cross-tenant requests are rejected server-side.

Resources

The API is organized around resources. The resources exposed may include:

Only resources actually exposed by the live API are available — check your account for the current list.

Example: list customers

curl "https://app.wazbot.app/api/v1/customers?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "cus_8f2a1c",
      "name": "Ada Obi",
      "phone": "+2348000000000",
      "created_at": "2026-01-12T09:30:00Z",
      "updated_at": "2026-01-14T11:05:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1
  }
}

Example: create a lead

curl -X POST https://app.wazbot.app/api/v1/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4" \
  -d '{
    "name": "New Enquiry",
    "phone": "+2348000000001",
    "source": "website"
  }'

const res = await fetch("https://app.wazbot.app/api/v1/leads", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "a1b2c3d4",
  },
  body: JSON.stringify({
    name: "New Enquiry",
    phone: "+2348000000001",
    source: "website",
  }),
})
const lead = await res.json()

import requests

res = requests.post(
    "https://app.wazbot.app/api/v1/leads",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "a1b2c3d4",
    },
    json={"name": "New Enquiry", "phone": "+2348000000001", "source": "website"},
)
lead = res.json()

Example: send a message

curl -X POST https://app.wazbot.app/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_72be10",
    "type": "text",
    "text": "Hello! How can we help you today?"
  }'

Common fields

Pagination

List endpoints return results in pages. Use page and page_size query parameters to page through results; the response includes pagination details and an empty data array when there are no more results. Confirm the default and maximum page size against the live API.

Filtering & sorting

Where supported, list endpoints accept filter, search, status, and date-range parameters, and allow sorting. Use the actual parameter names documented for each resource in the live API.

Idempotency

For requests that create records or trigger actions, send an Idempotency-Key header with a unique value. If the same request is retried with the same key, the API returns the original result instead of creating a duplicate.

Rate limits

The API enforces rate limits. When you exceed a limit, the API responds with a rate-limit error (HTTP 429); retry after a short, increasing delay (exponential backoff). Actual limits and time windows are defined by the live API and may vary by plan.

Errors

Errors use standard HTTP status codes and include a machine-readable code and a request ID.

{
  "error": {
    "code": "validation_error",
    "message": "The 'phone' field is required.",
    "request_id": "req_5d9a2f1"
  }
}

Request IDs

Each response includes a request ID (for example, in the error body or a response header). Include this ID when contacting support so issues can be investigated quickly.

Webhooks

Webhooks notify your server when events happen in WazBot. Configure a webhook endpoint (an HTTPS URL on your server) to receive event notifications in real time.

Events

Supported event types may include:

• Customer created / updated
• Lead created / updated
• Conversation created / updated
• Message received / message status changed
• Form submitted
• Funnel lead created
• Campaign and automation events
• Support events

The live API determines the final list of supported events.

Payload

{
  "event": "message.received",
  "event_id": "evt_3a1f9c",
  "created_at": "2026-02-01T10:15:00Z",
  "business_id": "biz_41ab",
  "data": {
    "conversation_id": "conv_72be10",
    "message_id": "msg_90de",
    "from": "+2348000000000",
    "text": "Hi, is this available?"
  }
}

Security & verification

Where webhook signing is implemented, each delivery includes a signature header. Verify the signature using your webhook secret before trusting the payload, and validate the timestamp to guard against replay. Never publish your webhook secret.

Reliability

Respond quickly with a 2xx status to acknowledge receipt. A 4xx indicates the delivery was rejected, and a 5xx is treated as a temporary failure that may be retried. Because deliveries may be retried, process events idempotently so duplicates are handled safely.

Security guidance

• Keep API keys and webhook secrets server-side only.
• Use HTTPS for all requests and webhook endpoints.
• Grant each key the minimum scopes it needs.
• Rotate and revoke credentials promptly when they change hands or are exposed.