WAQueen
WAQueen

Developer reference

WhatsApp API documentation.

Queue text and media messages, manage WhatsApp sessions, inspect delivery state, and replay durable webhooks with a stable OpenAPI-backed contract.

01POST /messages
02GET /sessions
03POST /webhooks
OpenAPI JSONPostman collectionDashboard docs
Public send quickstart
curl -X POST https://waqueen.com/api/v1/messages \
  -H "Authorization: Bearer wsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "text": "Order shipped",
    "idempotencyKey": "order-4821-shipped"
  }'
Live contract
Queue, deliver, verify
01Message accepted
02Delivery webhook signed
03Replay available
HMAC
Retries
OpenAPI
Spec first

The live OpenAPI JSON is the source for generated tools and contract checks.

Async by default

Messaging responses confirm queue acceptance. Delivery updates arrive through webhooks.

Stable examples

Postman requests include baseUrl, apiKey, sessionId, messageId, and webhookDeliveryId variables.

Developer workflow

From one request to a complete WhatsApp workflow.

MessagesSessionsWebhooksMediaContactsQueue
01

Authenticate

Create scoped API keys for the workspace and keep every request tied to a controlled session.

02

Send

Queue text or media messages through a stable contract with idempotency and delivery state.

03

Observe

Listen to signed webhook events, replay failures, and connect WhatsApp activity back to your system.

Reference

Endpoints

This catalog is rendered from the same OpenAPI source served by /api/openapi.

Method

Showing 102 of 102 OpenAPI operations.

WhatsApp

Public WhatsApp utility endpoints for external tools.

post
/api/v1/whatsapp/check-number

Check whether a phone number has WhatsApp

Checks a direct phone number through a linked WhatsApp session. If sessionId is omitted, WAQueen selects the best connected or recoverable session for the API key's business.

whatsapp:check

Messages

Queue text, media, poll, and quick-reply messages for WhatsApp delivery.

post
/api/v1/messages

Queue a text, media, poll, or quick-reply message

Accepts a text, single media, poll, or quick-reply message into the durable per-session FIFO queue. Quick replies are sent as a single-answer WhatsApp poll for reliability. If sessionId is omitted, WAQueen selects the best send-ready session. If sessionId is provided with allowFallback=true, WAQueen may use another send-ready session only when the requested session is temporarily restoring. The response confirms queue acceptance; final delivery arrives through webhook status events.

messages:send
post
/api/v1/media/upload

Upload media for a later message send

Stores one media file in WAQueen-controlled storage and returns a mediaId. Use that mediaId in POST /api/v1/messages to avoid depending on an external public media URL.

messages:send

Business

Create the tenant workspace and manage the structured AI Business Brain profile.

post
/api/businesses

Create business workspace and AI brain profile

Completes first-run onboarding. The `brain` object is optional for backward compatibility, but the dashboard wizard sends it to create structured AI context.

get
/api/businesses/current

Read current business workspace

patch
/api/businesses/current

Update current business profile

get
/api/businesses/brain

Read AI Business Brain profile

put
/api/businesses/brain

Update AI Business Brain profile

post
/api/businesses/brain/generate-summary

Preview generated AI business prompt summary

Knowledge

Create, index, search, and govern AI Business Brain knowledge sources.

get
/api/businesses/knowledge-sources

List knowledge sources

knowledge:read
post
/api/businesses/knowledge-sources

Create and optionally index a knowledge source

knowledge:write
get
/api/businesses/knowledge-sources/{id}

Read a knowledge source

knowledge:read
patch
/api/businesses/knowledge-sources/{id}

Update a knowledge source

knowledge:write
delete
/api/businesses/knowledge-sources/{id}

Archive a knowledge source

knowledge:write
post
/api/businesses/knowledge-sources/{id}/reindex

Reindex a knowledge source

knowledge:write
post
/api/businesses/knowledge/search

Search indexed knowledge chunks

knowledge:read
post
/api/businesses/ai-context/preview

Preview AI reply context

Builds the same compact context pack the AI reply pipeline will use: business profile, contact/conversation state, approved KB chunks, source IDs, and safety/handoff decision flags.

knowledge:read
get
/api/businesses/services

List governed services and pricing

knowledge:read
post
/api/businesses/services

Create a governed service or priced catalog item

knowledge:write
get
/api/businesses/services/{id}

Read a governed service

knowledge:read
patch
/api/businesses/services/{id}

Update a governed service

knowledge:write
delete
/api/businesses/services/{id}

Archive a governed service

knowledge:write
post
/api/businesses/services/{id}/publish

Publish a governed service and index it

knowledge:write
post
/api/businesses/services/{id}/archive

Archive a governed service

knowledge:write
get
/api/businesses/services/{id}/revisions

List service revisions

knowledge:read
get
/api/businesses/faqs

List governed FAQs

knowledge:read
post
/api/businesses/faqs

Create a governed FAQ

knowledge:write
get
/api/businesses/faqs/{id}

Read a governed FAQ

knowledge:read
patch
/api/businesses/faqs/{id}

Update a governed FAQ

knowledge:write
delete
/api/businesses/faqs/{id}

Archive a governed FAQ

knowledge:write
post
/api/businesses/faqs/{id}/publish

Publish a governed FAQ

knowledge:write
get
/api/businesses/faqs/{id}/revisions

List FAQ revisions

knowledge:read
get
/api/businesses/policies

List governed policies

knowledge:read
post
/api/businesses/policies

Create a governed policy

knowledge:write
get
/api/businesses/policies/{id}

Read a governed policy

knowledge:read
patch
/api/businesses/policies/{id}

Update a governed policy

knowledge:write
delete
/api/businesses/policies/{id}

Archive a governed policy

knowledge:write
post
/api/businesses/policies/{id}/publish

Publish a governed policy

knowledge:write
get
/api/businesses/policies/{id}/revisions

List policy revisions

knowledge:read

Sessions

Create, pair, monitor, and operate WhatsApp sessions.

get
/api/sessions

List WhatsApp sessions

post
/api/sessions

Create a WhatsApp session

get
/api/sessions/{id}

Get one WhatsApp session

patch
/api/sessions/{id}

Update session settings

delete
/api/sessions/{id}

Delete a WhatsApp session

get
/api/sessions/{id}/qr

Read QR pairing state

post
/api/sessions/{id}/qr

Start or refresh QR pairing

get
/api/sessions/{id}/status

Read connection status

get
/api/sessions/{id}/persistence

Read persisted auth health

get
/api/sessions/{id}/diagnostics

Read deep session diagnostics

get
/api/sessions/{id}/events

List recent session events

post
/api/sessions/{id}/restart

Restart a WhatsApp session socket

post
/api/sessions/{id}/logout

Logout a WhatsApp session

Queue

Inspect, clear, cancel, and retry outbound message queue rows.

get
/api/sessions/{id}/queue

Inspect a session outbound queue

messages:read
post
/api/sessions/{id}/queue/clear

Cancel all unlocked queued messages for one session

messages:manage
get
/api/messages/{id}

Read one outbound message lifecycle record

messages:read
post
/api/messages/{id}/cancel

Cancel one queued outbound message

messages:manage
post
/api/messages/{id}/retry

Move a failed or cancelled message back to the queue

messages:manage

Inbox

Read conversations, inspect message threads, mark chats read, and reply from the inbox.

get
/api/inbox/events

Stream inbox snapshots

Server-sent event stream for dashboard-style realtime inbox refresh. Emits `snapshot` events with the current conversation list and, when `sessionId` plus `chatJid` are provided, the selected thread messages. Clients should keep ordinary REST polling as a fallback.

messages:read
get
/api/inbox/conversations

List inbox conversations

messages:read
post
/api/inbox/conversations

Create or find an inbox conversation

Bootstraps an empty conversation from a contact, phone number, or chat JID so operators can open the thread and send the first message.

messages:manage
get
/api/inbox/conversations/{chatJid}

Get one inbox conversation

messages:read
patch
/api/inbox/conversations/{chatJid}

Update inbox conversation metadata

messages:manage
get
/api/inbox/conversations/{chatJid}/messages

List messages in one conversation

messages:read
post
/api/inbox/conversations/{chatJid}/resync

Request WhatsApp history resync

Requests more WhatsApp history for a conversation. If an oldest stored WhatsApp message exists, WAQueen asks Baileys for older messages for that chat. If no anchor exists and fallbackFullSync is true, WAQueen requests a full session history sync restart.

messages:manage
post
/api/inbox/conversations/{chatJid}/read

Mark one conversation read

messages:manage
post
/api/inbox/conversations/{chatJid}/reply

Reply to a conversation

messages:send

Contacts

Manage CRM contact records, policy flags, and WhatsApp availability checks.

get
/api/contacts

List contacts

contacts:read
post
/api/contacts

Create or upsert a contact

contacts:write
get
/api/contacts/{id}

Get one contact

contacts:read
patch
/api/contacts/{id}

Update a contact

contacts:write
delete
/api/contacts/{id}

Delete a contact

contacts:write
patch
/api/contacts/{id}/lead

Update persisted lead state for one contact

contacts:write
post
/api/contacts/{id}/block

Block or unblock a contact

contacts:write
post
/api/contacts/{id}/opt-out

Opt a contact out or back in

contacts:write
post
/api/contacts/check-whatsapp

Check WhatsApp account availability

contacts:write
post
/api/contacts/bulk-tags

Bulk add or remove contact tags

contacts:write

Tags

Manage the business tag catalog used by contacts, conversations, and segmentation.

get
/api/tags

List tags

contacts:read
post
/api/tags

Create or restore a tag

contacts:write
get
/api/tags/{id}

Get one tag

contacts:read
patch
/api/tags/{id}

Update a tag

contacts:write
delete
/api/tags/{id}

Archive a tag

contacts:write

Segments

Create saved dynamic or static contact segments with opt-out and block safety defaults.

get
/api/segments

List segments

contacts:read
post
/api/segments

Create a segment

contacts:write
post
/api/segments/preview

Preview unsaved segment rules

contacts:read
get
/api/segments/{id}

Get one segment

contacts:read
patch
/api/segments/{id}

Update a segment

contacts:write
delete
/api/segments/{id}

Archive a segment

contacts:write
get
/api/segments/{id}/contacts

List contacts in a segment

contacts:read
post
/api/segments/{id}/preview

Preview one saved segment

contacts:read
post
/api/segments/{id}/recalculate

Recalculate segment membership cache

contacts:write

Webhooks

Inspect and replay durable webhook deliveries.

get
/api/webhook-deliveries

List webhook delivery attempts

webhooks:read
post
/api/webhook-deliveries/{id}/replay

Replay a delivered or failed webhook delivery

webhooks:write
post
/api/sessions/{id}/webhook/test

Queue a signed test webhook

webhooks:write
get
/api/v1/notifications/receive

Receive the next webhook notification

GreenAPI-style polling fallback for customers without a public webhook endpoint. Returns the oldest available event notification, then the client confirms processing with DELETE /api/v1/notifications/{id}.

webhooks:read
delete
/api/v1/notifications/{id}

Delete a processed webhook notification

webhooks:write

API Keys

Create, rotate, and revoke API keys for public API access.

get
/api/api-keys

List API keys

post
/api/api-keys

Create an API key

delete
/api/api-keys

Revoke an API key

post
/api/api-keys/{id}/rotate

Rotate an API key

Developer

Machine-readable API documentation and test artifacts.

get
/api/openapi

Download OpenAPI specification

get
/api/openapi.json

Download OpenAPI specification as JSON

get
/api/postman

Download Postman collection