Migrate from Vonage to Bird

Move a Vonage SMS integration to Bird while preserving the sender, customer preferences and records your team uses to investigate messages.

1. Identify the current Vonage interface

Record whether the integration uses the dedicated SMS API at rest.nexmo.com/sms/json or the separate Messages API. This guide maps the dedicated SMS API. Keep a separate inventory for Messages API authentication, message UUIDs and status callbacks; its payload is not interchangeable with the request below.

Capture the sender, recipient formatting, encoding, per-message callback overrides and consumer that receives replies. Preserve your account and application references alongside provider message IDs. The SMS API reference is the source for the mapping below.

2. Prepare the receiving sender

Use Bird sender setup for the intended country. Confirm number ownership, registration and destination enablement before changing production requests. Retaining a Vonage number needs a supported transfer; changing the API client does not move the number or its registrations.

Reconcile opt-outs from your application, keyword handling and support records. Preserve the scope of each preference when importing Bird suppressions. A new sender or provider is not new customer consent. Confirm reply support for the chosen sender before replacing an inbound workflow.

3. Replace the send adapter

Use the Node.js or Python SMS quickstart. Map your business message ID to the returned Bird message ID; retain old Vonage IDs for historical investigations.

The dedicated SMS API and Messages API have different request and response shapes. The request below targets the dedicated SMS API with HTTP Basic authentication; the separate Messages API needs its own authentication and callback mapping.

Vonage SMS API	Bird implementation
from, to, text	Select an eligible from, a +-prefixed E.164 to, and text with an explicit purpose in category.
messages[].message-id	Save the send response id with the application message record.
messages[].status of 0	Request acceptance; inspect delivery events afterward. HTTP success alone can conceal a per-message refusal on Vonage.
client-ref	Store application correlation in metadata; it does not make a send idempotent.
callback, status-report-req	Register a workspace webhook subscription; Bird does not choose callback URLs per message.
Receipt messageId	Event data.sms_id identifies the message; webhook-id identifies the event delivery.

Before running either example, configure your provider credentials and owned sender. Set VONAGE_SMS_TO according to the Vonage SMS API’s number format, and SMS_TO with a leading + for Bird. Install the Bird CLI and set BIRD_API_KEY, BIRD_SMS_FROM and a retained MESSAGE_KEY.

Exemple de code

curl --fail-with-body --silent --show-error \
  https://rest.nexmo.com/sms/json \
  --user "$VONAGE_API_KEY:$VONAGE_API_SECRET" \
  --data-urlencode "from=$VONAGE_SMS_FROM" \
  --data-urlencode "to=$VONAGE_SMS_TO" \
  --data-urlencode 'text=Your studio visit is tomorrow at 14:00.'

Exemple de code

bird sms send \
  --from "$BIRD_SMS_FROM" \
  --to "$SMS_TO" \
  --text "Your studio visit is tomorrow at 14:00." \
  --category transactional \
  --idempotency-key "$MESSAGE_KEY"

For application code, use the Node.js quickstart or Python quickstart. In the Bird event handler, verify the signature and deduplicate on the webhook-id header. Do not use the message ID as an event deduplication key: the same message can have several lifecycle events.

4. Translate event handling

Vonage delivery receipts contain status and err-code; delivered is different from an accepted send. Retain those raw values with the historical message record. Replace the receipt parser with the Bird event catalog, including the different failure outcomes. Do not convert a missing receipt into delivery or collapse a temporary non-delivery into a permanent failure.

Use the persistent receipt handler to verify signatures, store repeated deliveries once and apply events without relying on arrival order. For replies, the two-way worker consumes sms.received and sends through the API. Check that the sender is reply-capable and that imported suppressions still apply.

Encoding also needs a deliberate check: Vonage's dedicated SMS API has a type selection, whereas Bird detects encoding from the text. Bird's optional smart_encoding can change supported characters; review the encoding rules before enabling it. Preserve any custom expiry, flash or binary-message behavior separately instead of assuming it is a free-text SMS option.

5. Test and move one route

Run a handset send, Unicode content, an incoming reply and a repeated event. Confirm a refused recipient is recorded as a refusal even if the old Vonage HTTP request succeeded. Check the rendered sender and segment count on a representative route.

Assign each logical message to one provider before attempting the send. Persist the request body, retry key and result ID. Retry the same Bird request with the same key within its idempotency window; a new key after an unknown result can create a second send. Reconcile unresolved attempts before moving them to the other provider.

Keep the old callback receiver available for messages sent before cutover. Increase new traffic by destination or application workflow, comparing observed outcomes for the same cohort. A rollback changes new routing and does not cancel messages already accepted.

References and next steps

Use a complete Next.js SMS application or FastAPI application for your first integration. Review SMS pricing, then start now or talk to sales about the migration.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptChoose a sender for your markets Utiliser l'outilCheck your message segments Explorer la fonctionnalitéCompare SMS providers