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 Embedded Signup — 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:

{
  "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.

Embedded Signup

For a Meta-driven onboarding experience that registers a new WABA, adds the phone number, and provisions a system user token in one browser flow, use Embedded Signup. The flow lives in your dashboard; the API surface is here for completeness.

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