Komunikacja dwukierunkowa
Wiadomości wracają. Więc je obsługuj.
Każda wiadomość, którą ktoś wyśle na Twój udostępniony numer, przychodzi jako webhook podpisany HMAC. Odczytaj tekst, odpowiedz z tego samego numeru i pozwól Bird obsłużyć STOP i HELP za Ciebie. Buduj przepływy konwersacyjne i automatyczne odpowiedzi na API, którym już wysyłasz.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const code = generateOtp();
const { data, error } = await bird.sms.send({
from: "Bird",
to: "+15005550006",
text: `Your Bird verification code is ${code}. Reply STOP to opt out.`,
category: "authentication",
}).safe();
if (error) throw error;
console.log(data.id);
// → "sms_4kT01Lq2m..."
Today at 2:14 PM
Ruch przychodzący to po prostu kolejny webhook.
Komunikacja dwukierunkowa jest częścią Bird SMS API. Gdy ktoś wyśle SMS na Twój numer, otrzymujesz zdarzenie sms.received na tym samym podpisanym, chronionym przed powtórzeniami endpoincie, który już obsługuje potwierdzenia doręczenia. Nie ma drugiej integracji ani pollingu: zweryfikuj podpis raz i rozgałęziaj logikę na podstawie typu.
Nasłuchuj, co wraca.
Wiadomość przychodząca i opt-out to zdarzenia, tak samo jak potwierdzenie dostarczenia. Zweryfikuj jeden podpis, rozgałęź na typie i obsłuż każde w handlerze, który już napisałeś.
import { bird } from "@/lib/bird";
export async function POST(req: Request) {
const event = bird.webhooks.unwrap(
await req.text(),
Object.fromEntries(req.headers),
);
switch (event.type) {
case "sms.received":
await handleInbound(event.data.from, event.data.text);
break;
case "sms.opted_out":
await removeFromCampaigns(event.data.from);
break;
}
return new Response(null, { status: 204 });
}Ładunek to ta sama koperta na każdym kanale Bird: identyfikator evt_, podpis HMAC i chroniony przed powtórzeniem znacznik czasu.
sms.receivedWiadomość przychodząca dotarła na Twój numer: zawiera nadawcę, Twój numer i treść wiadomości.sms.deliveredOdpowiedź, którą wysłałeś, dotarła do telefonu (DLR operatora).sms.opted_outNadawca wysłał STOP: Bird dodał go do listy wykluczeń i blokuje przyszłe wysyłki.
Podpisana wiadomość przychodząca, w całości.
Oto jak wygląda zdarzenie sms.received w drodze. Pole from to ten, kto wysłał Ci SMS, pole to to Twój udostępniony numer, a segmenty i kodowanie są raportowane tak samo jak przy wysyłce, więc długa odpowiedź przychodząca nigdy nie jest niespodzianką.
{
"id": "evt_7nQ9xLp2aR...",
"type": "sms.received",
"created_at": "2026-06-26T14:03:11Z",
"data": {
"id": "sms_5hV02Mr3n...",
"from": "+15005550006",
"to": "+14155550172",
"text": "YES book me in for Thursday",
"encoding": "GSM-7",
"segments": 1
}
}Odpowiedz z tego samego numeru.
Odpowiedź to wysyłka z zamienionymi polami from i to. Ustaw from na swój numer, a to na pierwotnego nadawcę, a rozmowa pozostaje na jednym numerze, więc odbiorca widzi wątek zamiast nowego nadawcy za każdym razem. Buduj na tym automatyczne odpowiedzi, potwierdzenia lub pełny przepływ konwersacyjny.
async function handleInbound(from: string, text: string) {
if (/^yes\b/i.test(text)) {
const { error } = await bird.sms.send({
from: "+14155550172", // your two-way number
to: from, // reply to the sender
text: "Booked. See you Thursday at 10am.",
category: "transactional",
}).safe();
if (error) throw error;
}
}STOP, HELP i START obsługujemy za Ciebie.
Bird rozpoznaje zarezerwowane słowa kluczowe, zanim dotrą do Twojego handlera: STOP dodaje nadawcę do Twojej listy wykluczeń i wyzwala sms.opted_out, HELP odsyła automatyczną odpowiedź pomocniczą, a START ponownie go zapisuje. Późniejsze wysyłki na wykluczony numer są blokowane automatycznie. Nadal możesz używać własnych słów kluczowych dla YES, BOOK lub czegokolwiek, czego potrzebuje Twój przepływ. Pełne zasady słów kluczowych i rezygnacji znajdziesz w obsłudze rezygnacji.
Dwie rzeczy, których zechcesz w następnej kolejności.
Obsługa wiadomości przychodzących wymaga numeru obsługującego komunikację dwukierunkową: numery długie, krótkie i bezpłatne mogą odbierać wiadomości, alfanumeryczne identyfikatory nadawcy — nie. Dla bogatszej wymiany na tym samym urządzeniu (wskaźniki pisania, potwierdzenia odczytu, karuzele) RCS rozszerza konwersację tam, gdzie urządzenie to obsługuje.
Zagłęb się w dokumentacji.
Podłącz webhooki dla zdarzeń przychodzących, przeczytaj opis błędów dla awarii, które będziesz obsługiwać, i sprawdź nadużycia i zgodność pod kątem reguł słów kluczowych i zgody.
FAQ dotyczące dwukierunkowego SMS
Jak przychodzący SMS dociera do mojej aplikacji?
Czy mogę odpowiedzieć na wiadomość przychodzącą?
Co się dzieje, gdy ktoś wyśle SMS o treści STOP?
Czy potrzebuję specjalnego numeru do komunikacji dwukierunkowej?
Reszta platformy SMS
Jedno API, jeden zestaw kluczy. Poznaj pozostałe możliwości.
Wysyłaj i odbieraj na jednym numerze, jednym API.
Ruch przychodzący dwukierunkowy to jedna z możliwości API SMS od Bird: wysyłanie, numery, zgodność, routing i analityka są dostarczane wraz z nim, na infrastrukturze, którą prowadzimy od dekady.