Migracja SMS z Bandwidth
Ta strona mapuje endpoint Messages API, Applications i callbacki wiadomości Bandwidth na Bird. Wykonuj główny przewodnik migracji po kolei i korzystaj z tych mapowań w krokach 3, 4 i 5.
Dwie różnice kształtują cały port. Bandwidth dzieli kanał między dwa hosty: wysyłka działa na hoście wiadomości w ścieżce Twojego konta, uwierzytelniana przez HTTP Basic, a rejestracja 10DLC działa na głównym hoście API. Bird umieszcza wysyłkę, rejestrację i zdarzenia doręczeń pod jednym bazowym URL-em i jednym kluczem bearer. Z kolei applicationId w każdym wysyłanym żądaniu Bandwidth niesie konfigurację callbacków; Bird nie ma odpowiednika tego obiektu, ponieważ callbacki są subskrypcją obszaru roboczego, a nie właściwością wiadomości.
Przekaż to swojemu agentowi
Użyj tego briefu w swoim agencie kodującym. Zaczyna się od odkrywania i generuje plan migracji do przeglądu, zanim cokolwiek zmieni się na produkcji.
Przykład kodu
Help me migrate my SMS integration from Bandwidth 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/bandwidth.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 Bandwidth 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 | Bandwidth | Bird |
|---|---|---|
| Odbiorca | to (tablica) | to (jeden na żądanie) |
| Nadawca | from | from |
| Treść | text | text |
| Routing callbacków | applicationId | webhook obszaru roboczego subskrybujący poniższe zdarzenia doręczeń |
| Intencja | (brak) | category, wymagane dla dowolnego tekstu |
| Dowolna etykieta | tag (jeden ciąg znaków) | metadata; tags tylko jeśli potrafisz go nazwać |
| Kontekst w obie strony | własny magazyn, z kluczem ID | metadata: dowolny JSON, zwracany przy każdym zdarzeniu |
| Priorytet doręczenia | priority | brak odpowiednika |
| Bezpieczne ponawianie | (brak w ich specyfikacji) | nagłówek Idempotency-Key |
| Media | media | brak odpowiednika: media_urls jest odrzucane |
Uwagi do portowania:
- to zmienia się z tablicy na jednego odbiorcę. Bandwidth przyjmuje listę; Bird wysyła jedną wiadomość na żądanie. Pętla zastępuje tablicę, a każde wywołanie może nieść własny Idempotency-Key.
- applicationId znika zamiast się przenosić. Istnieje, aby wskazać Bandwidth, gdzie wysyłać callbacki. W Bird to subskrypcja obszaru roboczego, więc nic w wysyłce go nie wskazuje.
- tag i tags to nie to samo pole. tag w Bandwidth to jeden dowolny ciąg znaków; tags w Bird to pary {name, value}, które stają się wymiarami zapytań. Pojedynczy nieprzejrzysty ciąg znaków lepiej przenosić w metadata.
- Nic w Messages API nie odpowiada category. Zdecyduj dla każdego typu wiadomości, czy jest to transactional, marketing, authentication czy service.
Przenieś opt-outy
Nie ma listy do wyeksportowania i to jest ustalenie, a nie luka w tym przewodniku.
Poza toll-free Bandwidth nie prowadzi za Ciebie list opt-in ani opt-out. Ich własna dokumentacja mówi wprost: obowiązek honorowania poleceń i utrzymywania list spoczywa na kliencie. Toll-free jest wyjątkiem, gdzie STOP i jego warianty są wymuszane na warstwie sieciowej niezależnie od Twojej konfiguracji; long code i short code nie mają takiej obsługi.
Dlatego w tej migracji autorytatywna lista jest już Twoja. To tabela, flaga na rekordzie kontaktu lub sprawdzenie, które Twoja ścieżka wysyłki wykonuje przed wywołaniem API, a pierwszym zadaniem jest ustalenie, które z nich jest autorytatywne, zamiast prosić kogokolwiek o eksport. Twój własny log wiadomości przychodzących to rozwiązanie awaryjne: część opt-outów zaczęła się jako wiadomości przychodzące, inne przyszły przez support, formularze lub inny kanał preferencji.
Następnie zaimportuj przez pętlę suppressions. Suppression w Bird to jedna para nadawca–subskrybent, więc subskrybent zablokowany u trzech nadawców to trzy rekordy. Odczytywanie i zarządzanie suppressions zawiera polecenie oraz wyjaśnienie, dlaczego ręczna suppression blokuje każdą kategorię, łącznie z transakcyjną.
Zdecyduj, kto jest właścicielem listy po cutoverze, bo tu zyskujesz coś, co łatwo stracić z oczu. Bird odpowiada na słowa kluczowe stop ze swojego katalogu dla każdego kraju, więc gdy zaczniesz tu wysyłać, platforma utrzymuje suppressions za Ciebie: subskrybent, który wyśle STOP, tworzy rekord z powodem keyword_stop bez udziału Twojej aplikacji. Jeśli Twój kod dalej prowadzi własną listę i ją egzekwuje, obie listy rozjeżdżają się, a typowym objawem jest subskrybent, który wznowił subskrypcję po jednej stronie, ale nie po drugiej. Utrzymuj jawnego właściciela preferencji odbiorców i synchronizuj istotne zmiany celowo. Same suppressions nadawcy nie obejmują preferencji na poziomie całego obszaru roboczego ani żądań spoza katalogu słów kluczowych. Powody nawarstwiają się zamiast łączyć, więc para zaimportowana jako manual, która później wyśle STOP, posiada dwa rekordy, a wiadomości pozostają zablokowane, dopóki oba nie zostaną zakończone.
Przetłumacz statusy doręczeń
Użyj tej tabeli do porównania koncepcji cyklu życia, a nie do mechanicznego zmieniania nazw zdarzeń. Bird wybiera zdarzenie o niepowodzeniu 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. Brakujące potwierdzenie doręczenia pozostaje nieznane. Zachowuj surowy status i kod dostawcy obok znormalizowanego wyniku.
| Wynik | Typ callbacku Bandwidth | Bird |
|---|---|---|
| API zaakceptowało wiadomość | odpowiedź 202, brak zdarzenia | sms.accepted |
| Przekazano operatorowi | message-sent | sms.sent |
| Operator potwierdził doręczenie | message-delivered | sms.delivered |
| Nie dotarło do operatora | message-failed | sms.rejected |
| Operator odrzucił wiadomość | message-failed | sms.failed |
| Operator zgłosił niedoręczenie | message-failed | sms.undelivered |
| Operator zrezygnował | message-failed | sms.expired |
| Żądanie odrzucone przy przyjęciu | błąd żądania | błąd HTTP; brak wiadomości ani zdarzenia |
Dwie rzeczy w tej tabeli warto wdrożyć, a nie przeczytać i pominąć.
Przebuduj obsługę stanów końcowych w oparciu o rekord wiadomości i znaczniki czasu zdarzeń Bird. Dostarczenia webhooków mogą się powtarzać lub przychodzić w złej kolejności; Twój konsument nie może zakładać jednego dostarczenia jednego końcowego callbacku. Status odrzucenia i status niepowodzenia doręczenia mogą trafić do różnych zdarzeń Bird, nawet jeśli oba pochodzą od operatora.
message-sending nie ma wiersza, ponieważ dotyczy tylko MMS, a message-read dotyczy tylko RBM; żadne z nich nie jest wywoływane dla SMS.
Dwie mechaniki zmieniają się razem z nazwami:
- Subskrypcje zastępują Application. Bandwidth kieruje callbacki na podstawie applicationId wskazanego w wiadomości. Bird dostarcza do endpointów zarejestrowanych w Twoim obszarze roboczym, z których każdy subskrybuje wybrane typy zdarzeń, więc nowy konsument to nowa subskrypcja, a nie nowy Application i ponowne wdrożenie.
- Standard Webhooks zastępuje ich uwierzytelnianie callbacków. Bird wysyła JSON podpisane zgodnie ze Standard Webhooks; zamień weryfikację 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 zasubskrybowania i nie ma symbolu wieloznacznego, który je zastępuje. Utwórz endpoint zawiera polecenie i jedną rzecz, którą trzeba zrobić dobrze za pierwszym razem, czyli zapisanie sekretu podpisującego, który odpowiedź pokazuje dokładnie raz.
Cutover
Destinations, nadawcy i rampa ruchu są niezależne od dostawcy i opisane w głównym przewodniku. Dwa elementy specyficzne dla Bandwidth należy uwzględnić w planie cutoveru: Twoja marka 10DLC i kampania są zarejestrowane w The Campaign Registry przez Bandwidth i nie stają się automatycznie rejestracjami Bird. Potwierdź odpowiednią procedurę migracji lub rejestracji przed zleceniem płatnej pracy. Numery, które posiadasz w Bandwidth, wymagają przeniesienia, które organizuje support, według własnego harmonogramu, a nie Twojego.
Wymagania po stronie Bird zacznij od Rejestracja 10DLC: opisuje znaczenie każdego pola, typy podmiotów rozpoznawane przez rejestr oraz wywołanie requirements, które informuje, co dostarczyć przed utworzeniem marki, czyli krok płatny.
Kolejne kroki
-
Porównanie Bird i Bandwidth dla SMS: ocena produktu i kwestie migracyjne
-
Wysyłanie SMS: pełny payload, na który portujesz
-
Opt-outy i słowa kluczowe: pokrycie słów kluczowych w poszczególnych krajach i zarządzanie suppressions
-
Zdarzenia SMS: słownik zdarzeń, na który przenosi się 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.