@@ -225,11 +225,6 @@ out be acknowledged by the client, and will eventually close the channel if
225225enough unacknowledged events accumulate. The `Urbit` object handles event
226226acknowledgement automatically, so you don't need to worry about this.
227227
228−Since the `Urbit` object handles channels internally, you don't typically need
229−to deal with them at all. There is, however, the [`delete()`](#delete-channel)
230−function if you want to close the whole channel and end all subscriptions at
231−once.
232−
233228Eyre automatically creates a channel when a poke or subscription request is
234229first sent to `/~/channel/[a new channel ID]`. If your web app is served
235230external to the ship and you use the `authenticate` function [described
@@ -238,6 +233,41 @@ the channel. If your web app is served directly from the ship and you use
238233`Urbit` class constructor, it won't open the channel right away. Instead, the
239234channel will be opened whenever you first send a poke or subscription request.
240235
236+### Connection state
237+
238+`Urbit` class includes three optional callbacks that fire when the SSE
239+connection state changes:
240+
241+| Callback | Description |
242+| `Urbit.onOpen` | Called when an SSE channel connection is successfully established. |
243+| `Urbit.onRetry` | This is called whenever a reconnection attempt is made due to an interruption, for example if there are network problems. |
244+| `Urbit.onError` | This is called when there is an unrecoverable error, for example after enough reconnection attemps have failed. |
245+
246+As mentioned in the previous section, typically a channel will be opened and an
247+SSE connection established after you first poke the ship or make a subscription
248+request. If successful, whatever function you provided to `onOpen` will be
249+called. If at some point the connection is interrupted, a reconnection attempt will be made three times:
250+
251+1. Instantly.
252+2. 750ms after the first.
253+3. 3000ms after the second.
254+
255+Each attempt will call the function you provided to `onRetry`, if any. If all
256+three reconnection attempts failed, or if a fatal error occurred, the function
257+you provided `onError` will be called with an `Error` object containing an error
258+message as its argument.
259+
260+How you use these (if you do at all) is up to you and depends on the nature of
261+your app. If you want to try reconnecting when `onError` fires, note that Eyre
262+will delete a channel if it's had no messages from the client in the last 12
263+hours. The timeout is reset whenever it receives a message, including the acks
264+that are automatically sent by the `Urbit` object in response to subscription
265+updates.
266+
267+If you don't want to account for the possibility of the channel having been
268+deleted in your app's logic, you can also just call the [`reset()`](#reset)
269+function before you try reconnecting and consequently open a brand new channel.
270+
241271### Authentication
242272
243273**If your front-end is served directly from the Urbit ship, this step can be