messenger

Original source / Raw SKILL.md

---
name: messenger
description: OpenClaw skill for Facebook Messenger Platform workflows, including messaging, webhooks, and Page inbox operations using direct HTTPS requests.
---

# Facebook Messenger API Skill (Advanced)

## Purpose
Provide a production-oriented guide for Messenger Platform workflows: sending messages, handling webhooks, and managing Page messaging using direct HTTPS calls.

## Best fit
- You need bot-style messaging in Facebook Messenger.
- You want clean webhook handling and message UX.
- You prefer direct HTTP requests rather than SDKs.

## Not a fit
- You need advanced Graph API Ads or Marketing workflows.
- You must use complex browser-based OAuth flows.

## Quick orientation
- Read `references/messenger-api-overview.md` for base URLs and core object map.
- Read `references/webhooks.md` for verification and signature validation.
- Read `references/messaging.md` for Send API fields and message types.
- Read `references/permissions-and-tokens.md` for token flow and required permissions.
- Read `references/request-templates.md` for concrete HTTP payloads.
- Read `references/conversation-patterns.md` for UX flows (get started, menu, fallback).
- Read `references/webhook-event-map.md` for event types and routing.

## Required inputs
- Facebook App ID and App Secret.
- Page ID and Page access token.
- Webhook URL and verify token.
- Message UX and allowed interactions.

## Expected output
- A clear messaging workflow plan, permissions checklist, and operational guardrails.

## Operational notes
- Validate signatures on all webhook events.
- Keep replies short and acknowledge quickly.
- Handle rate limits and retries with backoff.

## Security notes
- Never log tokens or app secrets.
- Use least-privilege permissions.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/messenger-api-overview.md

```markdown
# Messenger Platform Overview

## 1) Base URL and request style
- Base: `https://graph.facebook.com`
- Use a pinned version: `/vXX.X`.
- Send API via Page access token.

## 2) Core objects
- `Page`, `User`, `Conversation`, `Message`.
- Webhook events for messaging.

## 3) High-level flow
- Obtain Page access token.
- Configure webhook subscription.
- Receive messages, reply via Send API.

## 4) Common errors
- `4xx` for permissions/validation.
- `5xx` for transient errors.

```

### references/webhooks.md

```markdown
# Webhooks

## 1) Verification (GET)
- Expect `hub.mode`, `hub.verify_token`, `hub.challenge`.
- Respond with `hub.challenge` to confirm.

## 2) Signature validation
- Validate `X-Hub-Signature-256` with your app secret.

## 3) Events
- `messages`, `messaging_postbacks`, `messaging_optins`, `message_reads`.

## 4) Reliability
- Acknowledge quickly, process async.
- Keep handlers idempotent.

```

### references/messaging.md

```markdown
# Messaging (Send API)

## 1) Send message
- Endpoint: `POST /me/messages`
- Required fields:
  - `recipient` (id)
  - `message` (text or attachment)

## 2) Common message types
- Text: `message.text`
- Attachment: `message.attachment` (image, video, file)
- Quick replies: `message.quick_replies`

## 3) Messaging UX
- Keep messages short.
- Use quick replies for common choices.
- Include fallback text for attachments.

## 4) Read receipts and typing
- `sender_action`: `typing_on`, `typing_off`, `mark_seen`.

```

### references/permissions-and-tokens.md

```markdown
# Permissions and Tokens

## 1) Token types
- User access token (used to fetch Page token).
- Page access token (used for Send API and management).

## 2) Common permissions
- `pages_messaging`
- `pages_manage_metadata`
- `pages_show_list`

## 3) Token flow
- Obtain user token with required scopes.
- Call `/me/accounts` to fetch Page access token.
- Use Page token for messaging actions.

## 4) Operational guidance
- Use least-privilege permissions.
- Rotate tokens when possible.

```

### references/request-templates.md

```markdown
# HTTP Request Templates (Send API)

## Send text message
POST `/me/messages`
```json
{
  "recipient": { "id": "PSID" },
  "message": { "text": "Hello from the bot" }
}
```

## Send attachment (image)
POST `/me/messages`
```json
{
  "recipient": { "id": "PSID" },
  "message": {
    "attachment": {
      "type": "image",
      "payload": { "url": "https://example.com/image.jpg" }
    }
  }
}
```

## Quick replies
POST `/me/messages`
```json
{
  "recipient": { "id": "PSID" },
  "message": {
    "text": "Choose one",
    "quick_replies": [
      { "content_type": "text", "title": "A", "payload": "A" },
      { "content_type": "text", "title": "B", "payload": "B" }
    ]
  }
}
```

## Sender actions
POST `/me/messages`
```json
{
  "recipient": { "id": "PSID" },
  "sender_action": "typing_on"
}
```

```

### references/conversation-patterns.md

```markdown
# Conversation Patterns

## 1) Handover protocol (human agent)
- Use Primary/Secondary Receiver when routing to human support.
- Provide a clear system message when handing off.

## 2) Persistent menu
- Provide top-level actions (e.g., Help, Settings, Status).
- Keep labels short and consistent.

## 3) Get Started
- Use a short onboarding flow after the first interaction.
- Offer 2–3 quick replies to guide the user.

## 4) Fallbacks
- For unknown inputs, send a gentle fallback and show quick replies.
- Avoid repeating the same fallback in a loop.

## 5) Rate and tone
- Acknowledge quickly.
- Keep messages concise and action-oriented.

```

### references/webhook-event-map.md

```markdown
# Webhook Event Map

## Core events
- `messages`: inbound user messages.
- `messaging_postbacks`: button/postback payloads.
- `messaging_optins`: opt-in events.
- `message_reads`: read receipts.
- `message_deliveries`: delivery confirmations.

## Routing recommendations
- Handle postbacks before plain text.
- De-duplicate using message IDs.
- Keep handlers idempotent for retries.

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "codedao12",
  "slug": "messenger",
  "displayName": "Messenger",
  "latest": {
    "version": "1.0.1",
    "publishedAt": 1770265901454,
    "commit": "https://github.com/clawdbot/skills/commit/d05c0f7ad0c1b83a71b5057c82508ea39393e013"
  },
  "history": [
    {
      "version": "1.0.0",
      "publishedAt": 1769965501534,
      "commit": "https://github.com/clawdbot/skills/commit/89a16f4d375b288d78fbe830b6bdcb37cf6f274b"
    }
  ]
}

```