6title: Messaging (Talk and Hall)
9# Messaging (Talk and Hall)
15Talk is the built-in frontend for the Urbit messaging and notifications
16protocol, Hall. Today we use Hall to chat and coordinate, but it's really
17a general purpose piece of infrastructure.
19For the time being come join us in `/urbit-meta` by using the
20<a href="#-quickstart">quickstart</a> below.
22Today, Hall is sort of like a distributed, encrypted Slack that can be
23used from the CLI and the browser. There’s no central Hall server.
24Any Urbit can host one.
26Hall is a general purpose tool for both aggregating and publishing
27streams of messages. Applications can use Hall as their transport
28protcol, API connectors can push disparate data sources into Hall,
29and so on. There are lots of things a distributed message protocol can
30be used for that we haven't even thought of.
32Here we'll be discussing how to operate the default CLI frontend, Talk,
33to send and receive messages. For a more in-depth look at Hall's internals,
34take a look at its [documentation](../../hall/architecture).
42For the most part we use Talk as a single-instance of Slack: one main
43channel (`/urbit-meta`) and direct messages. Everyone is more than welcome
44in `/urbit-meta`. It's the place to get help, ask questions and chat about
47Let's join `/urbit-meta`:
49Use `ctrl-x` to switch from Dojo to Talk.
53 ~your-urbit:talk> ;join /urbit-meta
55You'll see something like:
57 --------------| ;join /urbit-meta
58 --------------| :: onn /urbit-meta
59 --------------| bound '=' {[hos=~binzod nom=%urbit-meta]}
60 --------------| new = /urbit-meta
61 --------------| /urbit-meta: cap: For Urbit-related discussion. Politically
62 | correct and safe for work. Don't be rude!
63 --------------| /urbit-meta: fit: caps:n unic:n
66Post a line to `/urbit-meta`:
68 ~your-urbit:talk= Hello, world!
70You'll see, echoed back at you:
72 ~your-urbit= Hello, world!
74To send a direct message to someone, first set your audience:
76 ~your-urbit:talk= ;~talsur-todres
78You'll see your prompt change:
80 ~your-urbit:talk[~talsur-todres]
82Now you and `~talsur-todres` can exchange messages directly.
84 ~your-urbit:talk[~talsur-todres] Hey buddy!
86To set your audience back to `/urbit-meta`:
88 ~your-urbit:talk[~talsur-todres] ;/urbit-meta
90You'll see your prompt change back:
94You can also use the ASCII "glyph" assigned to your `/urbit-meta` circle as a shortcut:
96 ~your-urbit:talk[~talsur-todres] ;=
99(Your ship may have a different glyph than `=` for your circle)
101Use `;leave` to unsubscribe from a channel:
103 ~your-urbit:talk= ;leave /urbit-meta
105There are two ways of using Talk: from the CLI or through a web UI
106available at `http://your-urbit.urbit.org/~~/talk` (or
107`http://localhost:8080/~~/talk`).
109The web UI ships as compiled JavaScript on your Urbit, but has its own
110source repo [here](https://github.com/urbit/talk).
112Last, let's create a channel we can invite some friends to:
114 ~your-urbit:talk= ;create channel %my-channel 'Some description.'
116Now you can tell your friends to `;join ~your-urbit/my-channel`.
120Hall's design is similar in spirit to
121[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
122the underlying protocol for Usenet.
124Our design is pretty simple: Hall messages are called _posts_. Posts
125go to _circles_. Any urbit can host or subscribe to any number of circles.
127There are four kinds of circles: a write-only `%mailbox` for direct
128messages, an invite-only `%village` for private conversation, a read-only
129`%journal` for curated content, and a public-access `%channel` for
134A post can be a variety of different data structures. Let's look at the
135ones you can use from within Talk: lines, URLs, Hoon and
140A line is simply a string of text. Depending on the filtering rules set
141by the circle's host, these may or may not include uppercase and Unicode
144If the line starts with `@`, it's an action (IRC `/me`).
146 ~your-urbit:talk= @sends a message.
150 ~your-urbit sends a message.
154A URL is any valid URL.
156 ~your-urbit:talk= https://example.com/
160You can use Talk to evaluate Hoon code and share the result with everyone in a
161Hall circle. To do so, preface your Hoon with `#`.
163 ~your-urbit:talk= #(add 2 2)
167 ~your-urbit# (add 2 2)
172To indicate what you're saying is in direct response to a specific
173message, select the message (see Activating Lines below) and type your
176 ~some-urbit= Hello! How are you?
177 ~your-urbit:talk= ; Good, thanks!
181 ~your-urbit=^ Good, thanks!
185A line number identifying the *subsequent* line is displayed every 5
189 ~your-urbit= This is my message.
190 ~your-urbit= This is another message.
191 ~your-urbit sends a message.
192 ~your-urbit/ http://example.com/
193 ~your-urbit# (add 2 2)
196 ~your-urbit=^ That's my message!
198You can use a line number to *activate* a line:
202which prints the number, line identifier, timestamp, sender, audience,
206 0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
207 ~your-urbit to ~another-urbit
208 in reply to: ~your-urbit:
209 > This is my message.
212If information got truncated — like happens for long URLs or expressions —
213or if there's additional information available — as is the case with
214replies and attachments — activating the message will show you all the
217You can activate the most recent line with `;`, the second-most recent
220### Creating and managing circles
222###### `;create [type] %name 'description'`
223Creates and joins a circle, where `[type]` is any of the following:
224- `channel`: public circle. Has a blacklist for write control.
225- `village`: invite-only circle.
226- `journal`: publicly readable, invite-only for writing.
227- `mailbox`: publicly writeable, can only be read by its host.
229###### `;delete %name 'optional reason'`
230Deletes a circle. If a reason is specified, that gets sent to all
231subscribers before the circle gets deleted.
233###### `;depict %name 'description'`
234Changes the description of circle `%name`.
236###### `;filter %name [capitals] [unicode]`
237Configures the message filter for circle `%name`: whether to allow
238capital and/or unicode characters. `y`/`&`/`true` for allowed,
239`n`/`|`/`false` for disallowed.
241###### `;invite %name ~someone`
242Invite someone into your circle `%name`. If they were previously banished,
243removes them from the blacklist.
244Can also invite multiple ships at once, `~comma, ~separated`.
246###### `;banish %name ~someone`
247Banish someone from your circle `%name`. If they were previously invited,
248removes them from the whitelist.
249Can also banish multiple ships at once, `~comma, ~separated`.
251###### `;source %name ~other/circle`
252Adds `~other/circle` as a source for circle `%name`. This causes all
253messages sent to `~other/circle` to also appear in `%name`.
255###### `;unsource %name ~other/circle`
256Removes `~other/circle` as a source for circle `%name`.
260If you have joined a circle, you can make this information publicly
261available to help others find that circle as well.
263###### `;show ~some/circle`
264Adds a circle to your public membership list.
266###### `;hide ~some/circle`
267Removes a circle from your public membership list.
271You'll see status notifications when people enter or leave stations
274Turn off status (and config) notifications.
277Turn on status (and config) notifications.
280List everyone in all your subscribed circles. Optionally specify a
281specific circle to list members of just those.
283You'll see presence notifications when people enter or leave stations
286###### `;attend ~some/circle [presence]`
287Manually set your presence to show up as one of the following. (In the
288future, a sufficiently advanced client can automatically set these for
294- `gone` - not present
296###### `;name ~some/circle 'my handle'`
297Set a handle ("name") for yourself in a specific circle. It will display
298to users who have done `;set nicks`, but gets truncated if it's longer
303An audience consists of one or more messaging targets. These can be
304circles or ships. (In the latter case, it's secretly the `~ship/inbox`
308Glyphs are assigned by circle hash out of the following list
310 > = + - } ) , . " ' ^ $ % & @
312Alphanumeric characters and `|#;:*~_` are reserved; all others (the
313above list, and `\/!?({<`) can be manually assigned.
315###### `;bind + /urbit-test`
316Assigns the `+` glyph to `/urbit-test`.
318###### `;unbind + /urbit-test`
319Unassigns the `+` glyph from `/urbit-test`.
321To see what circle is bound to a glyph:
328Received posts are prefixed with a glyph to let you know what the
329audience is. You can activate an individual post to see the full
332There are a few special-purpose glyphs:
334- `|` - Informational messages
335- `:` - Posts directly to you
336- `;` - Posts to you and others (a multiparty conversation)
337- `*` - Posts to a complex audience that doesn't directly include you.
341The audience you're sending to is always shown in your prompt. If
342there's a glyph for it, it's shown as the glyph.
344Here we're talking to the station bound to `=`:
348Here we're talking directly to `~dannum-mitryl`:
350 ~your-urbit:talk[~dannum-mitryl]
354###### `;~urbit/circle`
355Set audience to `~urbit/circle`.
358Set audience to the station bound to the `=` glyph
360###### `;~dannum-mitryl`
361Set audience to `~dannum-mitryl` (a direct post).
364Set audience to a circle on your own ship
366###### `;~dannum-mitryl this is a private message`
367Set the audience and send a post in the same line. This works for all of the above.
369Your audience is configured with regard to the following rules (in order):
371- if you manually set the audience, that audience.
372- if you activated a post, the post you activated.
373- audience of the last post sent.
378List all local nicknames.
380###### `;nick ~some-urbit`
386###### `;nick ~some-urbit plato`
389###### `;nick ~some-urbit ~`
390Clear an assigned nickname.
393Show nicknames instead of urbit names. If no local nickname is set, uses
394that user's handle. If the user has no handle, just the urbit name.
397Show urbit names instead of nicknames.
399Nicknames and handles longer than 14 character will be truncated in
400output. Nicknames are strictly local - like the names on entries in a
403### Miscellaneous configuration
405###### `;set showtime`
406Show the timestamp for each message.
408###### `;unset showtime`
409Stop showing the timestamp for each message.
411###### `;set timezone [+/-][hours]`
412Adjust the display of the timestamps to a specific timezone. Relative to UTC.
415Emit a terminal bell sound if your six-syllable ship name is mentioned in
418###### `;unset notify`
419Do not notify when your ship name is mentioned.
421###### `;set width [number]`
422Set the rendering width of `:talk` to a specific number of characters.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list