Skip to content
Project BlueDocs
Popular pages
Guides / Getting startedQuickstartGet an API key, send your first message, and confirm delivery.API reference / MessagesPOSTSend a messageSend iMessage or SMS, with media, voice memos, and message effects./send-api-messageGuides / IntegrationsWebhooksReceive message and call events at your own endpoint.Guides / Getting startedAuthenticationCreate an API key and authenticate requests with a bearer token.AI tools / AI toolsMCP server & skillConnect Claude, Codex, Cursor, and other AI tools to Project Blue.
↑ ↓ Navigate↵ Openesc Close
Dashboard
For AI agents
View as Markdown

Typing indicators

Show the iMessage typing indicator (the three dots) to a recipient. Authenticate with a Bearer API key, same as every other endpoint.

POST/send-typing-indicatorBearer token
iMessage only, existing conversation required
Typing indicators are iMessage-only — SMS recipients never see them. The number must already have a conversation on the sending line; there is no indicator without a prior thread.

Request body

phoneNumberstring (E.164)Required
Recipient phone number in E.164 (e.g. +15551234567). Must already have an existing conversation on the sending line.
lineIdstring (UUID v4)
Optional sender line. Use the lineId from GET /get-lines. When omitted, uses the line that owns the existing conversation with this number.

The indicator auto-clears on the recipient's device after a short period or when a message arrives. The intended pattern is send-typing-indicator → wait about 2–4 seconds → send-api-message.

Response

On success the endpoint returns HTTP 200 with { status: "SENT" | "ERROR", number, error_message } — error_message is null when status is SENT. Auth and request-validation failures still use standard 4xx bodies with an error field. Treat device-level failures (status: "ERROR") as fire-and-forget — do not retry.

API reference