On-Site Documentation

3CX Middleware Troubleshooting

Common 3CX middleware errors, likely causes, and safe fixes.

Download PDF Overview Quickstart Connect Instance Send Messages Receive Webhooks Responsible Messaging 3CX Overview 3CX Webhooks 3CX Call Events 3CX Troubleshooting n8n Integration Endpoint Map OpenAPI SDK Overview PHP Examples Node.js Examples Python Examples Postman Collection Troubleshooting

Troubleshooting

Common issues

Pre-authentication errors

Before a 3CX webhook request is authenticated, WhatsApp Gateway returns a generic response for missing or wrong secrets, unknown or disabled integrations, IP allowlist failures, stale timestamps, and invalid signatures.

{
  "success": false,
  "error": "invalid_3cx_webhook",
  "message": "Invalid 3CX webhook request."
}

Specific pre-authentication reasons are recorded only in internal/admin logs where available.

`invalid_3cx_webhook`

Cause: The request could not be authenticated before processing.

Fix: Check the integration URL, webhook secret, optional IP allowlist, timestamp, and HMAC signature.

`payload_too_large`

Cause: Webhook body exceeds 256KB.

Fix: Reduce payload.

`webhook_rate_limited`

Cause: More than 60 requests per minute per integration.

Fix: Slow down the event sender.

`invalid_json`

Cause: Request body is not valid JSON.

Fix: Send a valid JSON payload with Content-Type: application/json.

`module_not_enabled`

Cause: 3CX Middleware is not enabled for the account.

Fix: Enable 3CX in the module settings or contact support.

`conversation_window_closed`

Cause: The recipient has not messaged first or the last inbound WhatsApp message is outside the active conversation window.

Fix: Ask the customer to message the WhatsApp number first, then reply from 3CX within the active window.

`outbound_disabled`

Cause: Outbound messaging disabled in integration settings.

Fix: Enable outbound.

`call_events_disabled`

Cause: Call events disabled.

Fix: Enable call events.

`missing_phone`

Cause: Event payload does not include customer phone.

Fix: Include to, from, customer_phone, caller, or phone.

`missing_message_text`

Cause: Outbound event does not include message text.

Fix: Include message_text or message in the event payload.

`message_purpose_not_allowed`

Cause: The message purpose is missing or not allowed.

Fix: Use support, operational, transactional, internal_team, or authentication.

`recipient_suppressed`

Cause: Recipient opted out or was blocked.

Fix: Review suppressed recipients.

`sending_throttled`

Cause: Sending speed was temporarily limited.

Fix: Retry later and review sending volume.

`gateway_send_failed`

Cause: Delivery could not be completed after responsible messaging checks.

Fix: Retry later or contact support if it continues.

`daily_message_limit_exceeded`

Cause: Customer plan limit reached.

Fix: Request a higher reviewed limit.

`policy_violation`

Cause: Message blocked by responsible messaging policy.

Fix: Review purpose, content, recipient source, and usage pattern.