Skip to content

API Reference

Manaa-Soft edited this page Aug 6, 2026 · 17 revisions

API Reference

OpenWA REST Endpoints

All endpoints are relative to: http://<host>:2785/api/sessions/<sessionId>/

Authentication: X-API-Key: <api_key> header on all requests.


Messages

POST /messages/send-text

Send a plain text message.

{
  "chatId": "967777715787@c.us",
  "text": "Hello world"
}

POST /messages/send-image

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

POST /messages/send-video

Same structure as send-image but for video.

POST /messages/send-audio

{
  "chatId": "967777715787@c.us",
  "url": "https://example.com/audio.mp3"
}

POST /messages/send-document

{
  "chatId": "967777715787@c.us",
  "url": "https://example.com/file.pdf",
  "filename": "invoice.pdf"
}

POST /messages/send-template

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).

POST /messages/reply

Reply to a specific message with a quote.

{
  "chatId": "967777715787@c.us",
  "quotedMessageId": "true_967777715787@c.us_3EB0...",
  "text": "This is my reply"
}

POST /messages/react

React to a message with an emoji.

{
  "chatId": "967777715787@c.us",
  "messageId": "true_967777715787@c.us_3EB0...",
  "emoji": "👍"
}

POST /messages/send-location

{
  "chatId": "967777715787@c.us",
  "latitude": -6.2088,
  "longitude": 106.8456,
  "description": "Office location",
  "address": "Jakarta, Indonesia"
}

POST /messages/send-contact

{
  "chatId": "967777715787@c.us",
  "contactName": "John Doe",
  "contactNumber": "+1234567890"
}

POST /messages/send-poll

{
  "chatId": "967777715787@c.us",
  "name": "What's your favorite color?",
  "options": ["Red", "Blue", "Green"],
  "allowMultipleAnswers": false
}

POST /messages/send-sticker

Send a sticker message. Supports URL or base64.

{
  "chatId": "967777715787@c.us",
  "url": "https://example.com/sticker.webp"
}

POST /messages/send-bulk

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 /messages/batch/:batchId

Get batch processing status and progress.

POST /messages/batch/:batchId/cancel

Cancel a running batch.

POST /messages/react

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 /messages/:chatId/:messageId/reactions

Get reactions for a specific message.

GET /api/sessions/:sessionId/messages/967777715787@c.us/true_.../reactions

POST /messages/forward

Forward an existing message to another chat.

{
  "messageId": "true_967777715787@c.us_3EB0...",
  "chatId": "967777711111@c.us"
}

DELETE /messages/:messageId

Delete a message. Add ?revoke=true to delete for everyone (revoke).

DELETE /api/sessions/:sessionId/messages/true_967777715787@c.us_3EB0...?revoke=true

POST /messages/edit

Edit a sent message's text body.

{
  "chatId": "967777715787@c.us",
  "messageId": "true_967777715787@c.us_3EB0...",
  "body": "Updated message text"
}

Chat Management

POST /chats/typing

Send a typing indicator to a chat.

{
  "chatId": "967777715787@c.us",
  "state": "typing"
}

States: typing, recording, paused

POST /chats/:chatId/read

Mark a chat as read/seen.

POST /api/sessions/:sessionId/chats/967777715787@c.us/read

POST /chats/:chatId/unread

Mark a chat as unread.

POST /api/sessions/:sessionId/chats/967777715787@c.us/unread

GET /chats/:chatId/history

Get live chat history from the WhatsApp client.

GET /api/sessions/:sessionId/chats/967777715787@c.us/history?limit=50

Status/Stories

POST /status/send-text

Post a text status/story.

{
  "text": "Hello World!",
  "backgroundColor": "#FF5722",
  "font": "serif"
}

POST /status/send-image

Post an image status/story.

{
  "image": { "url": "https://example.com/image.jpg" },
  "caption": "Check this out!"
}

POST /status/send-video

Post a video status/story.

{
  "video": { "url": "https://example.com/video.mp4" },
  "caption": "New video!"
}

GET /status

List all visible status/story updates (grouped by contact).

GET /status/:contactId

Get status updates from a specific contact.

GET /api/sessions/:sessionId/status/1234567890@c.us

GET /status/:statusId/media

Stream a stored status media file (image/video). Returns 404 for text statuses or expired items.

GET /api/sessions/:sessionId/status/:statusId/media

DELETE /status/:statusId

Delete your own status update.


Groups

GET /groups

List all groups the session belongs to.

POST /groups

Create a new WhatsApp group.

{
  "name": "My Group",
  "participants": ["967777715787@c.us", "967777711111@c.us"]
}

POST /groups/:groupId/participants/add

Add participants to a group.

{
  "participants": ["967777715787@c.us"]
}

POST /groups/:groupId/participants/remove

Remove participants from a group.

POST /groups/:groupId/participants/promote

Promote participants to group admin.

POST /groups/:groupId/participants/demote

Demote group admins to regular participants.

PUT /groups/:groupId/subject

Set/update group name.

{
  "subject": "New Group Name"
}

POST /groups/:groupId/leave

Leave a group.


Labels (WhatsApp Business)

GET /labels

List all WhatsApp Business labels.

POST /labels/:labelId/chats/:chatId

Add a label to a chat.

DELETE /labels/:labelId/chats/:chatId

Remove a label from a chat.


Calls

POST /calls/:callId/reject

Reject an incoming call.


Search

GET /search

Full-text message search across sessions.

GET /api/search?q=hello&limit=50

Profile

PUT /profile/name

Set display name.

{
  "name": "My Business Name"
}

PUT /profile/status

Set about text.

{
  "status": "Available on WhatsApp"
}

PUT /profile/picture

Set profile picture.

{
  "url": "https://example.com/photo.jpg"
}

Channels/Newsletters

GET /channels

List WhatsApp Channels the session is subscribed to.

GET /channels/:channelId

Get a specific channel by ID.

GET /channels/:channelId/messages

Get messages from a WhatsApp Channel.

GET /api/sessions/:sessionId/channels/:channelId/messages?limit=50

POST /channels/subscribe

Subscribe to a channel using an invite code.

{
  "inviteCode": "ABC123xyz"
}

DELETE /channels/:channelId

Unsubscribe from a WhatsApp Channel.


Contact Management

GET /contacts/check/:number

Check if a phone number is registered on WhatsApp.

GET /api/sessions/:sessionId/contacts/check/967777715787

Response:

{
  "isRegistered": true
}

POST /contacts/:jid/block

Block a contact.

POST /api/sessions/:sessionId/contacts/967777715787@c.us/block

DELETE /contacts/:jid/block

Unblock a contact.

DELETE /api/sessions/:sessionId/contacts/967777715787@c.us/block

Pairing Code

POST /pairing-code

Request an 8-character pairing code as an alternative to QR scanning.

{
  "phoneNumber": "967777715787"
}

Response:

{
  "pairingCode": "ABCD1234"
}

Templates

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

Template Variable Rendering

OpenWA uses this regex for variable substitution:

/\{\{\s*([\w.-]+)\s*\}\}|\{(\w+)\}/g

Conversion from Frappe format:

  • Frappe: {{1}}, {{2}}, {{3}}
  • OpenWA: {{param1}}, {{param2}}, {{param3}}
  • Conversion function: frappe_to_openwa_vars() in utils.py

Inbound Webhooks

Supported Events

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

Webhook Payload Structure

{
  "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"
  }
}

HMAC Verification

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.

Rate Limiting

  • 60 requests per minute per IP (configurable per account)
  • Exceeding the limit returns {"status": "error", "message": "Rate limit exceeded"} (HTTP 200)

Idempotency

OpenWA sends X-OpenWA-Idempotency-Key header. Duplicate keys within the configured TTL (default 1 hour) are rejected with {"status": "duplicate"} (HTTP 200).


Frappe Whitelisted Methods

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? }

Internal Methods (Not Whitelisted)

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

Error Handling

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)

SSRF Blocked

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)

8. WhatsApp Catalog (Bridge DocType)

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.

DocType: WhatsApp Catalog Product

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

get_catalog_products

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_catalog_product

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_direct

⚠️ Deprecated — delegates to 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_product_to_chat

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_product_to_customer

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_catalog_to_chat

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 }


Tier 2 Improvements (bridge-side)

Scheduled send

OpenWA has no delayed send, so scheduling is implemented in the bridge:

  • Set openwa_scheduled_at (Datetime) on a WhatsApp Message.
  • after_insert propagates it to the OpenWA Outbox entry's scheduled_at and does not enqueue it for immediate send.
  • The outbox processor (_process_outbox_entry_inner) skips Pending entries with scheduled_at > now without bumping attempts.
  • The scheduler safety-net (process_pending_outbox) only picks up Pending entries whose scheduled_at is null or <= now.

Base64 media outbound

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 as url (existing behavior).
  • base64 → sent as base64 + mimetype (mirrors the sticker pattern).
  • filename optional (used by send-document).
  • Caption still sent for non-audio media.

Media reply workaround

OpenWA POST /messages/reply is text-only. When a media message is sent with is_reply + reply_to_message_id:

  1. Media is sent unquoted via send-{type}.
  2. A text reply is sent quoting the returned media messageId.

Inbound event persistence (OpenWA Event Log)

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.

Reactions persistence

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).

Webhook DLQ replay

daily() now calls check_webhook_delivery_failures() which:

  1. Reads GET /api/webhooks/delivery-failures (limit 50 per session).
  2. Writes webhook.delivery_failure rows to the Event Log (deduped by idempotency key).
  3. 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.


Clone this wiki locally