Skip to main content
GET
GET /v1/sms/stream
Opens a long-lived Server-Sent Events (SSE) connection that pushes inbound SMS messages to your client in real time. Messages are scoped to the phone numbers owned by the authenticated API key.

Authentication

Requires a Bearer API key with the sms:read scope.

Events

connected

Sent immediately after the connection is established.

sms_received

Sent when an inbound SMS arrives on one of your active phone numbers.

Heartbeat

A comment-only heartbeat is sent every 30 seconds to keep the connection alive:

Connection behavior

  • Max duration: 300 seconds (5 minutes). Reconnect after the connection closes.
  • Reconnect: Re-open the stream (with a short backoff) after it closes. Do not use native EventSource — it cannot send an Authorization header, and you must never put your API key in the URL (it leaks into logs and history). Use fetch with a streamed body reader instead.
  • Scope filtering: Events are filtered to the user or team associated with the API key.

Example