Receiving SMS

textbee.dev forwards SMS messages sent to your registered Android device to your account. Use this for verification codes, customer inquiries, and two-way messaging.

Prerequisites

• A textbee.dev account
• A registered Android device
• SMS receiving enabled in the app

Enabling SMS receiving

1. Open the textbee.dev app on your Android device.
2. Go to Settings or Receive SMS and turn Receive SMS (or Enable Receiving) ON.
3. Incoming SMS will be forwarded to textbee.dev. You can confirm in the dashboard under Devices that receiving is enabled.

Recommended: use a webhook

For real-time handling of incoming SMS, set up a webhook. Your server gets a POST when each message is received — no polling needed.

1. In the dashboard, go to Webhooks and add a webhook URL.
2. Subscribe to the MESSAGE_RECEIVED event.
3. Implement your endpoint to accept the payload and return 200.

Details, payload format, and signing: Webhooks.

Fetching message history (API)

To list received messages (e.g. for history or backfill), use the message history endpoint with type=received:

GET https://api.textbee.dev/api/v1/gateway/devices/{DEVICE_ID}/messages

Headers: x-api-key: YOUR_API_KEY

Query parameters:

• page (optional): Page number. Default: 1.
• limit (optional): Items per page. Default: 50, max: 100.
• type (optional): all, sent, or received. Use received for incoming SMS only. Default: all.

Example (cURL):

curl -X GET "https://api.textbee.dev/api/v1/gateway/devices/YOUR_DEVICE_ID/messages?page=1&limit=50&type=received" \
  -H "x-api-key: YOUR_API_KEY"

The response includes a data array of messages and a meta object (page, limit, total, totalPages). Each message includes fields such as _id, message, sender, receivedAt, and device.

Next Steps

• Set up webhooks - Enable real-time notifications
• Send SMS - Reply to received messages
• Overview - Explore more capabilities

Need help? Check our FAQ or contact support.