Messaging API
Send WhatsApp and SMS messages, manage conversations, and run campaigns.
Messaging API
The Messaging API handles channel-based messaging — currently WhatsApp, with SMS surfacing through the same primitives. You connect a channel (a WhatsApp Business phone number, a sender ID), then send messages, manage two-way conversations, register templates, run campaigns, and consume webhook events for delivery and inbound messages.
How it fits together
┌─────────────────────┐
│ Channel (WABA #) │
│ /messaging/channels│
└──────────┬──────────┘
│ owns
▼
┌──────────────────┴──────────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Templates │ │ Conversations │
│ /templates │ │ /conversations │
└─────────────────┘ └────────┬────────┘
│ contain
▼
┌─────────────────┐
│ Messages │
│ /messages │
└─────────────────┘A conversation is auto-created on first message between your channel and a recipient. You don't manage conversations directly — the API surfaces them so you can list, read, and mark-as-read.
Endpoints
All endpoints are mounted under /v1/messaging/.... The API is tenant-scoped via the API key — you don't pass a tenant or auth ID in the URL.
Channels — set up the WhatsApp number
| Method | Path | Purpose |
|---|---|---|
POST | /v1/messaging/channels | Connect a WhatsApp Business number |
GET | /v1/messaging/channels | List channels |
GET | /v1/messaging/channels/{id} | Get a channel |
PUT | /v1/messaging/channels/{id} | Update display name, access token, status |
DELETE | /v1/messaging/channels/{id} | Remove a channel |
POST | /v1/messaging/channels/{id}/subscribe-webhooks | Re-subscribe Meta webhooks for the channel |
POST | /v1/messaging/channels/embedded-signup | Embedded Signup OAuth flow (browser-driven) |
Messages and conversations
| Method | Path | Purpose |
|---|---|---|
POST | /v1/messaging/messages | Send a message |
GET | /v1/messaging/conversations | List conversations |
GET | /v1/messaging/conversations/{id} | Get a conversation |
GET | /v1/messaging/conversations/{id}/messages | Get messages in a conversation |
POST | /v1/messaging/conversations/{id}/read | Mark a conversation as read |
Templates
| Method | Path | Purpose |
|---|---|---|
GET | /v1/messaging/channels/{channel_id}/templates | List templates for a channel |
POST | /v1/messaging/channels/{channel_id}/templates | Register a new template |
POST | /v1/messaging/channels/{channel_id}/templates/sync | Pull templates from Meta into TryVox |
GET | /v1/messaging/templates | List templates across all channels |
Campaigns
| Method | Path | Purpose |
|---|---|---|
POST | /v1/messaging/campaigns | Create a template-driven broadcast |
GET | /v1/messaging/campaigns | List campaigns |
GET | /v1/messaging/campaigns/{id} | Get one |
POST | /v1/messaging/campaigns/{id}/start | Start sending |
POST | /v1/messaging/campaigns/{id}/pause | Pause |
POST | /v1/messaging/campaigns/{id}/resume | Resume |
POST | /v1/messaging/campaigns/{id}/cancel | Cancel |
GET | /v1/messaging/campaigns/{id}/recipients | Per-recipient delivery status |
DELETE | /v1/messaging/campaigns/{id} | Delete |
Contacts
| Method | Path | Purpose |
|---|---|---|
POST | /v1/messaging/contacts | Create a contact |
GET | /v1/messaging/contacts | List |
GET | /v1/messaging/contacts/{id} | Get |
PUT | /v1/messaging/contacts/{id} | Update |
DELETE | /v1/messaging/contacts/{id} | Delete |
POST | /v1/messaging/contacts/import | Bulk import via CSV |
Inbound webhooks
WhatsApp webhooks from Meta land at /v1/webhooks/whatsapp (a public endpoint). TryVox verifies them and fans out to your subscribed webhooks (configured in Notifications → Webhooks) and to the in-dashboard inbox.
Real-time events
GET /v1/messaging/ws opens a WebSocket that streams in-tenant message and conversation events for dashboard-style UIs. Authentication uses a short-lived ticket — see the WebSocket section in your dashboard for issuing one.
Quick start
# 1. Connect your WhatsApp number (one-time)
CHANNEL=$(curl -s -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": "1234567890",
"waba_id": "9876543210",
"display_name": "Tryvox Support",
"access_token": "EAAG...your-meta-token..."
}')
CHANNEL_ID=$(echo "$CHANNEL" | jq -r .id)
# 2. Send a templated message (templates are required for first contact on WhatsApp)
curl -X POST https://api.tryvox.io/v1/messaging/messages \
-u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
-H "Content-Type: application/json" \
-d "{
\"channel_id\": \"$CHANNEL_ID\",
\"to\": \"+14155551234\",
\"message_type\": \"template\",
\"template_name\": \"hello_world\",
\"template_params\": {\"language\": \"en_US\", \"components\": []}
}"Authentication and gating
- All endpoints require HTTP Basic auth.
- Outbound SMS to
+91numbers is gated by Indian DLT registration. The validator runs before the message leaves TryVox and rejects with403 DLT_NOT_REGISTEREDif not registered. - WhatsApp messages outside the 24-hour customer service window must use a registered template. The API enforces this.