Chatwoot WhatsApp Cloud Integration — "Inactive WhatsApp Channel" Issue¶

Overview¶

During the setup of a WhatsApp Cloud channel in Chatwoot v4, messages were received correctly by the webhook but were not being delivered to agents or creating conversations. The following warning appeared in the Sidekiq logs:

cd /usr/src/chatwoot_v4/
docker compose logs -f rails | egrep -i 'whatsapp|webhook|webhooks'

Inactive WhatsApp channel: unknown - +94785407992

This document explains why this occurs and how to fix it.

Symptoms¶

Incoming WhatsApp messages reach the server (verified through HAProxy or Nginx logs).

Rails logs show the webhook being processed:

Processing by Webhooks::WhatsappController#process_payload

Sidekiq enqueues the job Webhooks::WhatsappEventsJob, but the log ends with:
```
Inactive WhatsApp channel: unknown - +94785407992
```
No conversations or messages appear in Chatwoot.

Root Cause¶

The WhatsApp channel (Channel::Whatsapp) was missing the phone_number field in its provider_config.

When Chatwoot receives a webhook request at a URL that includes the number (for example,
/webhooks/whatsapp/+94785407992), it tries to locate the channel using that E.164 number (phone_number).

If the provider_config lacks this field, Chatwoot cannot map the webhook event to the correct channel, resulting in the “Inactive WhatsApp channel” warning.

In this specific case: - provider_config['phone_number'] → nil - provider_config['phone_number_id'] → valid (e.g., "861598397034234") - Therefore, the channel existed, but Chatwoot could not match it using the number in the URL.

How to Diagnose¶

Check existing WhatsApp channels

docker compose exec rails sh -lc "bin/rails c <<'RUBY'
Channel::Whatsapp.includes(:inbox).find_each do |ch|
  inb = ch.inbox
  puts({
    channel_id: ch.id,
    inbox_id: inb&.id,
    inbox_name: inb&.name,
    account_id: inb&.account_id,
    enabled: (ch.respond_to?(:enabled) ? ch.enabled : true),
    provider_phone_number: (ch.provider_config['phone_number'] rescue nil),
    provider_phone_number_id: (ch.provider_config['phone_number_id'] rescue nil)
  })
end
RUBY"

If provider_phone_number is nil, this issue applies.

Confirm the warning in logs

docker compose logs -f sidekiq | grep 'Inactive WhatsApp channel'

Solution¶

Option 1 — Add the phone number to the channel¶

Run the following command in the Chatwoot Rails console:

docker compose exec rails sh -lc "bin/rails c <<'RUBY'
ch = Channel::Whatsapp.find(<CHANNEL_ID>)
cfg = ch.provider_config
cfg['phone_number'] = '+94785407992'             # E.164 format
cfg['phone_number_id'] ||= '861598397034234'     # The real phone_number_id from Meta
ch.provider_config = cfg
ch.enabled = true if ch.respond_to?(:enabled)
ch.save!
RUBY"

This explicitly sets the phone number in provider_config, allowing Chatwoot to match incoming webhooks that include the number in the URL.

Option 2 — Change the Callback URL (recommended)¶

Instead of including the phone number in the webhook path, configure Meta’s Callback URL as:

https://your-domain/webhooks/whatsapp

This route matches the webhook using the phone_number_id, which is already present in the configuration and avoids dependency on the phone_number field.

Verification¶

Send a real message to the WhatsApp number (not the “Send Test” payload from Meta, which uses static IDs).

Monitor logs:

docker compose logs -f sidekiq | grep WhatsappEventsJob
docker compose logs -f rails | grep 'Webhooks::WhatsappController'

The warning should no longer appear.

Check conversations in Chatwoot. A new conversation should be created in the corresponding inbox.

Preventive Measures¶

Always include both:
phone_number (E.164 format)
phone_number_id (from Meta)
Use the base webhook path (/webhooks/whatsapp) to avoid number-based mapping.
If the channel is created via API or script, ensure both values are saved to provider_config.
Re-save the channel after updating Meta credentials or tokens.

Summary¶

Problem	Root Cause	Solution
Webhook events logged but no messages delivered	Missing `provider_config['phone_number']`	Add the `phone_number` field or remove number from webhook path
Warning: “Inactive WhatsApp channel: unknown - +94785407992”	Chatwoot cannot match channel using phone number	Ensure both `phone_number` and `phone_number_id` are set correctly
Still not receiving messages	Using “Send test” sample payload with static data	Send a real WhatsApp message from a tester or live user

Issue resolved: Once the phone_number was saved in the channel’s provider_config, incoming WhatsApp messages were successfully processed and delivered to the assigned inbox.