cometchat-migrate-from-twilio

Ground truth: the TWILIO side (what to look for) is baked in references/inventory.md + references/feature-map.md — confirm each hit by reading the user's code and, where unsure, Twilio's current Conversations docs. The COMETCHAT side is never from memory: symbols from the target family's skills + catalog, feature existence from features.json, signatures via cometchat-<family>-core/references/docs-map.md (Docs MCP first — RULES.md → Fetch discipline). REST pages under DOCS_BASE = https://www.cometchat.com/docs.

Companion skills (read first)

• cometchat-<family>-core — the init → login → render (or the Chat SDK init/login) the migrated app lands on; <family> resolved in step 1.
• cometchat-security — the server token endpoint that replaces Twilio access tokens.

Use this skill when

"migrate my app from Twilio to CometChat", "replace Twilio Conversations", or "migrate my app to CometChat" when npx @cometchat/skills detect --json reports migrate_from vendor twilio. Sendbird/Stream apps → their own skills.

The single-prompt contract (read before step 1)

The migration request IS the approval (RULES.md → Competitor migration). Run every step to the end in one turn: no plan/approve gate, no questions — take the documented default and record it under Defaults taken. Work on a cometchat-migration git branch; never commit/push. You DO run the data-import script — but only at the very end and only after the user hands you the credentials (step 8); that single credential prompt is the sole exception to "no questions". Removing Twilio is the requested outcome; non-Twilio code is only rewired. Only STOP if: no Twilio usage found (hand to cometchat), the platform has no family in this pack (deliver the inventory as the report), or the app didn't build before you started (record it, migrate anyway, label pre-existing).

Twilio is headless — so this is client/SDK mode

Twilio Conversations ships no UI Kit; the app already has its own chat UI on the Twilio client. Default migration therefore keeps that UI and swaps the data layer to the CometChat Chat SDK (cometchat-<family>-core docs-map → SDK), mapping CometChat objects into the app's existing view models at the boundary. If the user instead wants CometChat's prebuilt UI, offer to replace their UI with the family UI Kit (a bigger change) — but the safe default is data-layer-only.

Migration workflow (BAKED — do every step, in order)

Every step applies to every app: users and history exist even in a small app, so steps 4 (toCometChatId) and 8 (data script) are ALWAYS delivered; skip only a step whose subject truly doesn't exist (no server → step 7), listed as skipped: <why>.

1. Detect. npx @cometchat/skills detect --json → framework, existing_cometchat, migrate_from. Resolve <family> (peers.yaml; per-platform targets in references/inventory.md). Run the app's build once and record pass/fail.
2. Inventory. Grep per references/inventory.md (packages, Client/Conversations.Client, access-token fetch, getConversationBySid/create, sendMessage, getMessages, participants, stateChanged/message listeners, media, attributes, push, the token server). Record each hit file:line → purpose.
3. Feature map. For each Twilio feature, use references/feature-map.md, then check the CometChat id in the family's features.json AND the docs (UI Kit + SDK). Present → migrate. An empty MCP search is INCONCLUSIVE, not "unsupported": re-query with CometChat vocabulary (e.g. "media recorder"/"voice notes", not "voice message recorder"; drop version/platform over-qualifiers), then LIVE-FETCH the likely docs page (fetch_cometchat_doc_page, or a plain fetch of the docs URL + .md), then cross-check the family CATALOG (installed component/symbol list). Mark UNSUPPORTED only when the CATALOG lacks it AND the live doc fetch (not merely an empty MCP search) also finds nothing (then remove + list). Never call unsupported from memory or from an empty search; if it genuinely can't be verified, KEEP it + needs-verification.
4. Install CometChat + wire init/login per cometchat-<family>-core. Identity: the CometChat UID is the app's Twilio identity through one shared toCometChatId() (references/concept-map.md §IDs), used by client login, the token server, and the data script.
5. Replace the data layer, file by file (references/concept-map.md): Twilio Client init/token → CometChat init/login; Conversation → a user or group conversation; Participant → group member; Message send/get → CometChat send/messages request; stateChanged/messageAdded listeners → CometChat listeners (removed on unmount); media → attachments; attributes → metadata. Keep the app's UI; map at the boundary. Remove each Twilio import as its last use goes.
6. Remove unsupported features FULLY — code, UI entry points, state, deps, tests. Log each for the report.
7. Server side. Replace the Twilio access-token endpoint (API Key/Secret + Conversations Service SID → JWT) with a CometChat auth-token endpoint (cometchat-security; create user if missing → POST /v3/users/{uid}/auth_tokens). Map Twilio webhooks (onMessageAdded, etc.) to CometChat webhooks; drop/list any with no equivalent. Replace other Conversations REST calls with CometChat REST, or remove + list.
8. Data-migration script — write it, then run the import for the user. scripts/cometchat-migration/ per references/data-migration.md: export users/conversations/participants/messages from the Twilio Conversations REST API → transform with the shared toCometChatId() → import via the CometChat Data Import API. When the code migration is done, tell the user the data-import script is ready and ask for the credentials it needs — the Twilio keys (TWILIO_ACCOUNT_SID, TWILIO_API_KEY, TWILIO_API_SECRET, TWILIO_CONVERSATIONS_SERVICE_SID) and the CometChat App ID, Region and full-access REST API key. (This one credential prompt is the sole exception to the no-questions contract.) The moment they provide them, RUN the import yourself from env vars — never write secrets into a repo file: a --dry-run first (show counts), then the real import, then report results. Only messages within CometChat's 6-month retention window import — tell the user to reach out to CometChat to import messages older than 6 months. If they decline to share credentials, leave running it as an action item.
9. Uninstall Twilio — remove every Twilio dependency (@twilio/conversations, twilio-conversations, twilio-chat, the server twilio SDK) + lockfile, env vars, native config, CI secrets. Reinstall. Update the app's own docs (README/.env.example) and rename twilio* identifiers.
10. Verify (§Verify it works). Fix build errors you introduced. No live tests unless asked.
11. Report. Write COMETCHAT_MIGRATION.md from references/report-template.md; END the reply with its Removed + Action items lists.

Common pitfalls

• Identities that CometChat rejects. Twilio identity strings can hold characters CometChat UIDs can't (alpha-dash, ≤100, lowercased). Sanitize with one shared function everywhere.
• 1:1 vs group. A Twilio conversation with exactly two participants → a CometChat user conversation, not a two-person group.
• Optimistic send / pagination / listeners differ — see references/concept-map.md behavioral gotchas; keep the app's UX identical, only the data source changes.
• Access token ≠ Auth Key. Twilio's client token maps to a CometChat auth token (server-minted), not the Auth Key. Never ship the Auth Key.
• Half-removed features / left-behind listeners — remove entry points too; remove every listener on unmount.
• Programmable Chat vs Conversations — older apps use twilio-chat (Channel/Member/Message); the mapping is the same shape, note which the app uses.

Verify it works

The app builds with the family's normal command · zero Twilio residue (grep -rIiE 'twilio' . finds only the report + data script) · every CometChat symbol exists in the catalog · every migrated feature is in features.json/docs; every UNSUPPORTED item is in the report with its files · client login, token server, and data script all use the same toCometChatId().

RUN it and read the logs — a compile is NOT a working app (do this; don't skip). When you're done implementing, START the app and confirm it LOADS with the chat surface rendered and NO errors in the browser console / dev-server terminal (native: platform run + logs). Fix EVERY runtime error you introduced — a Cannot read properties of undefined from a half-migrated reference, or an SDK enum/class read at module-load before the SDK is ready, is a migration bug (see cometchat-<family>-troubleshooting). If it can't be started here, SAY SO and give the user the exact run command + what to watch for — never silently skip this.