Repository navigation
API Reference
All endpoints are relative to: http://<host>:2785/api/sessions/<sessionId>/
Authentication: X-API-Key: <api_key> header on all requests.
Send a plain text message.
{
"chatId": "967777715787@c.us",
"text": "Hello world"
}Send an image. Supports URL or base64.
{
"chatId": "967777715787@c.us",
"url": "https://example.com/image.png",
"caption": "Optional caption"
}| Field | Type | Required | Notes |
|---|---|---|---|
chatId |
string | Yes |
phone@c.us or groupId@g.us
|
url |
string | One of url/base64 | HTTP(S) URL to image |
base64 |
string | One of url/base64 | Raw base64 data (no data: prefix) |
mimetype |
string | When using base64 | e.g. image/png, image/jpeg
|
filename |
string | No | Max 255 chars |
caption |
string | No | Max 1024 chars |
mentions |
string[] | No | WIDs to @mention |
Same structure as send-image but for video.
{
"chatId": "967777715787@c.us",
"url": "https://example.com/audio.mp3"
}{
"chatId": "967777715787@c.us",
"url": "https://example.com/file.pdf",
"filename": "invoice.pdf"
}Send a stored template with variable substitution. Text-only — renders header+body+footer, joins with \n\n, sends as plain text.
{
"chatId": "967777715787@c.us",
"templateId": "85f89390-6054-4d79-a4f0-15b973a38c60",
"vars": {
"param1": "Faissal Mannaa",
"param2": "ACC-SINV-2026-00047",
"param3": "50"
}
}| Field | Type | Required | Notes |
|---|---|---|---|
chatId |
string | Yes | |
templateId |
string | Conditional | Required when templateName absent |
templateName |
string | Conditional | Required when templateId absent |
vars |
Record<string,string> | No | Keys match {{key}} in template |
Important: send-template is always text-only. For image headers, use the two-step approach (send-image first, then send-template).
Reply to a specific message with a quote.
{
"chatId": "967777715787@c.us",
"quotedMessageId": "true_967777715787@c.us_3EB0...",
"text": "This is my reply"
}React to a message with an emoji.
{
"chatId": "967777715787@c.us",
"messageId": "true_967777715787@c.us_3EB0...",
"emoji": "👍"
}{
"chatId": "967777715787@c.us",
"latitude": -6.2088,
"longitude": 106.8456,
"description": "Office location",
"address": "Jakarta, Indonesia"
}{
"chatId": "967777715787@c.us",
"contactName": "John Doe",
"contactNumber": "+1234567890"
}{
"chatId": "967777715787@c.us",
"name": "What's your favorite color?",
"options": ["Red", "Blue", "Green"],
"allowMultipleAnswers": false
}Send a sticker message. Supports URL or base64.
{
"chatId": "967777715787@c.us",
"url": "https://example.com/sticker.webp"
}Send a text message to multiple contacts (async batch).
{
"chatIds": ["967777715787@c.us", "967777711111@c.us"],
"text": "Hello everyone!"
}Response (202 Accepted):
{
"batchId": "batch-uuid",
"status": "processing",
"totalMessages": 2,
"statusUrl": "/api/sessions/:sessionId/messages/batch/batch-uuid"
}Get batch processing status and progress.
Cancel a running batch.
Add or remove a reaction to a message. Send empty emoji to remove.
{
"chatId": "967777715787@c.us",
"messageId": "true_967777715787@c.us_3EB0...",
"emoji": "👍"
}Get reactions for a specific message.
GET /api/sessions/:sessionId/messages/967777715787@c.us/true_.../reactionsForward an existing message to another chat.
{
"messageId": "true_967777715787@c.us_3EB0...",
"chatId": "967777711111@c.us"
}Delete a message. Add ?revoke=true to delete for everyone (revoke).
DELETE /api/sessions/:sessionId/messages/true_967777715787@c.us_3EB0...?revoke=true
Edit a sent message's text body.
{
"chatId": "967777715787@c.us",
"messageId": "true_967777715787@c.us_3EB0...",
"body": "Updated message text"
}Send a typing indicator to a chat.
{
"chatId": "967777715787@c.us",
"state": "typing"
}States: typing, recording, paused
Mark a chat as read/seen.
POST /api/sessions/:sessionId/chats/967777715787@c.us/read
Mark a chat as unread.
POST /api/sessions/:sessionId/chats/967777715787@c.us/unread
Get live chat history from the WhatsApp client.
GET /api/sessions/:sessionId/chats/967777715787@c.us/history?limit=50
Post a text status/story.
{
"text": "Hello World!",
"backgroundColor": "#FF5722",
"font": "serif"
}Post an image status/story.
{
"image": { "url": "https://example.com/image.jpg" },
"caption": "Check this out!"
}Post a video status/story.
{
"video": { "url": "https://example.com/video.mp4" },
"caption": "New video!"
}List all visible status/story updates (grouped by contact).
Get status updates from a specific contact.
GET /api/sessions/:sessionId/status/1234567890@c.us
Stream a stored status media file (image/video). Returns 404 for text statuses or expired items.
GET /api/sessions/:sessionId/status/:statusId/media
Delete your own status update.
List all groups the session belongs to.
Create a new WhatsApp group.
{
"name": "My Group",
"participants": ["967777715787@c.us", "967777711111@c.us"]
}Add participants to a group.
{
"participants": ["967777715787@c.us"]
}Remove participants from a group.
Promote participants to group admin.
Demote group admins to regular participants.
Set/update group name.
{
"subject": "New Group Name"
}Leave a group.
List all WhatsApp Business labels.
Add a label to a chat.
Remove a label from a chat.
Reject an incoming call.
Full-text message search across sessions.
GET /api/search?q=hello&limit=50
Set display name.
{
"name": "My Business Name"
}Set about text.
{
"status": "Available on WhatsApp"
}Set profile picture.
{
"url": "https://example.com/photo.jpg"
}List WhatsApp Channels the session is subscribed to.
Get a specific channel by ID.
Get messages from a WhatsApp Channel.
GET /api/sessions/:sessionId/channels/:channelId/messages?limit=50
Subscribe to a channel using an invite code.
{
"inviteCode": "ABC123xyz"
}Unsubscribe from a WhatsApp Channel.
Check if a phone number is registered on WhatsApp.
GET /api/sessions/:sessionId/contacts/check/967777715787
Response:
{
"isRegistered": true
}Block a contact.
POST /api/sessions/:sessionId/contacts/967777715787@c.us/block
Unblock a contact.
DELETE /api/sessions/:sessionId/contacts/967777715787@c.us/block
Request an 8-character pairing code as an alternative to QR scanning.
{
"phoneNumber": "967777715787"
}Response:
{
"pairingCode": "ABCD1234"
}Templates are scoped per session. Name must be unique within a session.
| Method | Endpoint | Description |
|---|---|---|
| GET | /templates |
List all templates |
| GET | /templates/:templateId |
Get a specific template |
| POST | /templates |
Create a new template |
| PUT | /templates/:templateId |
Update a template |
| DELETE | /templates/:templateId |
Delete a template |
OpenWA uses this regex for variable substitution:
/\{\{\s*([\w.-]+)\s*\}\}|\{(\w+)\}/gConversion from Frappe format:
- Frappe:
{{1}},{{2}},{{3}} - OpenWA:
{{param1}},{{param2}},{{param3}} - Conversion function:
frappe_to_openwa_vars()inutils.py
| Event | Description | Handler |
|---|---|---|
message.received |
Incoming message from a contact |
_handle_inbound_message() — creates WhatsApp Message, Communication, Lead |
message.sent |
Outgoing message acknowledged by server |
_handle_status_update() — updates message status |
message.ack |
Delivery/read receipt |
_handle_status_update() — updates message status |
message.failed |
Send failure |
_handle_status_update() — marks message as Failed |
message.revoked |
Message deleted by sender |
_handle_message_revoked() — marks message as Revoked |
message.edited |
Sent message edited |
_handle_message_edited() — updates WhatsApp Message body |
message.reaction |
Reaction to a message |
_handle_message_reaction() — logs reaction |
status.received |
Contact posts a status/story |
_handle_status_received() — logs status update |
session.status |
Session status changed |
_handle_session_status() — updates account Active/Inactive |
session.qr |
QR code generated (needs scan) |
_handle_session_qr() — sets account Inactive |
session.authenticated |
Session authenticated successfully |
_handle_session_authenticated() — sets account Active |
session.disconnected |
Session disconnected |
_handle_session_status() — sets account Inactive |
session.reconnect_loop |
Session stuck in reconnect loop |
_handle_session_reconnect_loop() — logs error alert |
group.join |
Participant joined group |
_handle_group_membership() — logs event |
group.leave |
Participant left group |
_handle_group_membership() — logs event |
group.update |
Group metadata changed |
_handle_group_update() — logs changes |
call.received |
Incoming call ringing |
_handle_call_received() — logs call event |
{
"event": "message",
"data": {
"from": "967777715787@c.us",
"to": "967777713637@c.us",
"body": "Hello!",
"type": "text",
"id": "true_967777715787@c.us_3EB0...",
"timestamp": 1719312000,
"chatId": "967777715787@c.us",
"session": "manaa",
"author": "967777715787@c.us",
"pushName": "John Doe"
}
}OpenWA signs every webhook with:
- Header:
X-OpenWA-Signature: sha256=<hex-digest> - Computation:
HMAC-SHA256(webhook_secret, raw_body)
Lenient mode (default): When a secret is configured but no signature header is sent, the message is processed with a warning log.
- 60 requests per minute per IP (configurable per account)
- Exceeding the limit returns
{"status": "error", "message": "Rate limit exceeded"}(HTTP 200)
OpenWA sends X-OpenWA-Idempotency-Key header. Duplicate keys within the configured TTL (default 1 hour) are rejected with {"status": "duplicate"} (HTTP 200).
These are called from the client JS on the WhatsApp Account form.
| Method | Purpose | Args |
|---|---|---|
setup_openwa_session |
One-click setup: create session, start, fetch QR | { account_name } |
get_openwa_qr |
Fetch QR code for existing session | { account_name } |
get_openwa_session_status |
Get current session status (returns not_found if deleted from OpenWA) |
{ account_name } |
stop_openwa_session |
Disconnect the session | { account_name } |
reset_openwa_session |
Clear stale session ID so a new session can be created | { account_name } |
check_whatsapp_number |
Check if number is on WhatsApp | { account_name, number } |
block_contact |
Block a contact | { account_name, contact_id } |
unblock_contact |
Unblock a contact | { account_name, contact_id } |
send_typing_indicator |
Send typing state | { account_name, chat_id, state } |
send_bulk_openwa |
Bulk text to multiple contacts | { account_name, contacts, message } |
forward_message |
Forward a message | { account_name, message_id, chat_id } |
delete_message |
Delete or revoke a message | { account_name, message_id, revoke? } |
request_pairing_code |
Get 8-char pairing code | { account_name, phone_number } |
send_sticker |
Send sticker by URL or base64 | { account_name, chat_id, url?, base64? } |
edit_message |
Edit a sent message's text | { account_name, chat_id, message_id, body } |
post_status_text |
Post text status/story | { account_name, text, background_color?, font? } |
post_status_image |
Post image status/story | { account_name, url?, base64?, caption? } |
post_status_video |
Post video status/story | { account_name, url?, base64?, caption? } |
get_statuses |
List visible status updates | { account_name } |
reject_call |
Reject incoming WhatsApp call | { account_name, call_id } |
mark_chat_read |
Mark chat as read | { account_name, chat_id } |
mark_chat_unread |
Mark chat as unread | { account_name, chat_id } |
get_chat_history |
Get live chat history from WhatsApp | { account_name, chat_id, limit? } |
search_messages |
Full-text search across sessions | { account_name, query, limit? } |
list_groups |
List all groups | { account_name } |
create_group |
Create a new WhatsApp group | { account_name, name, participants } |
add_group_participants |
Add participants to group | { account_name, group_id, participants } |
remove_group_participants |
Remove participants from group | { account_name, group_id, participants } |
promote_group_admins |
Promote to group admin | { account_name, group_id, participants } |
demote_group_admins |
Demote group admin | { account_name, group_id, participants } |
set_group_name |
Set group name | { account_name, group_id, name } |
leave_group |
Leave a group | { account_name, group_id } |
list_labels |
List WhatsApp Business labels | { account_name } |
add_label_to_chat |
Add label to chat | { account_name, label_id, chat_id } |
remove_label_from_chat |
Remove label from chat | { account_name, label_id, chat_id } |
send_bulk_with_progress |
Async batch with progress tracking | { account_name, contacts, message } |
set_profile_name |
Set WhatsApp display name | { account_name, name } |
set_profile_status |
Set WhatsApp about text | { account_name, status } |
set_profile_picture |
Set profile picture | { account_name, url?, base64? } |
get_session_stats |
Get aggregate session statistics | { account_name } |
list_channels |
List WhatsApp Channels | { account_name } |
get_channel_messages |
Get channel messages | { account_name, channel_id, limit? } |
get_contact_statuses |
Get statuses from a specific contact | { account_name, contact_id } |
get_status_media |
Stream stored status media file | { account_name, status_id } |
subscribe_channel |
Subscribe to channel via invite code | { account_name, invite_code } |
unsubscribe_channel |
Unsubscribe from a channel | { account_name, channel_id } |
get_message_reactions |
Get reactions for a message | { account_name, chat_id, message_id } |
cancel_batch |
Cancel a running bulk batch | { account_name, batch_id } |
get_overview_stats |
Cross-session aggregate stats (admin) | { account_name } |
get_message_stats |
Message stats with time series (admin) | { account_name, period? } |
| Method | Purpose |
|---|---|
_ensure_session_ready() |
Pre-send session health check — auto-restarts if not ready |
on_account_update() |
Auto-sync webhook secret to OpenWA on save |
on_account_trash() |
Delete OpenWA session when account is deleted |
| HTTP Status | Cause |
|---|---|
| 400 | Missing mimetype with base64, missing chatId, session not active |
| 404 | Template UUID not found, session not found |
| 200 (with error body) | All inbound webhook errors (prevents retry loops) |
OpenWA blocks requests to private IPs by default. Fix in OpenWA's .env:
SSRF_ALLOWED_HOSTS=your-site-name,your-server-ip,localhost,127.0.0.1,minio
# your-site-name = your Frappe/ERPNext site name (e.g., my-site)
# your-server-ip = the IP used to connect from VM to host (e.g., 192.168.1.15)
# minio = MinIO service hostname (if used for file storage)The bridge provides a WhatsApp Catalog Product DocType that links ERPNext Items to a WhatsApp product catalog. OpenWA does not support WhatsApp catalog operations, so the bridge only uses the local DocType for reference and sends products as formatted text+image messages.
| Field | Type | Source |
|---|---|---|
product_name |
Data | Auto-fetched from Item, editable |
item_code |
Link → Item | ERPNext Item |
whatsapp_account |
Link → WhatsApp Account | Target account |
is_available |
Check | Default: Yes |
description |
Text Editor | Auto-fetched from Item, editable |
price |
Currency | Auto-fetched from Item rate |
currency |
Link → Currency | Default from system |
image |
Attach Image | Auto-fetched from Item image |
retailer_id |
Data | Optional external ID |
sync_status |
Select | Vestigial – OpenWA has no catalog sync |
openwa_product_id |
Data | Vestigial – OpenWA has no catalog sync |
last_sync_on |
Datetime | Read-only |
List all catalog products for an account.
Method: openwa_bridge.catalog.get_catalog_products
Args: { account_name: string }
Returns:
{
"status": "ok",
"products": [
{ "name": "WCP-0001", "product_name": "Widget", ... }
]
}Get a single catalog product.
Method: openwa_bridge.catalog.get_catalog_product
Args: { account_name: string, product_name: string }
Returns:
{
"status": "ok",
"product": { "name": "WCP-0001", ... }
}send_product_to_chat. Use send_product_to_chat instead.
Method: openwa_bridge.catalog.send_product_to_chat_direct
Args: { account_name: string, chat_id: string, product_name: string }
Send a catalog product to a WhatsApp chat as formatted text+image.
Method: openwa_bridge.catalog.send_product_to_chat
Args: { product_name: string, chat_id: string }
Send a catalog product to a Customer's WhatsApp number. Looks up the Customer's primary Contact, resolves the phone number to a chat ID, and sends the product as a text+image fallback message.
Method: openwa_bridge.catalog.send_product_to_customer
Args: { product_name: string, customer: string }
Raises: If no Contact or no phone number is found for the Customer.
Returns:
{
"status": "ok",
"method": "fallback",
"result": { "messageId": "true_967777715787@c.us_3EB0..." }
}Send the full catalog link to a chat. Falls back to a summary message.
Method: openwa_bridge.catalog.send_catalog_to_chat
Args: { account_name: string, chat_id: string }
OpenWA has no delayed send, so scheduling is implemented in the bridge:
- Set
openwa_scheduled_at(Datetime) on a WhatsApp Message. -
after_insertpropagates it to the OpenWA Outbox entry'sscheduled_atand does not enqueue it for immediate send. - The outbox processor (
_process_outbox_entry_inner) skips Pending entries withscheduled_at > nowwithout bumpingattempts. - The scheduler safety-net (
process_pending_outbox) only picks up Pending entries whosescheduled_atis null or<= now.
Image / video / audio / document sends now accept a base64 payload in addition to a URL link:
{
"image": {
"base64": "<base64-encoded bytes>",
"mimetype": "image/jpeg",
"filename": "photo.jpg"
}
}-
link→ sent asurl(existing behavior). -
base64→ sent asbase64+mimetype(mirrors the sticker pattern). -
filenameoptional (used bysend-document). - Caption still sent for non-audio media.
OpenWA POST /messages/reply is text-only. When a media message is sent with
is_reply + reply_to_message_id:
- Media is sent unquoted via
send-{type}. - A text reply is sent quoting the returned media
messageId.
Non-message webhook events are now persisted instead of only logged:
| event_type | Source webhook |
|---|---|
group.join / group.leave / group.update
|
group webhooks |
call.received |
incoming call |
status.received |
contact status/story |
message.reaction |
reaction on a message |
webhook.delivery_failure |
DLQ check (check_webhook_delivery_failures) |
Each row: whatsapp_account, session_id, timestamp, summary, payload
(Code field), related_group, related_contact. Inserts are best-effort and never
break webhook processing.
message.reaction events are stored on the WhatsApp Message doc in the
openwa_reactions JSON field as [{emoji, sender, timestamp}] (advance-only dedupe
per emoji+sender).
daily() now calls check_webhook_delivery_failures() which:
- Reads
GET /api/webhooks/delivery-failures(limit 50 per session). - Writes
webhook.delivery_failurerows to the Event Log (deduped by idempotency key). - Replays the affected account via
replay_webhooks(account_name)to backfill missed inbound messages.
403 from the DLQ endpoint (non-ADMIN key) is expected and skipped silently.