# TextBubbles API

> A unified REST API for sending iMessages with automatic SMS fallback.

Base URL: https://api.textbubbles.com
Docs: https://docs.textbubbles.com
Full API docs for LLMs: https://docs.textbubbles.com/llms-full.txt

## Authentication

All requests require a Bearer token: `Authorization: Bearer tb_xxxxxxxxxxxxx`
API keys are customer-scoped — all data is isolated per customer.
Rate limit: 100 requests/minute per API key.

## Quick Start

```bash
curl -X POST https://api.textbubbles.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155551234", "content": {"text": "Hello!"}}'
```

## Documentation Map

- [Getting Started](https://docs.textbubbles.com/getting-started): Quick start guide with code examples
- [Authentication](https://docs.textbubbles.com/authentication): API keys, rate limiting, error responses
- [Send Messages](https://docs.textbubbles.com/messages/send): POST /v1/messages — text, attachments, carousels, effects, replies, routing
- [List Messages](https://docs.textbubbles.com/messages/list): GET /v1/messages — retrieve and check status
- [Scheduled Messages](https://docs.textbubbles.com/messages/scheduled): Schedule messages up to 30 days ahead
- [Tapback Reactions](https://docs.textbubbles.com/messages/reactions): POST /v1/messages/:id/reactions
- [Message Effects](https://docs.textbubbles.com/messages/effects): iMessage effects (confetti, fireworks, etc.)
- [Webhook Setup](https://docs.textbubbles.com/webhooks/setup): Configure webhook URL, signature verification
- [Webhook Events](https://docs.textbubbles.com/webhooks/events): All event types and payload schemas
- [Realtime Events (SSE)](https://docs.textbubbles.com/webhooks/events#realtime-sse): GET /v1/events — live event stream without hosting a webhook endpoint
- [SDK Installation](https://docs.textbubbles.com/sdk/installation): npm install @textbubbles/js
- [TypeScript SDK](https://docs.textbubbles.com/sdk/typescript): SDK usage guide
- [Next.js Integration](https://docs.textbubbles.com/sdk/nextjs): Next.js integration guide
- [CLI Reference](https://docs.textbubbles.com/sdk/cli): CLI tool reference
- [API Reference](https://docs.textbubbles.com/api-reference): Complete endpoint listing and error codes

## Endpoint Summary

### Messages
- POST /v1/messages — Send a message (text, attachments, carousels, effects, scheduled)
- GET /v1/messages — List messages
- GET /v1/messages/:id — Get message status
- POST /v1/messages/:id/unsend — Unsend (iMessage only)
- POST /v1/messages/:id/retry — Retry a failed message (new provider ID, same TextBubbles ID)
- PUT /v1/messages/:id — Edit a message (iMessage only)
- POST /v1/messages/:id/reactions — Send tapback reaction
- DELETE /v1/messages/:id — Soft-delete
- GET /v1/messages/scheduled — List scheduled messages
- DELETE /v1/messages/:id/schedule — Cancel scheduled message

### Capabilities
- GET /v1/capabilities/:phone — Check iMessage/SMS/FaceTime support

### Numbers
- GET /v1/numbers — List available sender addresses

### Webhooks
- POST /v1/webhooks — Register a webhook (url, events, optional secret/name)
- GET /v1/webhooks/list — List all registered webhooks
- GET /v1/webhooks/{id} — Get a single webhook
- PATCH /v1/webhooks/{id} — Update url/events/secret/name or pause (active=false)
- DELETE /v1/webhooks/{id} — Remove a webhook
- POST /v1/webhooks/{id}/test — Deliver a synthetic webhook.test event to one webhook
- POST /v1/webhooks/{id}/rotate-secret — Rotate the signing secret for one webhook
- GET /v1/webhooks, PUT /v1/webhooks, DELETE /v1/webhooks, POST /v1/webhooks/test, POST /v1/webhooks/rotate-secret — deprecated single-webhook variants

### Realtime Events
- GET /v1/events — Server-Sent Events stream of realtime events (same payloads as webhooks)

### System
- GET /health — Health check (no auth required)