Skip to main content
POST
Create sender

Authorizations

Authorization
string
header
required

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

Body

application/json

Create a sender. Provide phoneNumber for an SMS/WhatsApp sender, or emailAddress (with a verified email domain) for an email sender — at least one is required.

name
string
required
phoneNumber
string

Phone number in E.164 format. Required for phone-based channels (SMS, WhatsApp). Omit for an email-only sender.

setAsDefault
boolean
default:false
webhookUrl
string<uri>

HTTPS URL for webhook events.

webhookEvents
enum<string>[]

Events to subscribe to.

Type of event that triggers the webhook.

Message lifecycle events:

  • message.queued: Message created and queued for sending. data.status = queued
  • message.sent: Message accepted by the provider. data.status = sent
  • message.delivered: Message delivered to recipient. data.status = delivered
  • message.read: Message was read by the recipient (WhatsApp only). data.status = read
  • message.failed: Message failed to send. data.status = failed

Inbound events:

  • message.inbound: New message received from a contact. Reactions are delivered as message.inbound with messageType='reaction'. When the contact replied to (quoted) an earlier message, data.content carries the reply context: replyToMessageId, replyToProviderMessageId, replyToFrom, replyToText, and replyToMessageType. data.providerTimestamp is the provider's original receive time in Unix milliseconds (the moment the channel received the message from the contact — WhatsApp, Telegram, Instagram, Messenger; null for SMS and email). Compare it against the top-level timestamp (when Zavu dispatched the webhook) to detect and ignore delayed deliveries.
  • message.status: A contact posted a WhatsApp status/story (currently WhatsApp Alternative only). It is NOT a conversation message and never enters the inbox — it is delivered only if you subscribe to message.status. data carries from (the author in E.164), messageType (text, image, video, audio), text (caption/text when present), mimetype (for media stories), and providerTimestamp. Media bytes are not included.
  • message.unsupported: Received a message type that is not supported

Broadcast events:

  • broadcast.status_changed: Broadcast status changed (pending_review, approved, rejected, sending, completed, cancelled)

Other events:

  • conversation.new: New conversation started with a contact
  • template.status_changed: WhatsApp template approval status changed

Partner events:

  • invitation.status_changed: A partner invitation status changed (pending, in_progress, completed, cancelled)

Custom domain events:

  • domain.verified: A custom email domain passed verification (DKIM, and SPF/DMARC/MAIL FROM if enhanced records are enabled)
  • domain.failed: A custom email domain failed verification or is partially verified
Available options:
message.queued,
message.sent,
message.delivered,
message.read,
message.failed,
message.inbound,
message.status,
message.unsupported,
broadcast.status_changed,
conversation.new,
template.status_changed,
invitation.status_changed,
domain.verified,
domain.failed
emailAddress
string<email>

From-address for the email channel (e.g. noreply@yourdomain.com). The address's domain must be a verified email domain in your project. Setting this attaches the email channel to the sender.

Example:

"noreply@yourdomain.com"

emailDomainId
string

ID of the verified email domain to attach. Optional — resolved from emailAddress's domain when omitted.

emailFromName
string

Display name shown in the recipient's inbox for the email channel.

Maximum string length: 100
emailReceivingEnabled
boolean

Enable inbound email receiving on this sender. Requires a verified MX record on the domain; ignored otherwise.

Response

Sender created.

id
string
required
Example:

"sender_12345"

name
string
required
Example:

"Primary sender"

phoneNumber
string
required

Phone number in E.164 format.

Example:

"+13125551212"

isDefault
boolean
default:false

Whether this sender is the project's default.

webhook
object

Webhook configuration for the sender.

whatsapp
object

WhatsApp Business Account information. Only present if a WABA is connected.

emailAddress
string

From-address for the email channel, if configured.

Example:

"noreply@yourdomain.com"

emailReceivingEnabled
boolean
default:false

Whether inbound email receiving is enabled for this sender.

emailCatchAllEnabled
boolean
default:false

Whether catch-all receiving is enabled. When true (and emailReceivingEnabled is true), this sender receives email addressed to any local part at its domain, not just its own address. The original recipient is delivered in the message.inbound webhook's data.to.

createdAt
string<date-time>
updatedAt
string<date-time>