> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumisreach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/sms/stream

> Subscribe to real-time inbound SMS events via Server-Sent Events (SSE).

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.

```bash theme={null}
curl -N "https://api.lumisreach.com/api/v1/sms/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Events

### `connected`

Sent immediately after the connection is established.

```
event: connected
data: {"clientId":"sms-42-1716000000000-abc1234","timestamp":1716000000000}
```

### `sms_received`

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

```
event: sms_received
data: {"message_id":"msg_abc123","from":"+14155551234","to":"+14155559999","body":"Hello!","received_at":"2026-05-22T18:30:00.000Z"}
```

| Field         | Type   | Description                                                |
| ------------- | ------ | ---------------------------------------------------------- |
| `message_id`  | string | Unique identifier for the message                          |
| `from`        | string | Sender phone number (E.164)                                |
| `to`          | string | Your Telnyx phone number that received the message (E.164) |
| `body`        | string | Message text content                                       |
| `received_at` | string | ISO 8601 timestamp of when the message was received        |

### Heartbeat

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

```
: heartbeat
```

## Connection behavior

* **Max duration:** 300 seconds (5 minutes). Reconnect after the connection closes.
* **Auto-reconnect:** Use `EventSource` in the browser for automatic reconnection with exponential backoff.
* **Scope filtering:** Events are filtered to the user or team associated with the API key.

## Example

<CodeGroup>
  ```javascript Browser (EventSource) theme={null}
  const es = new EventSource("/api/v1/sms/stream", {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  });

  es.addEventListener("connected", (e) => {
    console.log("Connected:", JSON.parse(e.data));
  });

  es.addEventListener("sms_received", (e) => {
    const msg = JSON.parse(e.data);
    console.log(`New SMS from ${msg.from}: ${msg.body}`);
  });

  es.onerror = () => {
    console.log("Connection lost, reconnecting...");
  };
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.lumisreach.com/api/v1/sms/stream"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}

  with requests.get(url, headers=headers, stream=True) as r:
      for line in r.iter_lines(decode_unicode=True):
          if line.startswith("data: "):
              data = json.loads(line[6:])
              print(f"Received: {data}")
  ```
</CodeGroup>