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

# WebSocket API

> Connect to Zeplo's real-time WebSocket API for live messaging, typing indicators, agent status updates, and message tracking.

# WebSocket API

The Zeplo WebSocket API provides real-time, bi-directional communication between your application and the Zeplo platform. Built on [Socket.IO](https://socket.io/), it delivers instant updates without polling.

## Overview

Use the WebSocket API to build live dashboards, in-app messaging interfaces, and real-time notification systems. Every event from the WhatsApp Business API is pushed to connected clients in real time.

> [!NOTE]
>
> The WebSocket API is Socket.IO compatible. You can use any Socket.IO client library to connect. The REST API and WebSocket API can be used together — the REST API for write operations and WebSockets for receiving real-time updates.

## Connection

Connect to the WebSocket endpoint with your authentication token:

```
wss://zeplo.ai?token=your_api_key_here
```

> [!WARNING]
>
> Always connect over `wss://` (TLS). Plain `ws://` connections are rejected by the server.

### Basic Connection

```javascript theme={null}
import { io } from "socket.io-client";

const socket = io("wss://zeplo.ai", {
  auth: {
    token: "your_api_key_here",
  },
  transports: ["websocket"],
});

socket.on("connect", () => {
  console.log("Connected to Zeplo WebSocket:", socket.id);
});

socket.on("disconnect", (reason) => {
  console.log("Disconnected:", reason);
});

socket.on("connect_error", (error) => {
  console.error("Connection failed:", error.message);
});
```

## Capabilities

> **Live Messaging**
>
> Receive incoming WhatsApp messages and send replies in real time. Messages are delivered instantly with full metadata including attachments, location, and contact cards.

> **Typing Indicators**
>
> Show when agents or customers are typing. Subscribe to typing events to build responsive chat interfaces that mirror the WhatsApp experience.

> **Agent Status**
>
> Track agent availability and assignment changes in real time. Know immediately when an agent joins, leaves, or is reassigned to a conversation.

> **Message Tracking**
>
> Monitor message delivery and read receipts as they happen. Track the full lifecycle of every message from sent to delivered to read.

## Why WebSockets?

> **Real-time updates**
>
> Unlike REST polling, WebSockets push updates the instant they occur. There is no delay between an event happening on the platform and your application receiving it. This is critical for live chat and support dashboards.

> **Bi-directional communication**
>
> WebSockets allow your application to both receive events and send commands over a single persistent connection. You can join conversations, send messages, and update status without making separate HTTP requests.

> **Efficient resource usage**
>
> A single WebSocket connection replaces hundreds of polling requests. This reduces bandwidth, server load, and latency. The connection stays alive with minimal overhead through Socket.IO's heartbeat mechanism.

> **Reliable delivery**
>
> Socket.IO provides automatic reconnection, event buffering, and fallback transports. If the connection drops, the client automatically reconnects and resubscribes to rooms so you never miss an event.

> **Scales with your application**
>
> The WebSocket API supports thousands of concurrent connections per API key. Rooms and namespaces let you subscribe only to the conversations and events you care about, keeping each connection lightweight.

## Next Steps

> **Events Reference**
>
> Explore all client-to-server and server-to-client events.

> **Authentication**
>
> Learn how to authenticate WebSocket connections securely.

> **REST API**
>
> Use the REST API alongside WebSockets for full platform access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.