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 ~samzod/urbit-meta
55You'll see something like:
57 --------------| ;join ~samzod/urbit-meta
58 --------------| :: onn ~samzod/urbit-meta
59 --------------| bound '=' {[hos=~samzod nom=%urbit-meta]}
60 --------------| new = ~samzod/urbit-meta
61 --------------| ~samzod/urbit-meta: hey ~samzod hear
64Post a line to `/urbit-meta`:
66 ~your-urbit:talk- Hello, world!
68You'll see, echoed back at you:
70 ~your-urbit- Hello, world!
72To send a direct message to someone, first set your audience:
74 ~your-urbit:talk- ;~talsur-todres
76You'll see your prompt change:
78 ~your-urbit:talk[~talsur-todres]
80Now you and `~talsur-todres` can exchange messages directly.
82 ~your-urbit:talk[~talsur-todres] Hey buddy!
84To set your audience back to `/urbit-meta`:
86 ~your-urbit:talk[~talsur-todres] ;~samzod/urbit-meta
88You'll see your prompt change back:
92You can also use the ASCII "glyph" assigned to your `/urbit-meta` circle as a shortcut:
94 ~your-urbit:talk[~talsur-todres] ;-
97(Your ship may have a different glyph than `-` for your circle)
99Use `;leave` to unsubscribe from a channel:
101 ~your-urbit:talk- ;leave ~samzod/urbit-meta
103There are two ways of using Talk: from the CLI or through a web UI
104available at `http://your-urbit.urbit.org/~~/talk` (or
105`http://localhost:8080/~~/talk`).
107The web UI ships as compiled JavaScript on your Urbit, but has its own
108source repo [here](https://github.com/urbit/talk).
110Last, let's create a channel we can invite some friends to:
112 ~your-urbit:talk> ;create channel %my-channel 'Some description.'
114Now you can tell your friends to `;join ~your-urbit/my-channel`.
118Hall's design is similar in spirit to
119[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
120the underlying protocol for Usenet.
122Our design is pretty simple: Hall messages are called _posts_. Posts
123go to _circles_. Any urbit can host or subscribe to any number of circles.
125There are four kinds of circles: a write-only `%mailbox` for direct
126messages, an invite-only `%village` for private conversation, a read-only
127`%journal` for curated content, and a public-access `%channel` for
132A post can be a variety of different data structures. Let's look at the
133ones you can use from within Talk: lines, URLs, Hoon and
138A line is simply a string of text. Depending on the filtering rules set
139by the circle's host, these may or may not include uppercase and Unicode
142If the line starts with `@`, it's an action (IRC `/me`).
144 ~your-urbit:talk> @sends a message.
148 ~your-urbit sends a message.
152A URL is any valid URL.
154 ~your-urbit:talk> https://example.com/
158You can use Talk to evaluate Hoon code and share the result with everyone in a
159Hall circle. To do so, preface your Hoon with `#`.
161 ~your-urbit:talk- #(add 2 2)
165 ~your-urbit# (add 2 2)
170To indicate what you're saying is in direct response to a specific
171message, select the message (see Activating Lines below) and type your
174 ~some-urbit- Hello! How are you?
175 ~your-urbit:talk> ; Good, thanks!
179 ~your-urbit>^ Good, thanks!
183A line number identifying the *subsequent* line is displayed every 5
187 ~your-urbit- This is my message.
188 ~your-urbit- This is another message.
189 ~your-urbit sends a message.
190 ~your-urbit/ http://example.com/
191 ~your-urbit# (add 2 2)
194 ~your-urbit>^ That's my message!
196You can use a line number to *activate* a line:
200which prints the number, line identifier, timestamp, sender, audience,
204 0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
205 ~your-urbit to ~another-urbit
206 in reply to: ~your-urbit:
207 > This is my message.
210If information got truncated — like happens for long URLs or expressions —
211or if there's additional information available — as is the case with
212replies and attachments — activating the message will show you all the
215You can activate the most recent line with `;`, the second-most recent
218### Creating and managing circles
220###### `;create [type] %name 'description'`
221Creates and joins a circle, where `[type]` is any of the following:
222- `channel`: public circle. Has a blacklist for write control.
223- `village`: invite-only circle.
224- `journal`: publicly readable, invite-only for writing.
225- `mailbox`: publicly writeable, can only be read by its host.
227###### `;delete %name 'optional reason'`
228Deletes a circle. If a reason is specified, that gets sent to all
229subscribers before the circle gets deleted.
231###### `;depict %name 'description'`
232Changes the description of circle `%name`.
234###### `;filter %name [capitals] [unicode]`
235Configures the message filter for circle `%name`: whether to allow
236capital and/or unicode characters. `y`/`&`/`true` for allowed,
237`n`/`|`/`false` for disallowed.
239###### `;invite %name ~someone`
240Invite someone into your circle `%name`. If they were previously banished,
241removes them from the blacklist.
242Can also invite multiple ships at once, `~comma, ~separated`.
244###### `;banish %name ~someone`
245Banish someone from your circle `%name`. If they were previously invited,
246removes them from the whitelist.
247Can also banish multiple ships at once, `~comma, ~separated`.
249###### `;source %name ~other/circle`
250Adds `~other/circle` as a source for circle `%name`. This causes all
251messages sent to `~other/circle` to also appear in `%name`.
253###### `;unsource %name ~other/circle`
254Removes `~other/circle` as a source for circle `%name`.
258If you have joined a circle, you can make this information publicly
259available to help others find that circle as well.
261###### `;show ~some/circle`
262Adds a circle to your public membership list.
264###### `;hide ~some/circle`
265Removes a circle from your public membership list.
269You'll see status notifications when people enter or leave stations
272Turn off status (and config) notifications.
275Turn on status (and config) notifications.
278List everyone in all your subscribed circles. Optionally specify a
279specific circle to list members of just those.
281You'll see presence notifications when people enter or leave stations
284###### `;attend ~some/circle [presence]`
285Manually set your presence to show up as one of the following. (In the
286future, a sufficiently advanced client can automatically set these for
292- `gone` - not present
294###### `;name ~some/circle 'my handle'`
295Set a handle ("name") for yourself in a specific circle. It will display
296to users who have done `;set nicks`, but gets truncated if it's longer
301An audience consists of one or more messaging targets. These can be
302circles or ships. (In the latter case, it's secretly the `~ship/inbox`
306Glyphs are assigned by circle hash out of the following list
308 > = + - } ) , . " ' ^ $ % & @
310Alphanumeric characters and `|#;:*~_` are reserved; all others (the
311above list, and `\/!?({<`) can be manually assigned.
313###### `;bind + /urbit-test`
314Assigns the `+` glyph to `/urbit-test`.
316###### `;unbind + /urbit-test`
317Unassigns the `+` glyph from `/urbit-test`.
319To see what circle is bound to a glyph:
326Received posts are prefixed with a glyph to let you know what the
327audience is. You can activate an individual post to see the full
330There are a few special-purpose glyphs:
332- `|` - Informational messages
333- `:` - Posts directly to you
334- `;` - Posts to you and others (a multiparty conversation)
335- `*` - Posts to a complex audience that doesn't directly include you.
339The audience you're sending to is always shown in your prompt. If
340there's a glyph for it, it's shown as the glyph.
342Here we're talking to the station bound to `=`:
346Here we're talking directly to `~dannum-mitryl`:
348 ~your-urbit:talk[~dannum-mitryl]
352###### `;~urbit/circle`
353Set audience to `~urbit/circle`.
356Set audience to the station bound to the `=` glyph
358###### `;~dannum-mitryl`
359Set audience to `~dannum-mitryl` (a direct post).
362Set audience to a circle on your own ship
364###### `;~dannum-mitryl this is a private message`
365Set the audience and send a post in the same line. This works for all of the above.
367Your audience is configured with regard to the following rules (in order):
369- if you manually set the audience, that audience.
370- if you activated a post, the post you activated.
371- audience of the last post sent.
376List all local nicknames.
378###### `;nick ~some-urbit`
384###### `;nick ~some-urbit plato`
387###### `;nick ~some-urbit ~`
388Clear an assigned nickname.
391Show nicknames instead of urbit names. If no local nickname is set, uses
392that user's handle. If the user has no handle, just the urbit name.
395Show urbit names instead of nicknames.
397Nicknames and handles longer than 14 character will be truncated in
398output. Nicknames are strictly local - like the names on entries in a
401### Miscellaneous configuration
403###### `;set showtime`
404Show the timestamp for each message.
406###### `;unset showtime`
407Stop showing the timestamp for each message.
409###### `;set timezone [+/-][hours]`
410Adjust the display of the timestamps to a specific timezone. Relative to UTC.
413Emit a terminal bell sound if your six-syllable ship name is mentioned in
416###### `;unset notify`
417Do not notify when your ship name is mentioned.
419###### `;set width [number]`
420Set 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