DEV Community: Sam

A2P 10DLC, Explained for Developers Who Just Want Their SMS to Send

Sam — Wed, 22 Jul 2026 10:01:15 +0000

You wired up Twilio. Your test messages went through. You shipped. Then a week later, delivery rates cratered and your logs filled with error 30034, and now you are reading a PDF from a mobile carrier that uses the phrase "messaging ecosystem integrity" without irony.

This post is the explanation I wanted when that happened to me. No compliance-speak. Just what the system is, why your messages are failing, and the architectural decision that makes most of the pain go away.

What A2P 10DLC actually is

A2P means application-to-person: a machine sending a message to a human. 10DLC means 10-digit long code, which is a normal-looking phone number as opposed to a short code (like 55555) or a toll-free number.

For years, developers used regular phone numbers to send application traffic because it was cheap and nobody stopped them. Spammers noticed the same thing. US carriers responded by building a registration system: if you want to send application traffic over a 10-digit number, you register who you are and what you are sending, and unregistered traffic gets filtered or blocked outright.

That is the whole thing. It is not a law. It is a set of carrier policies enforced through a shared registry called The Campaign Registry.

The practical consequence: your unregistered number is not "working but slow." It is on a path to being blocked entirely, and carriers have gotten progressively less patient about it.

The registration hierarchy

Three objects, nested.

Brand is you, the legal entity. EIN or equivalent tax ID, legal business name, address, website. This produces a trust score.

Campaign is a specific use case attached to a brand. Two-factor authentication, appointment reminders, marketing, customer care, and so on. One brand can run several campaigns. Each is reviewed independently.

Number is the phone number assigned to a campaign. A campaign can hold multiple numbers.

The piece that surprises people is the trust score. It is assigned to your brand, not your campaign, and it directly controls your throughput. A low-score brand might get 75 message segments per minute across all its numbers. A vetted, high-score brand gets thousands. Registering a second number does not increase your ceiling, because the ceiling belongs to the brand.

Sole proprietors have their own track with much lower limits, typically a single number and a few thousand segments per day. If you are pre-incorporation, this is the lane you are in, and it is worth knowing before you architect anything that assumes volume.

The distinction that changes everything

Carriers categorize traffic broadly along a conversational-to-promotional axis, and the compliance burden is wildly different at each end.

Promotional traffic is you initiating contact. Sending offers, announcements, campaigns, anything blasted to a list. This requires documented consent for every recipient, gets the heaviest scrutiny during campaign review, has the strictest content filtering, and is where most rejections happen.

Conversational traffic is a reply. The user texted you, or the user took an action in your system that explicitly requested a message, and your message is a direct response to that. Consent is implicit in the initiating action. Review is lighter. Filtering is more forgiving.

Most developers architect their SMS feature as a broadcast system with a recipient list, then spend weeks fighting registration. If your product can be built so that every outbound message is triggered by an inbound event, you have moved yourself into the easier category by design rather than by paperwork.

Inbound-triggered architecture

Here is the pattern concretely. Instead of maintaining a list and pushing to it, you make every message a response.

The user calls your number, or fills a form, or replies to a message. That inbound event is the trigger. Your system responds. Every outbound message in your logs traces back to an inbound action with a timestamp.

// Webhook receives inbound event (call completed, form submitted, SMS received)
app.post('/webhook/inbound', async (req, res) => {
  const { from, eventType, callSid } = req.body;

  // The consent record IS the inbound event. Store it.
  const consentRecord = await db.consent.create({
    phone: from,
    source: eventType,          // 'inbound_call' | 'inbound_sms' | 'web_form'
    reference: callSid,
    timestamp: new Date(),
    ip: req.ip || null
  });

  // Outbound is now a reply, not a broadcast
  await twilio.messages.create({
    to: from,
    from: process.env.REGISTERED_NUMBER,
    body: buildResponse(eventType),
    statusCallback: 'https://yourapp.com/webhook/status'
  });

  res.sendStatus(200);
});

Two things this buys you beyond category classification.

First, your consent record is generated automatically as a byproduct of normal operation. When a carrier or your provider asks how you obtained consent for a given number, you have a timestamped inbound event with a call SID or form submission attached. You are not reconstructing anything from a spreadsheet.

Second, your opt-out handling gets simple, because you are already listening on the inbound path.

const STOP_KEYWORDS = ['STOP', 'STOPALL', 'UNSUBSCRIBE', 'CANCEL', 'END', 'QUIT'];
const HELP_KEYWORDS = ['HELP', 'INFO'];

async function handleInboundSms(from, body) {
  const normalized = body.trim().toUpperCase();

  if (STOP_KEYWORDS.includes(normalized)) {
    await db.optOut.upsert({ phone: from, optedOutAt: new Date() });
    return null; // Carrier auto-replies to STOP. Do not send your own.
  }

  if (HELP_KEYWORDS.includes(normalized)) {
    return `${BRAND_NAME}: support at ${SUPPORT_EMAIL}. Reply STOP to opt out. Msg&data rates may apply.`;
  }

  const optedOut = await db.optOut.findUnique({ where: { phone: from } });
  if (optedOut) return null;

  return await generateReply(from, body);
}

Note the STOP branch returns null. Carriers intercept STOP and send their own confirmation. If you also send one, you have just messaged someone who opted out, and that lands on you.

Provider comparison

The registration process is standardized through The Campaign Registry, so the differences are in tooling, fees, and how much of the process the provider absorbs.

Twilio has the most polished registration UI and the best documentation. It also has the most conservative filtering, so borderline content gets blocked sooner. Registration fees are passed through with a markup. If you want the process to be as guided as possible and you can absorb slightly higher per-message costs, this is the default.

Telnyx is meaningfully cheaper per segment and per registration, with a more developer-oriented API surface. The onboarding is less hand-held, and the support experience assumes you know what you are doing. Good fit once you understand the system.

Plivo sits between the two on both price and tooling. Strong international coverage if you have traffic outside the US, which matters because 10DLC is a US-only regime and your architecture may need to branch by country.

For all three, brand registration takes minutes to hours. Campaign approval typically takes one to several business days and is where rejections happen.

The gotchas

Campaign rejections are usually about your website, not your code. Reviewers check that your site describes the messaging use case, shows how consent is collected, and has a privacy policy stating you do not sell phone numbers. A campaign describing appointment reminders when your homepage says nothing about appointments gets rejected. Fix the site before resubmitting.

Your sample messages must match what you actually send. Submit real message templates with variables clearly marked. Generic placeholders read as evasive.

HELP is mandatory and STOP is enforced. Every campaign needs a working HELP response with your brand name and support contact. Failure to honor opt-outs is the fastest route to having a campaign killed.

Segments, not messages. Throughput limits count segments. A message over 160 GSM-7 characters splits into multiple segments. One emoji forces the entire message into UCS-2 encoding, dropping the segment boundary to 70 characters. A cheerful 200-character message with a single emoji is four segments against your quota.

Sole proprietor limits are real. If you registered as an individual, you have a hard ceiling that no amount of optimization gets around. Plan for incorporation before you plan for scale.

Toll-free is a different regime. Toll-free numbers do not use 10DLC registration. They have their own verification process, often faster to approve, with different throughput characteristics. Worth evaluating if 10DLC registration is blocking you and your use case fits.

The short version

10DLC is not a tax you pay after building. It is a constraint that should shape the design.

If every outbound message in your system is a reply to something the user did, you get easier classification, automatic consent records, simpler opt-out handling, and a campaign application that reviewers approve without a fight. If your system is a broadcast engine with a list, you will fight the registry, and you will keep fighting it every time you add a use case.

Build it as a conversation. The compliance mostly takes care of itself.

I build VoiceIntego, an AI voice receptionist for dental and home service businesses, which is where the inbound-triggered pattern above comes from.

What I learned building an AI voice agent stack solo (Vapi + n8n, 2 months in)

Sam — Sat, 13 Jun 2026 21:09:32 +0000

Two months ago I started building voice agents for small service businesses. dental clinics and HVAC companies that lose real money every time a call goes to voicemail. I'm doing it solo, alongside a day job, which means every wrong turn costs me a weekend I don't get back.

Here's what actually went wrong, what I'd tell myself on day one, and the parts of the stack that held up.

The stack, briefly

Vapi for the voice layer (speech-to-text, the LLM turn, text-to-speech)
n8n self-hosted on a cheap VPS for orchestration — booking lookups, calendar writes, follow-up triggers
A Google Sheets + n8n layer for scheduling and logging while I'm pre-revenue and don't want to pay for tooling I haven't validated

Nothing here is exotic. That was the point. I wanted boring, debuggable infrastructure I could reason about at 11pm.

Lesson 1: The hard problem isn't the AI. It's the handoff.

I assumed the voice model would be the scary part. It wasn't. Modern voice platforms handle the conversation surprisingly well out of the box.

The actual pain was everything around the conversation — what happens when the agent needs to check an appointment slot, write to a calendar, or hand off to a human gracefully. That orchestration logic is where I lost the most time, and it's the part no demo video ever shows you.

If you're evaluating this space: budget your time for the plumbing, not the model.

Lesson 2: Self-hosting n8n is worth it, but prune your execution data or die

Running n8n in Docker on a small VPS is genuinely fine for low volume. What nobody warned me about: execution data accumulates fast and will quietly eat your disk.

The fix is one environment variable:

Set it early. I found out the way you'd expect — a workflow failing for no obvious reason, an hour of confusion, then a df -h showing a nearly full disk.

Lesson 3: Cold outreach taught me more than my landing page did

I ran a cold email campaign to roughly 1,600 leads over two months. Clean domain warmup, SPF/DKIM/DMARC all verified, aggregate reports showing no auth failures.

Replies: basically zero.

That stung, but it was useful. It forced me to confront that deliverability being technically correct and the message being compelling are completely different problems. The infrastructure was fine. The offer and the targeting weren't sharp enough yet. No amount of DNS hygiene fixes a message that doesn't land.

Lesson 4: Narrow beats broad, faster than I expected

Early on I wanted to serve "service businesses." Too vague. The moment I picked one vertical and wrote scripts for specific call patterns — new patient booking, after-hours emergencies, the weird edge cases a real receptionist handles — everything got easier. The demos got sharper. The objections got predictable.

If you're building anything agent-shaped: pick the narrowest viable slice and over-fit to it. You can generalize later.

What I'd tell myself on day one

The model is the easy 20%. Plan for the orchestration.
Turn on data pruning before you need it.
Correct infrastructure ≠ a message people respond to. Validate the offer separately.
Go narrower than feels comfortable.

If you're building in the voice-agent or automation space and have hit the same walls, I'd genuinely like to compare notes in the comments.

I'm building [VoiceIntego], AI voice agents for service businesses, mostly so businesses stop losing jobs to voicemail. Still early. Happy to talk shop.

Building an AI Voice Agent for Appointment Booking: What I Learned

Sam — Fri, 05 Jun 2026 09:53:17 +0000

Over the past few months I’ve been building VoiceIntego, an AI voice agent that answers calls and books appointments for service businesses (dental clinics, HVAC, plumbing). Here are some of the technical lessons that surprised me along the way.

Latency is the whole game

With text chatbots, a 2-second delay is fine. On a phone call, anything over ~800ms feels broken — people start talking over the AI. The hard part isn’t the LLM response; it’s the round trip: speech-to-text → LLM → text-to-speech, all streaming. You have to stream every stage and start TTS before the full response is generated.

Interruptions break naive pipelines

Real callers interrupt. “Actually, can we do Tuesday instead—” mid-sentence. A simple request/response loop can’t handle this. You need barge-in detection: monitor the incoming audio stream and cancel the current TTS playback the moment the caller starts speaking again.

Booking logic needs guardrails, not vibes

Letting the LLM “decide” availability is a recipe for double-bookings. The reliable pattern: the LLM extracts intent (date, time, service), then deterministic code checks the actual calendar API and confirms. The model handles language; your code handles truth.

Confirmation loops matter more than you’d think

Always read the booking back: “So that’s a cleaning on Tuesday the 9th at 2pm — correct?” Phone audio is noisy and names/times get misheard constantly. One extra confirmation turn cuts errors dramatically.

Phone numbers and edge cases everywhere

Voicemail detection, callers who mumble, background noise, people who say “yeah” to mean no. The happy path is maybe 20% of the work.

If you’re building something in this space, happy to compare notes. You can see what I’m working on at VoiceIntego.