Troubleshooting

The most common failures, and the one-line fix.

401 Unauthorized

Your JWT is missing, malformed, or expired. Re-authenticate and resend with Authorization: Bearer <jwt>. On the WebSocket you'll get an error event with AUTH_MISSING or AUTH_INVALID before the socket disconnects — pass the token in auth.token.

403 Forbidden

You're authenticated but your role lacks the permission. Check your chat_rights[]:

Sending needs update ≠ D on the provider; read-only agents get 403 on send/edit/delete.
Filtering the inbox by another agent (assigned_admin_slugs) needs full access (read = A) or super-admin.

404 on a session or chat you "know" exists

Not always missing — a session/chat outside your visibility is masked as 404. If you should see it, your read level is too low (you're M/G, it's someone else's). Raise the level or reassign the record.

400 on send

type=text with no body → "Body is required". Send a non-empty body.
Media type with no file → "Files required for media messages". Use multipart/form-data with the files field.
Bad :providerType in the URL → enum validation 400. Use one of WAHA | WHATSAPP_CLOUD | FACEBOOK | INSTAGRAM | TIKTOK.

The message "sends" but never arrives

Sending is async — the API returns { success: true } before the provider delivers. Watch the message-ack WebSocket event for the real status. If it never acks: the session may be disconnected (check session.status.updated / the session status) or the provider rejected it (e.g. WhatsApp Cloud 24-hour window).

Edit/delete does nothing

Only WAHA supports edit and delete. On Cloud/Facebook/Instagram/TikTok those capabilities aren't available.

Inbound messages don't show up

The provider webhook isn't reaching you or failed signature checks. Verify the provider is pointed at /api/v1/messaging/webhook/<provider> and the secret (WAHA_HMAC_SECRET, WHATSAPP_CLOUD_APP_SECRET, FACEBOOK_APP_SECRET, …) matches — a bad signature returns 401. See Webhooks.