Messenger Setup

Messenger setup connects a Facebook Page to one Kravos.ai deployment. Customer messages arrive as Meta webhooks, and Kravos.ai sends replies through the configured Page.

Required Kravos.ai Configuration

The channel settings status endpoint reports this readiness at GET /api/settings/channels.

Meta Setup Checklist

1. Create or choose your Meta app and add Messenger.
2. Connect the Facebook Page that should send and receive messages.
3. Create a Page access token that can send messages for that Page.
4. Set META_PAGE_ID to the Page ID.
5. Set the callback URL to:

https://your-web-app.example.com/api/webhooks/messenger

1. Enter the same verify token that you configured as META_VERIFY_TOKEN.
2. Subscribe the Page webhook to message events.
3. Subscribe to message echo events if you want manual Page replies to pause AI in Kravos.ai.
4. Create or activate a tenant ChannelConfig for MESSENGER when you need first-message fallback routing.

What The Messenger Webhook Accepts

Challenge request

Meta verifies the URL with a GET request that includes:

When the token matches, Kravos.ai returns the raw challenge text with status 200. Invalid tokens return 403. Missing META_VERIFY_TOKEN returns 503.

Message delivery request

Meta delivers messages with POST /api/webhooks/messenger.

Implemented behavior:

• reads the raw request body before parsing JSON
• verifies x-hub-signature-256 with HMAC SHA-256 and META_APP_SECRET
• returns 401 for missing or invalid signatures
• returns 400 for invalid JSON
• extracts messages from entry[].messaging[]
• uses message.mid as the provider message ID
• uses sender.id as the customer Page-scoped ID for inbound customer messages
• deduplicates provider message IDs for 24 hours
• enqueues channel.inbound jobs for new customer messages

Manual Replies And Echo Events

Messenger can send echo events when the business replies manually from the Page inbox. The implemented handler treats message.is_echo: true as a manual business reply.

For echo events, Kravos.ai:

1. resolves the end user from the echo recipient ID
2. finds matching AI_ACTIVE Messenger conversations
3. changes those conversations to HUMAN_ACTIVE
4. returns echoCount in the webhook response
5. does not enqueue an inbound AI-processing job

This prevents the AI from replying over a human Page agent.

Message Support

Messenger profile lookup is best-effort. If META_MESSENGER_ACCESS_TOKEN or META_ACCESS_TOKEN is available, the worker requests the sender's name, first_name, last_name, and profile_pic. Lookup failures do not block message processing.

Testing Messenger

Use Meta's webhook verification first. Then send a test message to the connected Facebook Page.

A successful customer message returns:

{
  "data": {
    "received": true,
    "deduped": false,
    "dedupedCount": 0,
    "enqueued": 1,
    "echoCount": 0
  }
}

A manual Page reply echo can return echoCount: 1 and enqueued: 0.

Troubleshooting

Meta cannot verify the webhook

• Confirm the public URL is HTTPS and points to /api/webhooks/messenger.
• Confirm META_VERIFY_TOKEN exactly matches the token entered in Meta.
• Confirm the Meta app and Page subscription are active.

POST returns 401

• Confirm META_APP_SECRET belongs to the same Meta app sending the webhook.
• Confirm the request still has the original raw body when signature verification runs.

POST returns 503

• Check for missing META_APP_SECRET.
• Confirm there is an active ChannelConfig for MESSENGER if this is a first-time user.
• In multi-tenant deployments, confirm first-message routing is not ambiguous across multiple tenants.

AI replies after a human replied in Messenger

• Confirm Meta is sending echo events with message.is_echo: true.
• Confirm the echo recipient ID matches the stored end user's Messenger ID.
• Confirm the conversation was still AI_ACTIVE before the manual reply.

Related Docs