Skip to content

Updated CLI walkthrough for setting up with Facebook #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jreakin merged 2 commits into from
Jan 30, 2026
Merged

Updated CLI walkthrough for setting up with Facebook #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5b1b763
Updated CLI walkthrough for setting up with Facebook
jreakin Jan 29, 2026
7c155a8
Added testing for new changes
jreakin Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,3 +84,4 @@ Desktop.ini
# Project-specific
# Note: .python-version is kept for uv/python version management
# Remove this line if you want to ignore it
WEBHOOK_INFO.txt
81 changes: 81 additions & 0 deletions docs/FACEBOOK_SETUP_QUICK.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# Facebook Setup Quick Reference

## Get Your Credentials

### 1. Create Facebook App (5 min)

1. Go to https://developers.facebook.com/apps
2. Click "Create App" → Choose "Business"
3. Name: "Your Bot Name"
4. Complete security check

### 2. Add Messenger (2 min)

1. In app dashboard → "Add Products" → "Messenger"
2. Click "Set Up"

### 3. Get Page Access Token (3 min)

1. Messenger Settings → "Access Tokens"
2. Click "Add or Remove Pages"
3. Select your page → Grant permissions
4. Click "Generate Token"
5. **Copy immediately!** (Starts with EAAA...)

### 4. Find Page ID (1 min)

- Look in the page dropdown in Access Tokens
- Format: 15-digit number like `123456789012345`
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation says "15-digit number" but the validation in setup_cli.py accepts 15-17 digits. Consider updating to "15-17 digit number" to match the actual validation and avoid user confusion.

Copilot uses AI. Check for mistakes.

### 5. Create Verify Token (1 min)

- Use: `openssl rand -base64 32`
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The suggested command openssl rand -base64 32 will generate tokens with /, +, and = characters that fail the validation regex in setup_cli.py which only accepts [a-zA-Z0-9_-]. Consider changing to openssl rand -hex 16 which produces 32 hex characters that will pass validation.

Suggested change
- Use: `openssl rand -base64 32`
- Use: `openssl rand -hex 16`

Copilot uses AI. Check for mistakes.
- Or create your own: `my-bot-verify-2024`
- **Save it** — you need this for webhook setup!

## Run CLI Setup

```bash
uv run python -m src.cli.setup_cli setup
```

Paste when prompted:

- Website URL
- Page ID (15 digits)
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation says "Page ID (15 digits)" but the validation accepts 15-17 digits. For consistency, update to "(15-17 digits)" to match the actual validation.

Suggested change
- Page ID (15 digits)
- Page ID (15-17 digits)

Copilot uses AI. Check for mistakes.
- Page Access Token (EAAA...)
- Verify Token (your choice, or press Enter for random)

Type `?` at any credential prompt for detailed help on where to find it.

## Deploy and Configure Webhook

After deploying to Railway:

1. Get Railway URL: `https://your-app.railway.app`
2. Facebook App → Messenger → Webhooks
3. Add Callback URL: `https://your-app.railway.app/webhook`
4. Enter Verify Token (same as CLI setup)
5. Subscribe to: `messages`
6. Subscribe your page

## Troubleshooting

**Token invalid?**

- Regenerate in Messenger Settings
- Copy the entire token (starts with EAAA, 100+ characters)

**Webhook verification failed?**

- Check verify token matches exactly what you entered in CLI
- Ensure app is deployed and running
- Test: `https://your-app.railway.app/health`

**Messages not arriving?**

- Page subscribed to webhook?
- "messages" subscription checked?
- Check Railway logs: `railway logs`

For more operational issues, see [RUNBOOK.md](../RUNBOOK.md).
Loading
Loading