Platform Capability Atlas

A complete, implementation-aligned map of messaging, webhook, media, and operational capabilities.

Control Plane and Runtime Responsibilities

  • Dashboard Mantap! (control plane): project setup, API key management, and device onboarding actions.
  • WA Gateway (runtime plane): direct messaging API, webhooks, media retrieval, and message lifecycle events.
  • Internal Mantul integration: engineer uses device_id-only calls while mapping and auth resolution are performed server-side.

Runtime API Surface

  • POST /devices, GET /devices, DELETE /devices/{device_id}, POST /devices/{device_id}/qr, POST /devices/{device_id}/disconnect
  • POST /devices/{device_id}/messages, GET /devices/{device_id}/messages
  • GET /devices/{device_id}/groups, GET /devices/{device_id}/profile?jid=..., GET /devices/{device_id}/presence?jid=...
  • GET /media?path=..., GET /health

Outbound Message Capability Matrix

TypeSupportedMain Fields
textYesto, text
imageYesto, url or data_base64, mime_type, caption (optional)
videoYesto, url or data_base64, mime_type, caption (optional)
audioYesto, url or data_base64, mime_type, ptt (optional voice-note mode)
documentYesto, url or data_base64, mime_type, file_name (optional), caption (optional)
stickerYesto, url or data_base64, mime_type
contactYesto, contact_name, vcard
locationYesto, latitude, longitude, address (optional label)
buttons/interactiveBeta (feature flag)to, text, buttons[], footer (optional)
pollBeta (feature flag)to, poll_question, poll_options[], poll_multi (optional)

Webhook Event Catalog

EventPurpose
messageInbound/outbound message data, including attachment metadata.
receiptDelivery/read progression for message IDs.
message_revokedMessage was deleted/revoked.
button_response, list_response, interactive_response, poll_responseReplies to interactive content.
presence, chat_presenceAvailability and chat activity changes.
device_qr_generated, device_connected, device_disconnected, device_destroyedDevice lifecycle transitions.
logout, warningConnection or platform warnings (logged out, temporary ban, stream issues, outdated client).

Webhook Delivery and Security

  • Webhook delivery is automatic for message, receipt, and lifecycle events when webhook path is configured.
  • Gateway sends signature headers (X-WA-Timestamp, X-WA-Signature, X-WA-Signature-Alg) and does not expose webhook secret value.
  • Receiver should validate HMAC signature and timestamp on every callback.

Attachment Ingestion Capabilities

  • Inbound attachment payload includes message_type, media_path, media_mime_type, media_size, and optional caption/text.
  • contact payload includes backward-compatible fields (contact_name, contact_vcard) and normalized contact object(s).
  • location payload includes latitude, longitude, location_name, and location_address when present.
  • Use GET /media?path=... to fetch binary file securely (internal auth resolved server-side in Mantul flow).

Built-In Safety and Reliability Controls

  • Media input supports url or data_base64 with size and MIME enforcement.
  • Media URL fetch uses SSRF guards (host and scheme validation).
  • Message send includes provider retry with backoff on rate-limit scenarios.
  • API includes per-token/global rate-limit and request-size controls.
  • Internal device-control endpoints are guarded by host/IP whitelist policies for Onebrick server sources.
  • Host/IP whitelist policy is scoped to internal device routes, not a replacement for webhook callback receiver filtering.