Channels

Channels let one agent talk to customers outside the web widget. Use them when the customer starts in a messaging app, but you still want Kravos.ai to create the end user, store the conversation, run the agent, and show the thread in the dashboard.

How Channel Messages Flow

1. Meta sends a signed webhook to the web app domain.
2. Kravos.ai verifies the provider signature against the raw request body.
3. The handler normalizes provider-specific payloads into one inbound message shape.
4. The handler deduplicates the provider message ID in Redis for 24 hours.
5. A channel-inbound BullMQ job creates or updates the end user, conversation, and message.
6. If the conversation is AI_ACTIVE, the worker calls the agent runtime.
7. Any AI reply is queued as channel-outbound and sent back through Meta Graph API.

Supported Channel Behavior

Configuration Sources

Channel setup uses two kinds of configuration.

Deployment environment variables

These are used by the implemented Meta webhook handlers and outbound sender:

Tenant channel config rows

ChannelConfig rows store tenant-level channel metadata:

• channel
• isActive
• encrypted credentials
• JSON settings
• optional webhookUrl

Credentials are encrypted and write-only. Platform MCP tools can list channel metadata and update or create channel configs without returning the encrypted credentials.

How Inbound Routing Works

Kravos.ai tries to route each incoming WhatsApp or Messenger message in this order:

1. Find the latest existing conversation for the same external user ID and channel.
2. If no conversation exists, find an active ChannelConfig for that channel.
3. If exactly one tenant has an active config, use that tenant's oldest active agent.
4. If no config exists, no active agent exists, or multiple tenants are active for the same channel, return 503.

For multi-tenant deployments using one shared Meta app, avoid ambiguous first-message routing. Use separate provider apps per tenant, or keep only one active ChannelConfig per channel for first-contact fallback.

Channel Settings Status

The authenticated endpoint GET /api/settings/channels reports deployment readiness for WhatsApp and Messenger.

It returns:

• the app URL being used
• the WhatsApp webhook URL
• the Messenger webhook URL
• booleans for each required environment variable
• configured: true only when every requirement for that channel is present

This status endpoint is read-only. It does not create Meta apps, create ChannelConfig rows, or save access tokens.

Testing Channels

Start with a provider challenge test, then test a real message.

1. Confirm /api/settings/channels shows a webhook URL and all required booleans are true.
2. In Meta, verify the webhook URL with the same META_VERIFY_TOKEN configured in Kravos.ai.
3. Send a real WhatsApp or Messenger test message.
4. Confirm the webhook response is 200 and the response body has data.received: true.
5. Confirm the worker is running so channel-inbound and channel-outbound jobs are processed.
6. Open the conversation in the dashboard and verify the end user identity and messages.

Reliability And Duplicates

• Meta inbound messages are deduplicated for 24 hours with dedupe:{channel}:{providerMessageId}.
• Inbound messages also use a database uniqueness check on conversationId and channelMessageId.
• Outbound channel messages use a 7-day Redis dedupe key before persisting the provider message ID.
• channel-inbound jobs retry 5 times with exponential backoff starting at 2 seconds.
• channel-outbound jobs retry 3 times with exponential backoff starting at 2 seconds.
• There is no separate dead-letter queue. Failed jobs are retained in BullMQ up to the configured failed-job retention count.

Related Docs

WhatsApp Setup

Configure Meta WhatsApp Cloud API webhooks and outbound replies.

Messenger Setup

Configure Facebook Messenger webhooks, Page replies, and echo handling.

Incoming Webhooks

Review webhook verification, dedupe, retries, and troubleshooting.