Mastodon Functions

Post content to Mastodon social media servers. These functions enable workflows to share AI-generated content, notifications, and updates to the Fediverse.

Overview

The Mastodon integration provides two functions:

• postToMastodon() - Post with explicit credentials
• postLatestPromptToMastodon() - Convenience function using environment variables

Environment Variables

Set these in Admin Console → Settings → Variables:

Variable	Required	Description
MASTODON_URL	Yes	Your Mastodon instance URL (e.g., https://mastodon.social)
MASTODON_ACCESS_TOKEN	Yes	OAuth access token from your Mastodon app

Getting a Mastodon Access Token

1. Go to your Mastodon instance → Preferences → Development
2. Click "New Application"
3. Set application name (e.g., "Rocketwave Bot")
4. Select scopes: read, write, write:statuses
5. Submit and copy the access token

---

Functions

postToMastodon

Post a status to Mastodon with explicit credentials.

Signature:

async function postToMastodon(
  mastodonUrl: string, 
  accessToken: string, 
  status: string
): Promise<{
  id: string;
  url: string;
  created_at: string;
  content: string;
}>

Parameters:

Parameter	Type	Description
mastodonUrl	string	Mastodon instance URL (e.g., https://mastodon.social)
accessToken	string	OAuth access token
status	string	The status text to post (max 500 chars by default)

Returns: Object with post details

Example:

// Post a simple status
const result = await postToMastodon(
  'https://mastodon.social',
  'your-access-token',
  'Hello from Rocketwave! 🚀'
);

print('Posted:', result.url);
print('Post ID:', result.id);

---

postLatestPromptToMastodon

Convenience function that posts the latest AI response using environment variables for credentials.

Signature:

async function postLatestPromptToMastodon(): Promise<{
  id: string;
  url: string;
  created_at: string;
  content: string;
}>

Requirements:

• MASTODON_URL environment variable must be set
• MASTODON_ACCESS_TOKEN environment variable must be set
• A prompt entity must have already executed in the workflow

Example:

// Assumes a Prompt entity ran earlier in the workflow
await postLatestPromptToMastodon();
print('Posted AI response to Mastodon');

---

Complete Examples

Example 1: Sports Commentary Bot

A workflow that generates and posts sports commentary:

Event Condition:

{
  "type": "group",
  "operator": "AND",
  "conditions": [
    { "type": "rule", "field": "message.sport", "comparison": "equals", "value": "nfl" },
    { "type": "rule", "field": "message.eventType", "comparison": "equals", "value": "touchdown" }
  ]
}

Prompt Template:

Generate an exciting tweet about this touchdown:
Player: {{message.player}}
Team: {{message.team}}
Yards: {{message.yards}}

Keep it under 280 characters with 1-2 relevant emojis.

Action Script:

// Get the AI-generated commentary
const commentary = await latestPromptResponse();

if (commentary) {
  // Post to Mastodon
  try {
    const result = await postToMastodon(
      MASTODON_URL,
      MASTODON_ACCESS_TOKEN,
      commentary
    );
    
    print('Posted touchdown update!');
    print('URL:', result.url);
    
    // Pass post info to next node
    output = {
      posted: true,
      postUrl: result.url,
      postId: result.id
    };
  } catch (error) {
    print('Failed to post:', error.message);
    output = { posted: false, error: error.message };
  }
} else {
  print('No AI response to post');
}

---

Example 2: Simple AI Post (One-liner)

If you just want to post the latest AI response with no customization:

Action Script:

// This uses MASTODON_URL and MASTODON_ACCESS_TOKEN from environment
await postLatestPromptToMastodon();

---

Example 3: Formatted Post with Hashtags

Action Script:

const aiResponse = await latestPromptResponse();

if (aiResponse) {
  // Format with hashtags and branding
  const status = `${aiResponse}

#NFL #Sports #AI #RocketwaveBot`;

  // Check length (Mastodon default limit is 500)
  if (status.length > 500) {
    print('Warning: Status too long, truncating...');
    const truncated = status.substring(0, 497) + '...';
    await postToMastodon(MASTODON_URL, MASTODON_ACCESS_TOKEN, truncated);
  } else {
    await postToMastodon(MASTODON_URL, MASTODON_ACCESS_TOKEN, status);
  }
  
  print('Posted formatted status');
}

---

Example 4: Conditional Posting

Only post during certain hours or for certain content:

Action Script:

const response = await latestPromptResponse();

// Check if we should post
const shouldPost = message.priority === 'high' || message.forcePost === true;

if (shouldPost && response) {
  print('Posting high-priority content');
  
  const result = await postToMastodon(
    MASTODON_URL,
    MASTODON_ACCESS_TOKEN,
    response
  );
  
  output = { posted: true, url: result.url };
} else {
  print('Skipping post - priority:', message.priority);
  output = { posted: false, reason: 'low priority' };
}

---

Example 5: Error Handling with Retry Info

Action Script:

const content = await latestPromptResponse();

if (!content) {
  print('No content to post');
  output = { success: false, error: 'no_content' };
  return;
}

if (!MASTODON_URL || !MASTODON_ACCESS_TOKEN) {
  print('Mastodon not configured');
  output = { success: false, error: 'not_configured' };
  return;
}

try {
  const result = await postToMastodon(
    MASTODON_URL,
    MASTODON_ACCESS_TOKEN,
    content
  );
  
  print('Successfully posted to Mastodon');
  output = {
    success: true,
    postId: result.id,
    postUrl: result.url,
    createdAt: result.created_at
  };
  
} catch (error) {
  print('Mastodon API error:', error.message);
  
  // Provide useful error info
  output = {
    success: false,
    error: error.message,
    recoverable: !error.message.includes('401'), // Auth errors not recoverable
    contentLength: content.length
  };
}

---

Troubleshooting

"Mastodon configuration missing"

Cause: Environment variables not set

Solution:

1. Go to Admin Console → Settings → Variables
2. Add MASTODON_URL with your instance URL
3. Add MASTODON_ACCESS_TOKEN with your token

"Mastodon API error 401"

Cause: Invalid or expired access token

Solution:

1. Generate a new token in your Mastodon instance
2. Update the MASTODON_ACCESS_TOKEN variable

"Mastodon API error 422"

Cause: Invalid status content (too long, empty, or duplicate)

Solution:

• Check status length (max 500 chars default)
• Ensure content is not empty
• Mastodon rejects duplicate statuses within a short time

"No prompt responses available"

Cause: Using postLatestPromptToMastodon() before any Prompt entity ran

Solution:

• Ensure a Prompt entity executes before the Action
• Use postToMastodon() with explicit content instead

---

Best Practices

1. Check content before posting - Validate length and content
2. Handle errors gracefully - Don't let Mastodon failures crash workflows
3. Use environment variables - Don't hardcode tokens in scripts
4. Log post results - Track URLs for debugging and analytics
5. Respect rate limits - Mastodon instances may rate limit frequent posts

Related Topics

• Prompt Functions - Generate content to post
• Script Runtime - How scripts execute
• Social Media Pipeline Example - Complete workflow