SMS von Plivo migrieren

Diese Seite ordnet Plivos Message API, Powerpacks und Zustellungs-Callbacks Bird zu. Folgen Sie dem Hauptmigrationsleitfaden der Reihe nach und verwenden Sie diese Zuordnungen für die Schritte 3, 4 und 5.

Der Versand ist der einfache Teil. Beide akzeptieren JSON mit Feldnamen in Kleinbuchstaben, und beide halten die 10DLC-Registrierung neben dem Versand statt auf einem separaten Host. Zwei Dinge ändern sich. Plivos POST https://api.plivo.com/v1/Account/{auth_id}/Message/ authentifiziert mit einer Auth ID und einem Auth Token über HTTP Basic; POST /v1/sms/messages nimmt einen Bearer-API-Schlüssel gegen Ihren regionalen Host entgegen, ohne Account-Segment im Pfad. Und ein Plivo Powerpack bündelt Nummernpool, Sticky-Sender-Verhalten und Opt-out-Status in einem Objekt; Bird verteilt diese auf Sender, Suppressions und Keyword-Regeln, sodass es nichts gibt, was als Powerpack nachgebaut werden müsste.

Übergeben Sie das an Ihren Agenten

Verwenden Sie dieses Briefing in Ihrem Coding-Agenten. Es beginnt mit einer Bestandsaufnahme und erstellt einen überprüfbaren Migrationsplan, bevor Produktionsänderungen vorgenommen werden.

Codebeispiel

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.

Den Sendeaufruf zuordnen

Funktion	Plivo	Bird
Empfänger	dst	to (einer pro Request)
Absender	src oder powerpack_uuid	from
Inhalt	text	text
Kanalauswahl	type: sms, mms, whatsapp	der Endpoint selbst; /v1/sms/messages ist SMS
Intent	(keiner)	category, erforderlich bei Freitext
Zustellberichte	url + method, pro Nachricht	ein Workspace-Webhook; nur JSON POST, siehe unten
Roundtrip-Kontext	eigener Speicher, per UUID	metadata: beliebige JSON, bei jedem Event zurückgegeben
Filterbare Labels	(keine)	tags: {name, value}-Paare
Sichere Wiederholungen	(nicht dokumentiert)	Idempotency-Key-Header
Medien	media_urls	kein Äquivalent: media_urls wird abgelehnt

Portierungshinweise:

Eine Powerpack-UUID wird zu einem einfachen Absenderwert. Plivo löst den Nummernpool, das Sticky-Sender-Verhalten und die lokale Präsenz hinter der UUID auf. Bird nimmt den Absender selbst in from entgegen. Wählen Sie ihn also pro Versand, oder nutzen Sie einen Template-Versand, der einen gültigen Absender für das Ziel auswählt und from ablehnt.
type hat kein Gegenstück, weil der Endpoint es mitbringt. Plivo wählt den Kanal pro Request; SMS, WhatsApp und andere Kanäle von Bird sind separate Endpoints. Eine Codebasis, die type zur Laufzeit umschaltet, wird in Aufrufe verschiedener Endpoints aufgeteilt.
Nichts an der Message API entspricht category. Entscheiden Sie pro Nachrichtentyp, ob es transactional, marketing, authentication oder service ist. Authentifizierungs-Traffic sollte insbesondere entsprechend gekennzeichnet werden, statt im Marketing-Standard zu verbleiben.
Prüfen Sie die Retry-Semantik separat. Plivos Sende-Referenz dokumentiert keinen Idempotenzschlüssel und keinen Deduplizierungsmechanismus, sodass ein Timeout Sie im Unklaren lässt. Senden Sie den Idempotency-Key-Header ab der ersten Portierung mit, um das Risiko doppelter Requests innerhalb des dreistündigen Replay-Fensters zu reduzieren; es ist keine Exactly-once-Zustellgarantie.

Opt-outs übernehmen

Plivos DND-Dienst blockiert ausgehende Nachrichten von einer Plivo-Nummer an ein Ziel, sobald dieses Ziel mit einem Opt-out-Keyword antwortet. Ein blockierter Versand kommt mit Plivo-Fehlercode 200 zurück, einem der Nachrichten-Fehlercodes und keinem HTTP-Status, auch wenn er so aussieht. Diese Zuordnung entspricht der Funktionsweise einer Bird-Suppression: ein Absender und ein Empfänger. Der importierte Geltungsbereich muss also jeden Absender und jedes Programm abdecken, das in der Anfrage der Person enthalten ist.

Eins wird mehr, und das ist der Grund, vor dem Import zu zählen. Innerhalb einer US-10DLC-Kampagne behandelt Plivo ein Opt-out von einer beliebigen Nummer als Opt-out von jeder Nummer, die mit dieser Kampagne verknüpft ist. Bird speichert Paare, sodass ein Empfänger, der sich von einer Vier-Nummern-Kampagne abgemeldet hat, zu vier Suppressions statt einer wird. Berechnen Sie, wie viele Paare Ihre Liste ergibt, bevor Sie beginnen, denn das entscheidet, ob der Import eine Schleife von Dutzenden oder Tausenden ist.

Die Liste zu exportieren ist ein Konsolen-Export und kein API-Aufruf: Filtern Sie die Nummern in der Plivo-Konsole, wählen Sie sie aus und nutzen Sie Export CSV im Menü „Choose Action '. Importieren Sie das Ergebnis über die Suppressions-Schleife. Suppressions lesen und verwalten enthält den Befehl und den Grund, warum eine manuelle Suppression jede Kategorie einschließlich transaktionaler blockiert.

Bird verarbeitet unterstützte Stopp-Keywords über seinen länderspezifischen Katalog. Ein Versand an ein unterdrücktes Paar wird bei der Annahme mit E12077 SMSRecipientSuppressed abgelehnt. Ein vom Carrier gemeldetes Opt-out ist ein separates recipient_opted_out-Zustellergebnis. Ersetzen Sie die Behandlung des Plivo-Fehlercodes 200 durch die entsprechenden Annahme- und Zustellpfade und erstellen Sie benutzerdefinierte Antworten als Keyword-Regeln neu.

Das wird später erneut relevant, sobald Traffic fließt. Gründe stapeln sich, statt zusammenzufallen: Ein Paar, das Sie als manual importiert haben und das dann STOP sendet, erhält einen zweiten Eintrag mit Grund keyword_stop, und Nachrichten bleiben blockiert, bis jeder Eintrag für dieses Paar beendet ist. Die Wiederaufnahme eines einmal importierten Empfängers erfordert also das Entfernen beider Einträge, und eine Wiederaufnahme, die nur den Keyword-Eintrag löscht, sieht erfolgreich aus und ändert nichts.

Zustellstatus übersetzen

Verwenden Sie diese Tabelle zum Vergleich von Lifecycle-Konzepten, nicht zum mechanischen Umbenennen von Events. Bird wählt ein Fehler-Event anhand des gemeldeten Status und Grundes. Ein abgelehnter API-Request erzeugt keine Nachricht; eine Ablehnung nach Annahme kann sms.rejected erzeugen, einschließlich einer Carrier-Ablehnung. Fehlende Zustellnachweise bleiben unbekannt. Bewahren Sie den rohen Provider-Status und -Code neben Ihrem normalisierten Ergebnis auf.

Ergebnis	Plivo message_state	Bird
API hat die Nachricht angenommen	queued	sms.accepted
An den Carrier übergeben	sent	sms.sent
Carrier hat Zustellung bestätigt	delivered	sms.delivered
Carrier hat Nichtzustellung gemeldet	undelivered	sms.undelivered
Permanenter Fehler	failed	sms.failed
Vor dem Versand abgelehnt	rejected	sms.rejected
Gültigkeitsfenster abgelaufen	(keiner)	sms.expired

Zwei Mechanismen ändern sich zusammen mit den Bezeichnungen:

Endpoints ersetzen Callback-URLs pro Nachricht. Plivo nimmt bei jedem Versand eine url entgegen, sodass das Ziel von demjenigen gewählt wird, der den Aufruf schreibt. Bird liefert an Endpoints, die Ihr Workspace registriert, jeweils abonniert auf die gewünschten Event-Typen. Ein neuer Consumer ist also ein neues Abonnement, keine Änderung an jeder Aufrufstelle.
Signierte JSON-Posts ersetzen einen GET-Callback, falls Sie diesen gewählt haben. Plivos method wählt GET oder POST für den Zustellbericht; Bird POSTt ein JSON-Event und bietet kein GET an. Wenn Sie method=GET gesetzt haben, liest Ihr Handler das Ergebnis aus Query-String-Parametern, und dieser Handler wird umgeschrieben statt nur neu registriert. Das Gleiche gilt einen Leitfaden weiter, auf dem Connectivity-Platform-Pfad.
Ein Signaturschema ersetzt drei Header. Plivo signiert Callbacks mit X-Plivo-Signature-V2, X-Plivo-Signature-Ma-V2 und X-Plivo-Signature-V2-Nonce. Bird sendet JSON, signiert gemäß Standard Webhooks. Der Verifizierer wird also ersetzt, nicht angepasst: Tauschen Sie ihn gegen das Rezept in Webhooks & Events aus.

Registrieren Sie den Endpoint einmal und benennen Sie die Event-Typen, die Ihr Handler empfangen soll: Die sms.*-Events oben sind die Liste, die Sie abonnieren, und es gibt keinen Platzhalter, der sie ersetzt. Endpoint erstellen enthält den Befehl und das eine Detail, das beim ersten Aufruf stimmen muss: das Signing-Secret zu speichern, das die Antwort genau einmal anzeigt.

Plivos numerische error_code-Werte haben keine 1:1-Zuordnung. Bird meldet einen Fehler mit einem standardisierten error-Code wie invalid_destination, content_rejected, provider_unavailable oder recipient_opted_out; die vollständige Liste finden Sie auf der Events-Seite. Richten Sie Ihr Alerting darauf aus.

Umstellung

Ziele, Absender und die Traffic-Rampe sind anbieterunabhängig und im Hauptleitfaden behandelt. Zwei Plivo-spezifische Punkte gehören in den Umstellungsplan.

Ihre 10DLC-Marke und -Kampagne sind über Plivo bei The Campaign Registry registriert und werden nicht automatisch zu Bird-Registrierungen. Bestätigen Sie das anwendbare Migrations- oder Registrierungsverfahren, bevor Sie kostenpflichtige Arbeit beauftragen. Die Kette ist hier kürzer. Plivo registriert zunächst ein Profil und dann eine Marke dagegen, unter /v1/Account/{auth_id}/10dlc/; Bird hat kein Profil-Objekt, sodass die Geschäftsdaten, die Plivo im Profil hält, direkt bei der Marke angegeben werden. Beginnen Sie mit Für 10DLC registrieren: Es erklärt, was jedes Feld bedeutet, welche Entity-Typen die Registry erkennt, und den Requirements-Call, der Ihnen mitteilt, was Sie angeben müssen, bevor Sie die Marke erstellen – das ist der kostenpflichtige Schritt.

Nummern, die Sie bei Plivo besitzen, erfordern eine Portierung, die der Support nach seinem eigenen Zeitplan arrangiert und nicht nach Ihrem. Starten Sie sie früh, dann läuft sie parallel zur Codeänderung.

Nächste Schritte

Bird und Plivo für SMS vergleichen: Produktbewertung und Migrationsüberlegungen
SMS senden: das Payload, zu dem Sie portieren, vollständig
Opt-outs und Keywords: Keyword-Abdeckung pro Land und Suppressions-Verwaltung
SMS-Events: das Event-Vokabular, auf das Ihr Callback-Handler umzieht
Webhooks & Events: Endpoint-Einrichtung und Standard-Webhooks-Verifizierung