Migracja SMS od innego dostawcy

1. Włącz kraje docelowe
2. Skonfiguruj nadawcę
3. Zmapuj wywołanie wysyłki do POST /v1/sms/messages
4. Przenieś listę rezygnacji
5. Przełącz raporty doręczeń na webhooki
6. Przetestuj na symulowanych odbiorcach przed przełączeniem

1. Włącz kraje docelowe

2. Skonfiguruj nadawcę

• Alfanumeryczne identyfikatory nadawcy tworzysz samodzielnie 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, 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, 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.

3. Zmapuj wywołanie wysyłki

• 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 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, 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, 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; 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.

4. Przenieś listę rezygnacji

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

• Obie strony są wymagane dla supresji per nadawca. Rezygnacja obejmująca cały obszar roboczy należy do osobnego właściciela preferencji. 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ę.

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

• Doręczenia są podpisywane zgodnie ze Standard Webhooks, 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.
• 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.

6. Przetestuj na symulowanych odbiorcach

• 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.

Migracja od konkretnego dostawcy

• Twilio: form-encoded PascalCase do JSON, Messaging Services do nadawców, StatusCallback do subskrybowanych webhooków
• Plivo: src i dst do from i to, Powerpacks do nadawców, pary DND do supresji
• Telnyx: najbliższy send do Bird, profile wiadomości rozdzielone na nadawców i subskrypcje, rezygnacje na poziomie profilu do par
• Bandwidth: dwa hosty do jednego, callbacki applicationId do webhooków obszaru roboczego i lista rezygnacji, którą Twoja aplikacja już posiada
• Sinch: batche do pojedynczych wysyłek, body do text, członkostwo w grupach odbudowane jako supresje
• Infobip: trójpoziomowy payload spłaszczony, per-konto base URL do regionalnego hosta, Blocklist rozszerzony do par
• Bird 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: oceń workflow produktu i kwestie migracyjne
• Wysyłanie SMS: pełny payload wysyłki, nadawcy, segmenty i asynchroniczny model 202
• Rezygnacje i słowa kluczowe: co Bird obsługuje za Ciebie i jak zarządzać supresjami
• Zdarzenia SMS: słownik zdarzeń i payloady per zdarzenie
• Webhooks & events: konfiguracja endpointu, weryfikacja podpisu, ponowienia i powtórki