API Reference

Complete list of all TextBubbles API endpoints. Base URL: https://api.textbubbles.com

Messages

Capabilities

GET /v1/capabilities/:phoneNumber

Check which messaging channels are available for a recipient, along with their current Focus status and a recommended channel. Results are cached to avoid repeatedly probing Apple infrastructure.

Authentication: Requires Bearer token (Authorization: Bearer tb_xxxxx)

Path Parameters:

Example Request

curl https://api.textbubbles.com/v1/capabilities/+14155551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "phoneNumber": "+14155551234",
    "capabilities": {
      "imessage": true,
      "sms": true,
      "facetime": true
    },
    "focused": false,
    "recommendedChannel": "imessage",
    "lastChecked": "2026-03-28T09:55:00.000Z",
    "cached": true
  },
  "requestId": "req_abc123"
}

When the recipient is currently in a Focus mode, the response also includes focusMode:

{
  "success": true,
  "data": {
    "phoneNumber": "+14155551234",
    "capabilities": { "imessage": true, "sms": true, "facetime": true },
    "focused": true,
    "focusMode": "Do Not Disturb",
    "recommendedChannel": "imessage",
    "lastChecked": "2026-03-28T09:55:00.000Z",
    "cached": false
  },
  "requestId": "req_abc123"
}

Response Fields

Errors

Tip: Use this endpoint before calling POST /v1/messages when you want to branch your application logic based on whether the recipient supports iMessage effects, tapbacks, or FaceTime calls. The recommendedChannel field is a convenient default for the routing.preference on message send.

Numbers

GET /v1/numbers

List all phone numbers and email addresses available as valid from addresses for your account.

Authentication: Requires Bearer token (Authorization: Bearer tb_xxxxx)

Example Request

curl -H "Authorization: Bearer tb_xxxxx" https://api.textbubbles.com/v1/numbers

Example Response

{
  "success": true,
  "data": [
    {
      "phoneNumber": "+14155551234",
      "email": "user@icloud.com",
      "instanceName": "TextBubbles Service 001",
      "isDefault": true,
      "healthStatus": "healthy"
    },
    {
      "phoneNumber": "+19876543210",
      "email": null,
      "instanceName": "TextBubbles Service 002",
      "isDefault": false,
      "healthStatus": "healthy"
    }
  ]
}

Fields

Note: Use the phoneNumber or email values as the from field when sending messages to control which sender address is used.

Webhooks

Health Check

The health check endpoint requires no authentication and is not rate-limited. It returns the overall service status along with individual dependency checks.

Response

{
  "status": "ok",
  "timestamp": "2026-04-10T12:00:00.000Z",
  "checks": {
    "database": { "status": "ok" },
    "redis": { "status": "ok" },
    "imessage": { "status": "ok" },
    "whatsapp": {
      "status": "not_enabled",
      "experimental": true
    }
  }
}

The top-level status is "ok" when the database and Redis are both reachable, or "degraded" if either is down. iMessage and WhatsApp statuses are reported for visibility but do not affect the top-level status.

SMS fallback is handled natively by the iMessage provider — when an iMessage send fails to a non-iMessage recipient, the provider automatically falls back to SMS via a connected iPhone. There is no separate SMS provider to monitor.

Instance Health Status

Each iMessage provider instance is independently monitored every 2 minutes. Instance health is stored as one of four values:

Instance Health Warnings

When an instance has degraded status, the response includes an array of warning strings describing what is wrong. The following conditions trigger warnings:

An instance can have multiple warnings at the same time. Warnings are cleared automatically when the next health check finds the condition resolved.

Error Codes