API
Drive your Wexio inbox from your own backend - send and receive across WhatsApp, Telegram, Viber, Instagram and Web with a scoped API key
The Wexio API lets you run your inbox from your own code. Mint an Org API key, give it the scopes it needs, and call the same GraphQL operations the dashboard uses: send and receive messages, triage conversations, sync contacts, connect channels, manage your team.
This API lives on the integration branch and is rolling out. The shapes here are taken from the shipped schema on that branch, but it is not yet on production - confirm availability before you build against it.
This section is for engineers. If you are an operator replying to conversations in the dashboard, see the main Documentation tab.
Two Ways to Use It
As a single organization. Your org, your key, your inbox. You mint a key, scope it, and automate your own conversations - a CRM sync, an escalation bot, a nightly export.
As a tech provider. Your organisation is of kind TECH_PROVIDER - you serve your own customers through Wexio's API, as a headless channel engine. You provision an isolated Wexio org per customer with PARTNER_ADMIN, and your key acts on any of them by naming it in X-Wexio-Org. Onboarding a client - org, channels, widget, help centre - is entirely headless. Your customers never see Wexio.
The API is the same in both cases. A tech provider is a superset: child-org targeting plus wholesale billing.
AI features are technically available to a tech provider - there is no feature gate - but they are not part of the standard tech-provider offering. Check with your account manager before you design around them.
A tech provider is not the same as a distribution partner. Both are sometimes called "partner", and they are different things:
| Tech provider | Distribution partner | |
|---|---|---|
| Org kind | TECH_PROVIDER | PARTNERSHIP |
| What it does | Serves its own clients through the API | Distributes Wexio to others |
| Billing | Usage-based, wholesale | Retail |
| Client orgs | Provisions MANAGED children | Refers orgs, which stay ordinary retail customers |
| Coupons / referrals | Blocked | Available |
This section is about the tech provider model. If you distribute Wexio rather than build on it, none of the provisioning below applies to you.
Several operations and one scope still carry "partner" in their names - PARTNER_ADMIN, partnerUsageSummary, registerPartnerWebhook, partnerRelation: MANAGED. Those names predate the split and refer to the tech provider model described here, not to a PARTNERSHIP org.
Concepts
| Term | Meaning |
|---|---|
| Org API key | A server-to-server credential, wx_<keyId>_<secret>, belonging to one org and carrying an explicit scope list. |
| Scope | A permission on the key, such as MESSAGES_SEND. A call without the required scope is refused. |
| Tech provider | An org of kind TECH_PROVIDER: it may provision and act on managed client orgs, and is billed by usage. |
| Client org | An isolated org a tech provider provisions and manages (partnerRelation: MANAGED). Its usage rolls up to the provider. |
X-Wexio-Org | Header naming a managed child org to act on. Tech-provider keys only. |
| Conversation | The inbox row for a contact. |
| Chat (thread) | One channel thread inside a conversation. Most operations take a chatId. |
Two Auth Surfaces
| Surface | Credential | Used for |
|---|---|---|
| Machine | Authorization: Bearer wx_... | Everything in this reference: messaging, inbox, contacts, channels, team |
| Dashboard | Member login | Minting and revoking keys, and everything the API deliberately excludes |
Key management cannot be done with a key - a leaked key can't mint more. Everything else, including partner provisioning, is available to a sufficiently scoped key. See Authentication.
What You Can Do
| Capability | Scope | Where |
|---|---|---|
| Send, edit, delete messages; react; upload media | MESSAGES_SEND | Messaging |
| Read conversations, messages, search, media | MESSAGES_READ | Reading the inbox |
| Triage: read state, close, assign, block, labels | CONVERSATIONS_MANAGE | Managing the inbox |
| Read and write contacts and custom fields | CONTACTS_READ / CONTACTS_MANAGE | Contacts |
| Connect channels, hosted Meta connect, manage the web widget | CHANNELS_MANAGE | Channels |
| Publish Help articles and News posts | CONTENT_READ / CONTENT_MANAGE | Content |
| List and manage team members | TEAM_READ / TEAM_MANAGE | Team |
| Receive live events over HTTP | - | Webhooks |
| Let AI agents message over MCP | MESSAGES_READ / MESSAGES_SEND | MCP |
| Provision client orgs, fan-out webhook, usage (tech providers) | PARTNER_ADMIN | Client orgs |
Read What the API does not cover before you design around it.
Start Here
- Mint a key with the right scopes.
- Learn the auth model - scopes, PII masking, child orgs.
- Register a webhook to receive messages, then reply with
sendMessage. - Check the channel constraints before building first-touch messaging.