Migracja SMS z Plivo
Ta strona mapuje Message API, Powerpacks i callbacki dostarczenia Plivo na Bird. Wykonuj główny przewodnik migracji po kolei i korzystaj z tych mapowań w krokach 3, 4 i 5.
Wysyłka to najłatwiejsza część. Oba przyjmują JSON z nazwami pól pisanymi małymi literami i oba trzymają rejestrację 10DLC przy wysyłce, a nie na osobnym hoście. Dwie rzeczy się zmieniają. POST https://api.plivo.com/v1/Account/{auth_id}/Message/ Plivo uwierzytelnia się Auth ID i Auth Token przez HTTP Basic; POST /v1/sms/messages przyjmuje klucz bearer API pod regionalnym hostem, bez segmentu konta w ścieżce. Plivo Powerpack łączy pulę numerów, sticky sender i stan rezygnacji w jeden obiekt; Bird rozdziela je na nadawców, supresje i reguły słów kluczowych, więc nie ma niczego do odtworzenia jako Powerpack.
Przekaż to swojemu agentowi
Użyj tego briefu w swoim agencie kodującym. Zaczyna od rozpoznania i tworzy plan migracji do przeglądu, zanim nastąpi jakakolwiek zmiana produkcyjna.
Przykład kodu
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.Zmapuj wywołanie wysyłki
| Co robi | Plivo | Bird |
|---|---|---|
| Odbiorca | dst | to (jeden na żądanie) |
| Nadawca | src lub powerpack_uuid | from |
| Treść | text | text |
| Selektor kanału | type: sms, mms, whatsapp | sam endpoint; /v1/sms/messages to SMS |
| Intencja | (brak) | category, wymagane dla wolnego tekstu |
| Raporty dostarczenia | url + method, per wiadomość | webhook obszaru roboczego; tylko JSON POST, patrz niżej |
| Kontekst podróży | własny magazyn, klucz UUID | metadata: dowolny JSON, zwracany przy każdym zdarzeniu |
| Filtrowalne etykiety | (brak) | tags: pary {name, value} |
| Bezpieczne ponowienia | (brak w dokumentacji) | nagłówek Idempotency-Key |
| Media | media_urls | brak odpowiednika: media_urls jest odrzucane |
Uwagi dotyczące portowania:
- UUID Powerpacza staje się zwykłą wartością nadawcy. Plivo rozwiązuje pulę numerów, sticky sender i lokalną obecność za UUID. Bird przyjmuje samego nadawcę w from, więc wybierz go przy każdej wysyłce albo użyj wysyłki szablonowej, która wybiera prawidłowego nadawcę dla miejsca docelowego i odrzuca from.
- type nie ma odpowiednika, bo niesie go sam endpoint. Plivo wybiera kanał per żądanie; SMS, WhatsApp i inne kanały Bird to osobne endpointy. Kod, który przełącza type w czasie działania, dzieli się na wywołania do różnych endpointów.
- Nic w Message API nie odpowiada category. Zdecyduj per typ wiadomości, czy to transactional, marketing, authentication czy service. Ruch uwierzytelniający w szczególności powinien być tak oznaczony, zamiast zostawiać go w domyślnej kategorii marketing.
- Przejrzyj semantykę ponowień osobno. Dokumentacja wysyłki Plivo nie opisuje klucza idempotencji ani mechanizmu deduplikacji, więc timeout zostawia cię z domysłami. Wysyłaj nagłówek Idempotency-Key od pierwszego portu, aby zmniejszyć ryzyko zduplikowanych żądań w trzygodzinnym oknie odtwarzania; to nie jest gwarancja dostarczenia exactly-once.
Przenieś rezygnacje
Usługa DND Plivo blokuje wiadomości wychodzące z jednego numeru Plivo do jednego odbiorcy, gdy ten odbiorca odpowie słowem kluczowym rezygnacji. Zablokowana wysyłka wraca oznaczona kodem błędu Plivo 200, który jest jednym z kodów błędów wiadomości, a nie statusem HTTP, choć tak wygląda. To sparowanie działa tak samo jak supresja Bird: jeden nadawca i jeden subskrybent, więc importowany zakres musi obejmować każdego nadawcę i program uwzględniony w żądaniu danej osoby.
Jedna rzecz się rozrasta i to jest powód, żeby policzyć przed importem. W kampanii US 10DLC Plivo traktuje rezygnację z dowolnego numeru jako rezygnację ze wszystkich numerów powiązanych z tą kampanią. Bird przechowuje pary, więc subskrybent, który zrezygnował z kampanii czteronumerowej, staje się czterema supresjami zamiast jednej. Oblicz, ile par tworzy twoja lista, zanim zaczniesz, bo to decyduje, czy import to pętla dziesiątek czy tysięcy.
Pobranie listy to eksport z konsoli, a nie wywołanie API: przefiltruj numery w konsoli Plivo, zaznacz je i użyj Export CSV z menu Choose Action. Zaimportuj wynik przez pętlę supresji. Odczytywanie i zarządzanie supresjami zawiera polecenie oraz wyjaśnienie, dlaczego ręczna supresja blokuje każdą kategorię, w tym transakcyjną.
Bird obsługuje wspierane słowa kluczowe stop przez swój katalog specyficzny dla danego kraju. Wysyłka do zablokowanej pary jest odrzucana przy przyjęciu z E12077 SMSRecipientSuppressed. Zgłoszony przez operatora opt-out to osobny wynik dostarczenia recipient_opted_out. Zastąp obsługę kodu błędu Plivo 200 odpowiednimi ścieżkami przyjęcia i dostarczenia, a niestandardowe odpowiedzi odtwórz jako reguły słów kluczowych.
To ma znaczenie ponownie później, gdy ruch już płynie. Powody się kumulują, a nie scalają: para zaimportowana jako manual, która następnie wyśle STOP, otrzymuje drugi rekord z powodem keyword_stop, a wiadomości pozostają zablokowane, dopóki każdy rekord dla tej pary nie wygaśnie. Wznowienie subskrybenta, którego kiedyś zaimportowałeś, oznacza więc usunięcie obu, a wznowienie usuwające tylko rekord słowa kluczowego wygląda na udane, ale niczego nie zmienia.
Przetłumacz statusy dostarczenia
Użyj tej tabeli do porównania koncepcji cyklu życia, a nie do mechanicznej zmiany nazw zdarzeń. Bird wybiera zdarzenie błędu na podstawie zgłoszonego statusu i powodu. Odrzucone żądanie API nie tworzy wiadomości; odrzucenie po akceptacji może wygenerować sms.rejected, w tym odrzucenie przez operatora. Brak dowodów dostarczenia pozostaje nieznany. Zachowaj surowy status i kod dostawcy obok znormalizowanego wyniku.
| Rezultat | Plivo message_state | Bird |
|---|---|---|
| API zaakceptował wiadomość | queued | sms.accepted |
| Przekazano do operatora | sent | sms.sent |
| Operator potwierdził dostarczenie | delivered | sms.delivered |
| Operator zgłosił niedostarczenie | undelivered | sms.undelivered |
| Trwała awaria | failed | sms.failed |
| Odrzucono przed wysłaniem | rejected | sms.rejected |
| Upłynęło okno ważności | (brak) | sms.expired |
Dwie mechaniki zmieniają się wraz z nazwami:
- Endpointy zastępują URL-e callbacków per wiadomość. Plivo przyjmuje url przy każdej wysyłce, więc miejsce docelowe wybiera ten, kto pisze wywołanie. Bird dostarcza do endpointów zarejestrowanych w obszarze roboczym, z których każdy subskrybuje interesujące go typy zdarzeń, więc nowy konsument to nowa subskrypcja, a nie zmiana w każdym miejscu wywołania.
- Podpisane posty JSON zastępują callback GET, jeśli tak właśnie wybrałeś. method Plivo wybiera GET lub POST dla raportu dostarczenia; Bird wysyła (POST) zdarzenie JSON i nie oferuje GET. Jeśli ustawiłeś method=GET, twój handler odczytuje wynik z parametrów query-string, i ten handler to przepisanie, a nie ponowna rejestracja. To samo dotyczy sąsiedniego przewodnika, na ścieżce Connectivity Platform.
- Jeden schemat podpisu zastępuje trzy nagłówki. Plivo podpisuje callbacki za pomocą X-Plivo-Signature-V2, X-Plivo-Signature-Ma-V2 i X-Plivo-Signature-V2-Nonce. Bird wysyła JSON podpisane zgodnie ze Standard Webhooks, więc weryfikator jest wymieniany, a nie korygowany: zamień go na przepis z Webhooks & events.
Zarejestruj endpoint raz, podając typy zdarzeń, których twój handler potrzebuje: powyższe zdarzenia sms.* to lista do subskrypcji i nie ma wildcarda, który je zastępuje. Utwórz endpoint zawiera polecenie oraz jedną rzecz, którą trzeba zrobić dobrze przy pierwszym wywołaniu: zapisanie sekretu podpisu, który odpowiedź pokazuje dokładnie raz.
Numeryczne wartości error_code Plivo nie mają mapowania jeden-do-jednego. Bird raportuje błąd zestandaryzowanym kodem error, takim jak invalid_destination, content_rejected, provider_unavailable lub recipient_opted_out; pełna lista jest na stronie zdarzeń. Zmapuj na nie swoje alerty.
Przełączenie
Odbiorcy, nadawcy i rampa ruchu są niezależne od dostawcy i opisane w głównym przewodniku. Dwa elementy specyficzne dla Plivo należą do planu przełączenia.
Twoja marka i kampania 10DLC są zarejestrowane w The Campaign Registry przez Plivo i nie stają się automatycznie rejestracjami Bird. Potwierdź właściwą procedurę migracji lub rejestracji, zanim zlecisz płatną pracę. Łańcuch jest tu krótszy. Plivo rejestruje najpierw profil, a potem markę do niego, pod /v1/Account/{auth_id}/10dlc/; Bird nie ma obiektu profilu, więc dane biznesowe, które Plivo trzyma w profilu, podaje się na samej marce. Zacznij od Rejestracja 10DLC: opisuje, co oznacza każde pole, typy podmiotów rozpoznawane przez rejestr oraz wywołanie requirements, które mówi, co podać, zanim utworzysz markę, czyli krok płatny.
Numery, które posiadasz w Plivo, wymagają portu organizowanego przez wsparcie, według jego harmonogramu, nie twojego. Rozpocznij wcześnie, a będzie przebiegał równolegle ze zmianą kodu.
Następne kroki
-
Porównaj Bird i Plivo dla SMS: ocena produktu i aspekty migracji
-
Wysyłanie SMS: pełny payload, na który portujesz
-
Rezygnacje i słowa kluczowe: pokrycie słów kluczowych per kraj i zarządzanie supresjami
-
Zdarzenia SMS: słownik zdarzeń, na który przechodzi twój handler callbacków
-
Webhooks & events: konfiguracja endpointów i weryfikacja Standard Webhooks
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.