The WA Gateway Integration Playbook

Control Plane vs Runtime Plane

• Dashboard Mantap!: project provisioning, API key rotation/management, device lifecycle setup (create/disconnect/regenerate QR).
• Direct to WA Gateway: runtime messaging integration (/messages, webhook consumption, and /media download).

From Provisioning to Production Traffic

1. Create and connect a device from Dashboard Mantap! Messenger Management.
2. Send outbound messages using POST /devices/{device_id}/messages.
3. Receive inbound/outbound events on your webhook endpoint, including mention and forwarded-message metadata when WhatsApp provides it.
4. Download attachments using GET /media?path=... when media_path is present.

Quick Start for Direct Integration

1. Create an app and save the returned app token.
2. Create one device for that app, then scan the QR until the device becomes connected.
3. Send messages with Authorization: Bearer <app_token>.
4. Configure webhook path so inbound messages, receipts, forwarded-message context, and device lifecycle events are pushed automatically to your backend.
5. Fetch attachments using GET /media?path=... when webhook payload includes media_path.

App Token Policy (Important)

• Direct runtime integration: your backend must send Authorization: Bearer <app_token> on WA runtime calls.
• Mantap Messenger Management: operators do not need to paste app token manually; Mantap backend resolves and manages token state server-side.
• Rotate app token after credential exposure, role change, or planned key hygiene.
• Never embed app token in frontend bundles, browser local storage, or logs.

Webhook Behavior You Can Rely On

• Event message is emitted automatically on new inbound and outbound messages.
• Event delivery transport is fixed to POST with JSON body (Content-Type: application/json).
• Non-2xx and network failures are retried with backoff: 10s, 30s, 90s.
• X-WA-Request-ID is stable per event across retries for easier end-to-end tracing.
• Webhook secret is not sent in plain text; only HMAC signature headers are sent.
• If webhook path is relative, runtime needs base URL (project domain URL or WEBHOOK_BASE_URL) to build destination URL.

High-Impact Endpoints You Will Use Daily

• POST /devices/{device_id}/messages - send text and attachments.
• POST webhook_url - receive message, receipt, lifecycle, and presence events.
• GET /media?path={media_path} - retrieve binary media from webhook payload.

Server Connection Checklist

• Gateway health: GET /health should return ok.
• Device session readiness: wait until device status is connected before send operations.
• If send fails with connection-related errors, run POST /devices/{device_id}/disconnect then regenerate QR via POST /devices/{device_id}/qr.
• If Mantap page and direct runtime responses differ, treat it as backend proxy/session path issue first, not frontend rendering.

Access Modes (Simplified)

• Documentation routes under /docs/* are public and do not require auth headers.
• For internal Onebrick engineer flow via Mantul, API calls are device_id-only and auth is resolved server-side.
• Base URL for WA Gateway runtime: https://wa.onebrick.io.
• Direct runtime integration uses Authorization: Bearer <app_token>.