Textbee

https://textbee.dev/docs
Admin
Textbee is an open-source SMS gateway that transforms your Android device into a cost-effective SMS...
Tokens:7,871
Snippets:67
Trust Score:7.2
Update:6 months ago
Show doc for...
Tokens:
Raw
### Webhook Handler Example (Node.js/Express)

Source: https://textbee.dev/docs/webhooks

Example implementation of a webhook handler using Node.js and Express to process incoming SMS events.

```APIDOC
## Webhook Handler Example (Node.js/Express)

This example demonstrates how to set up an Express server to receive and process webhook events from textbee.dev.

```javascript
const express = require('express');
const app = express();

// Use express.json() to parse JSON bodies. For signature verification, you might need express.raw() before parsing.
app.use(express.json()); 

app.post('/webhook/textbee', (req, res) => {
  const { event, data } = req.body;

  // It's highly recommended to verify the signature here before processing
  // const signature = req.headers['x-textbee-signature'];
  // const secret = process.env.WEBHOOK_SECRET;
  // if (!verifyWebhookSignature(req.body, signature, secret)) {
  //   return res.status(401).json({ error: 'Invalid signature' });
  // }

  switch (event) {
    case 'MESSAGE_RECEIVED':
      console.log(`Received message from ${data.sender}: ${data.message}`);
      // Process received message data
      break;
    case 'MESSAGE_SENT':
      console.log(`Message sent to ${data.recipient}`);
      // Process sent message data
      break;
    case 'MESSAGE_DELIVERED':
      console.log(`Message delivered to ${data.recipient}`);
      // Process delivered message data
      break;
    case 'MESSAGE_FAILED':
      console.error(`Failed to send message to ${data.recipient}: ${data.error}`);
      // Process failed message data
      break;
    default:
      console.log(`Received unknown event: ${event}`);
  }

  // Respond with 200 OK to acknowledge receipt
  res.status(200).json({ success: true });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
});
```
```

--------------------------------

### GET /api/v1/gateway/devices/{DEVICE_ID}/messages

Source: https://textbee.dev/docs/receiving-sms

Retrieves a list of messages received by a specific device, allowing for history tracking or data backfilling.

```APIDOC
## GET /api/v1/gateway/devices/{DEVICE_ID}/messages

### Description
Fetch a paginated list of SMS messages received by the specified device.

### Method
GET

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

### Parameters
#### Path Parameters
- **DEVICE_ID** (string) - Required - The unique identifier of the registered Android device.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination. Default: 1.
- **limit** (integer) - Optional - Number of items per page. Default: 50, Max: 100.
- **type** (string) - Optional - Filter by message type: 'all', 'sent', or 'received'. Use 'received' for incoming SMS.

### Request Example
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"

### Response
#### Success Response (200)
- **data** (array) - List of message objects containing _id, message, sender, receivedAt, and device.
- **meta** (object) - Pagination metadata including page, limit, total, and totalPages.

#### Response Example
{
  "data": [
    {
      "_id": "msg_123",
      "message": "Hello world",
      "sender": "+123456789",
      "receivedAt": "2023-10-27T10:00:00Z",
      "device": "device_id"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}
```

--------------------------------

### Webhook Payload Structure for MESSAGE_RECEIVED

Source: https://textbee.dev/docs/webhooks

An example of the JSON payload sent by textbee.dev to your webhook endpoint when an SMS is received. It includes event metadata, sender information, and device details.

```json
{
  "event": "MESSAGE_RECEIVED",
  "timestamp": "2026-01-20T10:30:00Z",
  "data": {
    "_id": "abc123",
    "sender": "+1234567890",
    "message": "Hello!",
    "receivedAt": "2025-01-15T10:30:00Z",
    "device": { "_id": "device123", "enabled": true, "model": "Pixel 7" },
    "createdAt": "2025-01-15T10:30:01Z",
    "updatedAt": "2025-01-15T10:30:01Z"
  }
}
```

--------------------------------

### POST /webhooks

Source: https://textbee.dev/docs/webhooks

This endpoint is used to configure webhooks. You need to provide a public URL that accepts HTTP POST requests and specify the events you want to receive notifications for. A signing secret can also be provided for security.

```APIDOC
## POST /webhooks

### Description
Configure a webhook to receive real-time notifications for SMS events.

### Method
POST

### Endpoint
/webhooks

### Parameters
#### Request Body
- **url** (string) - Required - The public URL to receive webhook POST requests.
- **events** (array of strings) - Required - A list of events to subscribe to (e.g., "MESSAGE_RECEIVED", "MESSAGE_SENT").
- **secret** (string) - Optional - A secret string for signature verification (recommended).

### Request Example
```json
{
  "url": "https://your-domain.com/webhook/textbee",
  "events": [
    "MESSAGE_RECEIVED",
    "MESSAGE_SENT",
    "MESSAGE_DELIVERED",
    "MESSAGE_FAILED"
  ],
  "secret": "your-super-secret-key"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created webhook.
- **url** (string) - The configured webhook URL.
- **events** (array of strings) - The subscribed events.

#### Response Example
```json
{
  "id": "whk_123abc",
  "url": "https://your-domain.com/webhook/textbee",
  "events": [
    "MESSAGE_RECEIVED",
    "MESSAGE_SENT",
    "MESSAGE_DELIVERED",
    "MESSAGE_FAILED"
  ]
}
```
```

--------------------------------

### Implement TextBee Webhook Listener in Flask

Source: https://textbee.dev/docs/webhooks

This Python snippet demonstrates how to create a Flask endpoint that listens for TextBee webhook events. It parses the JSON payload and handles different event types such as message reception, sending, delivery, and failure.

```python
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/textbee', methods=['POST'])
def webhook():
    payload = request.json
    event = payload.get('event')
    data = payload.get('data') or {}
    if event == 'MESSAGE_RECEIVED':
        print(f"Received from {data.get('sender')}: {data.get('message')}")
    elif event == 'MESSAGE_SENT':
        print(f"Sent to {data.get('recipient')}")
    elif event == 'MESSAGE_DELIVERED':
        print(f"Delivered to {data.get('recipient')}")
    elif event == 'MESSAGE_FAILED':
        print(f"Failed to {data.get('recipient')}: {data.get('error')}")
    return jsonify({'success': True}), 200

if __name__ == '__main__':
    app.run(port=3000)
```

--------------------------------

### Handling Webhook Events with Node.js and Express

Source: https://textbee.dev/docs/webhooks

A basic implementation of an Express server endpoint to receive and process various SMS event types sent by textbee.dev.

```javascript
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/textbee', (req, res) => {
  const { event, data } = req.body;
  switch (event) {
    case 'MESSAGE_RECEIVED':
      console.log(`Received from ${data.sender}: ${data.message}`);
      break;
    case 'MESSAGE_SENT':
      console.log(`Sent to ${data.recipient}`);
      break;
    case 'MESSAGE_DELIVERED':
      console.log(`Delivered to ${data.recipient}`);
      break;
    case 'MESSAGE_FAILED':
      console.error(`Failed to ${data.recipient}: ${data.error}`);
      break;
    default:
      console.log(`Event: ${event}`);
  }
  res.status(200).json({ success: true });
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});
```

--------------------------------

### Webhook Signature Verification in Node.js

Source: https://textbee.dev/docs/webhooks

Demonstrates how to verify the authenticity of incoming webhook requests using HMAC SHA256 signature verification. This ensures that the request originated from textbee.dev.

```javascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhook/textbee', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-textbee-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  const payload = JSON.parse(req.body);
  res.status(200).json({ success: true });
});
```

--------------------------------

### Webhook Security: Signature Verification

Source: https://textbee.dev/docs/webhooks

Implement signature verification to ensure webhook requests originate from textbee.dev.

```APIDOC
## Webhook Security: Signature Verification

To verify that webhooks are coming from textbee.dev, use signature verification.

1.  When creating a webhook, set a **secret** (a random string).
2.  textbee.dev will include a signature in the `X-Textbee-Signature` header.
3.  Verify the signature on your server.

### Example: Signature Verification (Node.js/Express)
```javascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhook/textbee', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-textbee-signature'];
  const secret = process.env.WEBHOOK_SECRET; // Ensure your secret is stored securely
  
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  const payload = JSON.parse(req.body);
  // Process webhook payload...
  
  res.status(200).json({ success: true });
});
```
```

--------------------------------

### Webhook Event Payloads

Source: https://textbee.dev/docs/webhooks

Details on the structure of payloads sent for different SMS events.

```APIDOC
## Webhook Event Payloads

Webhooks send JSON payloads containing `event`, `timestamp`, and `data`.

### MESSAGE_RECEIVED
Sent when an SMS is received on your device.

#### Payload Example
```json
{
  "event": "MESSAGE_RECEIVED",
  "timestamp": "2026-01-20T10:30:00Z",
  "data": {
    "_id": "abc123",
    "sender": "+1234567890",
    "message": "Hello!",
    "receivedAt": "2025-01-15T10:30:00Z",
    "device": { "_id": "device123", "enabled": true, "model": "Pixel 7" },
    "createdAt": "2025-01-15T10:30:01Z",
    "updatedAt": "2025-01-15T10:30:01Z"
  }
}
```

### MESSAGE_SENT
Sent when an SMS has been sent from your device. `data` includes message id, recipient(s), and device info.

### MESSAGE_DELIVERED
Sent when the carrier reports delivery. `data` includes message id, recipient, and delivery time.

### MESSAGE_FAILED
Sent when sending failed. `data` includes message id, recipient, and error details.
```

--------------------------------

### SMS Message Template Syntax

Source: https://textbee.dev/docs/sending-sms/sending-bulk-sms

The template syntax used in the dashboard to inject CSV data into messages. Variables are defined using double curly braces matching the CSV header names.

```text
Hello {{ name }}, your order #{{ orderId }} is ready!
```

--------------------------------

### Fetch SMS Message History (API)

Source: https://textbee.dev/docs/receiving-sms

Retrieve a list of received SMS messages from your textbee.dev account using the API. This is useful for historical data or backfilling. Requires your device ID and API key. The response contains a data array of messages and pagination metadata.

```http
GET https://api.textbee.dev/api/v1/gateway/devices/{DEVICE_ID}/messages?type=received
Headers: x-api-key: YOUR_API_KEY
Query parameters: page (optional), limit (optional), type (optional, use 'received')
```

```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"
```

--------------------------------

### Send SMS via textbee.dev API

Source: https://textbee.dev/docs/sending-sms/sending-sms

Sends an SMS message to a specified recipient using the textbee.dev gateway. Requires an API key, device ID, and a JSON payload containing the recipient's phone number in E.164 format and the message text.

```javascript
const axios = require('axios');

const DEVICE_ID = 'YOUR_DEVICE_ID';
const API_KEY = 'YOUR_API_KEY';

async function sendSMS(recipient, message) {
  const response = await axios.post(
    `https://api.textbee.dev/api/v1/gateway/devices/${DEVICE_ID}/send-sms`,
    {
      recipients: [recipient],
      message,
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': API_KEY,
      },
    }
  );

  return response.data;
}

// Usage
sendSMS('+1234567890', 'Hello from textbee.dev!');
```

```bash
curl -X POST \
  https://api.textbee.dev/api/v1/gateway/devices/YOUR_DEVICE_ID/send-sms \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "recipients": ["+1234567890"],
    "message": "Hello from textbee.dev!"
  }'
```

--------------------------------

### Bulk SMS CSV Format

Source: https://textbee.dev/docs/sending-sms/sending-bulk-sms

The required CSV format for bulk SMS operations. It must include a phone number column and optional columns for personalization variables like names or order IDs.

```csv
phone,name,orderId
+1234567890,John,1001
+0987654321,Jane,1002
```

--------------------------------

### POST /api/v1/gateway/devices/{DEVICE_ID}/send-sms

Source: https://textbee.dev/docs/sending-sms

Sends an SMS message through a registered Android device linked to the user's account.

```APIDOC
## POST /api/v1/gateway/devices/{DEVICE_ID}/send-sms

### Description
Sends an SMS message to one or more recipients using a specific Android device registered on the textbee.dev platform.

### Method
POST

### Endpoint
https://api.textbee.dev/api/v1/gateway/devices/{DEVICE_ID}/send-sms

### Parameters
#### Path Parameters
- **DEVICE_ID** (string) - Required - The unique identifier of the Android device to send the SMS from.

#### Request Body
- **recipients** (array) - Required - Array of phone numbers in E.164 format (e.g., +1234567890).
- **message** (string) - Required - The content of the SMS message.
- **simSubscriptionId** (number) - Optional - The index of the SIM card to use on multi-SIM devices.

### Request Example
{
  "recipients": ["+1234567890"],
  "message": "Hello, this is a test message!"
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the success status of the request.

#### Response Example
{
  "success": true,
  "message": "SMS queued successfully"
}
```

--------------------------------

### POST /api/v1/gateway/devices/{DEVICE_ID}/send-sms

Source: https://textbee.dev/docs/sending-sms/sending-sms

Sends an SMS message to one or more recipients using a registered Android device.

```APIDOC
## POST /api/v1/gateway/devices/{DEVICE_ID}/send-sms

### Description
Sends an SMS message to specified recipients using a registered Android device linked to your textbee.dev account.

### Method
POST

### Endpoint
https://api.textbee.dev/api/v1/gateway/devices/{DEVICE_ID}/send-sms

### Parameters
#### Path Parameters
- **DEVICE_ID** (string) - Required - The unique identifier of the Android device to send the SMS from.

#### Request Body
- **recipients** (array) - Required - Array of phone numbers in E.164 format (e.g., +1234567890).
- **message** (string) - Required - The text content of the SMS message.
- **simSubscriptionId** (number) - Optional - The index of the SIM card to use on multi-SIM devices.

### Request Example
{
  "recipients": ["+1234567890"],
  "message": "Hello, this is a test message!"
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the success status of the request.

#### Response Example
{
  "status": "success"
}
```
Tokens:
Raw