Migrating from Twilio to Naive

• The number lives behind a Twilio Account SID + Auth Token, its own console, and its own billing — disconnected from wherever the agent’s cards, email, secrets, and KYC live.
• A2P 10DLC compliance (Brand + Campaign registration, Messaging Services, sender pools) is yours to wire up and keep registered against your business entity.
• “Who let this agent text a customer, and what else can it touch?” is answered in Twilio for messaging, and in unrelated systems for everything else. The rented DID has no shared accountability with the rest of the agent’s footprint.

• The tenant user that owns the number is the same user that owns its cards, its email inboxes, its vault secrets, and its KYC.
• The 10DLC carrier campaign is registered against the entity that user already formed and KYC’d — accountability is built into provisioning, not bolted on.
• Whether an agent may send SMS — and whether provisioning a new number freezes for human approval — is decided by that user’s Account Kit and per-agent assignment at execution time.

​

Concept map

​

Before / after: the core path

import twilio from "twilio";

const client = twilio(
  process.env.TWILIO_ACCOUNT_SID!,
  process.env.TWILIO_AUTH_TOKEN!,
);

// 1. Search for a US number, then buy it (two calls)
const [candidate] = await client
  .availablePhoneNumbers("US")
  .local.list({ areaCode: 415, smsEnabled: true, limit: 1 });

const number = await client.incomingPhoneNumbers.create({
  phoneNumber: candidate.phoneNumber, // e.g. "+14155551234"
});
// → number.sid ("PNxxxx"), number.phoneNumber

// 2. (separately) register an A2P 10DLC Brand + Campaign and attach a
//    Messaging Service before US carriers will deliver application traffic.

// 3. Send a message from it
const sent = await client.messages.create({
  from: number.phoneNumber,
  to: "+14155559876",
  body: "Your order shipped!",
});
// → sent.sid, sent.status

import { Naive } from "@usenaive-sdk/server";

const naive = new Naive({ apiKey: process.env.NAIVE_API_KEY! });
const client = naive.forUser("acme"); // same id space as your own users

// 1. Provision a US number — buys it AND submits the 10DLC campaign in one call.
//    `ein` is required the first time (carrier brand registration).
const { phone, campaign } = await client.phone.provision({
  ein: "12-3456789",
  area_code: "415",
  label: "Support",
});
// → phone.id (UUID), phone.e164, campaign.status ("created" | "in_review" | "active")

// 2. Send a message from it (blocked with `compliance_pending` until the
//    campaign is approved — no message sent, no credit charged).
const sent = await client.phone.send({
  from: phone.id,
  to: "+14155559876",
  body: "Your order shipped!",
});
// → sent.status, credits used/remaining

• One call to provision, not two-plus. Twilio is search → buy → register A2P → attach a Messaging Service. Naive’s provision buys the number and submits the 10DLC campaign together.
• from is a UUID, not the E.164 string. Twilio’s from is the number itself. Naive’s phone.send takes the phone.id UUID; the e164 string is returned for display.
• Outbound is carrier-gated on both — Naive surfaces it inline. Until the 10DLC campaign is active, Naive returns compliance_pending (no charge); poll phone.status() for progress.
• The id is your identity, not a separate account. In Twilio the Account SID scopes Twilio. In Naive the same forUser(id) handle also owns the agent’s cards, email, vault, and KYC.

​

Receiving replies

// Configure the number's inbound webhook, then handle Twilio's POST:
app.post("/sms", (req, res) => {
  const from = req.body.From;   // "+14155559876"
  const body = req.body.Body;   // the inbound text
  // Optionally reply synchronously with TwiML:
  res.type("text/xml").send("<Response><Message>Got it</Message></Response>");
});

// Or read the message logs:
const msgs = await client.messages.list({ to: number.phoneNumber, limit: 20 });

// Poll inbound for a number (newest first, cursor-paginated):
const messages = await client.phone.messages(phone.id, { limit: 20 });
for (const m of messages) {
  const full = await client.phone.read(m.id); // full body + any media URLs
}

// Or subscribe to the inbound event (verify against GET /v1/webhooks/event-types):
const sub = await naive.webhooks.create(
  "https://app.example.com/api/webhooks/naive",
  ["sms.received"],
);
// store sub.secret — verify with verifyWebhookSignature()

• On Naive, inbound texts are captured automatically and queryable via phone.messages / phone.read — that path always works the moment a number is live.
• The sms.received webhook is documented in the phone primitive for real-time reactions. The canonical emitted-event list is GET /v1/webhooks/event-types — treat that as the source of truth and confirm the event before depending on it (see gaps).
• There is no synchronous TwiML reply. To answer an inbound message, call phone.send.

​

Minimal viable migration

npm install @usenaive-sdk/server

​

Consolidate further once you’re on Naive

// One subaccount per customer; isolates numbers and messages, and only those.
const sub = await client.api.accounts.create({ friendlyName: "acme" });
const subClient = twilio(sub.sid, sub.authToken);
const number = await subClient.incomingPhoneNumbers.create({ phoneNumber });
await subClient.messages.create({ from: number.phoneNumber, to, body });

// The card, the vault secrets, the email inbox, the KYC for this customer's
// agent live in entirely separate systems with their own tenancy.

// One tenant user per customer; isolates *every* primitive.
const acme = await naive.users.create({
  external_id: dbCustomer.id,
  email: dbCustomer.email,
});

const client = naive.forUser(acme.id);

const { phone } = await client.phone.provision({ ein: "12-3456789", area_code: "415" });
await client.phone.send({ from: phone.id, to, body });

// The SAME client owns this customer's card, email inbox, vault, and KYC —
// one identity, isolated end to end, and the number is registered against it.
await client.cards.create({ spending_limit_cents: 25_000 });
await client.email.createInbox({ local_part: "support" });
await client.vault.put("internal.api_key", "key_xyz");

​

Gain #1 — one identity across primitives

• With Twilio, the agent’s numbers are an island behind an Account SID. With Naive, naive.forUser(acme.id) is a single handle to phone and cards and email and vault and KYC.
• The number is not an anonymous DID — its 10DLC campaign is registered against the entity that identity already formed and verified. Tear the customer down from one place; sibling tenants can never read each other’s messages, cards, or secrets.

​

Gain #2 — execution-time permission enforcement

• Whether an agent may send SMS at all is per-agent assignment on the number, and whether provisioning a new number freezes for human review is policy on the Account Kit — not a check you hand-write and not a Twilio API-Key scope you manage separately.

// Provisioning a number is approval-gated by default; SMS sending is not.
const starter = await naive.accountKits.create({
  name: "Starter",
  primitives_config: {
    phone: { enabled: true, requiresApproval: true }, // new numbers freeze for approval
    cards: { enabled: false },                          // no card for this tier
  },
});
await naive.accountKits.assignUser(starter.id, acme.id);

// An agent only gets to text from a number you connect it to:
await client.phone.assign(phone.id, agentId, ["send_sms", "receive_sms"]);

• The agent’s code is identical for every tier — client.phone.send({ ... }). Whether the call runs is decided at execution time:
  • An agent without send_sms on the number is refused with forbidden, with no code change on your side.
  • phone.requiresApproval: true freezes a provision until a human approves — the API replays it only after approval. Sending SMS is a routine action and is not approval-gated.

​

Gain #3 — unified accountability

• Every provision, send, and inbound reply for a customer lands in one per-user activity log — alongside their card, email, vault, and KYC events, not in a separate Twilio console:

const { events } = await naive.forUser(acme.id).logs.query({ limit: 50 });
// "what did this agent do, for whom?" — phone, cards, email, vault, one timeline

• That is the question that is hard to answer when SMS lives in Twilio, cards live in Stripe, and secrets live somewhere else. Under Naive it is a single query.

​

What does not map yet

​

Where to go next

• phone primitive — full provision/send/receive lifecycle + 10DLC gating
• phone SDK sub-client — typed method signatures
• phone CLI — provision, send, messages, assign, release
• Webhooks — outbound event subscriptions (confirm sms.received via GET /v1/webhooks/event-types)
• Account Kits and Approvals — the policy model behind execution-time governance and provision approval
• Verification and Formation — the KYC + entity that the carrier registration (and the consolidation) hangs off
• Tenant users — the identity that owns the number, cards, email, and vault