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

# Mobile Integration

> Integrate VIZOCHOK into React Native, Flutter, and native mobile apps via direct WebSocket connection.

Mobile apps integrate with VIZOCHOK via the WebSocket API directly. The JS SDK widget is designed for web browsers; mobile platforms should build their own chat UI on top of the WebSocket protocol.

## What You Need to Build

To integrate VIZOCHOK into a mobile app, you need to implement:

<CardGroup cols={2}>
  <Card title="WebSocket Client" icon="plug">
    Connect to `wss://api.vizochok.com/api/v1/ws/chat`, handle authentication, send/receive JSON messages, manage reconnection.
  </Card>

  <Card title="Chat UI" icon="message">
    Text input, message bubbles, streaming text display (token-by-token), typing indicators.
  </Card>

  <Card title="Product Cards" icon="grid-2">
    Render `product_cards` messages as native product list with images, prices, quantity steppers, and "Add" buttons.
  </Card>

  <Card title="Cart Sync" icon="cart-shopping">
    Listen for `cart_changed` events and update your app's cart state. Send `action` messages when user interacts with product cards.
  </Card>
</CardGroup>

## WebSocket Message Types to Handle

Your mobile client needs to handle these server messages:

| Message Type           | Purpose                               | UI Action                        |
| ---------------------- | ------------------------------------- | -------------------------------- |
| `auth_ok`              | Authentication confirmed              | Enable chat input                |
| `conversation_started` | New conversation created              | Save `conversation_id`           |
| `session_restored`     | Reconnected to existing session       | Restore cart state               |
| `text_delta`           | Streaming text chunk                  | Append to current message bubble |
| `text_end`             | Text block complete                   | Stop streaming indicator         |
| `status`               | Progress update (e.g. "Searching...") | Show status indicator            |
| `product_cards`        | Product results                       | Render native product list       |
| `quick_replies`        | Suggestion buttons                    | Show tappable option pills       |
| `cart_changed`         | Cart was modified                     | Update cart badge/state          |
| `ingredient_checklist` | Recipe ingredients                    | Render checkable list            |
| `error`                | Error occurred                        | Show error message               |
| `response_complete`    | Ready for next message                | Enable input                     |

And send these client messages:

| Message Type | When                                                     |
| ------------ | -------------------------------------------------------- |
| `auth`       | First message after connection                           |
| `message`    | User sends text                                          |
| `action`     | User taps product card, quick reply, or checklist submit |
| `ping`       | Every 30 seconds (keepalive)                             |
| `pong`       | In response to server `ping`                             |

For full field specifications, see [WebSocket Protocol](/concepts/websocket-protocol).

## Platform-Specific Considerations

### React Native

* Use a WebSocket library (built-in `WebSocket` API or `react-native-websocket`)
* Handle `AppState` changes: disconnect on background, reconnect on foreground
* Store `conversation_id` in `AsyncStorage` for session persistence
* Use `FlatList` for message rendering with streaming text support

### Flutter

* Use `web_socket_channel` package for WebSocket connection
* Listen to `AppLifecycleState` for background/foreground transitions
* Store `conversation_id` in `shared_preferences`
* Use `StreamBuilder` to render incoming messages reactively

### Native iOS / Android

* iOS: `URLSessionWebSocketTask` (iOS 13+) or Starscream
* Android: OkHttp WebSocket or Java-WebSocket
* Both: handle network reachability changes, reconnect with exponential backoff

## Connection Lifecycle for Mobile

<Steps>
  <Step title="App opens chat screen">
    Connect to WebSocket, send `auth` message with API key and user ID.
  </Step>

  <Step title="User sends a message">
    Send `message` with text and `conversation_id`. Show streaming response as `text_delta` messages arrive.
  </Step>

  <Step title="User interacts with products">
    When user taps "Add" on a product card, send `action` message with `sku` and `quantity`. Listen for `cart_changed` to confirm.
  </Step>

  <Step title="App goes to background">
    Close WebSocket connection gracefully. Save `conversation_id`.
  </Step>

  <Step title="App returns to foreground">
    Reconnect to WebSocket, send `auth` with saved `conversation_id`. Server sends `session_restored` with cart state.
  </Step>
</Steps>

## Reconnection Strategy

Implement exponential backoff with jitter, matching the web SDK behavior:

| Parameter     | Value                          |
| ------------- | ------------------------------ |
| Initial delay | 1,000 ms                       |
| Max delay     | 10,000 ms                      |
| Formula       | `min(1000 * 2^attempt, 10000)` |
| Jitter        | +/- 25%                        |
| Max attempts  | 30                             |

Do not reconnect on auth errors (close codes `4001`, `4002`, `4003`, `4004`).

## Code Examples

For working Python and Node.js WebSocket connection examples, see [WebSocket Direct Integration](/guides/websocket-direct). The same protocol applies to mobile clients in any language.