Guide: Setting Up Discourse Forum Integration

[system]

Setting Up Discourse Forum Integration

Connect OpenPawz to your Discourse forum and let your agents manage topics, posts, users, and more.

---

Prerequisites

• A Discourse forum (self-hosted or hosted)
• Admin access to create an API key

---

Step 1: Create a Discourse API Key

1. Go to your Discourse admin panel: https://yourforum.com/admin/api/keys
2. Click New API Key
3. Configure:
   • Description: OpenPawz Integration
   • User Level: Single User
   • User: Select your bot account (or system for full admin access)
   • Scope: Global (all endpoints) — or limit to specific endpoints
4. Click Save and copy the API key

Important: The API Username must be an actual Discourse username (like system or your bot account), not the key description.

---

Step 2: Configure in OpenPawz

1. Open Settings → Integrations
2. Find Discourse and click Configure
3. Enter:
   • Forum URL: https://yourforum.com (no trailing slash)
   • API Key: The key you created
   • API Username: system or your bot username
4. Click Test Connection to verify

---

Step 3: Test the Connection

Ask your agent:

Test the Discourse connection

The discourse_test_connection tool runs a 3-step diagnostic:

1. Reachability — can we reach the forum?
2. Authentication — is the API key valid?
3. Functional — can we list categories?

---

Available Tools (51 total)

Topics (12 tools)

• discourse_list_topics — List topics with filters
• discourse_get_topic — Read a topic and its posts
• discourse_create_topic — Create a new topic
• discourse_update_topic — Edit title, category, tags
• discourse_close_topic / discourse_open_topic
• discourse_pin_topic / discourse_unpin_topic
• discourse_archive_topic
• discourse_delete_topic
• discourse_invite_to_topic
• discourse_set_topic_timer

Posts (8 tools)

• discourse_reply — Reply to a topic
• discourse_edit_post — Edit post content
• discourse_delete_post
• discourse_like_post / discourse_unlike_post
• discourse_get_post
• discourse_post_revisions — View edit history
• discourse_wiki_post — Toggle wiki mode

Categories (5 tools)

• discourse_list_categories
• discourse_get_category
• discourse_create_category
• discourse_edit_category
• discourse_delete_category

Users (12 tools)

• discourse_list_users — Filter by active/new/staff/suspended
• discourse_get_user — Profile info
• discourse_create_user
• discourse_suspend_user / discourse_unsuspend_user
• discourse_silence_user / discourse_unsilence_user
• discourse_set_trust_level
• discourse_add_to_group / discourse_remove_from_group
• discourse_list_groups
• discourse_send_pm — Private messages

Search & Tags (5 tools)

• discourse_search — Full-text search with filters
• discourse_list_tags
• discourse_tag_topic
• discourse_create_tag
• discourse_list_tag_groups

Admin (14 tools)

• discourse_site_settings / discourse_update_setting
• discourse_site_stats
• discourse_list_badges / discourse_create_badge / discourse_grant_badge / discourse_revoke_badge
• discourse_list_plugins
• discourse_list_backups / discourse_create_backup
• discourse_list_reports
• discourse_set_site_text
• discourse_create_group / discourse_update_group

---

Example Prompts

Read recent topics:

What are the latest topics on the forum?

Create a topic:

Create a new topic in Announcements titled "Weekly Update" with a summary of this week's changes

Moderate:

Close topic #42 and pin topic #15 globally

User management:

Set user johndoe to trust level 2

---

Troubleshooting

403 Forbidden

• API Username must be a real Discourse username, not the key description
• Check the API key scope includes the endpoint you’re calling

404 Not Found

• Verify the forum URL is correct (no trailing slash)
• The endpoint may not exist on older Discourse versions

429 Too Many Requests

• Rate limiting active — the tools automatically retry with backoff

---

Questions? Ask in Questions or check the Discourse API docs.