Elk bericht dat iemand naar je geprovisioneerde nummer stuurt, komt binnen als een HMAC-ondertekende webhook. Lees de text, antwoord vanaf hetzelfde nummer, en laat Bird STOP en HELP voor je afhandelen. Bouw conversationele flows en auto-replies op de API waarmee je al verstuurt.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.sms.send({
from: "Bird",
to: "+15005550006",
text: "Your order #4821 has shipped. Track it: bird.ly/t/4821x",
category: "transactional",
}).safe();
if (error) throw error;
console.log(data.id);
// → "sms_4kT01Lq2m..."
Inbound is gewoon nog een webhook.
Tweerichtingsverkeer is onderdeel van de Bird SMS API. Wanneer iemand uw nummer sms't, ontvangt u een sms.received event op hetzelfde ondertekende, replay-beschermde endpoint dat al uw bezorgbevestigingen verwerkt. Geen tweede integratie en geen polling: verifieer de handtekening één keer en schakel op het type.
Luister naar wat terugkomt.
Een inkomend bericht en een opt-out zijn events, net als een delivery receipt. Verifieer één signature, schakel op het type, en handel elk af in de handler die je al schreef.
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 });
}De payload is dezelfde envelope op elk Bird-kanaal: een evt_-id, een HMAC-signature, en een replay-beschermde timestamp.
sms.receivedEen inkomend bericht is op uw nummer binnengekomen: bevat de afzender, uw nummer en de tekst.sms.deliveredEen antwoord dat je verstuurde bereikte het toestel (carrier DLR).sms.opted_outDe afzender heeft STOP gestuurd: Bird heeft hen onderdrukt en blokkeert toekomstige berichten.
Een ondertekend inkomend bericht, volledig.
Zo ziet een sms.received-event er op de lijn uit. De from is wie je sms'te, de to is je geprovisioneerde nummer, en segments en encoding worden op dezelfde manier gerapporteerd als bij een verzending, zodat een lang inkomend antwoord nooit een verrassing is.
{
"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
}
}Antwoord vanaf hetzelfde nummer.
Een antwoord is een verzending met from en to omgewisseld. Zet from op je nummer en to op de oorspronkelijke afzender, en het gesprek blijft op één nummer, zodat de ontvanger een thread ziet in plaats van elke keer een nieuwe afzender. Bouw daarbovenop auto-replies, bevestigingen of een volledige conversationele flow.
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 en START handelen we voor je af.
Bird herkent de gereserveerde trefwoorden voordat ze je handler bereiken: STOP zet de afzender op je onderdrukkingslijst en activeert sms.opted_out, HELP stuurt een automatisch hulpantwoord en START schrijft ze weer in. Latere verzendingen naar een onderdrukt nummer worden automatisch geblokkeerd. Je kunt je eigen trefwoorden voor YES, BOOK of wat je flow nodig heeft gewoon behouden. De volledige trefwoord- en opt-outregels staan in opt-outafhandeling.
Twee dingen die je hierna wilt.
Voor inkomende berichten heeft u een tweerichtings-geschikt nummer nodig: long codes, short codes en gratis nummers kunnen ontvangen, alfanumerieke afzender-ID's niet. Voor rijkere interactie op hetzelfde toestel (typindicatoren, leesbevestigingen, carrousels) upgradet RCS het gesprek waar het apparaat dit ondersteunt.
Ga dieper in de docs.
Wire webhooks aan voor inbound events, lees de error-referentie voor de fouten die je gaat afhandelen, en bekijk misbruik en compliance voor de keyword- en consentregels.
De rest van het SMS-platform
Eén API, één set keys. Verken de andere mogelijkheden.
Verstuur en ontvang op één nummer, één API.
Two-way inbound is één mogelijkheid van de Bird SMS API: verzenden, nummers, compliance, routering en analytics komen ermee mee, op infrastructuur die we al tien jaar draaien.