Messaging

Receive SMS

When someone texts one of your numbers, Pulsr forwards the message to your webhook within seconds, so replies, confirmations and opt-outs land in your product.

Set up a number

01In the dashboard, open Numbers and get a number that supports two-way SMS in your country.
02In the number’s settings, set the inbound webhook URL, for example https://yourapp.com/webhooks/inbound?token=….
03Optionally, add keywords (like STOP or JOIN). The first word of the message is matched and returned separately.

What you receive

POST to your webhook

{  "results": [    {      "messageId": "817790313235066447",      "from": "33639981234",      "to": "33644630000",      "text": "STOP",      "cleanText": "",      "keyword": "STOP",      "receivedAt": "2026-10-19T09:41:00.000+0000",      "smsCount": 1,      "price": { "pricePerMessage": 0, "currency": "EUR" },      "callbackData": null    }  ],  "messageCount": 1,  "pendingMessageCount": 0}

Field	Description
`from`	The sender’s number. Reply to it.
`to`	Your number that received the message.
`text`	The full message.
`keyword`, `cleanText`	The matched keyword, and the text without it.
`receivedAt`	When Pulsr received it.
`smsCount`	How many parts the message had.

Handle and reply

Reply by sending a message from the number that received it, so the conversation stays in one thread on the person’s phone.

app/webhooks/inbound/route.ts

import { pulsr } from "@/lib/client";export async function POST(req: Request) {  // Check the token first, see the Webhooks guide  const { results } = await req.json();  for (const sms of results) {    if (sms.keyword === "STOP") {      await db.contact.optOut(sms.from);      continue;    }    // Answer from the number they wrote to    await pulsr("POST", "/sms/3/messages", {      messages: [{        sender: sms.to,        destinations: [{ to: sms.from }],        content: { text: "Thanks, we will reply within the hour." },      }],    });  }  return new Response(null, { status: 200 });}

Fetch instead of webhooks

GET/sms/1/inbox/reports

Numbers without a webhook URL keep inbound messages for you to fetch. Each message is returned once; pendingMessageCount tells you how many are still waiting.

inbox.ts

const inbox = await pulsr("GET", "/sms/1/inbox/reports?limit=100");const { results, pendingMessageCount } = inbox;for (const sms of results) {  console.log(sms.from, sms.text);}// pendingMessageCount > 0 means there is more to fetch

Set up a number

01In the dashboard, open Numbers and get a number that supports two-way SMS in your country.
02In the number’s settings, set the inbound webhook URL, for example https://yourapp.com/webhooks/inbound?token=….
03Optionally, add keywords (like STOP or JOIN). The first word of the message is matched and returned separately.

What you receive

POST to your webhook

{  "results": [    {      "messageId": "817790313235066447",      "from": "33639981234",      "to": "33644630000",      "text": "STOP",      "cleanText": "",      "keyword": "STOP",      "receivedAt": "2026-10-19T09:41:00.000+0000",      "smsCount": 1,      "price": { "pricePerMessage": 0, "currency": "EUR" },      "callbackData": null    }  ],  "messageCount": 1,  "pendingMessageCount": 0}

Field	Description
`from`	The sender’s number. Reply to it.
`to`	Your number that received the message.
`text`	The full message.
`keyword`, `cleanText`	The matched keyword, and the text without it.
`receivedAt`	When Pulsr received it.
`smsCount`	How many parts the message had.

Handle and reply

Reply by sending a message from the number that received it, so the conversation stays in one thread on the person’s phone.

app/webhooks/inbound/route.ts

import { pulsr } from "@/lib/client";export async function POST(req: Request) {  // Check the token first, see the Webhooks guide  const { results } = await req.json();  for (const sms of results) {    if (sms.keyword === "STOP") {      await db.contact.optOut(sms.from);      continue;    }    // Answer from the number they wrote to    await pulsr("POST", "/sms/3/messages", {      messages: [{        sender: sms.to,        destinations: [{ to: sms.from }],        content: { text: "Thanks, we will reply within the hour." },      }],    });  }  return new Response(null, { status: 200 });}

Fetch instead of webhooks

GET/sms/1/inbox/reports

Numbers without a webhook URL keep inbound messages for you to fetch. Each message is returned once; pendingMessageCount tells you how many are still waiting.

inbox.ts

const inbox = await pulsr("GET", "/sms/1/inbox/reports?limit=100");const { results, pendingMessageCount } = inbox;for (const sms of results) {  console.log(sms.from, sms.text);}// pendingMessageCount > 0 means there is more to fetch