Skip to main content
PingBack’s real-time layer is built on Socket.IO with a Redis backplane. All live features — new messages, typing indicators, delivery receipts, and agent status — flow through this connection.
Socket.IO supports both WebSocket and long-polling transports. PingBack uses WebSocket by default and falls back to polling automatically when WebSocket is unavailable.

Connect

Connect to https://api.pingback.live and pass your business_id in the auth handshake object. PingBack rejects connections that do not include a business_id.

Room system

PingBack uses rooms to scope events to the right audience. Join a room to start receiving its events. To join a conversation room, emit join_conversation:

Events to listen for (server → client)

These events are emitted by the server. Listen for them in your client.

new_message

Fires when any participant in the conversation sends a message. Payload:

typing

Fires when a participant starts or stops typing. Payload: { conversation_id, user_id, is_typing }

delivered

Fires when a message is marked as delivered. Payload: { message_id, delivered_at }

read

Fires when a message is marked as read. Payload: { message_id, read_at }

agent_status_changed

Fires when an agent’s online status changes. Payload: { agent_id, status }

conversation_assigned

Fires when a conversation is assigned to an agent. Payload: { conversation_id, assigned_by }

Events to emit (client → server)

These events are sent from your client to PingBack.

join_conversation

Join a conversation room to receive its events. Payload: { conversation_id: number }

client_message

Send a message from the customer widget. PingBack creates a new conversation automatically if conversation_id is omitted. Payload:

typing

Broadcast a typing indicator to all participants in the conversation. Payload: { conversation_id: number, user_id: number, is_typing: boolean }

Complete integration example

The example below shows how to connect, join a conversation, send messages, and handle incoming events in a customer-facing widget.