SMS migreren vanuit Plivo
Deze pagina vertaalt Plivo's Message API, Powerpacks en delivery-callbacks naar Bird. Volg de hoofdmigratiegids op volgorde en gebruik deze vertaaltabellen voor stap 3, 4 en 5.
Het verzenden is het makkelijke deel. Beide accepteren JSON met veldnamen in kleine letters, en beide houden 10DLC-registratie naast het verzenden in plaats van op een aparte host. Twee dingen veranderen. Plivo's POST https://api.plivo.com/v1/Account/{auth_id}/Message/ authenticeert met een Auth ID en Auth Token via HTTP Basic; POST /v1/sms/messages gebruikt een bearer API-sleutel tegen je regionale host, zonder accountsegment in het pad. En een Plivo Powerpack bundelt een nummerpool, sticky-afzendergedrag en opt-outstatus in één object; Bird splitst die over afzenders, suppressions en keywordregels, dus er is niets om als Powerpack na te bouwen.
Geef dit aan je agent
Gebruik deze briefing in je coding-agent. Hij begint met inventarisatie en levert een reviewbaar migratieplan op voordat er iets in productie verandert.
Codevoorbeeld
Help me migrate my SMS integration from Plivo to Bird.
1. Inspect this repository's sends, senders, callbacks, schedules, templates, opt-outs and tests. List the traffic and behavior that must survive the migration.
2. Read the Markdown guides at https://bird.com/docs/guides/sms/migrate/plivo.md and https://bird.com/docs/guides/sms/migrate.md. Use an existing authenticated Bird MCP or CLI connection. If neither is available, follow https://bird.com/docs/ai/set-up-your-agent.md. Discover the actual operations; do not invent commands or ask me to paste credentials into chat.
3. Prepare the code changes, sender/destination requirements, consent migration, webhook verification and rollout/rollback plan. Preserve the scope of each customer's preferences, including requests outside SMS replies. Separate API batches from audience broadcasts and preserve any behavior that has no direct endpoint equivalent.
4. Show me the exact affected resources, destinations, test volume and known costs before an action that sends messages, spends money, registers or changes a sender, or moves production traffic. Require explicit human authorization for each paid submission or production change. Name one-off 10DLC registration and resubmission fees before requesting approval. An existing explicit approval for that exact action is sufficient; broad migration approval is not. Simulated SMS destinations are billable and still require authorization.
5. If I am keeping Plivo numbers, prepare the human support port request and obtain authorization to send it. Read bird support-tickets create --help, then use the available CLI or MCP support operation with the reviewed number list and requirements. Return the ticket ID and follow the reply; support arranges the port on its own schedule, separately from the code cutover.
6. Run local and intercepted tests first. When authorized, perform the agreed bounded integration tests, inspect accepted and final outcomes separately, and report failures or uncertainty. Do not claim a delivery receipt proves reading or that request idempotency guarantees exactly-once delivery.
7. Keep production cutover and retiring the old provider as explicit steps in the approved rollout. Finish with the diff, evidence, unresolved requirements and the next action.Vertaal de verzendaanroep
| Wat het doet | Plivo | Bird |
|---|---|---|
| Ontvanger | dst | to (één per request) |
| Afzender | src of powerpack_uuid | from |
| Berichttekst | text | text |
| Kanaalselector | type: sms, mms, whatsapp | het endpoint zelf; /v1/sms/messages is SMS |
| Intent | (geen) | category, verplicht bij vrije tekst |
| Afleverrapporten | url + method, per bericht | een werkruimte-webhook; alleen JSON POST, zie hieronder |
| Round-trip-context | je eigen opslag, op UUID gekeyd | metadata: willekeurige JSON, bij elk event teruggegeven |
| Filterbare labels | (geen) | tags: {name, value}-paren |
| Veilig opnieuw proberen | (niet gedocumenteerd) | Idempotency-Key-header |
| Media | media_urls | geen equivalent: media_urls wordt geweigerd |
Opmerkingen bij het porten:
- Een Powerpack-UUID wordt een gewone afzenderwaarde. Plivo lost de nummerpool, sticky-afzender en lokale aanwezigheid achter de UUID op. Bird neemt de afzender zelf in from, dus kies hem per verzending, of gebruik een template-verzending, die een geldige afzender voor de bestemming selecteert en from weigert.
- type heeft geen tegenhanger omdat het endpoint het bepaalt. Plivo selecteert het kanaal per request; SMS, WhatsApp en andere kanalen van Bird zijn aparte endpoints. Een codebase die type at runtime wisselt, splits je op in aanroepen naar verschillende endpoints.
- Niets in de Message API komt overeen met category. Bepaal per berichttype of het transactional, marketing, authentication of service is. Authenticatieverkeer in het bijzonder moet als zodanig gelabeld worden in plaats van in een marketingstandaard te blijven staan.
- Bekijk retry-semantiek apart. Plivo's verzendreference documenteert geen idempotency-sleutel of deduplicatiemechanisme, dus een timeout laat je gissen. Stuur de Idempotency-Key-header mee vanaf de eerste port om het risico op dubbele requests binnen het replayvenster van drie uur te verkleinen; het is geen exactly-once-aflevergarantie.
Opt-outs overnemen
Plivo's DND-service blokkeert uitgaande berichten van één Plivo-nummer naar één bestemming zodra die bestemming antwoordt met een opt-outkeyword. Een geblokkeerde verzending komt terug met Plivo-foutcode 200, een van hun berichtfoutcodes en geen HTTP-status, hoe zeer het er ook op lijkt. Die koppeling is ook hoe een Bird-suppression werkt: één afzender en één abonnee, dus de geïmporteerde scope moet elke afzender en elk programma omvatten dat in het verzoek van de persoon zit.
Eén ding groeit, en het is de reden om te tellen voordat je importeert. Binnen een US 10DLC-campagne behandelt Plivo een opt-out van één willekeurig nummer als een opt-out van elk nummer dat aan die campagne gekoppeld is. Bird slaat paren op, dus een abonnee die zich bij een campagne met vier nummers heeft afgemeld wordt vier suppressions in plaats van één. Bereken hoeveel paren je lijst oplevert voordat je begint, want dat bepaalt of de import een lus van tientallen of van duizenden is.
De lijst eruit halen is een console-export in plaats van een API-aanroep: filter de nummers in de Plivo-console, selecteer ze en gebruik Export CSV in het Choose Action-menu. Importeer het resultaat via de suppression-lus. Suppressions lezen en beheren bevat het commando, en de reden waarom een handmatige suppression elke categorie blokkeert, inclusief transactioneel.
Bird verwerkt ondersteunde stopkeywords via de landspecifieke catalogus. Een verzending naar een onderdrukt paar wordt bij toelating geweigerd met E12077 SMSRecipientSuppressed. Een door de carrier gemelde opt-out is een apart recipient_opted_out-afleverresultaat. Vervang de afhandeling van Plivo-foutcode 200 door de juiste toelatings- en afleverpaden, en maak eventuele aangepaste antwoorden opnieuw aan als keywordregels.
Dat speelt opnieuw zodra er verkeer loopt. Redenen stapelen in plaats van samen te voegen: een paar dat je als manual hebt geïmporteerd en dat vervolgens STOP sms't, krijgt een tweede record met reden keyword_stop, en berichten blijven geblokkeerd totdat elk record voor dat paar beëindigd is. Een abonnee hervatten die je ooit hebt geïmporteerd betekent dus beide verwijderen, en een hervatting die alleen het keywordrecord wist lijkt geslaagd maar verandert niets.
Afleverstatussen vertalen
Gebruik deze tabel om levenscyclusconcepten te vergelijken, niet om events mechanisch te hernoemen. Bird kiest een failure-event op basis van de gerapporteerde status en reden. Een geweigerd API-request maakt geen bericht aan; een afwijzing na acceptatie kan sms.rejected opleveren, inclusief een carrierafwijzing. Ontbrekend afleverbewijs blijft unknown. Bewaar de ruwe providerstatus en -code naast je genormaliseerde uitkomst.
| Uitkomst | Plivo message_state | Bird |
|---|---|---|
| API heeft het bericht geaccepteerd | queued | sms.accepted |
| Overgedragen aan de carrier | sent | sms.sent |
| Carrier bevestigt aflevering | delivered | sms.delivered |
| Carrier meldt niet-aflevering | undelivered | sms.undelivered |
| Permanente fout | failed | sms.failed |
| Geweigerd vóór verzending | rejected | sms.rejected |
| Geldigheidsvenster verlopen | (geen) | sms.expired |
Twee mechanismen veranderen samen met de namen:
- Endpoints vervangen per-bericht-callback-URL's. Plivo neemt een url bij elke verzending, dus de bestemming wordt bepaald door wie de aanroep schrijft. Bird levert af aan endpoints die je werkruimte registreert, elk geabonneerd op de gewenste eventtypen, dus een nieuwe consumer is een nieuw abonnement in plaats van een wijziging op elke aanroeplocatie.
- Ondertekende JSON-posts vervangen een GET-callback, als je daarvoor gekozen had. Plivo's method selecteert GET of POST voor het afleverrapport; Bird POSTt een JSON-event en biedt geen GET. Als je method=GET instelde, leest je handler de uitkomst uit query-stringparameters, en die handler is een herschrijving in plaats van een herregistratie. Hetzelfde geldt één gids verderop, op het Connectivity Platform-pad.
- Eén ondertekeningsschema vervangt drie headers. Plivo ondertekent callbacks met X-Plivo-Signature-V2, X-Plivo-Signature-Ma-V2 en X-Plivo-Signature-V2-Nonce. Bird verstuurt JSON ondertekend volgens Standard Webhooks, dus de verifier wordt vervangen in plaats van aangepast: wissel hem in voor het recept in Webhooks & events.
Registreer het endpoint eenmalig en geef de eventtypen op die je handler wil: de sms.*-events hierboven zijn de lijst om op te abonneren, en er is geen wildcard die ze vervangt. Een endpoint aanmaken bevat het commando en het enige dat je goed moet doen bij de eerste aanroep: het signing-secret opslaan dat de response precies één keer toont.
Plivo's numerieke error_code-waarden hebben geen één-op-één-vertaling. Bird rapporteert een fout met een gestandaardiseerde error-code zoals invalid_destination, content_rejected, provider_unavailable of recipient_opted_out; de volledige lijst staat op de eventspagina. Koppel je alerting daaraan.
Overschakelen
Bestemmingen, afzenders en de verkeersopbouw zijn provideronafhankelijk en staan in de hoofdgids. Twee Plivo-specifieke punten horen op het overschakelplan.
Je 10DLC-merk en -campagne zijn via Plivo geregistreerd bij The Campaign Registry en worden niet automatisch Bird-registraties. Bevestig de toepasselijke migratie- of registratieprocedure voordat je betaald werk indient. De keten is hier korter. Plivo registreert eerst een profiel en dan een merk ertegen, onder /v1/Account/{auth_id}/10dlc/; Bird heeft geen profielobject, dus de bedrijfsgegevens die Plivo op het profiel bewaart lever je op het merk zelf aan. Begin bij Registreren voor 10DLC: het behandelt wat elk veld betekent, de entiteitstypen die de registry erkent, en de requirements-aanroep die vertelt wat je moet aanleveren voordat je het merk aanmaakt, de stap waarvoor kosten gelden.
Nummers die je bij Plivo bezit hebben een port nodig die support regelt, op hun eigen schema in plaats van het jouwe. Begin er vroeg mee, dan loopt het parallel aan de codewijziging.
Volgende stappen
-
Bird en Plivo vergelijken voor SMS: productevaluatie en migratieoverwegingen
-
SMS verzenden: de volledige payload waarnaar je port
-
Opt-outs en keywords: keyworddekking per land en suppressionbeheer
-
SMS-events: de eventwoordenschat waarnaar je callback-handler verhuist
-
Webhooks & events: endpointconfiguratie en Standard Webhooks-verificatie
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.