# Messenger Overview

> Facebook Messenger and Marketplace chat messaging through your Facebook Page

The Messenger channel lets you receive and reply to Facebook Messenger conversations — including **Facebook Marketplace chats** — through your Facebook Page, using the same unified API as every other Zavu channel.

## When to Use Messenger

- **Marketplace sellers**: Reply to buyer inquiries on your listings, automatically or from the Inbox
- **Customer support**: Handle Page messages alongside WhatsApp, SMS, and Email in one place
- **AI agents**: Let a Zavu AI Agent answer Messenger conversations 24/7

## Basic Messenger Message

```typescript
const result = await zavu.messages.send({
  to: "24025631120151183", // Messenger user ID (PSID)
  text: "Thanks for your message!",
  channel: "messenger",
});
```

```bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "24025631120151183",
    "text": "Thanks for your message!",
    "channel": "messenger"
  }'
```

## Facebook Marketplace Chats

When a buyer messages your Page from a Marketplace listing, the conversation arrives through the same Messenger channel:

1. A buyer taps **Message** on your Marketplace listing
2. Zavu receives the message via your connected Facebook Page and creates a contact + conversation
3. You receive a `message.inbound` webhook (or your AI Agent replies automatically)
4. Reply from the Inbox, via the API, or let your agent handle it

> **Note:**
> Marketplace conversations follow the same rules as regular Page messages: same user IDs, same 24-hour window, same API.

## User IDs vs Phone Numbers

Like Telegram and Instagram, Messenger uses numeric user IDs (PSIDs — Page-Scoped IDs) instead of phone numbers:

```
Phone-based channels:  +14155551234
Messenger:             24025631120151183
```

> **Warning:**
> You cannot message a Messenger user by phone number. The user must message your Page first — their PSID arrives in the `from` field of the inbound message (prefixed as `messenger:{id}` in contacts and conversations).

PSIDs are scoped per Page: the same person has a different ID for each Facebook Page they talk to.

## 24-Hour Messaging Window

Messenger enforces a standard messaging window:

- You can reply freely within **24 hours** of the user's last message
- Outside the window, Meta rejects the send and the message fails with a clear error
- There are no pre-approved templates like WhatsApp — the user must message again to reopen the window

## Message Types

| Type | Use Case |
|------|----------|
| Text | Simple replies |
| Image | Photos and graphics |
| Video | Video clips |
| Audio | Voice notes |
| Document | Files and attachments |

## Delivery Status

| Status | Description |
|--------|-------------|
| `queued` | Message accepted by Zavu |
| `sending` | Being sent to Meta |
| `sent` | Accepted by Messenger |
| `failed` | Delivery failed (e.g., window closed) |

## Setup Requirements

Before sending Messenger messages, you need to:

1. A Facebook Page (the Page your Marketplace listings or business uses)
2. Connect the Page in your Zavu sender settings via Meta login

See [Messenger Setup](https://www.zavu.dev/docs/guides/messenger/setup) for detailed instructions.

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `24-hour messaging window closed` | User hasn't messaged in 24h | Wait for the user to message again |
| `Messenger requires a Facebook Page to be connected` | Channel not configured | Connect a Page in sender settings |
| `Invalid user ID` | Wrong PSID | Use the PSID from the inbound message |

## Next Steps

- [Messenger Setup](https://www.zavu.dev/docs/guides/messenger/setup) - Connect your Facebook Page
- [Receiving Messages](https://www.zavu.dev/docs/guides/receiving-messages/webhooks) - Handle inbound webhooks
- [AI Agents](https://www.zavu.dev/docs/guides/ai-agents/overview) - Auto-reply to Messenger chats