Developers

Wisebird API: connect customer chats to your systems

REST API, Webhooks and MCP to connect your systems

Read the full description

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.

What do I need to start using the API

  1. Create an API key per businessIn business settings in the app. Copy it right away, as the full key is shown only once
  2. Send the key as BearerIn the Authorization header on every request. Never in the query string. Use HTTPS
  3. Test in the sandbox firstTry it mode in the app sends requests to a test business before you use a live business key

Example · List conversations

curl https://wisebird.cloud/external/v1/conversations?status=open&limit=20 \
  -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx"

What endpoints are there

Every endpoint sits under one host and returns JSON. Full docs with schema are in the app.

GroupsMethod and pathWhat is it for
ConversationsGET /external/v1/conversationsThe 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/searchSearch chats by message, customer name or phone number
POST /external/v1/conversations/{id}/messagesSend messages to customers, supporting text, image, video, audio and file
TagsGET, POST /external/v1/tagsRead and create tags, add or remove tags from chats
MembersGET /external/v1/membersMembers and roles, used to assign chats
WebhooksGET, POST /external/v1/webhooksRegister 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"}'
  • Idempotency-KeyA unique value per message. Resending with the same key returns the same result and doesn't send a duplicate to the customer.
  • Channel limitsFile types and sizes depend on the channel
  • MessengerThere is a 24-hour limit on messages the business starts

What do Webhooks notify, and how do I verify the signature?

Register an endpoint, choose events and send a test event right away, no need to wait for a real chat

Eventv1v2Occurred on
message.receivedYesYesA customer sends a message on any channel
message.sentYesYesAI or team sends a message, with the sender in the payload
conversation.handoffYesYesAI hands the chat to your team with the reason and a summary
conversation.assignedNoneYesChat assigned to a member
conversation.taggedNoneYesTag added to or removed from a chat
lead.createdNoneYesA lead form or the AI creates a new lead in the pipeline
order.createdNoneYesSales 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

MCP, sandbox and partner API

  • Try it sandboxThe in-app developer page sends requests to a test business and shows results instantly, without affecting real customers
  • MCPLet external AI tools call Wisebird as a tool, under the same API key's permissions
  • partner APIOne key manages many businesses using credits from a shared wallet, for partners
  • Permissions and logsEvery request is recorded in the activity log. Revoke keys instantly in settings

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"

Related pages

Partner program

Multi-business management, a shared credit wallet and a central plan

See details

Security and PDPA

Data in Thailand, roles and permissions, and an activity log

See details

CRM / Pipeline

Alert rules to your LINE group, Telegram, Discord or webhook

See alerts

FAQ

Where do I create a Wisebird API key

Create 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

Can I send the API key in the query string

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

What happens if I accidentally send a message twice?

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

How do I verify a Webhook really came from Wisebird?

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.

Is there a sandbox to test without affecting real customers

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

What is MCP used for with Wisebird?

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

Create your first API key on the free plan

Sign up, connect a channel and fire your first request in the sandbox