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

# Ping & Pong

> Connection health check messages

## Overview

Ping and Pong messages are used to maintain and verify WebSocket connection health between workers and the iii framework. These messages implement a keepalive mechanism to detect disconnections and ensure the connection remains active.

## Ping

### Request

A Ping message is sent to verify that the connection is alive and the peer is responsive.

<ParamField name="type" type="string" required>
  Message type. Must be `"ping"`.
</ParamField>

### Example

```json theme={null}
{
  "type": "ping"
}
```

## Pong

### Response

A Pong message is sent in response to a Ping message to acknowledge the connection is healthy.

<ResponseField name="type" type="string" required>
  Message type. Must be `"pong"`.
</ResponseField>

### Example

```json theme={null}
{
  "type": "pong"
}
```

## Usage Patterns

### Client-Initiated Ping

The worker sends a Ping message and expects a Pong response:

```javascript theme={null}
// Worker sends
{
  "type": "ping"
}

// Framework responds
{
  "type": "pong"
}
```

### Server-Initiated Ping

The framework sends a Ping message and expects a Pong response from the worker:

```javascript theme={null}
// Framework sends
{
  "type": "ping"
}

// Worker responds
{
  "type": "pong"
}
```

### Heartbeat Implementation

Typical implementation with periodic pings:

```javascript theme={null}
// Send ping every 30 seconds
setInterval(() => {
  ws.send(JSON.stringify({ type: "ping" }));
}, 30000);

// Respond to incoming pings
ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.type === 'ping') {
    ws.send(JSON.stringify({ type: "pong" }));
  }
});
```

### Connection Timeout Detection

```javascript theme={null}
let lastPong = Date.now();
const TIMEOUT_MS = 60000; // 60 seconds

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.type === 'pong') {
    lastPong = Date.now();
  }
});

// Check for timeout
setInterval(() => {
  if (Date.now() - lastPong > TIMEOUT_MS) {
    console.error('Connection timeout - no pong received');
    ws.close();
  }
}, 10000);
```

## Error Cases

### No Pong Response

If a Pong is not received within the expected timeout period:

* The connection may be broken or experiencing network issues
* The peer may be unresponsive or overloaded
* Consider closing and reconnecting the WebSocket

### Delayed Pong

If Pong responses are consistently delayed:

* May indicate network latency issues
* The peer may be under heavy load
* Consider adjusting timeout thresholds

## Notes

* Ping/Pong messages have no additional fields beyond the `type`
* These are application-level keepalive messages (distinct from WebSocket protocol-level ping/pong frames)
* Implementations should respond to Ping messages promptly
* Typical ping intervals range from 15-60 seconds
* Timeout thresholds are usually 2-3x the ping interval
* Both client and server can initiate ping requests
* Pong responses should be sent immediately upon receiving a Ping
* Consider implementing exponential backoff for reconnection after timeout

## Best Practices

* **Implement bidirectional pings**: Both worker and framework should support sending and responding to pings
* **Set reasonable intervals**: Don't ping too frequently (wastes bandwidth) or too infrequently (slow to detect failures)
* **Use timeouts**: Always implement timeout detection for missed pongs
* **Log ping/pong timing**: Monitor latency and connection health
* **Handle reconnection**: Automatically reconnect when connection health checks fail
* **Combine with other health checks**: Use alongside application-level health monitoring

## Related Messages

* [WorkerRegistered](/api/messages/worker-registered) - Initial connection establishment