Getting Started
From zero to a message sent and received, for a single org and for a tech provider
As a Single Organization
- Mint a key. In the dashboard, under Settings → Webhooks and API → API keys, create an Org API key with only the scopes your integration needs. The secret is shown once - store it immediately.
- Register a webhook and store the signing secret. This is how you receive messages; a key cannot open a GraphQL subscription. See Webhooks.
- Find a chat to reply to. Call
searchConversationsand takeprimaryThread._id- or wait for amessage.inbound.createdwebhook and takedata.chat.id. - Reply with
sendMessage, then checkdeliveryStatuson the result.
That is the whole loop. Everything else - triage, contacts, team - layers on top.
As a Tech Provider
Steps 1–3 happen once. Steps 4–6 repeat for every client you add.
- Provider setup (Wexio). Wexio sets your organisation's kind to
TECH_PROVIDERand sets your rate card in your provider contract. This is the sole thing that makes the provisioning surface available - there is no capability to toggle and nothing self-serve about it. - Mint an API key on your provider org including
PARTNER_ADMIN, and store the secret. See Authentication. - Register one webhook endpoint with
registerPartnerWebhookand store the signing secret. It receives events for all your clients, tagged with the child org and yourexternalId. - Create a client org with
createClientOrg- setexternalIdto your own ID for that client. Tenant storage is inherited from your provider org automatically. - Connect their channels. Telegram and Viber with a bot token; WhatsApp and Instagram with hosted connect, which sends the customer through Meta's consent flow and binds the result to the child.
- Optionally provision the rest - a web widget, a help centre, operator accounts via team.
- Go live. Receive events on your webhook and reply with
sendMessage, naming the client inX-Wexio-Org.
Only step 1 needs Wexio, and only minting the key in step 2 happens in the dashboard. Everything from step 3 on is callable with the key - onboarding a client is headless end to end.
Becoming a tech provider changes how your own organisation is billed: usage-based against your provider contract, with no retail subscription. You and your client orgs cannot open, switch or cancel a plan, and cannot grant or redeem coupons or referrals. See Billing.
Choosing Scopes
Mint one key per job, with the narrowest set that job needs:
| The integration… | Scopes |
|---|---|
| Mirrors conversations, read-only | MESSAGES_READ |
| Mirrors and replies | MESSAGES_READ, MESSAGES_SEND |
| Replies and triages | add CONVERSATIONS_MANAGE |
| Syncs a CRM both ways | add CONTACTS_READ, CONTACTS_MANAGE, PII_READ |
| Fulfils data-deletion requests | add CONTACTS_ERASE |
| Deletes conversations permanently | add CONVERSATIONS_DELETE |
| Onboards client channels or manages the web widget | add CHANNELS_MANAGE |
| Publishes a help centre or news feed | add CONTENT_READ, CONTENT_MANAGE |
| Provisions client orgs and the fan-out webhook (tech providers) | add PARTNER_ADMIN |
| Provisions operator accounts | add TEAM_READ, TEAM_MANAGE |
| Writes internal notes | add NOTES_WRITE |
Scopes cannot be changed after minting - to widen a key, mint a replacement and revoke the old one.
Add PII_READ only if you genuinely need customer names, phones and emails. Without it, a leaked key exposes conversation flow but not identities.
Before You Build
- Read What the API does not cover - broadcasts, flow authoring and WhatsApp template authoring are not available to keys.
- Read Channel constraints before designing first-touch messaging. Only WhatsApp can start a conversation, and only with an approved template.
- WhatsApp and Instagram onboarding for your clients goes live once Wexio's Meta app clears App Review and business verification. Telegram, Viber and Web are available now.