Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Mastodon to Fondoo

Live4 min readUpdated

Connecting Mastodon lets your business publish posts to your Mastodon account on any instance (server). Your AI agent can draft and schedule posts with text, images or video, and you approve them before they go out. On hosted Fondoo, posting goes through Fondoo's Upload-Post account using an access token you create on your instance.

What Fondoo can do with it

Through Upload-Post (hosted Fondoo)

  • Text posts, a single image, up to 4 images (8 MB or less each), or a single video.
  • Up to 500 characters. Some instances allow more, but Fondoo checks against 500.
  • No multi-post threads, no stats (Upload-Post does not offer Mastodon analytics), and no deleting after publishing.

Directly (native, only if your Fondoo operator allows your instance)

  • Text, images, video and threads of up to 21 connected posts, all posted as public.
  • Stats: favourites, boosts and replies.
  • cancel_post can delete published posts.
  • The server operator must add your instance's address to the allowed list. Hosted Fondoo does not allow any Mastodon instance by default, so ask Fondoo support before choosing this path.

Both paths support drafts (draft_social_posts, one AI post unit per idea; save_social_draft), scheduling (schedule_social_posts), tracked links with UTM tags, and planning (get_social_calendar, get_post, get_publishing_capacity).

What needs your approval:

  • By default every Mastodon post needs the owner's approval. The agent's approve_social_posts becomes a request in your queue.
  • Only the owner can install the token (configure_upload_post_platform or configure_social_connection) and change posting rules (update_distribution_rules).

Before you start

  • A Mastodon account on the instance you want to post from, for example mastodon.social. Your instance's address is its web address, such as https://mastodon.social.
  • Check your instance's rules about automated or promotional posting. Many instances require bot-like accounts to be marked as bots.
  • Cost: Mastodon is free. Posting is part of your Fondoo plan. Your plan sets how many social sets you can have (Builder and Launch: one, Growth: three, Agency: ten), with one account per network in each set.

Step by step: get your credentials

You need two values: your instance URL and an access token.

  1. Sign in to your instance in a browser.
  2. Open Preferences → Development → New application (Upload-Post's connecting guide uses the same path). On most instances the page is at https://YOUR-INSTANCE/settings/applications.
  3. Application name: Fondoo. Leave Redirect URI as the default.
  4. Scopes: untick the broad defaults and tick only what Fondoo needs:
    • write:statuses to publish posts,
    • write:media to upload images and video,
    • read:accounts so the account can be identified,
    • read:statuses for stats (native path). These are the scopes Fondoo's native connector requests. Upload-Post does not publish its required scopes, so if Upload-Post rejects the token, add the full read and write scopes. A token can only call methods its scopes allow (Mastodon OAuth scopes).
  5. Click Submit, then click the new application's name.
  6. Copy Your access token. Keep it private; it can post as you.

Where each value goes: instance_url and access_token (Upload-Post path), or instance and accessToken (native path).

Connect it in Fondoo

(a) In the dashboard

The Connections page does not have a Mastodon tile yet. Start with your agent or the REST API below. Once connected, the account appears under Connected.

(b) By asking your agent

Set up Mastodon for the main site. Create the social connection and give me its connectionId so I can add the token myself.

Your agent runs:

connect_service({provider:"mastodon", siteId:"YOUR-SITE-UUID"})   // signed 15-minute instructions link
connect_social({siteId:"YOUR-SITE-UUID", provider:"upload_post", network:"mastodon",
                redirectUrl:"https://your-site.example/connected"})
  -> { connectionId, url }

Then you, the owner, add the token. Do not paste the token into an agent chat. Use the REST API with your own owner credentials:

curl -X POST https://api.getfondoo.com/v1/ops/configure_upload_post_platform \
  -H "Authorization: Bearer $FONDOO_OWNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"YOUR-SITE-UUID","connectionId":"CONNECTION-UUID","network":"mastodon","credential":{"instance_url":"https://mastodon.social","access_token":"YOUR-TOKEN","name":"@you@your-instance"}}'

Only instance_url, access_token and the optional name are accepted. Finally, run refresh_social_accounts({siteId, connectionId}).

Native path: after your operator allows the instance, the owner calls configure_social_connection({siteId, provider:"mastodon", credential:{instance:"https://mastodon.social", accessToken:"..."}}), then refresh_social_accounts with the returned connectionId.

Mastodon does not use add_connection_key or test_connection. refresh_social_accounts is the check.

Turn Mastodon on. The owner adds Mastodon to the posting rules with update_distribution_rules. Defaults: one post per day, 09:00 to 17:00 UTC, text only, review approval.

Test that it works

  1. list_social_accounts should show your Mastodon account.
  2. Save and schedule a short test post, then approve it.
  3. When due, get_post should show published. Check the post on your profile.

Troubleshooting

  • "Invalid platform credentials": a field is missing or misnamed. Use exactly instance_url and access_token (plus optional name).
  • 401 or 403 from the provider: the token was revoked, or it lacks write:statuses. Create a new application with the scopes above.
  • "Use an Upload-Post connection": the connectionId belongs to a different provider. Create it with connect_social and provider:"upload_post".
  • "mastodon: character limit 500": shorten the post. Links are tracked before the length check, so they count.
  • "Provider origin must be explicitly allowed by the server operator": you tried the native path with an instance that is not allowed. Use the Upload-Post path or ask your operator.
  • Rate limits: Mastodon allows 300 API calls per 5 minutes per account and 30 media uploads per 30 minutes by default; instances may differ (rate limits).

Limits, data and security

  • Limits: 500 characters, 4 images, 8 MB per image. Fondoo sets no daily cap for Mastodon; your cadence setting controls volume.
  • Retries: five automatic attempts, then an alert.
  • What Fondoo stores: the account ID and name, your posts, schedules and results. On the Upload-Post path, Fondoo passes the token to Upload-Post, which validates and encrypts it; Fondoo does not keep a copy. On the native path, Fondoo stores the token encrypted and never returns it.
  • Rotate or disconnect: in Preferences → Development, delete the Fondoo application (this revokes the token) or regenerate its token. Then send the new token with the same call, or run refresh_social_accounts to mark the account inactive.