Channels

A channel is the link between a WhatsApp Business Account (WABA) phone number and your TryVox tenant. It carries the access token, the WABA ID, and the per-channel webhook subscription. You can have multiple channels — one per WhatsApp number you want to send from.

Pre-requisites

Before connecting a channel you need:

1. A WABA registered in your Meta Business account.
2. A phone number added to that WABA, with phone_number_id from Meta.
3. A system user access token with whatsapp_business_messaging, whatsapp_business_management, and business_management scopes.

If you don't already have these, use Connect with Meta — it walks you through the Meta OAuth flow inside your dashboard and provisions all of the above.

Connect a channel

POST /v1/messaging/channels

Request body

Example

curl -X POST https://api.tryvox.io/v1/messaging/channels \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919876543210",
    "phone_number_id": "1234567890123456",
    "waba_id": "9876543210987654",
    "display_name": "Tryvox Support",
    "access_token": "EAAG...your-system-user-token..."
  }'

Response

201 Created:

{
  "data": {
    "id": "8f7a4b2e-91c2-4f3d-9a1e-2c4b6d8f0a1c",
    "phone_number": "+919876543210",
    "phone_number_id": "1234567890123456",
    "waba_id": "9876543210987654",
    "display_name": "Tryvox Support",
    "status": "active",
    "webhook_subscribed": true,
    "created_at": "2026-04-09T10:30:00Z"
  }
}

access_token is never returned. To rotate, PUT a new value.

On successful create, TryVox automatically subscribes Meta webhooks for the WABA so inbound messages flow to TryVox. If subscription fails (e.g. the access token lacks whatsapp_business_management scope), webhook_subscribed is false — call the re-subscribe endpoint after fixing the token.

List channels

GET /v1/messaging/channels

curl -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  https://api.tryvox.io/v1/messaging/channels

200 OK returns an array of channel records.

Get a channel

GET /v1/messaging/channels/{id}

404 CHANNEL_NOT_FOUND if the channel doesn't exist or belongs to another tenant.

Update a channel

PUT /v1/messaging/channels/{id}

curl -X PUT https://api.tryvox.io/v1/messaging/channels/$CHANNEL_ID \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"access_token": "EAAG...new-token..."}'

200 OK with the updated channel. access_token is still not returned.

Delete a channel

DELETE /v1/messaging/channels/{id}

204 No Content. Templates, conversations, and historical messages remain queryable. New sends to/from this channel are rejected with CHANNEL_NOT_FOUND.

Re-subscribe webhooks

POST /v1/messaging/channels/{id}/subscribe-webhooks

Triggers TryVox to call Meta's webhook subscription API for the channel's WABA. Use this when:

• The channel was created with a token that initially lacked permissions, and you've since fixed it.
• Meta has rotated the webhook subscription state and you're seeing missing inbound messages.
• You moved the WABA to a different Business and the subscription was reset.

curl -X POST \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  https://api.tryvox.io/v1/messaging/channels/$CHANNEL_ID/subscribe-webhooks

200 OK if Meta accepted the subscription. 502 with a Meta error code if it didn't.

Connect with Meta

This is what "Connect with Meta" in your dashboard does under the hood: a standard Meta OAuth redirect that authorizes TryVox against your existing Business, WABA, and phone number, then provisions a channel from what you pick. The flow lives in your dashboard; the API surface is here for completeness.

This is not the same thing as Meta's own "Embedded Signup" product (the JS-SDK popup flow with a config_id) — TryVox doesn't support that flow. If you already have a WABA and phone number, Connect with Meta below is the path to use.

Initiate

GET /v1/messaging/meta/oauth/init

Returns a Meta OAuth URL. Redirect the user there. Meta calls your dashboard back with a code.

Exchange the code

POST /v1/messaging/meta/oauth/exchange

{"code": "AQB...meta-oauth-code...", "state": "..."}

Returns an access token and the user's available Businesses, WABAs, and phone numbers.

Connect from OAuth

POST /v1/messaging/meta/connect-channel

{
  "waba_id": "9876543210987654",
  "phone_number_id": "1234567890123456",
  "access_token": "<from /exchange>"
}

Creates the channel and subscribes webhooks. Returns the same shape as POST /channels.

Lookups during the flow

These read directly from Meta and exist so your dashboard can pick the right WABA/number before calling connect-channel.

Errors

Troubleshooting: "(#200) You do not have the necessary permissions..."

This exact Meta error has two independent causes — check both:

1. Your access token is actually missing a scope. Confirm the token has whatsapp_business_messaging, whatsapp_business_management, and business_management all granted. Reconnect via Connect with Meta and approve every requested permission if any are missing.
2. The token has every scope, but the number's Meta verification isn't VERIFIED. Meta can reject sends with this same permission-shaped error when a number's phone verification has expired or was never completed — independently of what the token is allowed to do. Check the number's status in Meta Business Settings > WhatsApp Accounts > Phone Numbers and re-verify if it isn't VERIFIED.

Don't assume it's (1) just because the error text says "permissions" — a fully-permissioned token can still hit this error for reason (2).