Production integration

This guide shows the normal production flow for a WaGo customer deployment. The user runs the WaGo binary on their server, then their own app calls the HTTP API.

Architecture

Your app or dashboard
  -> WaGo HTTP API
  -> WhatsApp connection
  -> WhatsApp users and groups

WaGo webhook
  -> Your backend webhook receiver
  -> Your database, jobs, CRM, inbox, or automation

Keep WaGo and your app separated:

Part	Responsibility
WaGo	WhatsApp session, QR scan, sending, receiving, media, calls, webhooks.
Your backend	User login, permissions, token ownership, business rules, database, billing, webhook processing.
Your frontend	Session status UI, QR display, inbox UI, send forms, call UI.

Step 1: Store the WaGo token in your app

Each connected WhatsApp account uses a WaGo session token. Your app should map that token to your own user, team, workspace, or customer. If the token does not exist yet, create it with POST /session/init from a trusted backend. See Create a token for the full admin flow. Example database shape:

Field	Example
`workspace_id`	`workspace_123`
`wago_token`	`customer-token-1`
`wago_jid`	`[email protected]`
`webhook_url`	`https://app.example.com/wago/webhook`
`connected`	`true`
`logged_in`	`true`

Do not expose your admintoken to the frontend. If your product creates WaGo tokens for users, do that from your backend.

Step 2: Configure webhooks

Set the webhook URL for the token:

curl -X POST http://localhost:1337/webhook \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d '{
    "WebhookURL": "https://app.example.com/wago/webhook"
  }'

Then connect with the event types your app needs:

curl -X POST http://localhost:1337/session/connect \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d '{
    "Subscribe": ["Message", "ReadReceipt", "Presence", "ChatPresence", "Call", "LoggedOut"],
    "Immediate": true,
    "Phone": ""
  }'

Use ["All"] when building the first version. Reduce the list when your app is stable.

Step 3: Show scan status

Your frontend can poll:

curl -H "token: YOUR_TOKEN" \
  http://localhost:1337/session/status

Use these fields:

Field	Meaning
`Connected`	WaGo has an active WhatsApp connection.
`LoggedIn`	The device has been scanned and authenticated.
`Jid`	The connected WhatsApp account. Store it after scan.
`Events`	Subscribed event types.

If the session is not logged in, fetch the QR:

curl -H "token: YOUR_TOKEN" \
  http://localhost:1337/session/qr

Render QRCode as an image in your UI.

Step 4: Send a message

curl -X POST http://localhost:1337/send/text \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d '{
    "Phone": "15551234567",
    "Body": "Hello from WaGo"
  }'

Store the returned message ID. You need it for read receipts, message status, reactions, edits, and delete operations.

Step 5: Receive messages

Your webhook receives form data:

Form field	Use
`token`	Find the customer/session in your database.
`jsonData`	Parse as JSON and process the event.
`file`	Optional uploaded media file when WaGo forwards downloaded media.

Minimal receiver behavior:

Parse form data.
Parse jsonData.
Store the raw event.
Store key indexes such as token, type, message ID, chat JID, sender JID, and timestamp.
Save uploaded files before responding.
Respond with 2xx quickly.
Queue slow actions after the response.

See Webhook events for event examples.

Step 6: Handle media

For outbound media, choose one of two patterns:

Pattern	Use when
Base64 data URL	Files are small and already available in your app.
Direct URL	Files are large or already stored in object storage/CDN.

For inbound media, use webhook file forwarding if enabled. If you do not receive the file, use the media metadata from the message event and call the matching download endpoint.

Step 7: Production troubleshooting flow

When something fails, check in this order:

GET /server/ok to confirm the binary is reachable.
GET /session/status to confirm token, connection, and login.
GET /webhook to confirm webhook URL and subscriptions.
Server logs for the request status and WhatsApp error.
Your webhook receiver logs for delivery and parse errors.
The local API explorer at http://localhost:1337/api for a direct endpoint test.

Common production mistakes

Problem	Fix
Frontend uses `admintoken`	Move admin calls to your backend.
QR page never updates	Poll `/session/status` and refresh `/session/qr` only when needed.
Messages send but app does not update	Subscribe to `ReadReceipt` and store webhook events.
Media fails through proxy	Increase request body size and timeout limits.
Webhooks arrive multiple times	Deduplicate by message ID or event key.
Browser calls fail in production	Use HTTPS for both your app and WaGo API.
Calls work locally but not for some users	Network may require TURN, which is currently marked coming soon.

​Architecture

​Step 1: Store the WaGo token in your app

​Step 2: Configure webhooks

​Step 3: Show scan status

​Step 4: Send a message

​Step 5: Receive messages

​Step 6: Handle media

​Step 7: Production troubleshooting flow

​Common production mistakes