Inbound SMS

TextPilot can receive incoming SMS messages on your provisioned phone numbers and forward them to your application via webhooks.

Setup

Provision a phone number — Go to Dashboard → 10DLC Registration → Phone Numbers and request a number
Configure a webhook — Set up a webhook URL via the API or dashboard to receive inbound messages

Webhook Payload

When a message is received, TextPilot sends a POST request to your webhook URL:

{
  "type": "inbound_sms",
  "data": {
    "id": "inb_a1b2c3d4e5f6",
    "from": "+16195551234",
    "to": "+18585559876",
    "body": "Hello, thanks for the update!",
    "receivedAt": 1709913600000
  }
}

Webhook Verification

Each webhook request includes an X-TextPilot-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret.

import { createHmac } from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return expected === signature;
}

Viewing Inbound Messages

All inbound messages are stored and viewable in the dashboard under Messages → Inbound. Messages are displayed with sender number, recipient number, message body, and timestamp.

Reply Threading

Outbound and inbound messages share the same phone number context. You can build conversational flows by matching from/to numbers across outbound and inbound messages.

// Send an outbound message
const msg = await tp.send('+16195551234', 'Your code is 4821');

// When the user replies, you'll receive it on your webhook
// Match by phone number to build conversation threads