Inbox

MCP supports the Inbox reads and actions documented here. It uses explicit comment or root-post IDs for every mutation and follows the same Inbox product, tier, workspace, and user-permission checks. See the MCP tool reference.

BETA

Access to Inbox API features is currently in beta.

The organization must have an active Inbox subscription and an Inbox Large, Custom, or Agency tier.

Public fan comments

The Inbox API provides access to public fan comments in Swat.io.

Private messages and comments authored by the page are excluded.

Regular Inbox permissions of the users token apply.

List comments

inboxCommentFanList returns up to 50 comments, ordered by newest real_created value first. Optional filters combine with AND. Multiple filter_comment_tags values combine with OR.

query listInboxCommentFans {
  inboxCommentFanList(
    workspace_id: <WORKSPACE_ID>
    channel_ids: [<CHANNEL_ID>]
    filter_comment_tags: ["important", "product-feedback"]
  ) {
    comments {
      id
      
      deleted
      is_hidden
      message
      post_id
      real_created
      sentiment
      tags
      
      attachments {
        category
        description
        link
        source
        title
      }
      channel {
        id
      }
      profile {
        id
        channel_type
        name
        network_handle
      }
      ticket {
        id
      }
    }
    pagination {
      after
    }
  }
}

To retrieve the next page, pass the returned pagination.after value as the after argument and keep every other argument unchanged.

profile_ids identify a social-media profile across its channel-specific profile occurrences in the workspace.

Tickets

The Inbox API can list tickets and manage the comments and ticket state that the authenticated user may access. Inbox channel permissions, assignment restrictions, and subscription features continue to apply.

Use channels(workspace_id:, product: inbox) to discover Inbox channels. To filter tickets by platform, select the channel IDs for that platform and pass them to ticketList.

List tickets

ticketList returns up to 50 tickets per page. Use order: desc for newest first. visibility accepts public, private, or all; private returns direct-message tickets. status supports new, archived, mine, others, and starred.

query listInboxTickets {
  ticketList(
    workspace_id: <WORKSPACE_ID>
    channel_ids: [<CHANNEL_ID>]
    visibility: private
    status: new
    order: desc
  ) {
    tickets {
      id
      number
      status
      is_muted
      is_starred
      assignedUser {
        id
        first_name
        last_name
      }
      post {
        id
        message
        is_pm
        tags
        channel {
          id
          client_id
          name
          type
        }
        profile {
          id
          name
          network_handle
        }
      }
    }
    pagination {
      after
    }
  }
}

To retrieve the next page, pass pagination.after as after and keep all other arguments unchanged. Ticket text and tag searches use search_scope and search_term. A search cannot be combined with a status filter.

Retrieve a conversation

The ticket list includes the root post or direct message. Use commentsCollapsible with that post ID to retrieve subsequent messages. The result contains Comment entries and, when more messages are available, CommentsCollapsed entries. Use the collapsed entry's range values in a later request to load that range.

query getInboxConversation {
  commentsCollapsible(post_id: <POST_ID>, order: desc) {
    __typename
    ... on Comment {
      id
      message
      real_created
      deleted
      is_hidden
      is_seen
      sentiment
      tags
      profile {
        id
        name
        network_handle
      }
      attachments {
        category
        link
        source
        title
      }
    }
    ... on CommentsCollapsed {
      has_unseen
      nr_before
      nr_after
      parent_id
    }
  }
}

Assign users

Before assigning tickets, use assignableUsersInbox to retrieve users who can receive assignments for all selected channels.

query listAssignableInboxUsers {
  assignableUsersInbox(
    workspace_id: <WORKSPACE_ID>
    channel_ids: [<CHANNEL_ID>]
  ) {
    id
    first_name
    last_name
  }
}

Comment actions

The following actions use existing Inbox behavior. commentHide, commentLike, and commentsMarkAsSeen accept a boolean to reverse the action. Pass null to commentSetSentiment to remove the manual sentiment.

mutation manageInboxComment {
  commentHide(id: <COMMENT_ID>, hide: true) {
    id
    is_hidden
  }
  commentsAddTag(
    workspace_id: <WORKSPACE_ID>
    comment_ids: [<COMMENT_ID>]
    tag: "important"
  ) {
    id
    tags
  }
  commentsMarkAsSeen(
    workspace_id: <WORKSPACE_ID>
    comment_ids: [<COMMENT_ID>]
    seen: true
  ) {
    id
    is_seen
  }
}

Available comment actions are:

  • commentDelete(id:)
  • commentHide(id:, hide:)
  • commentLike(id:, like:, on_behalf_of_channel_id:)
  • commentSetSentiment(id:, sentiment:)
  • commentsAddTag(workspace_id:, comment_ids:, tag:)
  • commentsRemoveTag(workspace_id:, comment_ids:, tag:)
  • commentsMarkAsSeen(workspace_id:, comment_ids:, seen:)

Hide, delete, and like execute actions on the social network. Channel support and action permissions determine whether an action is available.

Ticket actions

Ticket actions identify tickets by their root post_ids. For predictable processing, limit each request to 50 post IDs.

mutation manageInboxTickets {
  ticketAssign(
    workspace_id: <WORKSPACE_ID>
    post_ids: [<POST_ID>]
    assign_user_id: <USER_ID>
  ) {
    id
    status
    assignedUser {
      id
    }
  }
  ticketMute(
    workspace_id: <WORKSPACE_ID>
    post_ids: [<POST_ID>]
    mute: true
  ) {
    id
    is_muted
  }
}

Available ticket actions are:

  • ticketArchive(workspace_id:, post_ids:)
  • ticketAssign(workspace_id:, post_ids:, assign_user_id:) - pass null to unassign
  • ticketMute(workspace_id:, post_ids:, mute:)
  • ticketStar(workspace_id:, post_ids:, star:)
  • postsAddTag(context: ticket, workspace_id:, post_ids:, tag:)
  • postsRemoveTag(context: ticket, workspace_id:, post_ids:, tag:)

Archiving clears an assignment and marks ticket content as read. Muting also archives the ticket; unmuting reopens it. Assigning a ticket reopens it.

Summarize a profile's comments

inboxCommentFanProfileSummary aggregates matching comments for one social media profile. channel_ids and filter_comment_tags optionally narrow the aggregate.

query summarizeInboxCommentFanProfile {
  inboxCommentFanProfileSummary(
    workspace_id: <WORKSPACE_ID>
    profile_id: <PROFILE_ID>
  ) {
    comment_count
    comment_real_created_first
    comment_real_created_last
    total_negative_sentiment_count
    total_neutral_sentiment_count
    total_positive_sentiment_count
    
    profile {
      id
      channel_type
      name
      network_handle
      link
      picture
    }
  }
}