Migrate from Twilio

This guide walks you through migrating a Twilio messaging integration to Zernio. It covers the surfaces that map directly: WhatsApp Business API, SMS/MMS, voice calling, and phone numbers (including porting your numbers over).

Zernio is not a drop-in for all of Twilio. If your integration is mostly messaging, the move is mechanical and this page covers every call you'll change. If you run complex TwiML voice apps, Verify, or SendGrid, keep those on Twilio; see What doesn't map below.

Quick Reference

Before You Start

How the concepts map

The biggest shift is the send model. Twilio is stateless: every send is To + From on one endpoint. Zernio is conversation-centric for WhatsApp: business-initiated template sends create or reuse a conversation (POST /v1/inbox/conversations), and free-form replies go into it (POST /v1/inbox/conversations/{conversationId}/messages). SMS keeps the familiar shape: POST /v1/sms/messages with from and to, and replies thread into the same inbox.

Step 1: Set Up Zernio Profiles

For each Twilio subaccount (or just once for a single-tenant app), create a profile:

curl -X POST https://zernio.com/api/v1/profiles \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation"}'

Save the returned profile._id; it's the profileId for everything below.

Step 2: Move Your Numbers

curl -X POST https://zernio.com/api/v1/phone-numbers/port-in/check \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -d '{"phoneNumbers": ["+13025551234"]}'

curl -X POST https://zernio.com/api/v1/phone-numbers/port-in \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -d '{
    "phoneNumbers": ["+13025551234"],
    "endUser": {
      "entityName": "Acme Corporation",
      "authPersonName": "Jane Smith",
      "streetAddress": "123 Market St",
      "locality": "San Francisco",
      "administrativeArea": "CA",
      "postalCode": "94103",
      "countryCode": "US"
    },
    "loaDocumentId": "DOC_ID_1",
    "invoiceDocumentId": "DOC_ID_2"
  }'

curl -X POST https://zernio.com/api/v1/phone-numbers/purchase \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -d '{"profileId": "PROFILE_ID", "country": "US", "wantsSms": true}'

curl -X GET "https://zernio.com/api/v1/connect/whatsapp?profileId=PROFILE_ID&redirect_url=https://yourapp.com/callback" \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY"

Step 3: Get Your Account IDs

Twilio addresses everything by phone number strings. Zernio addresses WhatsApp by accountId:

curl -X GET "https://zernio.com/api/v1/accounts?platform=whatsapp" \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY"

Store the mapping from each whatsapp:+E164 sender to its Zernio account _id. SMS keeps using raw E.164 numbers in from/to. To turn SMS on for a number you purchased or ported, call POST /v1/phone-numbers/{id}/sms once (idempotent; US numbers also need registration, below).

Step 4: Update Message Sending

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACxxxx/Messages.json \
  -u ACxxxx:auth_token \
  -d "To=whatsapp:+15551234567" \
  -d "From=whatsapp:+15557654321" \
  -d "ContentSid=HXxxxxxxxxxxxx" \
  -d 'ContentVariables={"1": "John", "2": "ORD-123"}'

curl -X POST https://zernio.com/api/v1/inbox/conversations \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -d '{
    "accountId": "abc123",
    "participantId": "15551234567",
    "templateName": "order_update",
    "templateLanguage": "en_US",
    "templateParams": ["John", "ORD-123"]
  }'

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACxxxx/Messages.json \
  -u ACxxxx:auth_token \
  -d "To=whatsapp:+15551234567" \
  -d "From=whatsapp:+15557654321" \
  -d "Body=Your order shipped!" \
  -d "MediaUrl=https://example.com/receipt.png"

curl -X POST https://zernio.com/api/v1/inbox/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -d '{
    "accountId": "abc123",
    "message": "Your order shipped!",
    "attachmentUrl": "https://example.com/receipt.png",
    "attachmentType": "image"
  }'

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACxxxx/Messages.json \
  -u ACxxxx:auth_token \
  -d "To=+14155559876" \
  -d "From=+13025551234" \
  -d "Body=Your order shipped!" \
  -d "MediaUrl=https://example.com/receipt.png"

curl -X POST https://zernio.com/api/v1/sms/messages \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -H "Idempotency-Key: 4f9d2c9e-8a1b-4f30-9d2f-1c2b3a4d5e6f" \
  -d '{
    "from": "+13025551234",
    "to": "+14155559876",
    "text": "Your order shipped!",
    "mediaUrls": ["https://example.com/receipt.png"]
  }'

{
  "accountId": "abc123",
  "message": "Confirm your appointment?",
  "buttons": [
    {"type": "postback", "title": "Yes", "payload": "confirm_yes"},
    {"type": "postback", "title": "No", "payload": "confirm_no"}
  ]
}

Step 5: Update Webhooks

This is the biggest paradigm change in the migration:

Register once:

curl -X POST https://zernio.com/api/v1/webhooks/settings \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -d '{
    "name": "messaging-events",
    "url": "https://yourapp.com/webhooks/zernio",
    "events": [
      "message.received", "message.sent", "message.delivered",
      "message.read", "message.failed", "conversation.started",
      "whatsapp.template.status_updated", "call.received", "call.ended"
    ],
    "secret": "your-signing-secret"
  }'

Field mapping (inbound WhatsApp message)

Signature verification

Twilio's URL-plus-sorted-params HMAC-SHA1 dance becomes a plain HMAC over the body:

// Twilio (before): twilio.validateRequest(authToken, signature, url, params)

// Zernio (after):
const expected = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers['x-zernio-signature'])
);

Debug with GET /v1/webhooks/logs (30-day retention) and POST /v1/webhooks/test.

Step 6: Templates

If you moved your WhatsApp sender (Step 2), your approved templates are already available; verify with GET /v1/whatsapp/templates?accountId=abc123. Creating new ones swaps the Content API for Meta's native shape:

Twilio (two calls: create, then submit for approval):

curl -X POST https://content.twilio.com/v1/Content \
  -u ACxxxx:auth_token \
  -H "Content-Type: application/json" \
  -d '{
    "friendly_name": "order_update",
    "language": "en",
    "variables": {"1": "John"},
    "types": {"twilio/text": {"body": "Hi {{1}}, your order is confirmed."}}
  }'

curl -X POST https://content.twilio.com/v1/Content/HXxxxx/ApprovalRequests/whatsapp \
  -u ACxxxx:auth_token \
  -H "Content-Type: application/json" \
  -d '{"name": "order_update", "category": "UTILITY"}'

Zernio (one call):

curl -X POST https://zernio.com/api/v1/whatsapp/templates \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -d '{
    "accountId": "abc123",
    "name": "order_update",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "body",
        "text": "Hi {{1}}, your order is confirmed.",
        "example": {"body_text": [["John"]]}
      }
    ]
  }'

Approval outcomes arrive on the whatsapp.template.status_updated webhook instead of polling ApprovalRequests.

US A2P Registration

Brand and Campaign registrations made through Twilio belong to Twilio's CSP account at The Campaign Registry, so they don't transfer between providers; US long-code SMS needs a fresh registration with Zernio (same underlying registry, similar fields):

curl -X POST https://zernio.com/api/v1/sms/registrations \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -d '{
    "registrationType": "standard_10dlc",
    "phoneNumbers": ["+13025551234"],
    "brand": {
      "entityType": "PRIVATE_PROFIT",
      "displayName": "Acme",
      "companyName": "Acme Corporation",
      "ein": "12-3456789",
      "country": "US",
      "vertical": "TECHNOLOGY",
      "street": "123 Market St", "city": "San Francisco",
      "state": "CA", "postalCode": "94103"
    },
    "campaign": {
      "usecase": "CUSTOMER_CARE",
      "description": "Order updates and customer support replies for Acme customers.",
      "messageFlow": "Customers opt in at checkout by checking the SMS updates box.",
      "sample1": "Your Acme order ORD-123 has shipped.",
      "helpMessage": "Acme support: reply with your question or email help@acme.com.",
      "optinKeywords": "START", "optinMessage": "You are subscribed to Acme updates. Reply STOP to opt out.",
      "optoutKeywords": "STOP", "optoutMessage": "You have been unsubscribed from Acme updates.",
      "helpKeywords": "HELP"
    }
  }'

• sole_prop_10dlc (no EIN) verifies via an OTP texted to your mobile (POST /v1/sms/registrations/{id}/verify-otp); toll_free covers toll-free verification.
• Poll GET /v1/sms/registrations/{id} for pending to approved; rejected campaigns can appeal (POST /{id}/appeal).
• Onboarding clients? POST /v1/sms/registrations/share mints a hosted single-use link so your customer fills in their own legal details, no Zernio login needed.
• Additional numbers reuse an approved campaign via POST /v1/phone-numbers/{id}/sms/reuse-registration (no new registration).

Voice

Twilio's voice model is programmable (your server returns TwiML per call). Zernio's is configuration plus API calls, which covers the common business-phone patterns without an app server:

• Inbound: POST /v1/phone-numbers/{id}/voice configures forwarding (tel:, sip:, or wss:// for AI voice agents), voicemail with a custom greeting, business hours, an IVR menu (up to 12 keys), recording, and transcription. All settings, no TwiML.
• Outbound: POST /v1/voice/calls with to, optional spoken greeting, answering-machine detection, and voicemailDropMessage (speak a message to a machine and hang up). Blind transfer via POST /v1/voice/calls/{id}/transfer. Cost preview via GET /v1/voice/calls/estimate.
• Browser calling: POST /v1/voice/calls/web issues a short-lived WebRTC token for a dashboard-style softphone.
• History + recordings: unified across PSTN and WhatsApp calls at GET /v1/calls (per-call cost breakdown; full transcripts on GET /v1/calls/{id}); recordings via GET /v1/calls/{id}/recording.
• WhatsApp Business Calling: supported on both platforms; on Zernio see Calling (call permissions, the voice_call interactive button, recording).
• Call lifecycle webhooks: call.received, call.ended (with duration and cost), call.failed.

Feature Map

You also gain: group chats API, a unified inbox that covers Instagram, Facebook, Telegram, and the rest of the social platforms alongside WhatsApp and SMS, template library instant approvals, and hosted onboarding links for your end customers (connect, KYC with white-label branding, A2P registration).

No Zernio equivalent (keep these on Twilio or plan around them):

• Programmable voice at TwiML depth (dynamic call flows, conferencing, SIP trunking, queues).
• Verify (managed OTP over SMS/voice/email), Video, SendGrid email, RCS.
• SMS message scheduling (SendAt); schedule from your own queue.
• Messaging Services sender pools (sticky sender, geomatch, alphanumeric sender IDs, short codes).
• Link shortening with click tracking.
• Serverless Functions; your webhook handlers run on your own infrastructure.
• SMS webhooks: inbound SMS and delivery receipts are read via the inbox API, not pushed as events (WhatsApp has full event coverage).

Cutover Strategy

Meta's per-template conversation charges continue either way (they're billed for the WABA regardless of provider), and template approvals survive the move because they live on the WABA.

Troubleshooting

Code Example: Node.js

const ZERNIO = 'https://zernio.com/api/v1';
const headers = {
  'Authorization': `Bearer ${process.env.ZERNIO_API_KEY}`,
  'Content-Type': 'application/json',
};

// Twilio: client.messages.create({ to: 'whatsapp:+1...', contentSid, contentVariables })
const sendWhatsAppTemplate = async ({ accountId, to, templateName, templateParams = [] }) => {
  const res = await fetch(`${ZERNIO}/inbox/conversations`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      accountId,
      participantId: to,          // digits with country code, no whatsapp: prefix
      templateName,               // template name instead of ContentSid
      templateLanguage: 'en_US',
      templateParams,
    }),
  });
  const { data } = await res.json();
  return data; // { messageId, conversationId, ... }
};

// Twilio: client.messages.create({ to, from, body })
const sendSms = async ({ from, to, text }) => {
  const res = await fetch(`${ZERNIO}/sms/messages`, {
    method: 'POST',
    headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() },
    body: JSON.stringify({ from, to, text }),
  });
  return res.json(); // { id, conversationId, status: "sent" }
};

Need Help?

• WhatsApp platform guides: /platforms/whatsapp
• Support: support@zernio.com
• Rate Limits: 60-1,200 req/min, bucketed by your team's connected-account count (0-2: 60, 3-2,000: 600, 2,001+: 1,200), see /guides/rate-limits