git.iko.soy/urbit.org
on 7fa97bd help sign in
urbit.org/docs/using/messaging.umd
504 lines 12 kB history raw
1:- :~ navhome/'/docs/'
2 navuptwo/'true'
3 next/'true'
4 sort/'5'
5 title/'Messaging (Talk and Hall)'
6 ==
7;>
9# Messaging (Talk and Hall)
12Talk is the built-in frontend for the Urbit messaging and notifications
13protocol, Hall. Today we use Hall to chat and coordinate, but it's really
14a general purpose piece of infrastructure. Test.
16For the time being come join us in `/urbit-meta` by using the
17'quickstart' section below.
19Today, Hall is sort of like a distributed, encrypted Slack that can be
20used from the CLI and the browser. There’s no central Hall server.
21Any Urbit can host one.
23Hall is a general purpose tool for both aggregating and publishing
24streams of messages. Applications can use Hall as their transport
25protcol, API connectors can push disparate data sources into Hall,
26and so on. There are lots of things a distributed message protocol can
27be used for that we haven't even thought of.
29Here we'll be discussing how to operate the default CLI frontend, Talk,
30to send and receive messages. For a more in-depth look at Hall's internals,
31take a look at its [documentation](../../hall/architecture).
33## Quickstart
35For the most part we use Talk as a single-instance of Slack: one main
36channel (`/urbit-meta`) and direct messages. Everyone is more than welcome
37in `/urbit-meta`. It's the place to get help, ask questions and chat about
38Urbit in general.
40Let's join `/urbit-meta`:
42Use `ctrl-x` to switch from Dojo to Talk.
44To join `/urbit-meta`:
46```
47~your-urbit:talk> ;join /urbit-meta
48```
50You'll see something like:
52```
53--------------| ;join /urbit-meta
54--------------| :: onn /urbit-meta
55--------------| bound '=' {[hos=~binzod nom=%urbit-meta]}
56--------------| new = /urbit-meta
57--------------| /urbit-meta: cap: For Urbit-related discussion. Politically
58 | correct and safe for work. Don't be rude!
59--------------| /urbit-meta: fit: caps:n unic:n
60~your-urbit:talk=
61```
63Post a line to `/urbit-meta`:
65```
66~your-urbit:talk= Hello, world!
67```
69You'll see, echoed back at you:
71```
72~your-urbit= Hello, world!
73```
75To send a direct message to someone, first set your audience:
77```
78~your-urbit:talk= ;~talsur-todres
79```
81You'll see your prompt change:
83```
84~your-urbit:talk[~talsur-todres]
85```
87Now you and `~talsur-todres` can exchange messages directly.
89```
90~your-urbit:talk[~talsur-todres] Hey buddy!
91```
93To set your audience back to `/urbit-meta`:
95```
96~your-urbit:talk[~talsur-todres] ;/urbit-meta
97```
99You'll see your prompt change back:
101```
102~your-urbit:talk=
103```
105You can also use the ASCII "glyph" assigned to your `/urbit-meta` circle as a shortcut:
107```
108~your-urbit:talk[~talsur-todres] ;=
109~your-urbit:talk=
110```
112(Your ship may have a different glyph than `=` for your circle)
114Use `;leave` to unsubscribe from a channel:
116```
117~your-urbit:talk= ;leave /urbit-meta
118```
120There are two ways of using Talk: from the CLI or through a web UI
121available at `http://your-urbit.urbit.org/~~/talk` (or
122`http://localhost:8080/~~/talk`).
124The web UI ships as compiled JavaScript on your Urbit, but has its own
125source repo [here](https://github.com/urbit/talk).
127Last, let's create a channel we can invite some friends to:
129```
130~your-urbit:talk= ;create channel %my-channel 'Some description.'
131```
133Now you can tell your friends to `;join ~your-urbit/my-channel`.
135## Manual
137Hall's design is similar in spirit to
138[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
139the underlying protocol for Usenet.
141Our design is pretty simple: Hall messages are called _posts_. Posts
142go to _circles_. Any urbit can host or subscribe to any number of circles.
144There are four kinds of circles: a write-only `%mailbox` for direct
145messages, an invite-only `%village` for private conversation, a read-only
146`%journal` for curated content, and a public-access `%channel` for
147general use.
149### Posts
151A post can be a variety of different data structures. Let's look at the
152ones you can use from within Talk: lines, URLs, Hoon and
153replies.
155#### Lines
157A line is simply a string of text. Depending on the filtering rules set
158by the circle's host, these may or may not include uppercase and Unicode
159characters.
161If the line starts with `@`, it's an action (IRC `/me`).
163```
164~your-urbit:talk= @sends a message.
165```
167will print as
169```
170~your-urbit sends a message.
171```
173#### URLs
175A URL is any valid URL.
177```
178~your-urbit:talk= https://example.com/
179```
181### Hoon
183You can use Talk to evaluate Hoon code and share the result with everyone in a
184Hall circle. To do so, preface your Hoon with `#`.
186```
187~your-urbit:talk= #(add 2 2)
188```
190will print as
192```
193~your-urbit# (add 2 2)
195```
197### Replies
199To indicate what you're saying is in direct response to a specific
200message, select the message (see Activating Lines below) and type your
201response.
203```
204~some-urbit= Hello! How are you?
205~your-urbit:talk= ; Well, thanks!
206```
208will print as
210```
211~your-urbit=^ Well, thanks!
212```
214### Activating Lines
216A line number identifying the *subsequent* line is displayed every 5
217lines.
219```
220---------[0]
221~your-urbit= This is my message.
222~your-urbit= This is another message.
223~your-urbit sends a message.
224~your-urbit/ http://example.com/
225~your-urbit# (add 2 2)
226 4
227---------[5]
228~your-urbit=^ That's my message!
229```
231You can use a line number to *activate* a line:
233```
234~your-urbit:talk= ;5
235```
237which prints the number, line identifier, timestamp, sender, audience,
238and contents:
240```
241? 0
2420v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
243~your-urbit to ~another-urbit
244in reply to: ~your-urbit:
245> This is my message.
246That's my message!
247```
249If information got truncated — like happens for long URLs or expressions —
250or if there's additional information available — as is the case with
251replies and attachments — activating the message will show you all the
252details.
254You can activate the most recent line with `;`, the second-most recent
255with `;;`, and so on.
257### Creating and managing circles
259###### `;create [type] %name 'description'`
261Creates and joins a circle, where `[type]` is any of the following:
262- `channel`: public circle. Has a blacklist for write control.
263- `village`: invite-only circle.
264- `journal`: publicly readable, invite-only for writing.
265- `mailbox`: publicly writeable, can only be read by its host.
267###### `;delete %name 'optional reason'`
269Deletes a circle. If a reason is specified, that gets sent to all
270subscribers before the circle gets deleted.
272###### `;depict %name 'description'`
274Changes the description of circle `%name`.
276###### `;filter %name [capitals] [unicode]`
278Configures the message filter for circle `%name`: whether to allow
279capital and/or unicode characters. `y`/`&`/`true` for allowed,
280`n`/`|`/`false` for disallowed.
282###### `;invite %name ~someone`
284Invite someone into your circle `%name`. If they were previously banished,
285removes them from the blacklist.
286Can also invite multiple ships at once, `~comma, ~separated`.
288###### `;banish %name ~someone`
290Banish someone from your circle `%name`. If they were previously invited,
291removes them from the whitelist.
292Can also banish multiple ships at once, `~comma, ~separated`.
294###### `;source %name ~other/circle`
296Adds `~other/circle` as a source for circle `%name`. This causes all
297messages sent to `~other/circle` to also appear in `%name`.
299###### `;unsource %name ~other/circle`
301Removes `~other/circle` as a source for circle `%name`.
303### Membership
305If you have joined a circle, you can make this information publicly
306available to help others find that circle as well.
308###### `;show ~some/circle`
310Adds a circle to your public membership list.
312###### `;hide ~some/circle`
314Removes a circle from your public membership list.
316### Status
318You'll see status notifications when people enter or leave stations
320###### `;set quiet`
322Turn off status (and config) notifications.
324###### `;unset quiet`
326Turn on status (and config) notifications.
328###### `;who`
330List everyone in all your subscribed circles. Optionally specify a
331specific circle to list members of just those.
333You'll see presence notifications when people enter or leave stations
334you're subscribed to.
336###### `;attend ~some/circle [presence]`
338Manually set your presence to show up as one of the following. (In the
339future, a sufficiently advanced client can automatically set these for
340you.)
342- `talk` - typing
343- `hear` - listening
344- `idle` - inactive
345- `gone` - not present
347###### `;name ~some/circle 'my handle'`
349Set a handle ("name") for yourself in a specific circle. It will display
350to users who have done `;set nicks`, but gets truncated if it's longer
351than 14 characters.
353### Audience
355An audience consists of one or more messaging targets. These can be
356circles or ships. (In the latter case, it's secretly the `~ship/inbox`
357circle.)
359### Circle glyphs
361Glyphs are assigned by circle hash out of the following list
363```
364> = + - } ) , . " ' ^ $ % & @
365```
367Alphanumeric characters and `|#;:*~_` are reserved; all others (the
368above list, and `\/!?({<`) can be manually assigned.
370###### `;bind + /urbit-test`
372Assigns the `+` glyph to `/urbit-test`.
374###### `;unbind + /urbit-test`
376Unassigns the `+` glyph from `/urbit-test`.
378To see what circle is bound to a glyph:
380```
381;what +
382/urbit-test
383```
385### Prefixes
387Received posts are prefixed with a glyph to let you know what the
388audience is. You can activate an individual post to see the full
389audience.
391There are a few special-purpose glyphs:
393- `|` - Informational messages
394- `:` - Posts directly to you
395- `;` - Posts to you and others (a multiparty conversation)
396- `*` - Posts to a complex audience that doesn't directly include you.
398#### Prompt
400The audience you're sending to is always shown in your prompt. If
401there's a glyph for it, it's shown as the glyph.
403Here we're talking to the station bound to `=`:
405```
406~your-urbit:talk=
407```
409Here we're talking directly to `~dannum-mitryl`:
411```
412~your-urbit:talk[~dannum-mitryl]
413```
415#### Configuration
417###### `;~urbit/circle`
419Set audience to `~urbit/circle`.
421###### `;=`
423Set audience to the station bound to the `=` glyph
425###### `;~dannum-mitryl`
427Set audience to `~dannum-mitryl` (a direct post).
429###### `;%circle`
431Set audience to a circle on your own ship
433###### `;~dannum-mitryl this is a private message`
435Set the audience and send a post in the same line. This works for all of the above.
437Your audience is configured with regard to the following rules (in order):
439- if you manually set the audience, that audience.
440- if you activated a post, the post you activated.
441- audience of the last post sent.
443### Local nicknames
445###### `;nick`
447List all local nicknames.
449###### `;nick ~some-urbit`
451Look up a nickname.
453###### `;nick plato`
455Search in reverse.
457###### `;nick ~some-urbit plato`
459Create a nickname.
461###### `;nick ~some-urbit ~`
463Clear an assigned nickname.
465###### `;set nicks`
467Show nicknames instead of urbit names. If no local nickname is set, uses
468that user's handle. If the user has no handle, just the urbit name.
470###### `;unset nicks`
472Show urbit names instead of nicknames.
474Nicknames and handles longer than 14 character will be truncated in
475output. Nicknames are strictly local - like the names on entries in a
476phonebook.
478### Miscellaneous configuration
480###### `;set showtime`
482Show the timestamp for each message.
484###### `;unset showtime`
486Stop showing the timestamp for each message.
488###### `;set timezone [+/-][hours]`
490Adjust the display of the timestamps to a specific timezone. Relative to UTC.
492###### `;set notify`
494Emit a terminal bell sound if your six-syllable ship name is mentioned in
495a message.
497###### `;unset notify`
499Do not notify when your ship name is mentioned.
501###### `;set width [number]`
503Set the rendering width of `:talk` to a specific number of characters.
504(Minimum of 30.)