Collaboration Tools

Tools for managing team collaboration, tracking tasks, facilitating discussions, and managing user access in Storyblok.

Overview

Collaboration tools help teams work together effectively:

Tasks - Create and assign work items with automation
Discussions - In-content comments and conversations
Collaborators - Manage team members and permissions
Comments - Reply to and manage discussion threads

Total tools: 19 (Tasks: 5, Discussions: 10, Collaborators: 4)

Tasks (5 tools)

Tasks can be automated workflows, webhooks, or manual todo items for team members.

Listing Tasks

retrieve_multiple_tasks

Purpose: Get all tasks in your space.

When to use:

See active tasks
Review task configuration
Find task IDs

Common conversation examples:

Show me all tasks in my space

List all active automation tasks

Key parameters:

space_id - Space ID (required)
page, per_page - Pagination

Returns: Array of task objects.

retrieve_single_task

Purpose: Get details of a specific task.

When to use:

Check task configuration
Verify webhook URL
Inspect task settings

Common conversation examples:

Show me task ID 123

What's the webhook for the publish task?

Key parameters:

task_id - Task ID (required)

Returns: Single task object with configuration.

Creating Tasks

create_task

Purpose: Create a new task (webhook, automation, or manual).

When to use:

Set up webhook triggers
Create automation workflows
Define custom tasks

Common conversation examples:

Create a webhook task that sends to https://api.example.com/publish
when stories are published

Set up a task to notify Slack when content is ready for review

Key parameters:

name - Task name (required)
task_type - Type: "webhook", "lambda", etc. (default: "webhook")
webhook_url - Webhook endpoint URL
description - Task description
lambda_code - Code for lambda tasks
user_dialog - User dialog configuration

Returns: Newly created task object.

Task types:

webhook - Call external API endpoint
lambda - Execute custom code
manual - Human task tracking

Updating Tasks

update_task

Purpose: Update an existing task.

When to use:

Change webhook URL
Update task description
Modify task configuration

Common conversation examples:

Update task 456 to use new webhook URL

Change the task description

Key parameters:

task_id - Task to update (required)
name - New task name
description - New description
task_type - New task type
webhook_url - New webhook URL
lambda_code - Updated lambda code
user_dialog - Updated dialog config

Returns: Updated task object.

Deleting Tasks

delete_task

Purpose: Delete a task.

When to use:

Remove unused tasks
Clean up old automations
Delete test tasks

Common conversation examples:

Delete task ID 789

Remove the old webhook task

Key parameters:

task_id - Task to delete (required)

Returns: Deletion confirmation.

Discussions (10 tools)

In-content discussions allow team members to comment directly on specific fields within stories.

Listing Discussions

retrieve_multiple_discussions

Purpose: Get all discussions for a story.

When to use:

See all comments on content
Review discussion status
Find unresolved discussions

Common conversation examples:

Show me all discussions for story 123

List all unsolved discussions on this blog post

Key parameters:

story_id - Story ID (required)
page, per_page - Pagination
by_status - Filter by "solved" or "unsolved"

Returns: Array of discussion objects.

retrieve_specific_discussion

Purpose: Get details of a specific discussion.

When to use:

Check discussion thread
See all comments
Verify discussion status

Common conversation examples:

Show me discussion ID 456

What's the status of this discussion?

Key parameters:

discussion_id - Discussion ID (required)

Returns: Single discussion object.

retrieve_my_discussions

Purpose: Get discussions you're involved in.

When to use:

See discussions where you're mentioned
Track conversations you're part of
Review your pending discussions

Common conversation examples:

Show me all discussions I'm involved in

What unsolved discussions mention me?

Key parameters:

page, per_page - Pagination
by_status - Filter by status

Returns: Array of discussions involving you.

retrieve_idea_discussions_comments

Purpose: Get comments for an idea discussion.

When to use:

Review idea feedback
See discussion on feature requests
Track idea conversations

Common conversation examples:

Show me comments on idea discussion abc-123

Key parameters:

discussion_uuid - Discussion UUID (required)

Returns: Array of comment objects.

Creating Discussions

create_discussion

Purpose: Start a new discussion on a story field.

When to use:

Comment on specific content
Ask questions about a field
Request changes to content

Common conversation examples:

Create a discussion on the headline field asking about tone

Start a discussion on the hero image requesting higher resolution

Key parameters:

story_id - Story ID (required)
title - Discussion title (required)
fieldname - Technical field name (required)
block_uid - Block UID (required)
component - Component name (required)
lang - Language code like "default" or "en" (required)
message_json - Message content as JSON (required)

Returns: Newly created discussion object.

Message JSON format:

[
  {
    "type": "text",
    "text": "Is this headline too long?",
    "attrs": {}
  }
]

Managing Discussions

resolve_discussion

Purpose: Mark a discussion as resolved.

When to use:

Close completed discussions
Mark issues as addressed
Archive discussion threads

Common conversation examples:

Mark discussion 789 as resolved

Resolve the discussion about the hero image

Key parameters:

discussion_id - Discussion ID (required)
solved_at - Timestamp (ISO 8601 format) (required)

Returns: Updated discussion object.

Comments (4 tools)

Comments are individual messages within discussions.

retrieve_multiple_comments

Purpose: Get all comments in a discussion.

When to use:

Read full conversation thread
See all replies
Export discussion history

Common conversation examples:

Show me all comments in discussion 123

What did people say about this field?

Key parameters:

discussion_id - Discussion ID (required)

Returns: Array of comment objects.

create_comment

Purpose: Add a comment to an existing discussion.

When to use:

Reply to discussions
Add feedback
Answer questions

Common conversation examples:

Add a comment to discussion 456 saying "Looks good to me!"

Reply to the discussion with approval

Key parameters:

discussion_id - Discussion ID (required)
message_json - Comment content as JSON (required)
message - Optional plain text

Returns: Newly created comment object.

update_comment

Purpose: Edit an existing comment.

When to use:

Correct mistakes
Update feedback
Clarify comments

Common conversation examples:

Update comment 789 to say "Actually, this needs revision"

Edit my last comment

Key parameters:

discussion_id - Discussion ID (required)
comment_id - Comment ID (required)
message_json - Updated content (required)
message - Optional plain text

Returns: Updated comment object.

delete_comment

Purpose: Delete a comment.

When to use:

Remove incorrect comments
Delete accidental comments
Clean up discussion threads

Common conversation examples:

Delete comment 999 from discussion

Remove my last comment

Key parameters:

discussion_id - Discussion ID (required)
comment_id - Comment ID (required)

Returns: Deletion confirmation.

Collaborators (4 tools)

Manage team members who have access to your Storyblok space.

Listing Collaborators

retrieve_multiple_collaborators

Purpose: Get all team members in your space.

When to use:

See who has access
Review team members
Audit permissions

Common conversation examples:

Show me all collaborators in my space

List all team members

Key parameters:

page, per_page - Pagination

Returns: Array of collaborator objects.

Adding Collaborators

add_collaborator

Purpose: Invite a new team member to your space.

When to use:

Add new team members
Grant access to freelancers
Invite stakeholders

Common conversation examples:

Add [email protected] as an editor

Invite [email protected] with admin role

Key parameters:

email - Email address (required)
role - Role string (e.g., "admin", "editor")
space_role_id - Single role ID
space_role_ids - Multiple role IDs
permissions - Array of specific permissions
allow_multiple_roles_creation - Allow multiple roles

Returns: Newly created collaborator object.

Common roles:

admin - Full access
editor - Edit content
developer - Technical access
guest - Limited access

Updating Collaborators

update_collaborator

Purpose: Update permissions or roles for existing team member.

When to use:

Change user roles
Update permissions
Modify access levels

Common conversation examples:

Update collaborator 123 to admin role

Change Sarah's permissions to include publishing

Restrict access to specific folders

Key parameters:

collaborator_id - Collaborator ID (required)
role - New role
user_id - User ID
permissions - New permissions array
space_role_id - New role ID
space_role_ids - Multiple role IDs
allowed_paths - Folder access restrictions
field_permissions - Field-level permissions

Returns: Updated collaborator object.

Removing Collaborators

delete_collaborator

Purpose: Remove a team member from your space.

When to use:

Remove ex-team members
Revoke access
Clean up user list

Common conversation examples:

Remove collaborator 456 from the space

Delete [email protected]'s access

Key parameters:

collaborator_id - Collaborator ID (required)
sso_id - SSO ID for SSO users (alternative)

Returns: Deletion confirmation.

Important: This immediately revokes all access!

When to Use What

Task Management

Goal	Best Tool	Example
Create webhook	`create_task`	"Send to Slack when published"
List tasks	`retrieve_multiple_tasks`	"Show all tasks"
Update webhook	`update_task`	"Change webhook URL"
Delete task	`delete_task`	"Remove old task"

Discussion Management

Goal	Best Tool	Example
Start discussion	`create_discussion`	"Ask about headline"
Reply to thread	`create_comment`	"Reply to comment"
Mark as resolved	`resolve_discussion`	"Close discussion"
See all discussions	`retrieve_multiple_discussions`	"List all story comments"
My discussions	`retrieve_my_discussions`	"What mentions me?"

Team Management

Goal	Best Tool	Example
Add team member	`add_collaborator`	"Invite [email protected]"
Update permissions	`update_collaborator`	"Make John an admin"
Remove access	`delete_collaborator`	"Remove old user"
List team	`retrieve_multiple_collaborators`	"Show all users"

Common Patterns

Webhook Integration Setup

Set up Slack notification when content is published:
1. Create webhook task pointing to Slack webhook URL
2. Configure to trigger on publish event
3. Test with sample story

Uses: create_task (with webhook_url and configuration)

Content Review Workflow

Content review process:
1. Author creates discussion on headline field
2. Editor replies with feedback via comment
3. Author updates content
4. Author replies with confirmation
5. Editor marks discussion as resolved

Uses: create_discussion → create_comment → create_comment → resolve_discussion

Team Onboarding

Add new team members:
1. List current collaborators to check existing access
2. Add new collaborator with appropriate role
3. Update permissions if needed

Uses: retrieve_multiple_collaborators → add_collaborator → update_collaborator (if needed)

Discussion Cleanup

Close all resolved discussions:
1. Get all discussions for a story
2. Filter for resolved ones
3. Archive or document as needed

Uses: retrieve_multiple_discussions → resolve_discussion (multiple times)

Guides

Examples

Common Tasks

Tips & Best Practices

Tasks

Descriptive names - Name tasks clearly ("Slack: New Blog Posts")
Test webhooks - Verify endpoint responds correctly
Document triggers - Note what events trigger each task
Error handling - Handle webhook failures gracefully
Security - Use authentication for webhook endpoints

Discussions

Be specific - Start discussions on exact fields, not whole stories
@mention users - Tag relevant team members for visibility
Resolve when done - Mark discussions resolved to keep organized
Use discussions for questions - Don't use for general chat
Review regularly - Check for unsolved discussions

Collaborators

Principle of least privilege - Give minimum needed permissions
Regular audits - Review team access quarterly
Remove promptly - Delete access when team members leave
Use roles - Leverage space roles instead of custom permissions
Document access - Keep record of who has what access

Team Collaboration

Clear communication - Write clear discussion titles
Timely responses - Reply to discussions within 24 hours
Resolution discipline - Close discussions when complete
Assign tasks - Use tasks to track ownership
Regular check-ins - Review pending discussions in team meetings

Collaboration Best Practices by Team Size

Small Teams (2-5 people)

Use simple roles (admin/editor)
Discussions for all feedback
Manual task tracking
Minimal automation

Medium Teams (6-20 people)

Define clear space roles
Use discussions for content review
Webhook tasks for notifications
Some automation (Slack, email)

Large Teams (20+ people)

Custom space roles with granular permissions
Structured discussion process
Heavy task automation
Integration with project management tools

Need help with team collaboration? Check out our collaboration guides for detailed workflows!