Mastodon plugin¶

The mastodon entry point targets the standard Mastodon status and media APIs. It supports native status lifecycle actions and Telegram mirroring with durable source-to-status mappings.

Configuration¶

Provide the instance base URL and a user access token with the write scopes required by that instance.

plugins:
  - module: cb_social_plugin.mastodon
    config:
      base_url: "https://social.example"
      access_token: "${MASTODON_ACCESS_TOKEN}"
      state_db_path: "/srv/data/social-publications.db"
      visibility: "unlisted"
      media_group_wait_seconds: 2

Optional defaults accepted by create/mirror actions include visibility, sensitive, spoiler_text, and language.

Actions¶

Action	Purpose
`mastodon.create_post`	Create a status with `POST /api/v1/statuses`.
`mastodon.update_post`	Edit a mapped status with `PUT /api/v1/statuses/:id`.
`mastodon.delete_post`	Delete a status.
`mastodon.upload_media`	Upload an attachment with `POST /api/v2/media`.
`mastodon.mirror_telegram_message`	Mirror one Telegram message/update.
`mastodon.flush_due_media_groups`	Publish staged Telegram albums that are due.

Native create supports media_ids, visibility, sensitivity, content warning, language, and an optional caller-supplied idempotency_key. Native update supports the same editable status fields apart from visibility and create idempotency.

Telegram mirroring¶

New Telegram messages receive a deterministic SHA-256-derived Idempotency-Key when Call Baxter creates the Mastodon status. When the Telegram source is edited, the durable mapping is used to update the same status ID.

actions:
  - kind: mastodon.mirror_telegram_message
    args:
      update: "{{ event.attrs.raw_update }}"
      required_hashtag: "#social"

Configure state_db_path in production. It is what lets the mirror distinguish an edit from a new publication and suppress duplicate/stale source versions across process restarts.

Images¶

The alpha mirror uploads Telegram photos and image documents through /api/v2/media, then passes the returned attachment IDs to the status create/edit request. Mastodon's API can process larger media asynchronously; this mirror intentionally limits itself to images and does not attempt the video/GIF polling workflow yet.

If Telegram media cannot be acquired, the failure is reported in media_errors unless media_required: true is configured.

Idempotency and failure boundary¶

Mastodon documents Idempotency-Key for status creation, and the mirror uses it for a stable Telegram source key. The server controls how long an idempotency key is retained, so the local state_db_path remains the durable duplicate-suppression authority for Call Baxter.

Native create/update/delete/media actions are still external side effects and are not exposed as generically replay-safe actions.