Skip to main content
skill CX Codex

migrate-to-sent — Claude Code skill: CPaaS migration from Twilio

migrate-to-sent is a skill that maps sends, statuses, webhooks, opt-outs, and templates when moving from Twilio, Sinch, Infobip, Vonage, or MessageBird/Bird to Sent v3.

MIT 2,700 installs ★ 40 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sentdm/sent-plugin --skill migrate-to-sent -a claude-code
Open on GitHub

What migrate-to-sent does

Any migration off a major CPaaS provider hits five translation problems, and this skill works through them in a fixed order. The first is ordered fallback. On Sent the channel array is a broadcast list, so porting an ordered array from Twilio or Sinch produces one message and one charge per recipient-channel pair. Tests pass; production spend multiplies. The rule is blunt: never port an ordered channel list. Omit channel or send ["sent"] and let the platform route.

Status vocabularies do not line up. Sent adds ROUTED and SCHEDULED, which have no incumbent equivalent. A handler that treats every non-delivered terminal state as retryable will retry consent blocks, and that is a compliance failure rather than a bug. Numeric provider error codes, Twilio's 21610 being the classic, get rewritten against Sent's string error.code families.

Webhook verification is a rewrite. Sent signs with x-webhook-signature: v1,{base64}, HMAC-SHA256 over {x-webhook-id}.{x-webhook-timestamp}.{raw_body}. The key is the signing secret with whsec_ stripped and the rest base64-decoded, compared in constant time; timestamps outside 300 seconds are rejected. Sent provides no per-event id, so dedupe keys must come from payload semantics. The skill tells you to build the receiver with sent-webhook-engineer instead of adapting the old verifier.

Opt-out stores need reconciliation, not a copy.

What it helps with

  • map send calls, statuses and webhooks from the old provider to Sent v3
  • avoid broadcast overbilling when porting an ordered channel array
  • rewrite retry logic so consent blocks are never retried
  • reconcile suppression lists without losing opt-outs during the move
  • convert WhatsApp templates to named parameters before cutover

Example prompts for the agent

  • Plan a migration from Twilio to Sent v3 and find every call site that needs rewriting
  • Check our webhook handlers and rewrite signature verification for Sent
  • Locate ordered channel arrays in the repo and replace them with automatic routing

How to install migrate-to-sent

1Skills CLI (Vercel)

npx skills add sentdm/sent-plugin --skill migrate-to-sent -a claude-code

2Manually: put the files in place

~/.claude/skills/migrate-to-sent/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/migrate-to-sent/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about migrate-to-sent

How do I install migrate-to-sent in Claude Code?

Run npx skills add sentdm/sent-plugin --skill migrate-to-sent -a claude-code. The skill lands at ~/.claude/skills/migrate-to-sent/SKILL.md.

What does migrate-to-sent do?

It plans and executes a migration from Twilio, Sinch, Infobip, Vonage or MessageBird/Bird to Sent v3: send calls, status vocabularies, webhook signature schemes, opt-out stores, templates and tenancy models, then a phased cutover with dual-run and rollback.

Why can't I just port the ordered channel list?

On Sent the channel array is a broadcast list. An ordered array port produces one message and one charge per recipient-channel pair, tests miss it, and production spend jumps. Omit channel or send ["sent"] and hand routing to the platform.

Source text

SKILL.md · MIT
---
name: migrate-to-sent
description: Plans and executes a migration from Twilio, Sinch, Infobip, Vonage, or MessageBird/Bird to Sent v3 — mapping send calls, status vocabularies, webhook signature schemes, opt-out stores, templates, and tenancy models, then cutting over safely with dual-run and rollback. Use when replacing an incumbent CPaaS provider, translating provider code or webhook handlers to Sent, or planning a phased cutover and its verification gates.
---

# Migrate to Sent

Every migration from a major CPaaS provider hits the same five translation problems. Work them in this order, because the first one silently doubles cost and is invisible in tests.

## 1. Ordered fallback becomes automatic routing

Incumbent platforms express cross-channel delivery through different caller-side arrays, failover objects, messaging-service features, or application-level priority configuration. Do not assume those shapes have a direct Sent request-field equivalent.

**Sent's `channel` array is a broadcast list.** Porting an ordered array produces one message and one charge per recipient-channel pair, which passes tests and multiplies production spend. The correct translation is automatic routing — omit `channel` or send `["sent"]` — which lets the platform select a route and reroute across up to three channel-and-provider pairs on the same `message_id`. Details belong to `sent-routing-strategist`; the migration rule is simply: **never port an ordered channel list.**

## 2. Status vocabularies do not line up

Incumbent statuses map onto Sent's, but Sent adds two states that have no equivalent and that break naive retry logic.

| Sent status | Closest incumbent analogue | Migration note |
| --- | --- | --- |
| `QUEUED` | Twilio `queued`, Sinch `QUEUED_ON_CHANNEL` | Accepted, not sent |
| `ROUTED` | no analogue | Route chosen; fires again on reroute |
| `SENT` | Twilio `sent`, Sinch `MESSAGE_SUBMIT` | Provider handoff only |
| `DELIVERED` | `delivered` everywhere | The first proof of handset receipt |
| `READ` | Twilio `read`, Sinch `READ` | WhatsApp and RCS only |
| `FAILED` | `failed`, `undelivered` | May still reroute; not necessarily final |
| `FILTERED` | Twilio error 21610 (opt-out) | **Policy gate. Never retry** |
| `BLOCKED` | account-level errors | **Account precondition.** Fix the account, then resend |
| `SCHEDULED` | no analogue | Quiet-hours parking; resumes automatically |

Two consequences for ported code. Handlers that treat every non-delivered terminal state as retryable will retry consent blocks, which is a compliance failure rather than a bug. And handlers keyed on numeric provider error codes — Twilio's `21610` is the classic — must be rewritten against Sent's string `error.code` families.

## 3. Webhook verification is a rewrite, not a port

No two providers sign the same way, and no Sent SDK ships a verifier.

| Provider | Scheme |
| --- | --- |
| Twilio | `X-Twilio-Signature`, base64 HMAC-**SHA1** over the full URL plus sorted POST parameters |
| Sinch | HMAC-SHA256 over `body.nonce.timestamp`, four `x-sinch-webhook-signature*` headers, or OAuth 2.0 |
| Infobip | Basic, HMAC-SHA256 over the raw body, or OAuth on a notification profile; **the header name is account-configured** |
| Vonage | JWT in `Authorization: Bearer`, or a legacy `sig` parameter |
| MessageBird/Bird | `messagebird-signature`, base64 HMAC-SHA256 over timestamp, URL, and a SHA-256 body hash |
| **Sent** | `x-webhook-signature: v1,{base64}`, HMAC-SHA256 over `{x-webhook-id}.{x-webhook-timestamp}.{raw_body}` |

Sent's key is the signing secret with `whsec_` stripped and the remainder base64-decoded, compared in constant time, with timestamps outside 300 seconds rejected. Because Sent provides no per-event id, dedupe keys must be derived from payload semantics. Build the receiver with `sent-webhook-engineer` rather than adapting the incumbent's verifier.

## 4. Opt-out stores must be reconciled, not migrated by copy

Every provider keeps its own suppression list — Twilio Advanced Opt-Out, Infobip Blocklist, Sinch OPT_IN/OPT_OUT events. Sent enforces consent at the platform level before events reach the application, stores it as `opt_out` on the contact, and applies it **channel-agnostically**: a `STOP` on SMS suppresses WhatsApp and RCS too.

Reconciliation rules: export the incumbent's suppression list before cutover, treat any opt-out on any incumbent channel as a global Sent opt-out, and never clear `opt_out` to "clean up" migrated data. Sent's ten default keywords are `STOP`, `CANCEL`, `UNSUBSCRIBE`, `QUIT`, `END`, `START`, `UNSTOP`, `SUBSCRIBE`, `HELP`, `INFO`, matched only when the entire trimmed body equals the keyword — so incumbent-specific keywords need custom keyword entries. Rewrite any incumbent keyword matcher as an exact local consent mirror and audit mechanism; the matcher must not write consent to Sent again. Consent semantics belong to `sent-two-way-messaging`.

## 5. Templates and tenancy are re-registered, not transferred

WhatsApp templates live with the WABA, so the migration question is whether the WABA moves. Positional placeholders (`{{1}}`, `{{2}}`) become **named** parameters in Sent, which means every call site that passed an ordered array must pass a named map. Approval is asynchronous and arrives as a `templates` webhook event, so build the template inventory before cutover rather than during it.

Tenancy maps as follows, with the boundary decision owned by `sender-profile-architect` and the API work by `sent-profile-provisioning`:

| Incumbent construct | Sent equivalent |
| --- | --- |
| Twilio subaccount | Sender Profile |
| Twilio Messaging Service | routing plus profile configuration, not a caller-side pool |
| Infobip Application or Entity | Sender Profile |
| Sinch Conversation API app | Sender Profile |
| Provider API credential per tenant | Profile-scoped API key, or organization key with `x-profile-id` |

## Migration sequence

1. **Inventory** every send call site, webhook handler, status branch, template, suppression list, and credential. Use `scripts/inventory_scan.py` to find them mechanically. It reads local regular files inside the selected repository, skips symbolic links and environment files, and reports paths, line numbers, and migration guidance without source excerpts. It makes no network requests.
2. **Map** each item using [references/provider-mapping.md](references/provider-mapping.md), flagging ordered-fallback arrays and numeric error codes as required rewrites.
3. **Stand up Sent in parallel**: credentials, one webhook per environment, verified receiver, templates re-registered and approved.
4. **Prove equivalence in sandbox** with `"sandbox": true`, then with a small live cohort confirmed to `DELIVERED`.
5. **Dual-run** with a traffic split, comparing delivery rates, latency, and cost per message on the same message classes.
6. **Cut over** by message class — lowest-risk transactional first, marketing last — keeping the incumbent receiver live.
7. **Decommission** only after a full billing cycle of clean data, then revoke incumbent credentials.

Sequencing detail, verification gates, and rollback triggers are in [references/cutover-playbook.md](references/cutover-playbook.md).

## Mistakes that survive testing

- Porting an ordered channel array. Doubles cost, never errors.
- Treating `FILTERED` as retryable. Compliance exposure.
- Reusing the incumbent's signature verifier. Every delivery returns 401.
- Assuming `202` means delivered. Sent acknowledges acceptance only.
- Keeping positional template placeholders. Parameters silently mismatch.
- Retrying on `401`. Ten consecutive auth failures lock the credential with escalating lockout.
- Omitting `Idempotency-Key` during dual-run. A timeout retry sends twice.
- Sending `x-profile-id` with a profile-scoped key. Returns `403`.
- Copying an incumbent's `Authorization: Bearer` pattern. Sent authenticates with `x-api-key`.

## Boundaries

This skill owns provider mapping and line-by-line migration planning. Hand the resulting Sent client and resilience work to `sent-integration-starter`, channel semantics to `sent-routing-strategist`, receiver construction to `sent-webhook-engineer`, WhatsApp onboarding to `waba-embedded-signup`, and US campaign registration to `sms-10dlc-registration`.

© sentdm · MIT · sentdm/sent-plugin

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set19

The whole set →
waba-embedded-signup waba-embedded-signup is a Claude Code skill that guides WhatsApp Business Account onboarding in Sent. It separates dashboard signup flows from API profile creation. CX Codex +1 2,900installs waba-template-author waba-template-author converts messaging copy into valid payloads for the Sent v3 API and reviews WhatsApp policy constraints. Useful for building utility, marketing, and OTP templates. CX Codex +1 2,900installs sent Turns vague Sent requests into a specific skill or MCP-backed operation instead of guessing. CX Codex +1 2,900installs sent-profile-provisioning The sent-profile-provisioning skill drives the Sender Profile lifecycle in Sent: list, inspect, create, update and delete over MCP tools, plus the wider REST flow. Useful when onboarding a tenant and getting a profile ready to send. CX Codex +1 2,700installs sent-routing-strategist sent-routing-strategist is a Claude Code skill that explains Sent channel selection and message rerouting. It applies when setting channel or investigating delivery outcomes. CX Codex +1 2,700installs sent-integration-starter sent-integration-starter is a Claude Code skill for adding Sent v3 to an existing project. It kicks in when wiring an SDK, sending messages, or setting up webhook handling. CX Codex +1 2,700installs sent-webhook-engineer sent-webhook-engineer — a skill for building and debugging Sent v3 webhook receivers: signature checks, replay rejection, event dedupe and delivery-log triage. CX Codex +1 2,700installs sent-two-way-messaging sent-two-way-messaging designs inbound messaging flows on Sent, covering keyword opt-outs, WhatsApp 24-hour window rules, RCS chips, and conversation history. Useful for support bots and webhooks. CX Codex +1 2,700installs

Project sponsors

Companies that keep this analytics open