Packages
hackney
4.0.2
4.7.2
4.7.1
4.7.0
4.6.1
4.6.0
4.5.2
4.5.1
4.5.0
4.4.5
4.4.3
4.4.2
4.4.1
4.4.0
4.3.0
4.2.3
4.2.2
4.2.1
4.2.0
4.1.0
4.0.3
4.0.2
4.0.1
4.0.0
3.2.1
3.2.0
3.1.2
3.1.1
3.1.0
3.0.3
3.0.2
3.0.1
3.0.0
retired
2.0.1
2.0.0
2.0.0-beta.1
1.25.0
1.24.1
1.24.0
1.23.0
1.22.0
1.21.0
1.20.1
1.20.0
1.19.1
1.19.0
1.18.2
1.18.1
1.18.0
1.17.4
1.17.3
1.17.2
1.17.1
1.17.0
1.16.0
1.15.2
1.15.1
1.15.0
1.14.3
1.14.2
1.14.0
1.13.0
1.12.1
1.12.0
1.11.0
1.10.1
1.10.0
1.9.0
1.8.6
1.8.5
1.8.4
1.8.3
1.8.2
1.8.0
1.7.1
1.7.0
1.6.6
retired
1.6.5
1.6.4
retired
1.6.3
1.6.2
1.6.1
1.6.0
1.5.7
1.5.6
1.5.5
1.5.4
1.5.3
1.5.2
1.5.1
1.5.0
1.4.10
1.4.8
1.4.7
1.4.6
1.4.5
1.4.4
1.4.3
1.4.2
1.4.1
1.4.0
1.3.2
1.3.1
1.3.0
1.2.0
1.1.0
1.0.6
1.0.5
1.0.2
1.0.1
0.15.2
0.15.0
0.14.3
0.14.2
0.14.1
0.14.0
0.13.1
Simple HTTP client with HTTP/1.1, HTTP/2, and HTTP/3 support
Current section
Files
Jump to
Current section
Files
guides/websocket_guide.md
# WebSocket Guide
hackney provides a WebSocket client with process-per-connection architecture.
## Quick Start
```erlang
{ok, Conn} = hackney:ws_connect(<<"wss://echo.websocket.org">>),
ok = hackney:ws_send(Conn, {text, <<"Hello!">>}),
{ok, {text, <<"Hello!">>}} = hackney:ws_recv(Conn),
hackney:ws_close(Conn).
```
## Connecting
### Simple Connection
```erlang
{ok, Conn} = hackney:ws_connect(<<"wss://example.com/socket">>).
```
### Connection with Options
```erlang
{ok, Conn} = hackney:ws_connect(<<"wss://example.com/socket">>, [
{connect_timeout, 5000},
{recv_timeout, 30000},
{headers, [{<<"authorization">>, <<"Bearer token">>}]},
{protocols, [<<"graphql-ws">>]}
]).
```
### Available Options
| Option | Default | Description |
|--------|---------|-------------|
| `connect_timeout` | 8000 | TCP connection timeout (ms) |
| `recv_timeout` | infinity | Receive timeout (ms) |
| `headers` | `[]` | Extra headers for upgrade |
| `protocols` | `[]` | Sec-WebSocket-Protocol values |
| `active` | `false` | Active mode: false, true, once |
| `ssl_options` | `[]` | SSL options for wss:// |
## Sending Messages
### Text Messages
```erlang
ok = hackney:ws_send(Conn, {text, <<"Hello">>}).
```
### Binary Messages
```erlang
ok = hackney:ws_send(Conn, {binary, <<1, 2, 3>>}).
```
### Ping/Pong
```erlang
ok = hackney:ws_send(Conn, ping).
ok = hackney:ws_send(Conn, {ping, <<"heartbeat">>}).
```
## Receiving Messages
### Passive Mode (Default)
```erlang
{ok, Frame} = hackney:ws_recv(Conn).
{ok, Frame} = hackney:ws_recv(Conn, 5000). %% With timeout
```
### Frame Types
```erlang
case hackney:ws_recv(Conn) of
{ok, {text, Text}} -> handle_text(Text);
{ok, {binary, Data}} -> handle_binary(Data);
{ok, ping} -> ok; %% Auto-responded
{ok, pong} -> ok;
{error, {closed, Code, Reason}} -> handle_close(Code)
end.
```
## Active Mode
### Enable Active Mode
```erlang
{ok, Conn} = hackney:ws_connect(URL, [{active, true}]).
%% Or later:
hackney:ws_setopts(Conn, [{active, true}]).
```
### Receive Messages
```erlang
receive
{hackney_ws, Conn, {text, Text}} -> handle(Text);
{hackney_ws, Conn, closed} -> done;
{hackney_ws_error, Conn, Reason} -> error
end.
```
### Active Once
```erlang
{ok, Conn} = hackney:ws_connect(URL, [{active, once}]),
receive {hackney_ws, Conn, Frame} -> ok end,
hackney:ws_setopts(Conn, [{active, once}]). %% Get next
```
## Closing Connections
```erlang
hackney:ws_close(Conn).
hackney:ws_close(Conn, {1000, <<"Goodbye">>}).
```
### Close Codes
| Code | Meaning |
|------|---------|
| 1000 | Normal closure |
| 1001 | Going away |
| 1002 | Protocol error |
## Example: Chat Client
```erlang
-module(chat).
-export([start/1, send/2]).
start(URL) ->
{ok, Conn} = hackney:ws_connect(URL, [{active, true}]),
spawn(fun() -> loop(Conn) end),
Conn.
send(Conn, Msg) ->
hackney:ws_send(Conn, {text, Msg}).
loop(Conn) ->
receive
{hackney_ws, Conn, {text, Text}} ->
io:format("~s~n", [Text]),
loop(Conn);
{hackney_ws, Conn, closed} ->
ok
end.
```
## Error Handling
```erlang
case hackney:ws_connect(URL) of
{ok, Conn} -> use(Conn);
{error, {http_error, 401}} -> unauthorized;
{error, timeout} -> timeout;
{error, Reason} -> {error, Reason}
end.
```
## Next Steps
- [HTTP Guide](http_guide.md)
- [Getting Started](../GETTING_STARTED.md)