Skip to main content
PATCH
Update sender

Authorizations

Authorization
string
header
required

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

Path Parameters

senderId
string
required

Body

application/json
name
string
enableVoice
boolean

Turn the voice channel on or off. The sender must already have a phone number provisioned for calls; enabling it otherwise returns 400 instead of storing a flag that changes nothing. Confirm with the channels array on the response.

enableSmsOneway
boolean

Turn the one-way SMS channel on or off. Enabling needs nothing else and takes effect immediately; disabling removes the channel from the sender. Confirm with the channels array on the response.

setAsDefault
boolean
webhookUrl
string<uri> | null

HTTPS URL for webhook events. Set to null to remove webhook.

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. data.conversationId is the inbox thread id (deep-link with https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}); it is null while the conversation row is still being created (the first message of a brand-new thread, or several near-simultaneous first messages), where conversation.new carries the id instead — GET /v1/messages/{messageId} always has it. 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.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. data carries conversationId (the inbox thread id — deep-link with https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}), the phoneNumber or email key, channel, firstMessageId, firstMessageText, and profileName.
  • template.status_changed: WhatsApp template approval status changed

Partner events:

  • invitation.status_changed: A partner invitation status changed (pending, in_progress, completed, cancelled, failed). data carries invitationId, clientName, clientEmail, connectionType (whatsapp_waba or messenger), previousStatus, and currentStatus. On completed it also carries senderId and connectedAccount (channel, id, name) — the WhatsApp number or Facebook Page that was linked. On failed it carries failureReason; the invitation link stays usable, so a client can retry it.

Voice Agent events: For every voice event, data carries callId, direction, from, to, status, durationSeconds, endReason, and transcriptAvailable. The terminal events (call.completed, call.failed) additionally carry cost — what the call was billed, in USD, combining telephony and the managed voice pipeline — and currency. They are dispatched after the call is charged, so cost is populated rather than zero; telephony can still be settling on an outbound call, in which case GET /v1/calls/{callId} holds the reconciled figure.

  • call.initiated: An outbound call was created and is dialing, or an inbound call was received. data.status = ringing
  • call.answered: The call was answered and the voice agent is connected. data.status = in_progress
  • call.completed: The call ended after a conversation. data.status = completed; durationSeconds and endReason describe how it ended, and transcriptAvailable indicates whether a transcript can be fetched.
  • call.failed: The call could not be completed (busy, no answer, canceled, or an error). data.status is the terminal status and endReason explains the cause.

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.status,
message.failed,
message.inbound,
message.unsupported,
broadcast.status_changed,
conversation.new,
template.status_changed,
invitation.status_changed,
call.initiated,
call.answered,
call.completed,
call.failed,
domain.verified,
domain.failed
webhookActive
boolean

Whether the webhook is active.

emailReceivingEnabled
boolean

Enable or disable inbound email receiving for this sender.

emailCatchAllEnabled
boolean

Enable or disable domain catch-all. When enabled (with emailReceivingEnabled true), this sender receives email for any address at its domain. Ignored (treated as false) if receiving is not enabled.

emailAddress
string<email>

Attach or change the sender's email from-address (e.g. noreply@yourdomain.com). The domain must be a verified email domain in your project.

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
webhookSignatureVersion
enum<string>

Move this webhook between signature schemes. v1 -> v2 directly returns 400; go through v1+v2 first. See https://docs.zavu.dev/guides/receiving-messages/signature-migration

Available options:
v1,
v1+v2,
v2
Example:

"v2"

Response

Sender updated.

id
string
required
Example:

"sender_12345"

name
string
required
Example:

"Primary sender"

phoneNumber
string
required

Phone number in E.164 format.

Example:

"+13125551212"

channels
string[]

Channels this sender can actually send on right now, computed from its configuration. Empty means the sender cannot send or receive anything yet: a phoneNumber alone does not enable SMS or voice. Check this rather than inferring capability from phoneNumber or emailAddress.

Example:
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>