v51

latestOpenAPI 3.0.3raw.githubusercontent.com2026-08-02172186551.1 KB

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/v1/messages

Headers

Zavu-Senderstring

Example:sender_12345

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

Request body

tostring 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.

Delivery channel. Use 'auto' for intelligent routing.

Type of message. Non-text types are supported by WhatsApp and Telegram (varies by type).

location_request asks the recipient to share their location and is WhatsApp-only. It takes no content object — the prompt goes in text (max 1024 characters) and the button label is fixed by WhatsApp. The recipient's answer arrives as an inbound location message whose content.replyToMessageId is the ID of the request.

request_contact_info asks the recipient to share their phone number and is WhatsApp-only. Like location_request it takes no content object — the prompt goes in text (max 1024 characters) and WhatsApp renders a fixed Share Contact Info button. The answer arrives as an inbound contact message. Use it to recover the phone number of a contact who adopted a WhatsApp username and is only known by their business-scoped user ID (BSUID); when they share it, Zavu automatically links the phone number to that contact.

textstring

Text body for text messages or caption for media messages.

subjectstring

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

htmlBodystring

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

replyTostring email

Reply-To email address for email messages.

idempotencyKeystring

Optional idempotency key to avoid duplicate sends.

metadataobject

Arbitrary metadata to associate with the message.

fallbackEnabledboolean

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

voiceLanguagestring

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 request

{
  "to": "+56912345678",
  "text": "Your verification code is 123456.",
  "content": {
    "mediaUrl": "https://example.com/image.jpg",
    "mimeType": "image/jpeg",
    "filename": "invoice.pdf",
    "ctaDisplayText": "See Dates",
    "ctaUrl": "https://example.com/schedule",
    "footerText": "Dates subject to change.",
    "templateVariables": {
      "1": "John",
      "2": "ORD-12345"
    },
    "templateButtonVariables": {
      "0": "abc-report-token"
    },
    "templateHeaderVariables": {
      "1": "Jorge y Laura"
    }
  },
  "subject": "Your order confirmation",
  "replyTo": "support@example.com",
  "idempotencyKey": "msg_01HZY4ZP7VQY2J3BRW7Z6G0QGE",
  "voiceLanguage": "es-ES",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "content_id": "logo"
    }
  ]
}

Response

Message accepted for delivery.

Example response

{
  "message": {
    "id": "jd7x2k3m4n5p6q7r8s9t0",
    "to": "+56912345678",
    "from": "+13125551212",
    "senderId": "sender_12345",
    "content": {
      "mediaUrl": "https://example.com/image.jpg",
      "mimeType": "image/jpeg",
      "filename": "invoice.pdf",
      "ctaDisplayText": "See Dates",
      "ctaUrl": "https://example.com/schedule",
      "footerText": "Dates subject to change.",
      "templateVariables": {
        "1": "John",
        "2": "ORD-12345"
      },
      "templateButtonVariables": {
        "0": "abc-report-token"
      },
      "templateHeaderVariables": {
        "1": "Jorge y Laura"
      }
    },
    "conversationId": "js723987cyghwqxxaxcf590qd18axd95"
  }
}