git.iko.soy/urbit.org
on db111b9 help sign in
urbit.org/using/messaging.md
665 lines 15 kB history raw
1+++
2title = "Messaging"
3weight = 2
4template = "doc.html"
5+++
6Talk is the built-in frontend for the Urbit messaging and notifications
7protocol, Hall. Today we use Hall to chat and coordinate, but it's really
8a general purpose piece of infrastructure.
10For the time being come join us in `~dopzod/urbit-help` by using the
11'quickstart' section below. `~dopzod` is the host ship, and `/urbit-help` is the
12channel on that ship.
14Today, Hall is sort of like a distributed, encrypted Slack that can be
15used from the CLI and the browser. There’s no central Hall server.
16Any urbit can host one.
18Hall is a general purpose tool for both aggregating and publishing
19streams of messages. Applications can use Hall as their transport
20protocol, API connectors can push disparate data sources into Hall,
21and so on. There are lots of things a distributed message protocol can
22be used for that we haven't even thought of.
24Here we'll be discussing how to operate the default CLI frontend, Talk,
25to send and receive messages. For a more in-depth look at Hall's internals,
26take a look at its [documentation](./docs/learn/arvo/hall.md).
28## Quickstart
30The most common use of talk right now is as a single-instance of Slack: one main
31channel (`~dopzod/urbit-help`) and direct messages. Everyone is more than welcome
32in `~dopzod/urbit-help`. It's the place to get help, ask questions and chat about
33Urbit in general.
35There are two ways of using Talk: from the terminal running the Urbit process,
36or through a web UI available at `http://localhost:8080/~~/talk`. This
37quick-start guide will cover the first method.
39### Joining a Channel
41In Hall, a medium for a message is called a _circle_. There are four types of
42circles, but we for now we'll be dealing with the _channel_: a publicly
43accessible chatroom for general use. We'll discuss the other three
44kinds in the [manual](#manual) section.
46Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from Dojo to Talk.
47Then:
49```
50~your-urbit:talk> ;join ~dopzod/urbit-help
51```
53Scrolling down your terminal window, you'll probably see the playback of
54previous `~dopzod/urbit-help` messages that you missed.
56Post a line to `~dopzod/urbit-help:`
58```
59~your-urbit:talk= Hello, world!
60```
62You'll see your message printed below messages from others that came before it:
64```
65~your-urbit= Hello, world!
66```
68### Direct Messaging
70To send a direct message to someone, first set your audience:
72```
73~your-urbit:talk= ;~talsur-todres
74```
76You'll see your prompt change:
78```
79~your-urbit:talk[~talsur-todres]
80```
82Now you and `~talsur-todres` can exchange messages directly.
84```
85~your-urbit:talk[~talsur-todres] Hey buddy!
86```
88To set your audience back to `~dopzod/urbit-help`:
90```
91~your-urbit:talk[~talsur-todres] ;~dopzod/urbit-help
92```
94You'll see your prompt change back:
96```
97~your-urbit:talk=
98```
100You can also use the ASCII "glyph" assigned to your `~dopzod/urbit-help` circle as a shortcut:
102```
103~your-urbit:talk[~talsur-todres] ;=
104~your-urbit:talk=
105```
107(Your ship may have a different glyph than `=` for your circle)
109Use `;leave` to unsubscribe from a channel:
111```
112~your-urbit:talk= ;leave ~dopzod/urbit-help
113```
115The web UI ships as compiled JavaScript on your urbit, but has its own
116source repo [here](https://github.com/urbit/talk).
118Last, let's create a channel we can invite some friends to:
120```
121~your-urbit:talk= ;create channel %my-channel 'Some description.'
122```
124Now you can tell your friends to `;join ~your-urbit/my-channel`.
126---
128<span id="manual"></span>
129## Manual
131Hall's design is similar in spirit to
132[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
133the underlying protocol for Usenet.
135Our design is pretty simple: Hall messages are called _posts_. Posts
136go to _circles_. Any urbit can host or subscribe to any number of circles.
138There are four kinds of circles: a write-only `%mailbox` for direct
139messages, an invite-only `%village` for private conversation, a read-only
140`%journal` for curated content, and a public-access `%channel` for
141general use.
143### Posts
145A post can be a variety of different data structures. Let's look at the
146ones you can use from within Talk: lines, URLs, Hoon and replies.
148#### Lines
150A line is simply a string of text. Depending on the filtering rules set
151by the circle's host, these may or may not include uppercase and Unicode
152characters (see [filter](#filter)).
154If the line starts with `@`, it's an action (like `/me` in IRC).
156```
157~your-urbit:talk= @sends a message.
158```
160will print as
162```
163~your-urbit sends a message.
164```
166#### URLs
168A URL is any valid URL.
170```
171~your-urbit:talk= https://example.com/
172```
174#### Hoon
176You can use Talk to evaluate Hoon code and share the result with everyone in a
177Hall circle. To do so, preface your Hoon with `#`.
179```
180~your-urbit:talk= #(add 2 2)
181```
183will print as
185```
186~your-urbit# (add 2 2)
188```
190#### Replies
192To indicate what you're saying is in direct response to a specific
193message, select the message (see Activating Lines below) and type your
194response.
196```
197~some-urbit= Hello! How are you?
198~your-urbit:talk= ; Well, thanks!
199```
201will print as
203```
204~your-urbit=^ Well, thanks!
205```
207### Activating Lines
209A line number identifying the **subsequent** line is displayed every 5
210lines.
212```
213---------[0]
214~your-urbit= This is my message.
215~your-urbit= This is another message.
216~your-urbit sends a message.
217~your-urbit/ http://example.com/
218~your-urbit# (add 2 2)
219 4
220---------[5]
221~your-urbit=^ That's my message!
222```
224You can use a line number to **activate** a line:
226```
227~your-urbit:talk= ;5
228```
230which prints the number, line identifier, timestamp, sender, audience,
231and contents:
233```
234? 0
2350v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
236~your-urbit to ~another-urbit
237in reply to: ~your-urbit:
238> This is my message.
239That's my message!
240```
242If information got truncated — like what happens for long URLs or expressions,
243or if there's additional information available — as is the case with
244replies and attachments (e.g. stack traces) — activating the message will show
245you all the details.
247You can also activate the most recent line with `;`, the second-most recent
248with `;;`, and so on.
250### Creating and managing circles
252As mentioned before, any urbit can host any number of circles. Existing circles
253can be deleted or modified with various commands. All commands in this section
254shoild be sent from the `talk>` prompt.
256#### Create
258Syntax: `;create [type] %name 'description'`
260Creates and joins a circle, where `[type]` is any of the following:
261- `channel`: public circle. Has a blacklist for write control.
262- `village`: invite-only circle.
263- `journal`: publicly readable, invite-only for writing.
264- `mailbox`: publicly writeable, can only be read by its host.
266Let's create an example mailbox:
268```
269sampel-palnet:talk> ;create mailbox %coolbox 'cool messages only'
270```
272Something like this should print:
274```
275--------------| ;create mailbox %coolbox 'cool messages only'
276--------------| :: onn %coolbox
277--------------| bound '>' {[hos=~sampel-palnet nom=%coolbox]}
278--------------| %coolbox: see ~sampel-palnet hear
279--------------| new > %coolbox
280--------------| %coolbox: cap: cool messages only
281--------------| %coolbox: fit: caps:Y unic:✔
282```
284###### Delete
286Syntax: `;delete %name 'optional reason'`
288Deletes a circle. If a reason is specified, that gets sent to all
289subscribers before the circle gets deleted.
291To delete our example above:
293```
294sampel-palnet:talk> ;delete %coolbox 'people sent uncool messages'
295```
297#### Change Description
299Syntax: `;depict %name 'description'`
301Changes the description of an existing circle `%name`.
303For example:
305```
306sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'
307```
309<span id="filter"></span>
310#### Filter
312Syntax: `;filter %name [capitals] [unicode]`
314Configures the message filter for circle `%name`: whether to allow
315capital and/or unicode characters. `y`/`&`/`true` for allowed,
316`n`/`|`/`false` for disallowed.
318So, to allow capital letters and disallow unicode in the circle `%coolbox`:
320```
321sampel-palnet:talk> ;filter %coolbox & |
322```
323or
324```
325sampel-palnet:talk> ;filter %coolbox y n
326```
328And we get the output:
330```
331--------------| ;filter %coolbox & |
332--------------| %coolbox: fit: caps:Y unic:n
333```
335#### Invite
337Syntax: `;invite %name ~someone`
339Invites someone into your circle `%name`. If they were previously banished,
340removes them from the blacklist.
341Can also invite multiple ships at once, `~comma, ~separated`.
343For example:
345```
346~sampel-palnet:talk> ;invite %coolbox ~lodleb-ritrul
347```
349#### Banish
351Syntax: `;banish %name ~someone`
353Removes someone from your circle `%name`. If they were previously invited,
354removes them from the whitelist.
355Can also banish multiple ships at once, `~comma, ~separated`.
357#### Source
359Syntax: `;source %name ~other/circle`
361Adds `~other/circle` as a source for circle `%name`. This causes all
362messages sent to `~other/circle` to also appear in `%name`.
364For example:
366```
367~sampel-palnet:talk> ;source %coolbox ~marzod/urbit-help
368```
370#### Unsource
372Syntax: `;unsource %name ~other/circle`
374Removes `~other/circle` as a source for circle `%name`.
376For example:
378```
379~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-help
380```
382### Circle Membership
384If you have joined a circle, you can make this information publicly
385available to help others find that circle as well.
387#### Show Membership
389Syntax: `;show ~some/circle`
391Adds a circle to your public membership list on your Hall profile. Hall profiles
392are not used yet.
394#### Hide Membership
396Syntax: `;hide ~some/circle`
398Removes a circle from your public membership list on your Hall profile. Hall
399profiles are not used yet.
401### Status
403You'll see status notifications when people enter or leave circles you're
404subscribed to.
406#### Notifications Off
408Syntax: `;set quiet`
410Turn off status (and config) notifications.
412#### Notifications On
414Syntax: `;unset quiet`
416Turn on status (and config) notifications.
418#### Who
420Syntax: `;who`
422List everyone in all your subscribed circles. Optionally specify a
423specific circle to list members of just those: `;who ~some/circle`
425For example:
427```
428~sampel-palnet:talk> ;who ~marzod/urbit-help
429```
431#### Attend
433Syntax: `;attend ~some/circle [presence]`
435Manually set your presence to show up as one of the following. (In the
436future, a sufficiently advanced client can automatically set these for
437you.)
439- `talk` - typing
440- `hear` - listening
441- `idle` - inactive
442- `gone` - not present
444For example:
446```
447~sampel-palnet:talk> ;attend ~marzod/urbit-help idle
448```
450#### Set Display Name
452Syntax: `;name ~some/circle 'my handle'`
454Set a handle ("name") for yourself in a specific circle. It will display
455to users who have done `;set nicks`, but gets truncated if it's longer
456than 14 characters.
458## Audience
460An audience consists of one or more messaging targets. These can be
461circles or ships. (In the latter case, it's secretly the `~ship/inbox`
462circle.)
464### Circle Glyphs
466Glyphs are found at the end of your prompt to as a quick indicator of where
467your messages will be sent.
469Glyphs are assigned by circle hash out of the following list:
471```
472> = + - } ) , . " ' ^ $ % & @
473```
475Alphanumeric characters and `|#;:*~_` are reserved; all others (the
476above list, and `\/!?({<`) can be manually assigned.
478For example, `-` the glyph at the end of the prompt below might indicates that
479messages sent from this prompt will go to some circle with that glyph:
481```
482~sampel-palnet:talk-
483```
485To see what circle is bound to a glyph, use the `;what` command followed by the
486glyph in question. For example, to see `=`:
488```
489~sampel-palnet:talk> ;what =
490/urbit-help
491```
493Not every audience has a glyph, however. When the audience doesn't have a glyph,
494such as in the case of direct-messaging a ship, we see their name at the end of
495the prompt instead. Here we're talking directly to `~dannum-mitryl`:
497```
498~sampel-palnet:talk[~dannum-mitryl]
499```
501#### Bind
503Syntax: `;bind [glyph] /circle-name`
505Assigns the chosen glyph to a circle owned by your ship.
507For example:
509```
510~sampel-palnet:talk> ;bind + /my-circle
511```
513#### Unbind
515Syntax: `;unbind [glyph] /circle-name`
517Unassigns the chosen glyph from a circle owned by your ship.
519For example:
521```
522~sampel-palnet:talk> ;unbind + /my-circle
523```
525### Prefixes
527Received posts are prefixed with a glyph to let you know what the
528audience is. You can activate an individual post to see the full
529audience.
531There are a few special-purpose glyphs:
533- `|` - Informational messages
534- `:` - Posts directly to you
535- `;` - Posts to you and others (a multiparty conversation)
536- `*` - Posts to a complex audience that doesn't directly include you.
539### Configuration
541#### Set Audience
543`;~ship/circle`
545Set audience to `~ship/circle`.
547#### Set Audience by Glyph
549Syntax: `;[glyph]`
551Set audience to the circle previously bound to the chosen glyph.
553#### Set Audience to Ship
555syntax `;~ship`
557Set audience to another ship.
559#### Set Audience to Own Circle
561Syntax: `;%circle`
563Set audience to a circle on your own ship
565#### Set Audience + Send Message
567Syntax: `;~dannum-mitryl this is a private message`
569Set the audience and send a post in the same line. This works for all of the
570above audience commands.
572Your audience is configured with regard to the following rules (in order):
574- if you manually set the audience, that audience.
575- if you activated a post, the post you activated.
576- audience of the last post sent.
578### Local nicknames
580#### See Nicknames
582Syntax: `;nick`
584List all local nicknames.
586#### Find Nickname
588Syntax: `;nick ~some-urbit`
590Look up a nickname using the known ship-name.
592#### Reverse Find Nickname
594syntax: `;nick plato`
596Find a ship's name using its nickname.
598#### Set Nickname
600Syntax: `;nick ~some-urbit plato`
602Create a new nickname.
604#### Clear Nickname
606Syntax: `;nick ~some-urbit ~`
608Clear an assigned nickname.
610#### Display Nicks, Not Ship-Names
612Syntax: `;set nicks`
614Show nicknames instead of ship-names. If no local nickname is set, uses
615that user's handle. If the user has no handle, just the urbit name.
617#### Display Ship-Names, Not Nicks
619Syntax: `;unset nicks`
621Show ship-names instead of nicknames.
623Nicknames and handles longer than 14 character will be truncated in
624output. Nicknames are strictly local - like the names on entries in a
625phonebook.
627### Miscellaneous configuration
629#### Show Timestamps
631Syntax: `;set showtime`
633Show the timestamp for each message.
635#### Hide Timestamps
637Syntax: `;unset showtime`
639Stop showing the timestamp for each message.
641#### Change Time Zone
643Syntax: `;set timezone [+/-][hours]`
645Adjust the display of the timestamps to a specific timezone. Relative to UTC.
647#### Sound Notification On
649Syntax: `;set notify`
651Emit a terminal bell sound if your six-syllable ship name is mentioned in
652a message.
654#### Sound Notification Off
656Syntax `;unset notify`
658Do not notify when your ship name is mentioned.
660#### Set Width
662Syntax: `;set width [number]`
664Set the rendering width of `:talk` to a specific number of characters.
665(Minimum of 30.)