Receiving SMS into your app with a webhook from your own Android number

How it works

1. Put the SIM that receives the messages in the textbee device and enable receiving on it, so every inbound text is stored on your account.
2. Register a webhook URL in the dashboard for MESSAGE_RECEIVED with a signing secret of at least twenty characters.
3. In the handler read the raw body, verify the HMAC-SHA256 in the X-Signature header, deduplicate on idempotencyKey, respond 200 fast, and process the message in a job.
4. Add a scheduled poll of /gateway/messages with a cursor as the safety net, so anything missed while your endpoint was down is picked up.

Send it

The API key comes from the dashboard and the phone registered on your account does the sending. Recipients are E.164 numbers; the example is fictional.

import { createHmac, timingSafeEqual } from 'node:crypto'
import { createServer } from 'node:http'

const SECRET = process.env.TEXTBEE_WEBHOOK_SECRET

createServer((request, response) => {
  const chunks = []
  request.on('data', (chunk) => chunks.push(chunk))
  request.on('end', () => {
    const rawBody = Buffer.concat(chunks)
    const expected = createHmac('sha256', SECRET).update(rawBody).digest('hex')
    const signature = request.headers['x-signature'] ?? ''
    if (signature.length !== expected.length || !timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
      response.writeHead(401).end()
      return
    }
    const event = JSON.parse(rawBody.toString())
    if (event.webhookEvent === 'MESSAGE_RECEIVED') console.log(`${event.sender}: ${event.message}`)
    response.writeHead(200).end()
  })
}).listen(process.env.PORT ?? 3000)

Consent and compliance

Inbound messages are data people sent you, so store only what you need, for as long as you need it, and honour a STOP inside any inbound text as an opt-out from your outbound messages. If the number is shared with a person, keep their private conversations out of your application.

Honest limits

Webhooks are delivered when the phone has uploaded the message, so a phone that is offline delivers its backlog later; the poll with a cursor catches that. Retries happen when your endpoint fails, and a subscription that keeps failing is paused, so return 200 before doing slow work.

One phone sends roughly 10 to 15 messages a minute, so a large blast takes time to drain. Carriers can filter bulk patterns on consumer SIMs. Marketing messages still need consent from the recipient under the local rules.

Frequently asked questions

Read next

• Webhook, defined
• Two-way SMS, defined
• Send and receive SMS in JavaScript
• Receive SMS with a webhook
• Webhooks documentation
• Receiving SMS
• A two-way SMS support inbox on your own Android number
• Bulk announcements from your own Android number
• All use cases