keii.dev
1# Using Chat
2
3TODO: better title
4
5Chat consists of HTTP-based and websocket-based APIs.
6
7The Chat websocket API allows receiving updates in real-time; this requires a connection to the [Notification Websocket](#websocket).
8Sending messages is still performed through the HTTP-based API.
9
10<aside class="notice">
11 Websocket messages may arrive before or after the related HTTP web request completes.
12 It is up to the client to handle this.
13</aside>
14
15To begin receiving chat messages, clients should send the [chat.start](#chatstart) event across the socket connection.
16To stop receiving chat messages, send [chat.end](#chatend).
17
18## Public channels and activity timeout
19
20To continue receiving chat messages in [PUBLIC](#channeltype) channels,
21clients must peridiocally request the [Chat Keepalive](#chat-keepalive) endpoint to remain active;
2230 seconds is a reasonable interval.
23When a client is no longer considered active, the server will stop sending messages in public channels to the client.
24
25Private messages are not affected by this activity timeout.
26
27## Getting the user's channel list
28
29TODO: update default parameter
30
31To get the list of channels the user is in, make a request to [Get Updates](#get-updates) with the `presence` as part of the `includes` parameter.
32e.g. `GET` `/chat/updates?includes[]=presence`
33
34## Creating a channel
35
36Make a request to the [Create Channel](#create-channel) endpoint.
37
38Only `PM` and `ANNOUNCE` type channels may be created. Creating a channel will automatically join it.
39Re-creating a `PM` channel will simply rejoin the existing channel.
40
41## Joining a channel
42
43Make a request to the [Join Channel](#join-channel) endpoint where `channel` is the `channel_id`.
44
45A [chat.channel.join](#chatchanneljoin) event is sent over the websocket when the user joins a channel.
46
47## Leaving a channel
48
49Make a request to the [Leave Channel](#leave-channel) endpoint.
50
51Leaving a channel will remove it from the User's channel list.
52
53A [chat.channel.part](#chatchannelpart) event is sent over the websocket when the user leaves a channel.
54
55## Sending messages
56
57Channels should be [joined](#joining-a-channel) or [created](#creating-a-channel) before messages are sent to them.
58To send a message to a channel, make a request to the [Send Message to Channel](#send-message-to-channel) endpoint.
59
60A [chat.message.new](#chatmessagenew) event is sent over the websocket when the user receives a message.
61
62## Getting info about a channel
63
64Make a request to the [Get Channel](#get-channel) endpoint.
65
66## Getting channel message history
67
68Make a request to the [Get Channel Messages](#get-channel-messages) endpoint.