Komunikacja dwukierunkowa

Wiadomości wracają. Więc je obsługuj.

Skonfiguruj w:

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.

send-otp.ts

200 · 0.4s

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.`,
}).safe();

if (error) throw error;
console.log(data.id);
// → "sms_4kT01Lq2m..."

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.`,
}).safe();

if (error) throw error;
console.log(data.id);
// → "sms_4kT01Lq2m..."

send-otp.ts

200 · 0.4s

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.`,
}).safe();

if (error) throw error;
console.log(data.id);
// → "sms_4kT01Lq2m..."

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.`,
}).safe();

if (error) throw error;
console.log(data.id);
// → "sms_4kT01Lq2m..."

Ruch przychodzący to po prostu kolejny webhook.

Komunikacja dwukierunkowa to część API SMS od Bird. Gdy ktoś wyśle SMS na Twój numer, otrzymujesz zdarzenie sms.received na tym samym podpisanym, chronionym przed powtórzeniem endpoincie, który już niesie Twoje potwierdzenia dostarczenia. Nie ma drugiej integracji ani odpytywania — zweryfikuj podpis raz i rozgałęź na typie.

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

app/api/webhooks/bird/route.ts

signed

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 wylądowała na Twoim numerze — niesie nadawcę, Twój numer i tekst.
sms.deliveredOdpowiedź, którą wysłałeś, dotarła do telefonu (DLR operatora).
sms.opted_outNadawca wysłał SMS o treści STOP — Bird zablokował go 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ą.

sms.received

evt_

{
  "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.

reply.ts

200 · reply

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.",
    }).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.

Ruch przychodzący wymaga numeru obsługującego komunikację dwukierunkową — long codes, short codes i toll-free mogą odbierać, alfanumeryczne identyfikatory nadawcy nie mogą. Dla bogatszej wymiany na tym samym telefonie (wskaźniki pisania, potwierdzenia odczytu, karuzele) RCS podnosi rozmowę na wyższy poziom 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?+

Każda wiadomość wysłana na Twój udostępniony numer przychodzi jako webhook sms.received podpisany HMAC. Weryfikujesz jeden podpis, odczytujesz pola from, to i text i routujesz ją do własnej logiki — ta sama koperta, którą już obsługujesz dla potwierdzeń dostarczenia.

Czy mogę odpowiedzieć na wiadomość przychodzącą?+

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ę, a wątek pozostaje na jednym numerze od początku do końca.

Co się dzieje, gdy ktoś wyśle SMS o treści STOP?+

Bird dodaje nadawcę do Twojej listy wykluczeń, wyzwala sms.opted_out i automatycznie blokuje późniejsze wysyłki na ten numer. HELP odsyła odpowiedź pomocniczą, a START ponownie go zapisuje — wszystko obsłużone, zanim dotrze do Twojego kodu, więc zachowujesz zgodność bez samodzielnego pisania logiki słów kluczowych.

Czy potrzebuję specjalnego numeru do komunikacji dwukierunkowej?+

Potrzebujesz numeru obsługującego komunikację dwukierunkową. Long codes, short codes i numery toll-free obsługują ruch przychodzący; alfanumeryczne identyfikatory nadawcy są tylko wysyłkowe i nie mogą odbierać odpowiedzi.

Reszta platformy SMS

Jedno API, jeden zestaw kluczy. Poznaj pozostałe możliwości.

WysyłanieAPI wysyłki: segmenty, bezpieczeństwo Unicode, wsadowość i idempotencja.NumeryLong codes, short codes, toll-free i alfanumeryczne identyfikatory nadawcy.ZgodnośćRejestracja A2P 10DLC, opt-out STOP/HELP i reguły identyfikatora nadawcy.Routing150+ krajów, 240 bezpośrednich łączy do operatorów i failover.AnalitykaMetryki dostarczalności i zaangażowania z potwierdzeń dostarczenia operatorów.Przegląd API SMSPełne API SMS: wysyłanie, numery, komunikacja dwukierunkowa, zgodność, routing i analityka.

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.

Poznaj platformę SMS Rozpocznij