FAQ SMS API

Zainstaluj SDK i wyślij wiadomość na autoryzowany numer testowy +15005550006 w około pięć minut. Możesz uruchomić test CI, zanim udostępnisz numer.

Jeden endpoint wysyłki, dwukierunkowy odbiór, provisioning numerów (numery długie, krótkie, bezpłatne i alfanumeryczne identyfikatory nadawcy), zgodność z A2P 10DLC i obsługą rezygnacji, routing bezpośrednio do operatora oraz analityka dostarczeń — wszystko w jednym API.

Bird dociera do ponad 150 krajów przez ponad 240 bezpośrednich połączeń z operatorami, z automatycznym przełączaniem tras klasy operatorskiej, gdy ścieżka do operatora ulega degradacji.

Aby wysyłać ruch aplikacja-do-osoby na numery amerykańskie — tak. Rejestracja marki i kampanii odbywa się w panelu, a status można sprawdzić przez API.

Za wiadomość, według stawki zależnej od kraju docelowego i typu nadawcy, z którego wysyłasz — kod długi w USA i alfanumeryczny nadawca w Wielkiej Brytanii mają osobne stawki. Ceny są publikowane per kraj na stronie cennika SMS.

Tak, rozliczenie odbywa się per segment, a nie per wiadomość. Jeden segment mieści 160 znaków GSM-7 lub 70, gdy choćby jeden emoji lub znak spoza alfabetu łacińskiego wymusza kodowanie Unicode dla całej wiadomości. Dłuższy tekst jest dzielony, a każdy segment jest rozliczany, więc jeden zbędny znak może podwoić koszt dużej kampanii.

Opłaty operatorskie naliczane są za wiadomość i różnią się w zależności od miejsca docelowego i operatora. W USA 10DLC wiąże się także z opłatami za rejestrację marki i kampanii. Wszystko jest wymienione na stronie opłat operatorskich SMS.

Log SMS pokazuje liczbę segmentów i koszt każdej wiadomości po jej wycenie; metryki SMS agregują zaakceptowany wolumen, segmenty i wydatki w czasie.

Wiadomość w GSM-7 mieści 160 znaków na segment; przejście na Unicode (UCS-2) dla emoji lub skryptów niełacińskich zmniejsza to do 70. Dłuższe wiadomości są łączone w segmenty, a SDK podaje ich liczbę przed wysłaniem.

Dwanaście segmentów, czyli około 1 836 znaków GSM-7 lub 804 znaki Unicode. Bird nigdy nie obcina treści: wiadomość przekraczająca limit zwraca błąd 422. Limit liczy segmenty, a nie znaki, właśnie dlatego, że dwa kodowania mieszczą różne ilości.

Do 100 w wywołaniu zbiorczym, każda z własnym odbiorcą i treścią. Pojedyncza wiadomość trafia do dokładnie jednego odbiorcy, więc wywołanie zbiorcze służy do rozesłania masowego.

Klucz na darmowym planie pozwala na 10 pojedynczych wysyłek i 5 wywołań zbiorczych na minutę, a płatne plany podnoszą oba limity. Każda odpowiedź zawiera nagłówek IETF RateLimit informujący o pozostałym limicie i czasie resetu okna, więc dostosuj tempo do niego zamiast do zakodowanej na stałe wartości.

To jest ustawiane przez operatorów, nie przez Bird. Zarejestrowany numer długi 10DLC otrzymuje przepustowość na podstawie wyniku zaufania marki i typu kampanii: więcej niż numer niezarejestrowany, mniej niż numer krótki. Numery krótkie mają najwyższą i najbardziej przewidywalną przepustowość.

W przypadku ruchu aplikacyjnego w USA, kod długi 10DLC pokrywa większość scenariuszy dwukierunkowych i OTP. Programy masowe typu jeden-do-wielu przechodzą na krótki kod; numer toll-free to opcja dla USA/Kanady bez 10DLC.

Kod długi lub numer toll-free jest dostępny natychmiast i zaczyna wysyłać po zakończeniu rejestracji lub weryfikacji. Krótkie kody podlegają weryfikacji operatorów i proces ten trwa zazwyczaj tygodnie.

Tak. Kody długie, krótkie kody i numery toll-free działają dwukierunkowo: skieruj ruch przychodzący numeru na webhook, a odpowiedzi dotrą jako podpisane zdarzenia. Alfanumeryczne identyfikatory nadawcy działają tylko jednokierunkowo.

To zależy od typu nadawcy i kraju. Ruch aplikacyjny w USA wymaga A2P 10DLC, numery toll-free wymagają weryfikacji, a wiele krajów wymaga wcześniejszej rejestracji identyfikatora nadawcy — wszystko to obsługiwane jest z poziomu dashboardu.

To krótki ciąg tekstowy, zwykle nazwa Twojej marki, który wyświetla się w polu „od

Powinien być krótki: zazwyczaj do 11 znaków w sieciach GSM. Dokładne ograniczenie zależy od kraju docelowego i operatora oraz tego, co każdy z nich akceptuje.

Numer toll-free to numer 8xx (800, 888, 877 i pozostałe prefiksy toll-free), który wysyła i odbiera SMS-y w USA i Kanadzie. Obsługuje ruch aplikacyjny bez A2P 10DLC, po przejściu weryfikacji toll-free.

Nie. Numery toll-free funkcjonują poza systemem A2P 10DLC. Zamiast tego przechodzą weryfikację toll-free, w ramach której operatorzy sprawdzają przypadek użycia i treść wiadomości, zanim numer uzyska możliwość wysyłki z pełną przepustowością.

Dziesięciocyfrowy numer długi (10DLC) to standardowy lokalny numer telefonu autoryzowany do wysyłania SMS aplikacja-do-osoby w USA po zarejestrowaniu marki i kampanii u operatorów.

Zarejestrowane numery długie 10DLC otrzymują zweryfikowaną przepustowość zależną od wyniku zaufania marki i typu kampanii: więcej niż numer niezarejestrowany, mniej niż numer krótki.

Short code to 5–6-cyfrowy numer zatwierdzony przez operatorów do masowej wysyłki SMS typu jeden-do-wielu: kampanie marketingowe, alerty i szybkie OTP. Zapewnia najwyższą przepustowość spośród typów nadawców i przechodzi weryfikację operatora przed uruchomieniem.

Planuj w tygodniach, nie minutach. Operatorzy weryfikują każdy program short code przed uruchomieniem, więc wiąże się on z realnym czasem oczekiwania — w przeciwieństwie do numeru długiego, który można kupić i zacząć wysyłać od razu po zakończeniu rejestracji.

Dedykowany short code należy wyłącznie do Ciebie, więc jego reputacja nadawcy jest w pełni Twoja. Współdzielony short code dzieli numer między nadawców za pomocą słów kluczowych: tańszy, szybszy na start, ale dziedziczysz reputację wszystkich innych użytkowników tego numeru.

Ty — w przypadku wysyłki dowolnego tekstu: podaj numer należący do Twojego workspace'a, short code lub alfanumeryczny identyfikator nadawcy, jeśli kraj docelowy na to pozwala. Jeśli go pominiesz, wysyłka zostanie odrzucona, a nie zgadywana. Wysyłka szablonowa jest wyjątkiem — sama wybiera nadawcę.

Informuje Bird i operatorów, dlaczego wysyłasz wiadomość, a zasady zgodności obowiązujące w danym kraju — takie jak polityka opt-out i cisza nocna — opierają się na niej. Jest wymagana przy wysyłce dowolnego tekstu; wysyłka szablonowa dziedziczy klasyfikację szablonu.

Przekaż klucz idempotentności, a ponowione żądanie zwróci oryginalny wynik zamiast wysyłać wiadomość dwukrotnie. Bez niego ponowienie jest traktowane jako nowa wiadomość.

Każda zmiana statusu wyzwala podpisany HMAC webhook (queued, sent, delivered lub failed), zawierający potwierdzenie doręczenia od operatora i liczbę segmentów.

Każda wiadomość wysłana na Twój provisionowany numer trafia jako podpisany HMAC webhook sms.received. Weryfikujesz jeden podpis, odczytujesz pola from, to i text, i kierujesz je do własnej logiki — ten sam format, który już obsługujesz dla potwierdzeń doręczenia.

Tak. Odpowiedz, wysyłając z tego samego numeru, na który przyszła wiadomość. Ustaw from na swój numer, a to na pierwotnego nadawcę — wątek pozostanie na jednym numerze od początku do końca.

Bird adds the sender to your suppression list and fires sms_suppression.created, and blocks later sends from that sender to that number automatically. HELP returns a help reply and START opts them back in, all handled before they reach your code, so you stay compliant without writing the keyword logic yourself.

Potrzebujesz numeru obsługującego komunikację dwukierunkową. Numery długie, numery krótkie i numery bezpłatne obsługują wiadomości przychodzące; alfanumeryczne identyfikatory nadawcy służą wyłącznie do wysyłania i nie mogą odbierać odpowiedzi.

Twoja wiadomość trafia bezpośrednio do operatora komórkowego przez jedno z naszych 240 bezpośrednich połączeń, a nie przez łańcuch pośredników. Mniej przeskoków oznacza mniej miejsc, w których wiadomość może utknąć lub potwierdzenie dostarczenia może zaginąć.

Bird wybiera nową trasę w czasie rzeczywistym. Jeśli ścieżka zaczyna gubić potwierdzenia lub zwalniać, następna wiadomość trafia zdrowszym połączeniem do tego samego operatora, a Twój kod wysyłki nie wymaga żadnych zmian.

Każda wiadomość zwraca potwierdzenie dostarczenia od operatora jako webhook sms.delivered lub sms.failed, zawierający mcc_mnc, kraj i latency_ms. To potwierdzenie pochodzi od samego operatora, a nie jest naszym domysłem.

Tak. Przy każdej wysyłce wykonujemy zapytanie MNP, aby ustalić aktualnego operatora odbiorcy, dzięki czemu przeniesiony numer trafia do operatora, który faktycznie go obsługuje. Aby sprawdzać numery niezależnie, skorzystaj z Lookup.

Routing równoważy koszt i jakość dostarczenia dla każdego miejsca docelowego. Ruch transakcyjny, jak jednorazowe kody dostępu, preferuje ścieżkę najwyższej jakości; ruch masowy może skłaniać się ku najniższemu kosztowi. Wybór następuje per wiadomość, za tym samym wywołaniem API.

Z potwierdzenia dostarczenia od operatora (DLR) dla każdej wysyłki. Bird rejestruje potwierdzenie powiązane z wiadomością, a następnie agreguje te potwierdzenia w statystyki dostarczeń, błędów i opóźnień. Liczba dostarczonych to potwierdzenie odbioru przez operatora, a nie przypuszczenie Bird.

Yes, from its own endpoint. The stats API has one breakdown per dimension (carrier, country, originator, category, status, error code, tag) plus daily and hourly series, and each row carries the one dimension you asked for. Crossing two of them, such as a carrier inside a country, means two calls and joining the rows yourself. A failure rate that looks fine nationally often turns out to be one carrier rejecting one sender ID.

Jedno i drugie. Każdy stan dostarczenia już przychodzi jako webhook, więc możesz zbudować własny magazyn danych ze strumienia zdarzeń. API statystyk jest po to, gdy wolisz, żeby Bird wykonał agregację zamiast samodzielnego prowadzenia liczników.

Przekaż identyfikator wiadomości do endpointu zdarzeń, a otrzymasz pełną oś czasu: w kolejce, wysłana, dostarczona lub niedostarczona — każdy etap ze znacznikiem czasu, a w przypadku błędu z kodem przyczyny od operatora. To jest raport, którego naprawdę potrzebujesz, gdy klient mówi, że SMS nigdy nie dotarł.

Tak. Wypisanie jest odwracalne. Odbiorca, który wyśle START, zostaje usunięty z listy blokad i może ponownie otrzymywać wiadomości. Decyzja należy do odbiorcy.

Lista blokad to zasób API, który można odpytywać. Sprawdź numer przed zbudowaniem grupy odbiorców, aby wypisany odbiorca nigdy nie trafił ponownie do wysyłki.

To zależy od tego, dokąd i co wysyłasz. Ruch aplikacyjny w USA wymaga rejestracji marki i kampanii A2P 10DLC. Wiele krajów wymaga wstępnej rejestracji identyfikatora nadawcy dla nadawców alfanumerycznych. Obsługa rezygnacji obowiązuje wszędzie i nie wymaga konfiguracji.

Bird składa każdą rejestrację u operatorów lub w rejestrach i raportuje jej status przez API. Twój kod może odpytywać stan rejestracji i czekać na zatwierdzenie, zamiast wysyłać w ramach kampanii, która jeszcze nie jest aktywna.

Nie. Używa tego samego klienta i kluczy co wysyłanie, numery i komunikacja dwukierunkowa. Status rejestracji i lista wykluczeń to zasoby API obok wywołania wysyłki, więc jedna integracja obejmuje zarówno wysyłanie, jak i zasady z nim związane.

Aby ograniczyć spoofing, wiele krajów doręcza tylko alfanumeryczne identyfikatory nadawcy, które zostały wcześniej zarejestrowane u lokalnych operatorów lub regulatora. Tam, gdzie obowiązuje ta zasada, niezarejestrowany identyfikator nadawcy jest odrzucany lub nadpisywany.

Bird. Przesyłasz identyfikator nadawcy i kraj docelowy z poziomu dashboardu, Bird przekazuje go do lokalnego rejestru, a API raportuje status, dzięki czemu wiesz, kiedy nadawca jest aktywny.

Zatwierdzenie przechodzi przez zewnętrznych operatorów i rejestry i różni się w zależności od kraju — zazwyczaj trwa od kilku dni do kilku tygodni. Sprawdzaj status rejestracji przez API i poczekaj na zatwierdzenie przed wysyłką z danego identyfikatora nadawcy.

A2P 10DLC to system amerykańskich operatorów dla SMS-ów typu application-to-person wysyłanych przez standardowe 10-cyfrowe numery długie. Firma rejestruje markę stojącą za ruchem oraz kampanię opisującą wiadomości, a operatorzy weryfikują oba elementy przed przyznaniem przepustowości.

Marka to podmiot prawny wysyłający ruch. Kampania opisuje konkretny przypadek użycia wiadomości w ramach tej marki. Jedna marka może mieć kilka kampanii, a numery przypisujesz do kampanii, nie do marki.

Weryfikacja marki i kampanii przechodzi przez operatorów i rejestr i zazwyczaj trwa od kilku dni do kilku tygodni. Sprawdzaj status kampanii przez API, aby Twój kod czekał na zatwierdzenie przed rozpoczęciem wysyłki.

Nie. 10DLC to system amerykański. Inne kraje mają własne zasady — wiele z nich wymaga wcześniejszej rejestracji identyfikatora nadawcy, a obsługa słów kluczowych opt-out obowiązuje niezależnie od kraju wysyłki.

Twoje połączenie z Bird jest szyfrowane przez HTTPS, podobnie jak webhook przychodzący, który do Ciebie wysyłamy. Ostatni odcinek nie leży w naszej gestii: SMS to protokół operatorski bez szyfrowania end-to-end, a wiadomość jest czytelna na telefonie i dla operatora. Dlatego nie umieszczaj poufnych danych w treści i preferuj WhatsApp lub e-mail do przesyłania wrażliwych informacji.

Każde zdarzenie jest podpisane HMAC. Zweryfikuj podpis za pomocą sekretu swojego endpointu, zanim podejmiesz działania na podstawie danych, i rotuj ten sekret z poziomu dashboardu w razie potrzeby.

W regionie, w którym hostowana jest Twoja organizacja — us1 lub eu1. Twój klucz API zawiera tę informację w prefiksie (bk_us1_…, bk_eu1_…), dzięki czemu SDK i CLI automatycznie wybierają właściwy endpoint bez konieczności konfiguracji.

Tylko to, do czego go uprawnisz. Klucz zawiera listę zakresów uprawnień (scopes), każdy na odczyt lub zapis, więc klucz do wysyłania SMS nie może zarządzać Twoimi numerami ani odczytywać innego kanału. Akcje zarządzania, takie jak zarządzanie członkami i wydawanie kluczy, są dostępne wyłącznie z dashboardu i żaden klucz nie ma do nich dostępu.

Jedno i drugie. Klucz przyjmuje listę dozwolonych zakresów CIDR i odrzuca żądania spoza nich, a rotacja pozostawia stary klucz aktywny na okres karencji (domyślnie 24 godziny lub zero, aby odciąć go natychmiast), więc wymiana nie wymaga przestoju.

Tak. Log audytu to tylko do odczytu, obejmujący całą organizację rejestr każdej akcji zarządzania, z informacją o autorze, workspace, czasie i wyniku, z możliwością eksportu do OCSF na potrzeby Twojego SIEM.

Certyfikaty i dokumentacja bezpieczeństwa znajdują się w Trust Center pod adresem trust.bird.com. Umowa o przetwarzanie danych, polityka prywatności i zasady dopuszczalnego użytkowania są opublikowane na bird.com/legal. W sprawie kwestionariusza dostawcy skontaktuj się ze swoim opiekunem konta w Bird.