Bots

Bots are automated forum accounts that post via API instead of through the website. Each bot belongs to one forum, has its own identity (with a BOT badge next to its name), and authenticates with a per-bot token. Bots are created and managed by forum owners.

When to use a bot

• Webhook integrations — pipe GitHub releases, GitLab merges, deployment notifications, or RSS feeds into a thread.
• Cross-system automation — a sibling app posts updates on behalf of an internal service. RPG Stack does this for game NPCs: a GM creates the NPC's Forumera account from the NPC page in RPG Stack (it appears here in your Bots tab) and the NPC's posts land in your threads under that account. If the GM turns on summons, members can @mention that account in a post and the NPC replies on its own.
• Scheduled posts — a cron job somewhere posts a daily standup or status note.

What bots can and can't do

| | | |---|---| | Can | Post in any thread of their forum, reply to existing posts, run unattended 24/7 | | Can't | Log in to the website, post in other forums, vote, send DMs, edit posts |

A leaked bot token can post as that one bot in that one forum. It cannot impersonate humans or affect other forums.

Create a bot

1. Open your forum's admin page → Bots tab.
2. Type a bot name (e.g. github-deploys) and click Create bot.
3. Copy the token shown in the success banner. You will not see it again — anything we store is a hash, not the plaintext.
4. Use the token in your integration's Authorization: Bearer <token> header.

The bot account shows up in your forum's member list with a BOT badge. Anyone reading the forum can tell its posts come from an automated account.

Post via API

Two pieces of information you'll need for every call:

• The thread's UUID. You can get it from the URL or from GET /api/internal/thread.
• Your bot's API token (fbt_…).

curl example

curl -X POST https://forumera.com/api/internal/post \
  -H "Authorization: Bearer fbt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "<thread-uuid>",
    "content": "Release v1.2.3 deployed to production."
  }'

The response is the created post (status 201). On error you get JSON with an error field and an HTTP status code.

Common error codes

| Status | Meaning | |---|---| | 401 | Token invalid or revoked. Check your Authorization header. | | 403 | Token isn't authorized for that thread's forum, or the author isn't a bot account. | | 404 | Thread not found. | | 400 | Thread is locked, or reply_to_post_id doesn't belong to the same thread, or content is missing / over 50,000 chars. | | 429 | Per-bot rate limit hit (60 posts/minute). Includes a Retry-After header. |

Reply to an existing post

Pass reply_to_post_id in the body. The post you're replying to must be in the same thread.

curl -X POST https://forumera.com/api/internal/post \
  -H "Authorization: Bearer fbt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "<thread-uuid>",
    "reply_to_post_id": "<post-uuid>",
    "content": "Build is green now."
  }'

Example: GitHub Actions

Post a comment to your forum every time a workflow runs successfully on main. Save the bot token as a repository secret named FORUMERA_BOT_TOKEN.

name: Notify forum on deploy
on:
  push:
    branches: [main]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Post to Forumera
        run: |
          curl -X POST https://forumera.com/api/internal/post \
            -H "Authorization: Bearer ${{ secrets.FORUMERA_BOT_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d "{
              \"thread_id\": \"<your-thread-uuid>\",
              \"content\": \"Deployed ${{ github.sha }} from ${{ github.actor }}.\"
            }"

Revoke a bot

If a token leaks or you no longer need a bot, click the trash icon next to it in the Bots tab. Revocation is immediate; the next API call returns 401. Past posts stay in the thread (the bot account itself is not deleted).

Rate limits and quotas

• 60 posts per minute per token. If you need more, split traffic across multiple bots.
• No per-day or per-month quota today. We may add one later if abuse becomes a problem.

Privacy and accuracy

• Bot accounts are clearly labeled with the BOT badge in the UI. Members can tell at a glance which posts are automated.
• Don't post personal information you wouldn't put in a thread manually. Bot posts are subject to the same content policy as human posts.
• Bot tokens are stored hashed; we cannot recover a lost token. Generate a new one if needed (and revoke the old).