📜 REST API Technical Reference

The WhatsApp Addon bridge exposes a REST API for programmatic interaction. This document is the authoritative source for all available endpoints.

---

🔒 Security & Headers

All requests (except /health) MUST include:

• X-Auth-Token: Your security token (found in the Web UI).
• Content-Type: application/json

---

🚀 Messaging Endpoints

Every sending endpoint supports these Global JSON Keys:

• number: (String) Target JID (e.g., 49123...@s.whatsapp.net or 12345...@g.us).
• quotedMessageId: (String, Optional) Reply to a specific message ID.
• expiration: (Number, Optional) Auto-delete timer in seconds.

POST /send_message

Basic text messaging.

• message: (String) The text content.

POST /send_image / send_video / send_document

Media transmission.

• url: (String) Publicly accessible HTTPS URL.
• caption / message: (String, Optional) The accompanying text.
• fileName: (String, Document Only) Override the recipient’s view.

POST /send_audio

• url: (String) Link to audio.
• ptt: (Boolean) Set true for voice-note style.

POST /send_poll

• question: (String)
• options: (Array of Strings) Max 12.
• selectableCount: (Integer, Optional) Use 1 for single-select polls or 0 for multi-choice polls.

POST /send_event

• target / number: (String) Target phone number or JID.
• name: (String) Event title.
• description: (String, Optional) Event description.
• date / startTime: (String/Int, Optional) ISO 8601 string or Unix timestamp.
• location: (String/Object, Optional) Location title string or object.
• joinLink: (String, Optional) Meeting link URL.
• isCanceled: (Boolean, Optional)

POST /send_location

• latitude: (Float)
• longitude: (Float)
• title: (String, Optional)
• description: (String, Optional)

POST /send_buttons

• message: (String) Body text.
• buttons: (Array) Objects with id and displayText.
• footer: (String, Optional)

POST /send_list

• title, text, button_text: (Strings)
• sections: (Array) Nested rows with id, title, description.

---

📝 Message Management

POST /edit_message

• message_id: (String)
• new_content: (String)

POST /revoke_message

• message_id: (String)

POST /send_reaction

• messageId: (String) Note case sensitivity.
• reaction: (String) Emoji.

POST /mark_as_read

• messageId: (String, Optional) If omitted, marks whole chat.

---

⚙️ Administration

POST /set_presence

• presence: composing, recording, paused, available, unavailable.

POST /settings/webhook

• url: Destination URL.
• enabled: (Boolean)
• token: (String, Optional) Secure validation header.

---

POST /api/sessions/purge

Purges all inactive, stale, or un-connected sessions from memory and disk storage /data/sessions. Protected against purging active, connecting, or QR-scanning sessions.

---

🤖 WhatsApp Control Commands (ha-app-*)

Send these commands directly as WhatsApp text messages to the paired bot (requires number to be in admin_numbers for protected commands):

• ha-app-ping: Connectivity check (“Pong!”).
• ha-app-getid: Returns current Chat ID / Group JID.
• ha-app-status: Comprehensive system status report (HA Core, OS, Uptime).
• ha-app-errors (or ha-app-issues): Filtered real-time error & warning diagnostic report.
• ha-app-diagnose (or ha-app-diag): Interactive diagnostic test across message features.
• ha-app-logs: Retrieves recent connection event log entries.
• ha-app-restart: Restarts WhatsApp daemon.
• ha-app-stats: Displays message statistics.
• ha-app-help: Lists all available commands.

---

📊 Connection & Info

GET /status

Returns: { "connected": bool, "version": string }

GET /stats

Returns internal traffic and error counters.

GET /qr

Returns: { "status": "scanning", "qr": "data:image/png..." }

GET /groups

Returns an array of all participating Group objects.

GET /contacts

Returns an array of all contacts cached from the paired phone: [ { id, name, notify, verified_name, img_url } ].

• name: Phonebook name from paired device.
• notify: Push name set by contact (populated when they message).
• verified_name: Business accounts only (otherwise null).
• img_url: Profile picture URL (defaults to null).

POST /contacts/check

Checks if a number exists on WhatsApp and whether it is in contacts. Body/Query: { "number": "4917..." } or phone. Returns: { "number": "...", "jid": "...", "exists": bool, "in_contacts": bool, "name": str|null, "notify": str|null, "verified_name": str|null }.

• Automatic normalization strips leading zeros (00 / 0) and country codes for robust suffix matching (min 7 digits) against phonebook contacts.

GET /health

Standard healthcheck. No Token required.