Skip to content

chatfuel-lab/wizard / content/modules/core/skill

examples/operations.graphql

View on GitHub
# Chatfuel GraphQL — core operations every module needs (chatfuel-core skill):
# identity, bot discovery, permission check, file readback, channels and platform links.
# Validate against references/schema.graphql (node scripts/validate-operations.mjs).
# Transport & auth: references/transport-auth.md. Files & tasks: references/files-tasks.md.

# ============================================================
# Fragments
# ============================================================

fragment RoleInfo on Role {
  roleTypeV2
  botPermissions {
    object
    action
  }
}

fragment BotInfo on Bot {
  id
  title
  isReady
  timezone
  workspace {
    id
    title
  }
}

# ============================================================
# Identity & bot discovery
# ============================================================

query CurrentUser {
  currentUser {
    id
    name
    email
    dashboardLocale
    countryCode
    isWhiteLabel
    profilePicture {
      id
      url
    }
  }
}

# The shared bot picker: how you discover botIDs once the token works.
query BotsList($first: Int, $after: BotsCursor, $filter: BotsFilter, $orderBy: BotsOrderByInput) {
  currentUser {
    id
    botsV2(first: $first, after: $after, filter: $filter, orderBy: $orderBy) {
      edges {
        node {
          ...BotInfo
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
    }
  }
}

# The Chatfuel workspace is the BILLING container: an agency pays for a
# workspace, and every bot inside it draws on that payment. `workspaces` lives
# on currentUser (there is no root `workspaces` field).
query WorkspacesList {
  currentUser {
    id
    workspaces {
      id
      title
      botsLimit
      bots {
        id
        title
      }
    }
  }
}

# Creates a bot INSIDE a workspace. `createBot` without one makes a throwaway
# workspace per bot (and leaves it behind when the bot is deleted), so anything
# that must bill to a paid workspace goes through this mutation.
# Errors arrive nested: errors[].extensions.errors[].extensions.code —
# TooManyBotsInWorkspace when the plan's bot limit is reached,
# NotEnoughPermissions when the id is unknown or belongs to somebody else.
mutation WorkspaceCreateBot($workspaceID: WorkspaceID!, $initialTitle: String!) {
  workspaceCreateBot(workspaceID: $workspaceID, initialTitle: $initialTitle) {
    id
    title
  }
}

# Own role + permissions in a bot. PermissionObject values gate each domain
# (Inbox = live chat, People = contacts, etc.) — see references/transport-auth.md.
query MyBotRole($botID: BotID!) {
  currentUser {
    id
    botRole(botID: $botID) {
      ...RoleInfo
    }
  }
}

# ============================================================
# Files (uploads are REST — see references/files-tasks.md)
# ============================================================

query FileGet($fileID: FileID!) {
  file(id: $fileID) {
    id
    url
    type
    status
    size
  }
}

mutation FileStartDownload($fileID: FileID!) {
  fileStartDownload(id: $fileID) {
    id
    url
    type
    status
    size
  }
}

# ============================================================
# Per-user storage
# ============================================================
# `setUserStorageItem` is the ONLY persistence this API offers a client, and it
# is scoped to the SIGNED-IN USER, not to the team or the bot. Any UI built on
# it must say "your views", never "shared views".
#
# It lives in core rather than in a module because it is a generic mechanism —
# an arbitrary id, an arbitrary string — that any module can use: a module may
# import `~api/generated/core` and nothing else, so one pair here serves all ten.
#
# `value` is nullable: an id that was never written reads back as an item with
# `value: null` rather than erroring, so a first-run read needs no special case.
# The stored string is UNTRUSTED — it is whatever some past version of the app
# wrote, and it must be parsed defensively rather than cast.

query UserStorageGet($id: ID!) {
  currentUser {
    id
    userStorageItem(id: $id) {
      id
      value
    }
  }
}

mutation UserStorageSet($id: ID!, $value: String!) {
  setUserStorageItem(id: $id, value: $value) {
    id
    value
  }
}

# ============================================================
# Whole-bot preview session (seeding only)
# ============================================================
# `previewResponsesStartForBot` mints a preview conversation on a synthetic
# contact and runs the bot's real pipeline against it. No module ships a UI for
# it — testing happens where the work is, pinned to one flow (flow-builder) or
# one automation (automations), and each of those owns its own start mutation.
#
# It lives in core because three SEED RECIPES need it and nothing else does:
# livechat, contacts and deals all bootstrap a demo conversation with it, and a
# recipe may not reach into another module's generated documents any more than
# app code may. One pair here serves all three.
#
# `ScopeNotConnectedToBot` is the expected refusal when the platform is not
# wired to the bot — recipes walk the platform list and try the next one.

fragment PreviewBotSessionParts on PreviewResponsesBotSession {
  id
  conversationID
  startedAt
  platform
}

mutation PreviewStartForBot($botID: BotID!, $platform: Platform!) {
  previewResponsesStartForBot(botID: $botID, platform: $platform) {
    ...PreviewBotSessionParts
  }
}

# Seeds one contact-side message into that conversation. The result is the echo
# of what you just sent; recipes do not read it, so it stays two fields wide.
mutation PreviewWidgetTextSend(
  $botID: BotID!
  $conversationID: ConversationID!
  $message: WidgetTextMessageSendInput!
) {
  previewResponsesWidgetTextSend(botID: $botID, conversationID: $conversationID, message: $message) {
    id
    clientId
  }
}

# ============================================================
# Channels & platform links
# ============================================================
# A platform link is a one-shot URL on Chatfuel's own page, valid for 24 hours
# from creation, that lets somebody who is NOT a member of the bot either
# connect a new WhatsApp phone / Instagram account / TikTok account to it
# (connection link) or re-grant the permissions on the asset already connected
# (access-refresh link). The page, the OAuth round trip and the provider
# redirect URIs are all Chatfuel's, so an app never hosts the consume side: it
# mints the link, hands over `url`, and reads the active map back. Full rules:
# references/platform-links.md.
#
# One active link per (bot, platform, kind): a second create silently replaces
# the first, whose URL then stops working. `PlatformOperationLinkPlatform` has
# no facebook member — a Facebook page is connected through the signed-in
# OAuth route instead.
#
# Error codes: PlatformNotSupportedForOperationLink,
# PlatformOperationLinkInvalidRedirectURL (redirect URLs must be https:// with
# a host), NoConnectedContactScopeForPlatform (access-refresh only: nothing of
# that platform is connected yet), PlatformOperationLinkNotFound (revoking a
# link that is no longer active), NotEnoughPermissions (Configure / Edit).

# Which channels the bot has. `contactScopes` needs access to the bot only; the
# link maps further down need Configure / Edit and are non-null, which is why
# they are a separate document — one that asked for both would answer nothing
# at all to a role that may read but not manage.
fragment BotChannelsParts on Bot {
  id
  contactScopes {
    __typename
    id
    ... on WhatsAppPhoneContactScope {
      phone {
        id
        displayPhoneNumber
        verifiedName
      }
    }
    ... on InstagramAccountContactScope {
      instagramAccount {
        id
        username
        name
      }
    }
    ... on TikTokAccountContactScope {
      tiktokAccount {
        id
        username
        name
      }
    }
    ... on FacebookContactScope {
      facebookPage {
        id
        name
      }
    }
    ... on WebWidgetContactScope {
      webWidget {
        id
        name
      }
    }
  }
}

query BotChannels($botID: BotID!) {
  bot(id: $botID) {
    ...BotChannelsParts
  }
}

fragment PlatformConnectionLinkParts on PlatformConnectionLink {
  linkID
  url
  platform
  createdAt
  expiresAt
  onSuccessRedirectURL
  onFailureRedirectURL
  creator {
    id
    name
  }
}

# `connectedContactScope` is an interface; the four concrete types the enum
# allows are selected, and `__typename` tells them apart. TikTok's `username`
# is nullable, Instagram's is not. A Facebook refresh link is bound to ONE page.
fragment PlatformAccessRefreshLinkParts on PlatformAccessRefreshLink {
  linkID
  url
  platform
  createdAt
  expiresAt
  onSuccessRedirectURL
  onFailureRedirectURL
  creator {
    id
    name
  }
  connectedContactScope {
    __typename
    ... on PublicWhatsAppPhoneContactScope {
      phone {
        displayPhoneNumber
        verifiedName
      }
    }
    ... on PublicInstagramAccountContactScope {
      instagramAccount {
        username
        name
      }
    }
    ... on PublicTikTokAccountContactScope {
      tiktokAccount {
        username
        name
      }
    }
    ... on PublicFacebookContactScope {
      facebookPage {
        id
        name
      }
    }
  }
}

# The whole active map, one slot per platform, null where nothing is active.
# Spread on the `Bot!` the revoke and disconnect mutations return, so none of
# them needs a refetch.
fragment ActivePlatformLinks on Bot {
  id
  activePlatformConnectionLinks {
    whatsapp {
      ...PlatformConnectionLinkParts
    }
    instagram {
      ...PlatformConnectionLinkParts
    }
    tiktok {
      ...PlatformConnectionLinkParts
    }
    facebook {
      ...PlatformConnectionLinkParts
    }
  }
  activePlatformAccessRefreshLinks {
    whatsapp {
      ...PlatformAccessRefreshLinkParts
    }
    instagram {
      ...PlatformAccessRefreshLinkParts
    }
    tiktok {
      ...PlatformAccessRefreshLinkParts
    }
    facebook {
      ...PlatformAccessRefreshLinkParts
    }
  }
}

query BotPlatformLinks($botID: BotID!) {
  bot(id: $botID) {
    ...ActivePlatformLinks
  }
}

# Configure / Edit. The web widget is refused (CannotDisconnectWidgetScope); a
# scope that is already gone answers ContactScopeDoesNotExist. Disconnecting
# revokes the access-refresh link bound to that scope, so the payload carries
# both the scopes and the link maps.
mutation BotDisconnectContactScope($botID: BotID!, $contactScopeID: ContactScopeID!) {
  botDisconnectContactScope(botID: $botID, contactScopeID: $contactScopeID) {
    ...BotChannelsParts
    ...ActivePlatformLinks
  }
}

# Answers the new link with `url` — hand that string to the person who will
# open it. `linkID` is the same secret in another form: treat both as
# credentials. Replaces any active connection link for that platform.
mutation BotPlatformConnectionLinkCreate(
  $botID: BotID!
  $platform: PlatformOperationLinkPlatform!
  $onSuccessRedirectURL: String
  $onFailureRedirectURL: String
) {
  botPlatformConnectionLinkCreate(
    botID: $botID
    platform: $platform
    onSuccessRedirectURL: $onSuccessRedirectURL
    onFailureRedirectURL: $onFailureRedirectURL
  ) {
    ...PlatformConnectionLinkParts
  }
}

mutation BotPlatformConnectionLinkRevoke($botID: BotID!, $linkID: PlatformOperationLinkID!) {
  botPlatformConnectionLinkRevoke(botID: $botID, linkID: $linkID) {
    ...ActivePlatformLinks
  }
}

# Needs a connected scope of that platform, or NoConnectedContactScopeForPlatform.
# The link is bound to that scope: disconnecting it revokes the link.
mutation BotPlatformAccessRefreshLinkCreate(
  $botID: BotID!
  $platform: PlatformOperationLinkPlatform!
  $onSuccessRedirectURL: String
  $onFailureRedirectURL: String
) {
  botPlatformAccessRefreshLinkCreate(
    botID: $botID
    platform: $platform
    onSuccessRedirectURL: $onSuccessRedirectURL
    onFailureRedirectURL: $onFailureRedirectURL
  ) {
    ...PlatformAccessRefreshLinkParts
  }
}

mutation BotPlatformAccessRefreshLinkRevoke($botID: BotID!, $linkID: PlatformOperationLinkID!) {
  botPlatformAccessRefreshLinkRevoke(botID: $botID, linkID: $linkID) {
    ...ActivePlatformLinks
  }
}
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall