Migrate from v1

​

v1 keeps working

​

What maps to what

​

Sending: from a header to an address

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Zavu-Sender: kd7abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"to": "+56912345678", "text": "Your code is 123456."}'

curl -X POST https://api.zavu.dev/v2/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "+13125551212", "to": "+56912345678", "text": "Your code is 123456."}'

​

Webhooks

1. PUT /v2/webhook with your new URL and events.
2. Check that your receiver verifies and handles the v2 payload. from, to and type sit at the top level; data is what v1 sends, without senderId.
3. PUT /v2/webhook again with "disableSenderWebhooks": true. That switches the v1 sender webhooks off and keeps their configuration, so each event arrives once.

​

What behaves differently in v2

​

Sending

• Only active connections are picked. Without channel, a connection that is switched off is skipped. If nothing active can reach the recipient, the answer is 409 no_channel. Naming a switched-off transport in channel is 403 channel_inactive.
• One answer for “nothing can send”. No channel, a channel that is not connected, an email to without email, a WhatsApp-only messageType without WhatsApp: all 409 no_channel, with details.connect listing what to connect and the request for each. v1 answers several of these with 400.
• Contradictions are refused. An email to with a channel other than email, channel: "email" with a phone number, or a WhatsApp-only messageType with another channel is 400, naming both fields.
• Bare digits are not guessed. A to of 8 to 15 digits without + is a chat id. When nothing in the request can reach a chat id, v2 refuses it with details.suggestion holding the number with its +. A number written with spaces, dashes or parentheses after its + is read as E.164.
• Fallback checks first. Before a failed WhatsApp message falls back to SMS, v2 checks that the connection it would fall back to is switched on and, for a +1 number, that the project has an approved 10DLC campaign. Otherwise the message stays failed, with errorCode CHANNEL_INACTIVE or TEN_DLC_REQUIRED.
• Replies stay in their thread. With conversationId, to can be omitted, and a to that is not the thread’s contact is 400. The 202 carries message.conversationId when the thread already exists.
• 10DLC refusals say how to fix them. 403 ten_dlc_required carries the registration as API calls, in order, and the channels that reach the same person without 10DLC.

​

Messages

• Amounts are USD rounded to 6 decimals.
• charged says what an SMS or one-way SMS took from your balance. costTotal is not that number for SMS.
• errorCode is a Zavu code. A delivery provider’s own code is translated where its meaning is known and kept in errorDetails.providerCode.
• attemptedChannels lists the transports tried before a fallback, and riskHold says whether the message is waiting for risk review.

​

Contacts

• An identifier another contact already holds on the same channel is 400 duplicate_identifier, with details.conflicts naming that contact. v1 refuses it too, as a plain 400 invalid_request with no details.
• A phone identifier (sms, whatsapp, voice) must be E.164; WhatsApp also takes a BSUID.
• Deleting a contact that is already gone is 404, as on v1.

​

Campaigns

• Creating a campaign checks its channel: a from without that channel is 409 no_channel, not a campaign that fails at send.
• Adding recipients: a malformed recipient, or bare digits on a phone campaign, refuses the whole request with 400 and the path of the recipient. A well-formed recipient the campaign cannot reach is skipped and reported in invalid, with code unreachable_by_channel or ten_dlc_required.
• Acting on a campaign in the wrong state (cancel a finished one, add recipients to or delete one that is not a draft) is 409 invalid_status. v1 answers 400.

​

Channels, agents, domains

• A Telegram token Telegram rejects is 400 invalid_bot_token.
• Connecting an agent to one-way SMS is 409 channel_cannot_receive: one-way SMS receives nothing, so the agent would never answer.
• POST /v2/agents lists every missing required field, not only the first.
• POST /v2/email-domains validates domain before anything is created, and adding a domain the project already has returns it with 200. A domain whose DKIM records could not be generated comes back verifiable: false with setupError.
• Verifying an email domain answers 404 only for a domain that is not yours, and 503 verification_unavailable when the DNS check could not run.

​

Errors and webhooks

• Every error is flat, and every 400 invalid_request carries details.errors with field paths. A body that is not JSON is 400 invalid_json, as on v1.
• A known path with the wrong method is 405, not 404, on every v2 path except /v2/numbers and /v2/functions.
• The v2 webhook cannot move straight from v2 signatures back to v1; go through v1+v2, as in the other direction.

​

What stays on v1