Channels

ScopeCHANNELS_MANAGE

Cached bot settings of a Telegram channel (null if never synced). Unknown, foreign and non-Telegram channel ids are the same NotFound.

query {
  channelTelegramBotSettings(integrationId: "…") { name description shortDescription commands menuButton }
}

ScopeCHANNELS_MANAGE

List the calling organisation's messaging channels with their status.

query {
  channels(provider: OPENAI) { createdAt updatedAt _id category provider }
}

ScopeCHANNELS_MANAGE

Connect an Instagram account using an Instagram User Access Token already obtained via Meta Business Login.

mutation {
  connectInstagramChannel(accessToken: "…") { createdAt updatedAt _id category provider }
}

ScopeCHANNELS_MANAGE

Connect a Telegram bot (BotFather token) to the calling organisation.

mutation {
  connectTelegramChannel(botToken: "…") { createdAt updatedAt _id category provider }
}

ScopeCHANNELS_MANAGE

Connect a Viber bot (Admin Panel auth token) to the calling organisation.

mutation {
  connectViberChannel(authToken: "…") { createdAt updatedAt _id category provider }
}

ScopeCHANNELS_MANAGE

Connect a WhatsApp number using credentials already obtained via Meta embedded signup (access token + WABA id + phone number id). Does not run the Meta OAuth flow.

mutation {
  connectWhatsAppChannel(input: { … }) { createdAt updatedAt _id category provider }
}

ScopeCHANNELS_MANAGE

Create the web messenger integration for the current organisation. Returns the integration row plus the plaintext sharedSecret - the ONLY response that surfaces the secret. Copy it into your backend now; subsequent queries won't expose it.

mutation {
  createWebIntegration(input: { … }) { integration sharedSecret }
}

ScopeCHANNELS_MANAGE

Create a new WhatsApp template and submit to Meta for approval. API keys have a per-organisation daily create cap (default 20).

mutation {
  createWhatsAppTemplate(input: { … }) { success template error externalTemplateId }
}

ScopeCHANNELS_MANAGE

Delete all Telegram bot commands. Unknown, foreign and non-Telegram channel ids are the same NotFound.

mutation {
  deleteChannelTelegramBotCommands(integrationId: "…") { name description shortDescription commands menuButton }
}

ScopeCHANNELS_MANAGE

Hard-delete the integration. Active visitor sessions become orphans and clean up via existing People retention sweeps. Visitor-facing endpoints start returning 503 immediately.

mutation {
  deleteWebIntegration(id: "…")
}

ScopeCHANNELS_MANAGE

Delete a WhatsApp template. On Meta this deletes ALL language variants of the template name (other local language rows drop on the next sync), and Meta blocks reusing the name for several weeks.

mutation {
  deleteWhatsAppTemplate(id: "…") { success error }
}

ScopeCHANNELS_MANAGE

Disconnect a messaging channel of the calling organisation (stops the bot, reconciles chats/conversations). Unknown / foreign ids are NotFound.

mutation {
  disconnectChannel(integrationId: "…", deletePeople: false) { integrationId organisationId dryRun deletedPeople deletedPeopleFieldValues }
}

ScopeCHANNELS_MANAGE

Start a hosted WhatsApp/Instagram connect for one of the partner's MANAGED client orgs. Returns the Meta OAuth URL to send the customer to; after consent the browser is 302ed to `returnUrl` with ?status=connected|error&provider=..&reason=..

mutation {
  partnerChannelConnectUrl(childOrganisationId: "…", channel: WHATSAPP, returnUrl: "…")
}

ScopeCHANNELS_MANAGE

Pause a messaging channel of the calling organisation (stops inbound processing). Unknown / foreign ids are NotFound.

mutation {
  pauseChannel(integrationId: "…") { createdAt updatedAt _id category provider }
}

ScopeCHANNELS_MANAGE

Resume a paused messaging channel of the calling organisation. Unknown / foreign ids are NotFound.

mutation {
  resumeChannel(integrationId: "…") { createdAt updatedAt _id category provider }
}

ScopeCHANNELS_MANAGE

Mint a new sharedSecret for the integration. The old secret stops verifying user_hash IMMEDIATELY - stage the new secret in your backend BEFORE calling this mutation if you need zero-downtime rotation. Returns the plaintext exactly once.

mutation {
  rotateWebIntegrationSecret(id: "…") { integration sharedSecret }
}

ScopeCHANNELS_MANAGE

Replace the Telegram bot command list (max 100). Unknown, foreign and non-Telegram channel ids are the same NotFound.

mutation {
  setChannelTelegramBotCommands(input: { … }) { name description shortDescription commands menuButton }
}

ScopeCHANNELS_MANAGE

Set the Telegram bot description (up to 512 chars; empty clears). Unknown, foreign and non-Telegram channel ids are the same NotFound.

mutation {
  setChannelTelegramBotDescription(input: { … }) { name description shortDescription commands menuButton }
}

ScopeCHANNELS_MANAGE

Set the Telegram bot display name (up to 64 chars; empty resets). Unknown, foreign and non-Telegram channel ids are the same NotFound.

mutation {
  setChannelTelegramBotName(input: { … }) { name description shortDescription commands menuButton }
}

ScopeCHANNELS_MANAGE

Set the Telegram bot short description (up to 120 chars; empty clears). Unknown, foreign and non-Telegram channel ids are the same NotFound.

mutation {
  setChannelTelegramBotShortDescription(input: { … }) { name description shortDescription commands menuButton }
}

ScopeCHANNELS_MANAGE

Set the Telegram chat menu button (DEFAULT, COMMANDS, or WEB_APP with text + HTTPS URL). Unknown, foreign and non-Telegram channel ids are the same NotFound.

mutation {
  setChannelTelegramMenuButton(input: { … }) { name description shortDescription commands menuButton }
}

ScopeCHANNELS_MANAGE

Pull all bot settings of a Telegram channel from Telegram and cache them. Unknown, foreign and non-Telegram channel ids are the same NotFound.

mutation {
  syncChannelTelegramBotSettings(integrationId: "…") { name description shortDescription commands menuButton }
}

ScopeCHANNELS_MANAGE

Sync templates from Meta for a WhatsApp integration

mutation {
  syncWhatsAppTemplates(integrationId: "…") { synced created updated deleted errors }
}

ScopeCHANNELS_MANAGE

Rename a messaging channel and/or set its AI auto-reply default. Credentials, provider and category cannot be changed here. Unknown / foreign ids are NotFound.

mutation {
  updateChannel(integrationId: "…", input: { … }) { createdAt updatedAt _id category provider }
}

ScopeCHANNELS_MANAGE

Patch operator-mutable fields on the web integration. publicKey is immutable (would break embedded loader snippets); use rotateWebIntegrationSecret to spin a new sharedSecret.

mutation {
  updateWebIntegration(id: "…", input: { … }) { _id name defaultLocale supportedLocales contentLocaleFallback }
}

ScopeCHANNELS_MANAGE

Update local metadata for a WhatsApp template (variableMappings, defaultMedia)

mutation {
  updateWhatsAppTemplate(input: { … }) { success error template }
}

ScopeCHANNELS_MANAGE

The web messenger integration for the current organisation, or null when none is configured. At most one per org by design.

query {
  webIntegration { _id name defaultLocale supportedLocales contentLocaleFallback }
}

ScopeCHANNELS_MANAGE

Look up a web integration by _id (scoped to the operator org).

query {
  webIntegrationById(id: "…") { _id name defaultLocale supportedLocales contentLocaleFallback }
}

ScopeCHANNELS_MANAGE

Get a specific WhatsApp template by ID

query {
  whatsAppTemplate(id: "…") { _id organisation integration name displayName }
}

ScopeCHANNELS_MANAGE

Get all WhatsApp templates for the organisation with filtering and pagination

query {
  whatsAppTemplates(filter: { … }) { items totalCount hasNextPage hasPreviousPage }
}