# Migracja SMS od innego dostawcy

Użyj tego przewodnika, aby przenieść produkcyjne SMS od innego dostawcy do Bird. Dwie rzeczy blokują pierwszą wysyłkę, a Twój obecny dostawca obsługuje je inaczej, więc omówimy je przed kodem: kraje, do których wysyłasz, i nadawca, od którego wysyłasz. Po nich przeportuj wywołanie wysyłki, przenieś listę rezygnacji, przekieruj raporty doręczeń na webhooki i przetestuj na symulowanych odbiorcach, zanim przełączysz rzeczywisty ruch.

Lista kontrolna migracji:

1. [Włącz kraje docelowe](#1-włącz-kraje-docelowe)
2. [Skonfiguruj nadawcę](#2-skonfiguruj-nadawcę)
3. [Zmapuj wywołanie wysyłki](#3-zmapuj-wywołanie-wysyłki) do `POST /v1/sms/messages`
4. [Przenieś listę rezygnacji](#4-przenieś-listę-rezygnacji)
5. [Przełącz raporty doręczeń na webhooki](#5-przełącz-raporty-doręczeń-na-webhooki)
6. [Przetestuj na symulowanych odbiorcach](#6-przetestuj-na-symulowanych-odbiorcach) przed przełączeniem

Kroki 3, 4 i 5 zależą od tego, od którego dostawcy odchodzisz. Twój [przewodnik po dostawcy](#migracja-od-konkretnego-dostawcy) zawiera mapowanie pól payloadu, tłumaczenie statusów i zdarzeń oraz informację, skąd wyeksportować listę rezygnacji.

Zacznij od kroków 1 i 2. Rejestracja nadawcy to najdłuższy element migracji SMS: przegląd przez operatora i rejestr może trwać dłużej niż zmiana kodu. Oceń oba zakresy przed ustaleniem daty przełączenia.

## 1. Włącz kraje docelowe

Twój obszar roboczy ma listę dozwolonych krajów docelowych z domyślną regułą odmowy, która na początku obejmuje tylko kraj macierzysty Twojej organizacji. Wysyłka gdziekolwiek indziej zwraca `422 SMSDestinationNotEnabled`, zanim Bird rozwiąże nadawcę, więc integracja przeniesiona wiernie i tak nie przejdzie przy pierwszej międzynarodowej wiadomości, dopóki nie otworzysz danego kraju.

Włącz każdy kraj, do którego wysyłasz, w [**SMS** > **Destinations**](https://bird.com/dashboard/w/sms/destinations). Weź listę z logów wiadomości obecnego dostawcy, a nie z pamięci: kraj, o którym zapomnisz, to cicha luka w dniu przełączenia, a kraj włączony, ale nigdy nieużywany, to niepotrzebna ekspozycja. Domyślna odmowa ogranicza też szkody wynikające z pompowania SMS, czyli generowania oszukańczego ruchu na numery premium rozliczane na Twój koszt.

## 2. Skonfiguruj nadawcę

Przy wysyłce free-text `from` jest nadawcą, którego widzi odbiorca, i przyjmuje jedną z trzech form: alfanumeryczny identyfikator nadawcy, numer telefonu w formacie E.164 należący do Twojego obszaru roboczego lub short code. Które formy działają, zależy od kraju docelowego, a nadawca, który tam jest nieprawidłowy, zostaje odrzucony z `422` wskazującym przyczynę. [Wysyłanie SMS](/docs/guides/sms/sending-sms#sender) opisuje zasady dla każdej formy.

Jak uzyskać każdy z nich:

- **Alfanumeryczne identyfikatory nadawcy** tworzysz samodzielnie w [**SMS** > **Senders**](https://bird.com/dashboard/w/sms/senders). Jeśli kraj docelowy wymaga rejestracji identyfikatora nadawcy, złóż rejestrację i poczekaj na zatwierdzenie, zanim skierujesz na niego ruch.
- **Ruch biznesowy w USA przez lokalne long code** wymaga odpowiedniej marki i kampanii 10DLC, skonfigurowanych w [**SMS** > **10DLC**](https://bird.com/dashboard/w/sms/10dlc), natomiast numery toll-free i dedykowane short code mają własne programy weryfikacji lub rejestracji. USA w ogóle nie akceptują alfanumerycznych identyfikatorów nadawcy, więc europejski identyfikator działający wszędzie indziej nie ma odpowiednika w USA.
- **Numery** uzyskujesz przez workflow Numbers, a dostępność i zarządzane provisionowanie zależą od typu i kraju docelowego. Sprawdź [numery SMS](/products/sms/numbers), aby znaleźć właściwą ścieżkę; dodanie alfanumerycznego nadawcy nie powoduje nabycia numeru.
- **Zachowanie obecnych numerów** nie jest samoobsługowe: Bird nie ma procesu port-in, który możesz przeprowadzić z poziomu dashboardu. Jeśli Twoi subskrybenci odpowiadają na numery, które posiadasz, zgłoś portowanie do supportu przed ustaleniem daty przełączenia i zaplanuj portowanie i zmianę kodu jako osobne zdarzenia.

[Wysyłka system-template](/docs/guides/sms/templates) używa innej formy żądania. Nadal wymaga odpowiedniego kraju docelowego i zgody odbiorcy. Dostarcza treść, kategorię i nadawcę, więc `from` nie jest akceptowany obok niej, a Bird wybiera nadawcę prawidłowego dla danego kraju.

## 3. Zmapuj wywołanie wysyłki

Endpoint pojedynczej wysyłki to [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message). Zbuduj payload JSON z `to`, `from`, `text` i `category`, a udane wywołanie zwróci `202 Accepted` z identyfikatorem wiadomości z prefiksem `sms_`. Doręczenie następuje po odpowiedzi i dociera do Ciebie przez zdarzenia webhookowe i endpointy odczytu. Pełny payload znajdziesz w [Wysyłanie SMS](/docs/guides/sms/sending-sms); mapowanie pól z Twojego obecnego payloadu jest w [przewodniku po dostawcy](#migracja-od-konkretnego-dostawcy).

Zanim przeportujesz kod, uwzględnij te różnice:

- **Jeden odbiorca na żądanie.** Bird nie ma tablicy odbiorców. Jeśli Twój obecny dostawca rozsyła jedno wywołanie do wielu numerów, staje się ono jednym wywołaniem na odbiorcę lub jednym [batchem](/docs/guides/sms/sending-sms#batch-sending) niezależnych wiadomości w jednym żądaniu.
- **`category` jest wymagany przy free text** i przyjmuje wartości `transactional`, `marketing`, `authentication` lub `service`. Większość dostawców wywnioskuje intencję z kampanii lub nadawcy; tutaj deklarujesz ją per wiadomość, a jeśli kraj docelowy wymaga rejestracji nadawcy, ta rejestracja jest zatwierdzona dla konkretnej kategorii i wysyłka poza nią zostaje odrzucona z `422 SenderCategoryNotPermitted`. Status `active` nadawcy nie powie Ci tego z wyprzedzeniem, bo jest raportowany bez odniesienia do kategorii; zamiast tego przeczytaj wymagania per kraj. Ustaw to poprawnie przy portowaniu, zamiast domyślnie przypisywać wszystko do jednej wartości.
- **Treść jest ograniczona liczbą segmentów, a Bird nie obcina.** Zbyt długa treść zostaje odrzucona z `422`. Znaki spoza GSM-7 ponad dwukrotnie zmniejszają pojemność segmentu, więc jeśli Twój obecny dostawca po cichu transliterował cudzysłowy typograficzne i myślniki, ustaw [`options.smart_encoding`](/docs/guides/sms/sending-sms#segments-and-encoding), aby zachować dotychczasową liczbę segmentów. Domyślnie jest wyłączony, bo modyfikuje skomponowaną treść.
- **Używaj `tags` do wymiarów filtrowania, a `metadata` do kontekstu.** Tagi to pary `{name, value}`, po których możesz filtrować i segmentować analitykę; metadane to dowolne JSON, które Bird przechowuje, zwraca przy odczycie i powtarza w każdym zdarzeniu webhookowym. Pojedyncze pole referencji klienta u Twojego starego dostawcy zwykle mapuje się na `metadata`.
- **Planowanie wysyłki per wiadomość i wychodzące MMS wymagają osobnego planu.** `scheduled_at`, `media_urls`, `validity_period` i per-odbiorca `personalization` to [pola zarezerwowane](/docs/guides/sms/sending-sms#reserved-fields), odrzucane z `422 SMSUnsupportedFeature`. Te części integracji nie przenoszą się razem z resztą: trzymaj zaplanowane wysyłki we własnej kolejce i wywołuj endpoint wysyłki w zamierzonym czasie nadania. W przypadku kampanii na grupy odbiorców oceń osobno [Broadcasts](/products/sms/marketing/campaigns); broadcast to nie zmiana nazwy pola endpointu.
- **Używaj `Idempotency-Key` do ograniczonych ponowień.** Wysyłaj unikatowy klucz per wiadomość logiczną i wykorzystuj go ponownie przy ponawianiu identycznego żądania w trójgodzinnym oknie powtórek. Powtórki redukują zduplikowane żądania, ale nie są gwarancją doręczenia exactly-once. Zobacz [Idempotency](/docs/guides/idempotency).

## 4. Przenieś listę rezygnacji

Zaimportuj rezygnacje **przed** pierwszą wysyłką produkcyjną. Wysłanie wiadomości do kogoś, kto powiedział Twojemu staremu dostawcy, żeby przestał, to naruszenie zgodności, które może zakończyć migrację porażką, a ani operator, ani regulator nie interesuje się, który dostawca zgubił wpis.

Supresja Bird obejmuje **parę nadawca–subskrybent**, co może być węższym zakresem niż blokada na poziomie usługi, profilu lub konta u Twojego starego dostawcy. Zachowaj faktyczne wycofanie zgody danej osoby dla każdego odpowiedniego nadawcy i programu. Dodaj każdą parę za pomocą [`POST /v1/sms/suppressions`](/docs/api/reference/create-sms-suppression):

```bash
while IFS=, read -r destination originator; do
  curl -s -X POST https://us1.platform.bird.com/v1/sms/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destination\": \"$destination\", \"originator\": \"$originator\"}"
done < opt-outs.csv
```

Ten sam import można wykonać z CLI jako `bird sms suppressions add --destination +15550001234 --originator +15557654321`.

Dwie rzeczy, które musisz wiedzieć o imporcie:

- **Obie strony są wymagane dla supresji per nadawca.** Rezygnacja obejmująca cały obszar roboczy należy do osobnego [właściciela preferencji](/docs/guides/sms/opt-outs-and-keywords#opting-out-of-every-sender). Wywołanie jest idempotentne: `201` tworzy nową supresję, `200` zwraca już istniejącą ręczną supresję, więc ponowne uruchomienie częściowego importu jest bezpieczne.
- **Zaimportowane pary otrzymują `reason: manual`, co blokuje każdą kategorię, w tym transakcyjną.** To surowsze niż supresja, którą Bird rejestruje samodzielnie ze słowa kluczowego stop. Jeśli subskrybent zrezygnował tylko z marketingu, świadomie zdecyduj, czy importować tę parę.

Przejrzyj istniejące zachowanie słów kluczowych i preferencji przed wyłączeniem starego kodu. Bird odpowiada na obsługiwane słowa kluczowe i rejestruje supresje tam, gdzie stosuje się jego katalog krajowy. Zachowaj obsługę nieobsługiwanych zapytań, szerszych preferencji i innych kanałów kontaktu. Niestandardowe słowa kluczowe kampanii i odpowiedzi konfiguruj przez [reguły słów kluczowych](https://bird.com/dashboard/w/sms/keyword-rules). Zobacz [Rezygnacje i słowa kluczowe](/docs/guides/sms/opt-outs-and-keywords), aby poznać zakres i pokrycie.

## 5. Przełącz raporty doręczeń na webhooki

Zarejestruj jeden endpoint za pomocą [`POST /v1/webhooks`](/docs/api/reference/create-webhook) i subskrybuj go na jawną listę typów zdarzeń. To zmiana strukturalna wymagana przez większość dostawców: zamiast callback URL per wiadomość lub per numer, Twój obszar roboczy ma endpointy, a każdy endpoint subskrybuje zdarzenia, które chce otrzymywać.

Nazwy zdarzeń Bird stosują konwencję `resource.action`. Ścieżka sukcesu to `sms.accepted`, potem `sms.sent`, potem `sms.delivered`, a `sms.undelivered`, `sms.failed`, `sms.expired` i `sms.rejected` pokrywają resztę; `sms.received` przenosi odpowiedzi na Twoje numery. Tłumaczenie ze słownika statusów Twojego obecnego dostawcy znajdziesz w [przewodniku po dostawcy](#migracja-od-konkretnego-dostawcy), a payloady per zdarzenie w [zdarzenia SMS](/docs/guides/sms/events).

Korelacja przenosi się bez problemu. Każde zdarzenie zawiera `sms_id`, `workspace_id`, `to` i `from` oraz powtarza `tags` i `metadata` z wysyłki, więc Twój handler odczytuje Twoje własne identyfikatory bezpośrednio ze zdarzenia, bez wyszukiwania wiadomości.

Dwa mechanizmy do przeniesienia razem z handlerem:

- **Doręczenia są podpisywane zgodnie ze [Standard Webhooks](https://www.standardwebhooks.com)**, przy użyciu nagłówków `webhook-id`, `webhook-timestamp` i `webhook-signature` z HMAC-SHA256 nad `{id}.{timestamp}.{raw body}`. Dostawcy podpisujący własnym schematem wymagają podmiany weryfikacji; przepis znajdziesz w [Webhooks & events](/docs/guides/webhooks#verify-signatures).
- **Doręczenie następuje co najmniej raz i bez gwarancji kolejności.** Deduplikuj po `webhook-id` i sortuj po `timestamp` z payloadu, nigdy po kolejności nadejścia.

Wiadomości przychodzące działają na tym samym modelu. Subskrybuj `sms.received` raz dla całego obszaru roboczego zamiast konfigurować URL przychodzący per numer i pamiętaj, że Bird nadal emituje `sms.received` dla odpowiedzi pasującej do słowa kluczowego stop, po zarejestrowaniu supresji.

## 6. Przetestuj na symulowanych odbiorcach

Bird symuluje wyniki doręczeń dla zestawu testowych odbiorców, więc możesz przetestować przeportowaną ścieżkę wysyłki i handler webhooków na rzeczywistych odpowiedziach API i rzeczywistych podpisanych doręczeniach bez fizycznego telefonu. To te same numery, których kilku dostawców używa do testowych poświadczeń, a wiadomość na jeden z nich nigdy nie trafia do operatora.

| Odbiorca       | Co widzi Twoja integracja                               |
| -------------- | ------------------------------------------------------- |
| `+15005550001` | Odrzucony przy nadaniu z `invalid_destination`          |
| `+15005550002` | `sms.sent`, potem `sms.undelivered` z `unreachable`     |
| `+15005550003` | `sms.sent`, potem `sms.failed` z `provider_unavailable` |
| `+15005550004` | `sms.sent`, potem `sms.failed` z `blocked_by_carrier`   |
| `+15005550006` | `sms.sent`, potem `sms.delivered`                       |
| `+15005550009` | `sms.sent`, potem `sms.failed` z `recipient_opted_out`  |

Obowiązują trzy warunki, a pierwsze dwa często zaskakują na świeżym obszarze roboczym:

- To numery amerykańskie, więc **Stany Zjednoczone muszą być włączone** w Destinations, a `from` musi być nadawcą prawidłowym dla USA. Alfanumeryczny identyfikator nadawcy jest tam odrzucany.
- **Symulowana wysyłka jest rozliczana** po normalnej stawce dla danego kraju. Nic nie trafia na telefon, ale obciążenie portfela jest rzeczywiste, więc dobierz rozmiar testu odpowiednio.
- Wynik zależy wyłącznie od odbiorcy. Nie ma osobnych testowych poświadczeń ani trybu testowego do wyłączenia.

Skuteczny smoke test wysyła do `+15005550006` i sprawdza, czy Twój handler przechodzi `sms.accepted` do `sms.sent` do `sms.delivered`; wysyła do `+15005550002` i `+15005550009` i sprawdza, czy obsługa błędów i rezygnacji reaguje na odpowiedni kod `error`; i wysyła jedną rzeczywistą wiadomość na telefon, który kontrolujesz, aby potwierdzić, że nadawca i treść wyświetlają się zgodnie z oczekiwaniami.

Następnie przełączaj stopniowo, nie naraz. Przenieś niewielki procent produkcyjnych wysyłek do Bird, obserwuj [log SMS](/docs/guides/sms/sms-log) i [metryki](/docs/guides/sms/tracking-and-metrics) pod kątem wskaźników doręczeń i kodów błędów w porównaniu z tym, co raportował Twój stary dostawca dla tych samych tras, i zwiększaj udział, gdy wyniki się utrzymują. Zachowaj starą integrację w stanie gotowym do wdrożenia, aż pierwszy pełny okres rozliczeniowy będzie wyglądał poprawnie.

## Migracja od konkretnego dostawcy

- [Twilio](/docs/guides/sms/migrate/twilio): form-encoded `PascalCase` do JSON, Messaging Services do nadawców, `StatusCallback` do subskrybowanych webhooków
- [Plivo](/docs/guides/sms/migrate/plivo): `src` i `dst` do `from` i `to`, Powerpacks do nadawców, pary DND do supresji
- [Telnyx](/docs/guides/sms/migrate/telnyx): najbliższy send do Bird, profile wiadomości rozdzielone na nadawców i subskrypcje, rezygnacje na poziomie profilu do par
- [Bandwidth](/docs/guides/sms/migrate/bandwidth): dwa hosty do jednego, callbacki `applicationId` do webhooków obszaru roboczego i lista rezygnacji, którą Twoja aplikacja już posiada
- [Sinch](/docs/guides/sms/migrate/sinch): batche do pojedynczych wysyłek, `body` do `text`, członkostwo w grupach odbudowane jako supresje
- [Infobip](/docs/guides/sms/migrate/infobip): trójpoziomowy payload spłaszczony, per-konto base URL do regionalnego hosta, Blocklist rozszerzony do par
- [Bird Connectivity Platform](/docs/guides/sms/migrate/connectivity-platform): `rest.messagebird.com` API, `originator` i `recipients` do `from` i `to`, callbacki GET `reportUrl` do podpisywanych webhooków

## Następne kroki

- [Porównaj dostawców SMS](/products/sms/compare): oceń workflow produktu i kwestie migracyjne

- [Wysyłanie SMS](/docs/guides/sms/sending-sms): pełny payload wysyłki, nadawcy, segmenty i asynchroniczny model 202
- [Rezygnacje i słowa kluczowe](/docs/guides/sms/opt-outs-and-keywords): co Bird obsługuje za Ciebie i jak zarządzać supresjami
- [Zdarzenia SMS](/docs/guides/sms/events): słownik zdarzeń i payloady per zdarzenie
- [Webhooks & events](/docs/guides/webhooks): konfiguracja endpointu, weryfikacja podpisu, ponowienia i powtórki

## Related resources

- [Choose a sender for your markets](/explained/sms/which-sms-sender-type-should-i-use) (answer)
- [Check your message segments](/tools/sms-segment-calculator) (tool)