API reference

Messages

The Messages API sends a templated WhatsApp message or an email to a contact and lists messages you've sent. WhatsApp (templated, multi-provider) and email send are real capabilities in TelVox Dial's agent panel; this public REST surface is in preview.

Preview

The Messages REST API is a developer-preview surface — endpoints, fields, and enums are illustrative and may change before GA. The channels themselves (WhatsApp and email) ship today in Dial.

Not offered

Messaging is WhatsApp and email only. TelVox does not offer SMS, MMS, video, or fax — there are no such endpoints, and these are not on the roadmap. There is also no AI voice-agent product. If you need SMS or MMS, TelVox is not the right tool.

Base URL

messages

illustrative

https://api.telvox.dev/v1

Message properties

A message is represented by the following fields. Which fields apply depends on the channel.

Property	Type	Description
sid	string	Unique identifier for the message, prefixed MG.
channel	enum	Delivery channel: whatsapp or email. These are the only supported channels.
to	string	Recipient. An E.164 phone number for WhatsApp, or an email address for email.
from	string	Sender identity — your approved WhatsApp sender, or the configured from-address for email.
template	string	Name of a pre-approved WhatsApp template. Required for WhatsApp business-initiated messages.
variables	object	Values substituted into the template placeholders.
subject	string	Email subject line. Email channel only.
body	string	Email body (or a free-form WhatsApp message inside an open session window).
status	enum	queued, sent, delivered, read, or failed — as reported by the underlying provider.
provider	string	The backing provider that handled delivery (e.g. a WhatsApp BSP, or the email transport).
created_at	string	ISO 8601 timestamp of when the message was accepted.

Channels

channel	Type	Description
whatsapp	channel	Templated, business-initiated WhatsApp via an approved sender and template; free-form replies within an open 24-hour session window.
email	channel	Transactional email send with subject and body from your configured from-address.

Send a message

POST/v1/messages

Send a WhatsApp template or an email. The required fields depend on the channel.

POST/v1/messages

illustrative

curl -X POST https://api.telvox.dev/v1/messages \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+14155550123",
    "template": "appointment_reminder",
    "variables": { "1": "Tue 10:30", "2": "Dr. Lee" }
  }'

201 created

Parameter	Type	Description
channelrequired	enum	whatsapp or email.
torequired	string	E.164 phone number (WhatsApp) or email address (email).
template	string	Approved WhatsApp template name. Required for business-initiated WhatsApp.
variables	object	Template variable values.
subject	string	Email subject. Email channel only.
body	string	Email body, or an in-session WhatsApp message.

Response

illustrative

{
  "sid": "MG5b7e2a90c1d34f60",
  "channel": "whatsapp",
  "to": "+14155550123",
  "from": "+14155550100",
  "template": "appointment_reminder",
  "status": "queued",
  "provider": "whatsapp-bsp",
  "created_at": "2026-06-21T17:21:03Z"
}

201 created

List messages

GET/v1/messages

Return messages you've sent, newest first, filterable by channel and status, with cursor pagination.

GET/v1/messages

illustrative

curl "https://api.telvox.dev/v1/messages?channel=whatsapp&limit=20" \
  -H "Authorization: Bearer $TELVOX_API_KEY"

200 ok

Response

illustrative

{
  "data": [
    {
      "sid": "MG5b7e2a90c1d34f60",
      "channel": "whatsapp",
      "to": "+14155550123",
      "status": "delivered",
      "created_at": "2026-06-21T17:21:03Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

200 ok