API Reference

Send a message

Send a message to a recipient via SMS or WhatsApp.

Channel selection:

If channel is omitted and messageType is text, defaults to SMS
If messageType is anything other than text, WhatsApp is used automatically

WhatsApp 24-hour window:

Free-form messages (non-template) require an open 24h window
Window opens when the user messages you first
Use template messages to initiate conversations outside the window

Plan allowances and email billing:

WhatsApp, Telegram, Instagram and Messenger share an allowance of 2,000 messages per month on Free. Over it, sends return 429 with code a2p_limit_exceeded and upgrade details; the counter resets on the 1st of each month. Paid plans have no message caps
Email is billed from your prepaid balance in 1,000-message blocks: $0.40 per 1,000 transactional emails,$ 0.80 per 1,000 marketing (broadcast) emails. A block is charged when your monthly count crosses each 1,000 boundary, and at zero balance email sends return 402 with code insufficient_balance. Free teams start with $2 of credit and additionally cap at 3,000 emails/month and 100/day. Teams on earlier plans keep their original email quotas instead
SMS and voice are billed per message from your balance on every plan

Email recipient pre-flight: Email messages are validated automatically before dispatch. Sends that would be a guaranteed hard bounce are failed instead of sent, protecting your bounce rate: the message transitions to failed (visible via GET /v1/messages/{messageId} and the message.failed webhook) with errorCode set to EMAIL_INVALID_RECIPIENT (malformed address), EMAIL_DOMAIN_NOT_FOUND (recipient domain has no MX or A records), or EMAIL_RECIPIENT_SUPPRESSED (address is on your suppression list after a previous bounce or complaint). Advisory signals (role addresses, disposable domains) do not block sends — check them beforehand with POST /v1/introspect/email.

POST

messages

curl --request POST \
  --url https://api.zavu.dev/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "+56912345678",
  "text": "Your verification code is 123456"
}
'

{
  "message": {
    "id": "jd7x2k3m4n5p6q7r8s9t0",
    "to": "+56912345678",
    "createdAt": "2023-11-07T05:31:56Z",
    "from": "+13125551212",
    "senderId": "sender_12345",
    "text": "<string>",
    "content": {
      "mediaUrl": "https://example.com/image.jpg",
      "mediaId": "<string>",
      "mimeType": "image/jpeg",
      "filename": "invoice.pdf",
      "latitude": 123,
      "longitude": 123,
      "locationName": "<string>",
      "locationAddress": "<string>",
      "contacts": [
        {
          "name": "<string>",
          "phones": [
            "<string>"
          ]
        }
      ],
      "buttons": [
        {
          "id": "<string>",
          "title": "<string>"
        }
      ],
      "listButton": "<string>",
      "sections": [
        {
          "title": "<string>",
          "rows": [
            {
              "id": "<string>",
              "title": "<string>",
              "description": "<string>"
            }
          ]
        }
      ],
      "ctaDisplayText": "See Dates",
      "ctaUrl": "https://example.com/schedule",
      "ctaHeaderText": "<string>",
      "ctaHeaderMediaUrl": "<string>",
      "footerText": "Dates subject to change.",
      "emoji": "<string>",
      "reactToMessageId": "<string>",
      "replyToMessageId": "<string>",
      "replyToProviderMessageId": "<string>",
      "replyToFrom": "<string>",
      "replyToText": "<string>",
      "replyToMessageType": "<string>",
      "templateId": "<string>",
      "templateVariables": {
        "1": "John",
        "2": "ORD-12345"
      },
      "templateButtonVariables": {
        "0": "abc-report-token"
      },
      "templateHeaderVariables": {
        "1": "Jorge y Laura"
      }
    },
    "conversationId": "js723987cyghwqxxaxcf590qd18axd95",
    "providerMessageId": "<string>",
    "errorCode": "<string>",
    "errorMessage": "<string>",
    "cost": 123,
    "costProvider": 123,
    "costTotal": 123,
    "metadata": {},
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Zavu-Sender

string

Optional sender profile ID. If omitted, the project's default sender will be used.

Example:

"sender_12345"

Body

application/json

Request body to send a message.

string

required

Recipient phone number in E.164 format, email address, WhatsApp business-scoped user ID (BSUID, e.g. US.13491208655302741918), or numeric chat ID (for Telegram/Instagram/Messenger). A BSUID is routed to WhatsApp and sent via the recipient field; use it to message a contact who adopted a username and whose phone number is hidden.

Example:

"+56912345678"

channel

enum<string>

default:auto

Delivery channel. Use 'auto' for intelligent routing. If omitted, channel is auto-selected based on sender capabilities and recipient type. For email recipients, defaults to 'email'.

Available options:

auto,

sms,

sms_oneway,

whatsapp,

telegram,

email,

instagram,

messenger,

voice

messageType

enum<string>

default:text

Type of message. Defaults to 'text'.

Available options:

text,

image,

video,

audio,

document,

sticker,

location,

contact,

buttons,

list,

cta_url,

request_contact_info,

location_request,

reaction,

template

text

string

Text body for text messages or caption for media messages.

Example:

"Your verification code is 123456."

content

object

Additional content for non-text message types.

Show child attributes

subject

string

Email subject line. Required when channel is 'email' or recipient is an email address.

Maximum string length: 998

Example:

"Your order confirmation"

htmlBody

string

HTML body for email messages. If provided, email will be sent as multipart with both text and HTML.

replyTo

string<email>

Reply-To email address for email messages.

Example:

"support@example.com"

idempotencyKey

string

Optional idempotency key to avoid duplicate sends.

Example:

"msg_01HZY4ZP7VQY2J3BRW7Z6G0QGE"

metadata

object

Arbitrary metadata to associate with the message.

Show child attributes

fallbackEnabled

boolean

default:true

Whether to enable automatic fallback to SMS if WhatsApp fails. Defaults to true.

voiceLanguage

string

Language code for voice text-to-speech (e.g., 'en-US', 'es-ES', 'pt-BR'). If omitted, language is auto-detected from recipient's country code.

Example:

"es-ES"

attachments

object[]

Email attachments. Only supported when channel is 'email'. Maximum 40MB total size.

Maximum array length: 50

Show child attributes

Response

Message accepted for delivery.

message

object

required

Show child attributes

⌘I

curl --request POST \
  --url https://api.zavu.dev/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "+56912345678",
  "text": "Your verification code is 123456"
}
'

{
  "message": {
    "id": "jd7x2k3m4n5p6q7r8s9t0",
    "to": "+56912345678",
    "createdAt": "2023-11-07T05:31:56Z",
    "from": "+13125551212",
    "senderId": "sender_12345",
    "text": "<string>",
    "content": {
      "mediaUrl": "https://example.com/image.jpg",
      "mediaId": "<string>",
      "mimeType": "image/jpeg",
      "filename": "invoice.pdf",
      "latitude": 123,
      "longitude": 123,
      "locationName": "<string>",
      "locationAddress": "<string>",
      "contacts": [
        {
          "name": "<string>",
          "phones": [
            "<string>"
          ]
        }
      ],
      "buttons": [
        {
          "id": "<string>",
          "title": "<string>"
        }
      ],
      "listButton": "<string>",
      "sections": [
        {
          "title": "<string>",
          "rows": [
            {
              "id": "<string>",
              "title": "<string>",
              "description": "<string>"
            }
          ]
        }
      ],
      "ctaDisplayText": "See Dates",
      "ctaUrl": "https://example.com/schedule",
      "ctaHeaderText": "<string>",
      "ctaHeaderMediaUrl": "<string>",
      "footerText": "Dates subject to change.",
      "emoji": "<string>",
      "reactToMessageId": "<string>",
      "replyToMessageId": "<string>",
      "replyToProviderMessageId": "<string>",
      "replyToFrom": "<string>",
      "replyToText": "<string>",
      "replyToMessageType": "<string>",
      "templateId": "<string>",
      "templateVariables": {
        "1": "John",
        "2": "ORD-12345"
      },
      "templateButtonVariables": {
        "0": "abc-report-token"
      },
      "templateHeaderVariables": {
        "1": "Jorge y Laura"
      }
    },
    "conversationId": "js723987cyghwqxxaxcf590qd18axd95",
    "providerMessageId": "<string>",
    "errorCode": "<string>",
    "errorMessage": "<string>",
    "cost": 123,
    "costProvider": 123,
    "costTotal": 123,
    "metadata": {},
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}