Channels

Scope: CHANNELS_MANAGE for everything on this page, except sending a template, which needs MESSAGES_SEND.

This is how a partner onboards a client's channels without a human ever opening the Wexio dashboard.

How Many Channels an Org Can Have

An organisation can connect several channels of the same provider: many WhatsApp numbers, many Instagram accounts, many Telegram bots, many Viber bots. Only the web widget is one per organisation.

channels

channels(provider: IntegrationProvider): [Integration!]!

Lists the org's connected channels. Pass provider to filter to one.

query Connected {
  channels { _id provider }
}

Connecting

Two shapes, depending on what the channel's platform requires.

Bot token channels

connectTelegramChannel(botToken: String!): Integration!
connectViberChannel(authToken: String!): Integration!

mutation ConnectTelegram {
  connectTelegramChannel(botToken: "7123456789:AAE…") { _id provider }
}

Meta channels - hosted connect (recommended)

partnerChannelConnectUrl(
  childOrganisationId: String!
  channel: HostedConnectChannel!
  returnUrl: String!
): String!

For WhatsApp and Instagram you do not have to handle Meta credentials yourself. This mutation returns a URL you send the customer to; Wexio runs the Meta consent flow, binds the result to the child org, and redirects back.

Returns String! - the URL to open. It carries a signed, single-use state that is valid for 10 minutes.

returnUrl is validated when you mint the link, not when the customer comes back:

mutation HostedConnect {
  partnerChannelConnectUrl(
    childOrganisationId: "6716b2f0a1c34d0012ab89ef"
    channel: WHATSAPP
    returnUrl: "https://app.crmco.com/clients/5541/channels"
  )
}

The flow: your page → Wexio's Meta consent screen → binds to the child → redirect to returnUrl with status.

Meta channels - direct credentials

connectWhatsAppChannel(input: ConnectWhatsAppChannelInput!): Integration!
connectInstagramChannel(accessToken: String!): Integration!

For when you already hold Meta credentials - your own Meta app, or a migration.

ConnectWhatsAppChannelInput

mutation ConnectWhatsApp {
  connectWhatsAppChannel(input: {
    accessToken: "EAAG…"
    wabaId: "102938475612345"
    phoneNumberId: "109876543210987"
    tokenExpiresIn: 5184000
  }) { _id provider }
}

Pause, Resume, Update

pauseChannel(integrationId: String!): Integration!
resumeChannel(integrationId: String!): Integration!
updateChannel(integrationId: String!, input: UpdateChannelInput!): Integration!

CHANNELS_MANAGE. Members need OWNER or ADMIN.

UpdateChannelInput

An empty update is a 400. mode: SPECIFIC requires an assistantId belonging to this org, or it is a not-found.

mode: RULES takes an ordered rules list of { condition, assistantId }; the first match wins and the top-level assistantId is the fallback. The concept is in choosing an assistant by rules; the condition format is below.

mutation Route {
  updateChannel(integrationId: "67f95b…", input: {
    aiAutoReply: {
      mode: RULES
      assistantId: "<fallback assistant>"
      rules: [
        { condition: { in: [{ var: "field.plan" }, ["Pro", "Enterprise"]] },
          assistantId: "<paid-plan assistant>" }
      ]
    }
  }) { _id }
}

The web widget takes the same rules as aiAutoReplyRules on createWebIntegration / updateWebIntegration.

Every assistantId, fallback included, must belong to the organisation - otherwise 404 AI assistant not found.

Writing a Rule Condition

A condition is JSON in a small subset of json-logic. The shape rule is strict and applies at every level: each object must have exactly one key, and that key must be one of the operators below. There is no escape hatch - a second key, a zero-key object, or an unknown key is rejected outright, which is also what keeps $-prefixed Mongo operators and __proto__ out of the stored value.

mode: RULES needs a paid plan. On Free it fails with PLAN_FEATURE_NOT_ALLOWED; see plan feature not allowed.

Operators

Facts

var reads only these. Nothing else about the visitor is exposed to a rule.

Examples

{"==": [{"var": "isAuthenticated"}, true]}
{"==": [{"var": "authMethod"}, "anonymous"]}
{"in": [{"var": "authMethod"}, ["jwt", "google"]]}
{"in": [{"var": "field.plan"}, ["Pro", "Enterprise"]]}
{"in": ["EMAIL_GOOGLE", {"var": "verified"}]}
{"and": [{"==": [{"var": "isAuthenticated"}, true]},
         {"==": [{"var": "field.plan"}, "Pro"]}]}

Limits

Every var path is also checked on save. It must be authMethod, isAuthenticated, verified, or a field.<key> / verifiedField.<key> whose <key> is an existing People field in your organisation - in either the {"var": "x"} or the {"var": ["x", default]} form. A path that is not, including a mistyped key, is a 400:

Unknown fact "field.pln" in an agent-selection rule. Use authMethod, isAuthenticated, verified, field.<key> or verifiedField.<key> with an existing People field key.

This exists because a misspelled fact fails closed at runtime: without the save-time check, the rule would simply never match and the typo would stay invisible.

What Fails, and How

An invalid condition is rejected on save, with a 400. A valid condition that cannot be evaluated - it reads a field this visitor does not have, say - is not an error: it simply does not match, and selection falls through to the next rule and then to the fallback.

Checking Which Rule Won

Read the outcome per chat, on Chat:

All three come back from any operation returning a Chat - searchChats, collectionChats - under MESSAGES_READ. They are on Chat, not Conversation.

An assistantId that is unknown, malformed, or belongs to another organisation is the same 404 AI assistant not found, fallback included. The error does not distinguish the three, so it cannot be used to probe for assistants in other organisations.

Deleting an assistant does not break a channel. Rules naming it are dropped, a RULES fallback naming it is cleared, and a channel in SPECIFIC mode naming it reverts to ORG_DEFAULT.

A channel that is non-messaging, foreign, malformed or missing is one Channel not found - no existence oracle. Every channel operation by a key writes an audit line.

disconnectChannel

disconnectChannel(integrationId: String!, deletePeople: Boolean = false): IntegrationCleanupResult!

Disconnects a channel and cleans up behind it.

Arguments

WhatsApp Templates

Outside WhatsApp's 24-hour window you can only reach a customer with an approved template. These read and refresh the template list.

whatsAppTemplates(filter: WhatsAppTemplateFilterInput): WhatsAppTemplateConnection!  # CHANNELS_MANAGE
whatsAppTemplate(id: String!): WhatsAppTemplate                                      # CHANNELS_MANAGE
syncWhatsAppTemplates(integrationId: String!): WhatsAppTemplateSyncResult!           # CHANNELS_MANAGE

Send one with sendWhatsAppTemplateMessage - that needs MESSAGES_SEND, not CHANNELS_MANAGE.

Creating and Deleting Templates

createWhatsAppTemplate(…): CreateWhatsAppTemplateResult!
updateWhatsAppTemplate(…): UpdateWhatsAppTemplateResult!
deleteWhatsAppTemplate(…): DeleteWhatsAppTemplateResult!

CHANNELS_MANAGE. Members need OWNER, ADMIN or EDITOR.

Media on a template - defaultMediaId, header media, carousel media - must belong to the same org, or it is a not-found. Creating is allowed on channels that are paused, idle, pending or failed, and refused on disconnected channels. A bad integration id raises a not-found error rather than returning a failure object.

Telegram Bot Settings

A key can manage the Telegram bot's own profile - what users see in Telegram before they ever message you.

channelTelegramBotSettings(integrationId: String!): TelegramBotSettings    # read
syncChannelTelegramBotSettings(integrationId: String!)                     # re-pull from Telegram
setChannelTelegramBotName(input: …)
setChannelTelegramBotDescription(input: …)
setChannelTelegramBotShortDescription(input: …)
setChannelTelegramBotCommands(input: …)
deleteChannelTelegramBotCommands(integrationId: String!)
setChannelTelegramMenuButton(input: …)

CHANNELS_MANAGE. Members need OWNER or ADMIN. All the mutations return TelegramBotSettings!.

syncChannelTelegramBotSettings re-reads the current state from Telegram and is expensive. A channel that is not Telegram, foreign or missing is one Channel not found.

Web Widget

The website chat widget is a channel too, and a key with CHANNELS_MANAGE can manage it end to end - useful for a partner provisioning a widget per client.

webIntegration: WebIntegration                                            # the org's widget
webIntegrationById(id: ID!): WebIntegration
createWebIntegration(input: CreateWebIntegrationInput!): WebIntegrationWithSecret!
updateWebIntegration(id: ID!, input: UpdateWebIntegrationInput!): WebIntegration!
rotateWebIntegrationSecret(id: ID!): WebIntegrationWithSecret!
deleteWebIntegration(id: ID!): Boolean!

CreateWebIntegrationInput

Returns WebIntegrationWithSecret! - { integration: WebIntegration!, sharedSecret: String! }.

The secret is what signs authenticated visitor sessions. Embedding and configuring the widget itself is covered in the Web Widget docs.

Which Channels Can Start a Conversation

Full detail in Channel constraints.