Socket.IO

Connect to a Socket.IO server, emit named events and see the events the server sends.

What Socket.IO is

Socket.IO is a library for real-time apps. It usually runs over a WebSocket, but it adds its own layer on top: messages are events with a name and one or more arguments, a server can be split into namespaces, and the sender can ask for an acknowledgement (a reply to one specific event).

Because of that extra layer, a plain WebSocket client cannot talk to a Socket.IO server. Use a Socket.IO tab for Socket.IO servers and a WebSocket tab for everything else.

Good to know

ApiWorkbench speaks Socket.IO protocol 4, used by servers on version 3 and 4. Version 2 servers are not supported.

Make your first connection

You need a Socket.IO server. If you do not have one, this small Node.js server answers every chat message event. Save it as server.js, run npm install socket.io, then node server.js.

const { Server } = require('socket.io');
const io = new Server(3000);

io.on('connection', (socket) => {
  socket.emit('welcome', { id: socket.id });
  socket.on('chat message', (data, reply) => {
    io.emit('chat message', data);
    if (reply) reply({ ok: true });
  });
});

1. In the tab bar, select the small arrow next to + and choose Socket.IO.

   A tab named New Socket.IO opens with http://localhost:3000 in the URL field.

2. Leave the URL as it is, or type your server's address.

3. Select Connect, or press Enter in the URL field.

   The status changes to Connected. The log shows the socket id the server gave this connection, and the welcome event.

4. On the Emit tab, type chat message in Event name.

5. In Argument 1, type {"text": "hello"}.

6. Turn on Ask for an acknowledgement.

7. Select Emit.

   The log lists the event you emitted, the server's acknowledgement with the time it took, and the chat message event the server sent to everyone.

The server address and namespaces

Type the server address with http://, https://, ws:// or wss://. A path after the host is the namespace, not the handshake path. https://chat.example.com/admin connects to the /admin namespace of chat.example.com.

Emit events

Field	What it does
Event name	The name of the event to emit. Names such as connect and disconnect are reserved.
Arguments	The values sent with the event, in order. Add argument adds another one.
JSON / Text	Select the tag on an argument to switch. JSON arguments are parsed, so text needs double quotes. Text arguments are sent as plain strings. Empty JSON rows send nothing.
Ask for an acknowledgement	Emits with a callback. The server's reply appears in the log next to the event. A note is added if nothing arrives in time.

Variables such as {{userId}} are filled in when you emit.

Listen for events

The Listen tab chooses which incoming events appear in the log.

• Catch-all is on by default: every event the server sends is logged, whatever its name.
• Turn Catch-all off to log only the events listed under Events to log. Select Add listener, type the event name, and switch each one on or off. Names must match exactly, including case.

You can change listeners while connected.

Handshake settings

Setting	What it does	Default
Handshake path	Where the server listens for Socket.IO connections. Change it only if the server was set up with another path.	/socket.io
Transports	WebSocket, Long polling or Polling, then upgrade. The client in ApiWorkbench speaks WebSocket only, so it always connects over WebSocket and says so in the log.	WebSocket
Auth payload (JSON)	A JSON object sent with the connection request. The server reads it as socket.handshake.auth. Leave it empty to send none.	Empty
Reconnect automatically	Retries up to 10 times, with waits growing from 1 second to 5 seconds. Disconnect stops it.	Off
Acknowledgement timeout (s)	How long to wait for an acknowledgement before a note is added to the log.	10

Params are added to the handshake URL as its query string. Headers are sent with the handshake, for example a token or a cookie.

WARNING

A server that allows only long polling cannot be reached, because the client connects over WebSocket whatever Transports says.

The message log

The lower pane works like the one on a WebSocket tab: search, filter by direction, copy and clear. See Read the message log.

Next steps

• WebSocket
• MQTT
• Variables