Meta DM Channel
Receive Facebook Messenger and Instagram direct messages — and comments — as webhook events, and reply, react, or show typing through the shared Send API. This page covers the Meta-specific details; the shared envelope, signing, and core actions live on the Webhook & Send API page.
Add-on · $29/month · Requires Creator+ planOverview
Facebook Messenger and Instagram DMs share one transport (Meta's Messenger Platform) and one source.channel value: meta_dm. They are the default channel — if you subscribe to message.received the moment a page is connected, events begin flowing with no further configuration.
Requirements: a connected Facebook Page and/or Instagram professional account (Settings → Connections) and the Webhook & Send API add-on active. No extra tier beyond Creator+ is required.
Inbound event types
| Event | Fires when |
|---|---|
| message.received | A customer sends a DM on Facebook or Instagram |
| message.reel_shared | A customer shares a reel into a DM thread |
| message.post_shared | A customer shares a regular post into a DM thread |
| comment.received | A customer comments on one of your posts or reels (independent of comment triggers) |
Supported send actions
Meta DM supports all four Send API actions: send_message, react, unreact, and typing_on — the only channel that supports reactions. Full request/response detail for each is on the Send-Reply API reference.
Inbound Payload
A DM event uses the standard envelope. source.platform is facebook or instagram; source.channel is always meta_dm.
{
"event_id": "a3f8e1c2d4b567890abcdef012345678",
"event_type": "message.received",
"occurred_at": "2026-02-20T08:15:00Z",
"source": {
"platform": "instagram",
"channel": "meta_dm"
},
"conversation": {
"id": 10482
},
"customer": {
"platform_user_id": "17841400123456789",
"platform_user_name": "Jane Doe",
"platform_user_username": "janedoe"
},
"message": {
"id": "mid.1234567890abcdef",
"text_raw": "Hi, do you have availability next Tuesday?",
"attachments": []
},
"meta": {
"version": "v1",
"payload_profile": "full",
"generated_at": "2026-02-20T08:15:00Z"
}
}Meta-specific fields
| Field | Type | Description |
|---|---|---|
| source.platform | string | facebook or instagram |
| customer.platform_user_id | string | The platform-assigned user ID (PSID). Pass this as platform_user_id to the Send API. Always present. |
| customer.platform_user_name | string|null | Display name. Present in full profile only. |
| customer.platform_user_username | string|null | Instagram @handle (no @). null for Facebook. Present in full profile only. |
| message.id | string | Platform message ID. Use as target_message_id when adding a reaction. |
| message.attachments | array | Media the customer sent. See the attachment fields on the Event Payload reference. Reel and post shares arrive as message.reel_shared / message.post_shared with the same envelope. |
Comment Payload
A comment.received event fires for every comment on your Instagram or Facebook posts and reels — you don't need a ChatGenius comment trigger configured. It replaces the message object with a source_post object (the post the comment was left on) and a comment object. Use source_post.id as the stable attribution join key.
When the comment also matched one of your comment triggers, comment.trigger_id, comment.trigger_name, comment.matched_keyword, and source_post.url are populated; otherwise those fields are null.
{
"event_id": "b7c2e1a4f9d063518adef0129876dcba",
"event_type": "comment.received",
"occurred_at": "2026-02-20T08:15:00Z",
"source": {
"platform": "instagram",
"channel": "meta_dm"
},
"conversation": {
"id": null
},
"customer": {
"platform_user_id": "17841400123456789",
"platform_user_name": null,
"platform_user_username": "janedoe"
},
"source_post": {
"id": "17912345678901234",
"url": "https://www.instagram.com/p/CtExAmple/"
},
"comment": {
"id": "17987654321098765",
"text_raw": "PRICE",
"matched_keyword": "price",
"trigger_id": 42,
"trigger_name": "Pricing DM",
"source_type": "comment"
},
"meta": {
"version": "v1",
"payload_profile": "full",
"generated_at": "2026-02-20T08:15:00Z"
}
}| Field | Type | Description |
|---|---|---|
| conversation.id | integer|null | Always null for comments (no conversation yet). The follow-up DM arrives as a separate message.received event with a populated id. |
| source_post.id | string | ID of the post/reel the comment was left on. Always present — the attribution join key. |
| source_post.url | string|null | Permalink. Populated only when the comment matched a trigger targeting a specific post; null otherwise. |
| comment.id | string | Platform comment ID. |
| comment.matched_keyword | string|null | The trigger keyword matched, or null when no trigger matched. |
| comment.trigger_id / trigger_name | integer / string | null | The matched comment trigger, or null. |
| comment.source_type | string | comment, story, live, or both — the surface the trigger fired on. |
Sending on Meta DM
Route by conversation_id, or by platform (facebook / instagram) plus platform_user_id (the customer's PSID). All four actions — send_message, react, unreact, typing_on — are documented in full on the Send-Reply API reference. Text limits: 1,000 chars on Instagram, 2,000 on Facebook.
curl -X POST https://sumgenius.ai/api/meta/webhook-send.php \
-H "X-SumGenius-Api-Key: sgwh_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"idempotency_key": "confirm-appt-10482-001",
"conversation_id": 10482,
"message_text": "Your appointment is confirmed for Tuesday at 2pm."
}'The Messaging Window
Meta restricts when a business can message a customer. This is a platform rule, enforced by Meta — not a ChatGenius limit.
- Standard 24-hour window. After a customer's last message, you have 24 hours to reply freely.
- 7-day human-agent extension. When a human agent needs more time, Meta's human-agent tag extends the window to 7 days. ChatGenius applies this tag automatically when appropriate, so agent replies within 7 days go through without extra work on your side.
- Outside the window, a send is rejected with "Meta 7-day window expired." or "Cannot send: customer has not initiated a valid messaging window." These are permanent failures — they are not retried, and if you subscribe to message.send_failed you receive an event so your system can reconcile.