Partner program
Multi-business management, a shared credit wallet and a central plan
See detailsDevelopers
REST API, Webhooks and MCP to connect your systems
The Wisebird developer API is a REST API and Webhooks for fetching chats, searching, sending messages and managing a business's tags and members, with a per-business API key and Bearer auth. It supports Idempotency-Key, signed Webhooks with test events, a Try-it sandbox, MCP and a partner API for managing multiple businesses.
Example · List conversations
curl https://wisebird.cloud/external/v1/conversations?status=open&limit=20 \ -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx"
Every endpoint sits under one host and returns JSON. Full docs with schema are in the app.
| Groups | Method and path | What is it for |
|---|---|---|
| Conversations | GET /external/v1/conversations | The chat list, filtered by status, channel, tag or assignee |
| GET /external/v1/conversations/{id} | A single chat with its messages and customer card | |
| GET /external/v1/conversations/search | Search chats by message, customer name or phone number | |
| POST /external/v1/conversations/{id}/messages | Send messages to customers, supporting text, image, video, audio and file | |
| Tags | GET, POST /external/v1/tags | Read and create tags, add or remove tags from chats |
| Members | GET /external/v1/members | Members and roles, used to assign chats |
| Webhooks | GET, POST /external/v1/webhooks | Register an endpoint, choose events and send a test event |
Example · Send a message with Idempotency-Key
curl -X POST https://wisebird.cloud/external/v1/conversations/cnv_123/messages \
-H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: 7f3c2a1e-order-4512-confirm" \
-H "Content-Type: application/json" \
-d '{"type":"text","text":"Order #4512 received. It ships within 2 business days."}'
# Send an attachment: set type to image | video | audio | file and pass the file url
# -d '{"type":"image","url":"https://example.com/receipt.png","caption":"Here is your receipt"}'
Register an endpoint, choose events and send a test event right away, no need to wait for a real chat
| Event | v1 | v2 | Occurred on |
|---|---|---|---|
| message.received | Yes | Yes | A customer sends a message on any channel |
| message.sent | Yes | Yes | AI or team sends a message, with the sender in the payload |
| conversation.handoff | Yes | Yes | AI hands the chat to your team with the reason and a summary |
| conversation.assigned | None | Yes | Chat assigned to a member |
| conversation.tagged | None | Yes | Tag added to or removed from a chat |
| lead.created | None | Yes | A lead form or the AI creates a new lead in the pipeline |
| order.created | None | Yes | Sales or orders from chat are recorded |
v2 adds events and payload fields; v1 still works, but new endpoints should use v2
Example · payload and signature header your endpoint will receive
POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Wisebird-Event: conversation.handoff
X-Wisebird-Signature: t=1760600000,v1=5f1c…e2a9
X-Wisebird-Delivery: evt_01HZX…
{"id":"evt_01HZX…","version":"v2","type":"conversation.handoff",
"business_id":"biz_42","created_at":"2026-10-16T09:30:00+07:00",
"data":{"conversation_id":"cnv_123","channel":"line","reason":"customer_requested_human",
"summary":"Customer asked about inflamed acne before a treatment; requested a doctor assessment"}}
# Verify the signature: HMAC-SHA256(secret, t + "." + raw_body) then compare it with v1 in constant time
# Reject if t is further from the current time than your tolerance, to prevent replay
Example · partner API specifying the business to manage
curl https://wisebird.cloud/external/v1/conversations?status=open \ -H "Authorization: Bearer wb_partner_xxxxxxxxxxxxxxxx" \ -H "X-Wisebird-Business: biz_42"
Multi-business management, a shared credit wallet and a central plan
See detailsData in Thailand, roles and permissions, and an activity log
See detailsAlert rules to your LINE group, Telegram, Discord or webhook
See alertsCreate it in the business settings page in the app. The key is shown in full once at creation, so copy it straight away. If you lose it, revoke it and create a new one
No. Send the key only in the Authorization header as Bearer over HTTPS. Keys in the query string are rejected because URLs often end up in logs
Set the Idempotency-Key header to a unique value per message. Resending with the same key returns the same result and doesn't send the message twice, which is ideal for retries
Every event carries a signature in the header, computed from the endpoint's secret. Compute it from the raw body and compare before processing. Send a test event to try it.
Yes. Try it mode on the app's developer page sends requests to a test business, never to real customers, and can fire Webhook test events with a real signature
Let external AI tools call Wisebird capabilities as tools, such as searching chats, fetching customer cards and sending messages, under the same API key's permissions
Sign up, connect a channel and fire your first request in the sandbox