git.iko.soy/urbit.org
on 342e045 help sign in
urbit.org/using/messaging.md
664 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## Manual
130Hall's design is similar in spirit to
131[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
132the underlying protocol for Usenet.
134Our design is pretty simple: Hall messages are called _posts_. Posts
135go to _circles_. Any urbit can host or subscribe to any number of circles.
137There are four kinds of circles: a write-only `%mailbox` for direct
138messages, an invite-only `%village` for private conversation, a read-only
139`%journal` for curated content, and a public-access `%channel` for
140general use.
142### Posts
144A post can be a variety of different data structures. Let's look at the
145ones you can use from within Talk: lines, URLs, Hoon and replies.
147#### Lines
149A line is simply a string of text. Depending on the filtering rules set
150by the circle's host, these may or may not include uppercase and Unicode
151characters (see [filter](#filter)).
153If the line starts with `@`, it's an action (like `/me` in IRC).
155```
156~your-urbit:talk= @sends a message.
157```
159will print as
161```
162~your-urbit sends a message.
163```
165#### URLs
167A URL is any valid URL.
169```
170~your-urbit:talk= https://example.com/
171```
173#### Hoon
175You can use Talk to evaluate Hoon code and share the result with everyone in a
176Hall circle. To do so, preface your Hoon with `#`.
178```
179~your-urbit:talk= #(add 2 2)
180```
182will print as
184```
185~your-urbit# (add 2 2)
187```
189#### Replies
191To indicate what you're saying is in direct response to a specific
192message, select the message (see Activating Lines below) and type your
193response.
195```
196~some-urbit= Hello! How are you?
197~your-urbit:talk= ; Well, thanks!
198```
200will print as
202```
203~your-urbit=^ Well, thanks!
204```
206### Activating Lines
208A line number identifying the **subsequent** line is displayed every 5
209lines.
211```
212---------[0]
213~your-urbit= This is my message.
214~your-urbit= This is another message.
215~your-urbit sends a message.
216~your-urbit/ http://example.com/
217~your-urbit# (add 2 2)
218 4
219---------[5]
220~your-urbit=^ That's my message!
221```
223You can use a line number to **activate** a line:
225```
226~your-urbit:talk= ;5
227```
229which prints the number, line identifier, timestamp, sender, audience,
230and contents:
232```
233? 0
2340v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
235~your-urbit to ~another-urbit
236in reply to: ~your-urbit:
237> This is my message.
238That's my message!
239```
241If information got truncated — like what happens for long URLs or expressions,
242or if there's additional information available — as is the case with
243replies and attachments (e.g. stack traces) — activating the message will show
244you all the details.
246You can also activate the most recent line with `;`, the second-most recent
247with `;;`, and so on.
249### Creating and managing circles
251As mentioned before, any urbit can host any number of circles. Existing circles
252can be deleted or modified with various commands. All commands in this section
253shoild be sent from the `talk>` prompt.
255#### Create
257Syntax: `;create [type] %name 'description'`
259Creates and joins a circle, where `[type]` is any of the following:
260- `channel`: public circle. Has a blacklist for write control.
261- `village`: invite-only circle.
262- `journal`: publicly readable, invite-only for writing.
263- `mailbox`: publicly writeable, can only be read by its host.
265Let's create an example mailbox:
267```
268sampel-palnet:talk> ;create mailbox %coolbox 'cool messages only'
269```
271Something like this should print:
273```
274--------------| ;create mailbox %coolbox 'cool messages only'
275--------------| :: onn %coolbox
276--------------| bound '>' {[hos=~sampel-palnet nom=%coolbox]}
277--------------| %coolbox: see ~sampel-palnet hear
278--------------| new > %coolbox
279--------------| %coolbox: cap: cool messages only
280--------------| %coolbox: fit: caps:Y unic:✔
281```
283###### Delete
285Syntax: `;delete %name 'optional reason'`
287Deletes a circle. If a reason is specified, that gets sent to all
288subscribers before the circle gets deleted.
290To delete our example above:
292```
293sampel-palnet:talk> ;delete %coolbox 'people sent uncool messages'
294```
296#### Change Description
298Syntax: `;depict %name 'description'`
300Changes the description of an existing circle `%name`.
302For example:
304```
305sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'
306```
309#### Filter
311Syntax: `;filter %name [capitals] [unicode]`
313Configures the message filter for circle `%name`: whether to allow
314capital and/or unicode characters. `y`/`&`/`true` for allowed,
315`n`/`|`/`false` for disallowed.
317So, to allow capital letters and disallow unicode in the circle `%coolbox`:
319```
320sampel-palnet:talk> ;filter %coolbox & |
321```
322or
323```
324sampel-palnet:talk> ;filter %coolbox y n
325```
327And we get the output:
329```
330--------------| ;filter %coolbox & |
331--------------| %coolbox: fit: caps:Y unic:n
332```
334#### Invite
336Syntax: `;invite %name ~someone`
338Invites someone into your circle `%name`. If they were previously banished,
339removes them from the blacklist.
340Can also invite multiple ships at once, `~comma, ~separated`.
342For example:
344```
345~sampel-palnet:talk> ;invite %coolbox ~lodleb-ritrul
346```
348#### Banish
350Syntax: `;banish %name ~someone`
352Removes someone from your circle `%name`. If they were previously invited,
353removes them from the whitelist.
354Can also banish multiple ships at once, `~comma, ~separated`.
356#### Source
358Syntax: `;source %name ~other/circle`
360Adds `~other/circle` as a source for circle `%name`. This causes all
361messages sent to `~other/circle` to also appear in `%name`.
363For example:
365```
366~sampel-palnet:talk> ;source %coolbox ~marzod/urbit-help
367```
369#### Unsource
371Syntax: `;unsource %name ~other/circle`
373Removes `~other/circle` as a source for circle `%name`.
375For example:
377```
378~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-help
379```
381### Circle Membership
383If you have joined a circle, you can make this information publicly
384available to help others find that circle as well.
386#### Show Membership
388Syntax: `;show ~some/circle`
390Adds a circle to your public membership list on your Hall profile. Hall profiles
391are not used yet.
393#### Hide Membership
395Syntax: `;hide ~some/circle`
397Removes a circle from your public membership list on your Hall profile. Hall
398profiles are not used yet.
400### Status
402You'll see status notifications when people enter or leave circles you're
403subscribed to.
405#### Notifications Off
407Syntax: `;set quiet`
409Turn off status (and config) notifications.
411#### Notifications On
413Syntax: `;unset quiet`
415Turn on status (and config) notifications.
417#### Who
419Syntax: `;who`
421List everyone in all your subscribed circles. Optionally specify a
422specific circle to list members of just those: `;who ~some/circle`
424For example:
426```
427~sampel-palnet:talk> ;who ~marzod/urbit-help
428```
430#### Attend
432Syntax: `;attend ~some/circle [presence]`
434Manually set your presence to show up as one of the following. (In the
435future, a sufficiently advanced client can automatically set these for
436you.)
438- `talk` - typing
439- `hear` - listening
440- `idle` - inactive
441- `gone` - not present
443For example:
445```
446~sampel-palnet:talk> ;attend ~marzod/urbit-help idle
447```
449#### Set Display Name
451Syntax: `;name ~some/circle 'my handle'`
453Set a handle ("name") for yourself in a specific circle. It will display
454to users who have done `;set nicks`, but gets truncated if it's longer
455than 14 characters.
457## Audience
459An audience consists of one or more messaging targets. These can be
460circles or ships. (In the latter case, it's secretly the `~ship/inbox`
461circle.)
463### Circle Glyphs
465Glyphs are found at the end of your prompt to as a quick indicator of where
466your messages will be sent.
468Glyphs are assigned by circle hash out of the following list:
470```
471> = + - } ) , . " ' ^ $ % & @
472```
474Alphanumeric characters and `|#;:*~_` are reserved; all others (the
475above list, and `\/!?({<`) can be manually assigned.
477For example, `-` the glyph at the end of the prompt below might indicates that
478messages sent from this prompt will go to some circle with that glyph:
480```
481~sampel-palnet:talk-
482```
484To see what circle is bound to a glyph, use the `;what` command followed by the
485glyph in question. For example, to see `=`:
487```
488~sampel-palnet:talk> ;what =
489/urbit-help
490```
492Not every audience has a glyph, however. When the audience doesn't have a glyph,
493such as in the case of direct-messaging a ship, we see their name at the end of
494the prompt instead. Here we're talking directly to `~dannum-mitryl`:
496```
497~sampel-palnet:talk[~dannum-mitryl]
498```
500#### Bind
502Syntax: `;bind [glyph] /circle-name`
504Assigns the chosen glyph to a circle owned by your ship.
506For example:
508```
509~sampel-palnet:talk> ;bind + /my-circle
510```
512#### Unbind
514Syntax: `;unbind [glyph] /circle-name`
516Unassigns the chosen glyph from a circle owned by your ship.
518For example:
520```
521~sampel-palnet:talk> ;unbind + /my-circle
522```
524### Prefixes
526Received posts are prefixed with a glyph to let you know what the
527audience is. You can activate an individual post to see the full
528audience.
530There are a few special-purpose glyphs:
532- `|` - Informational messages
533- `:` - Posts directly to you
534- `;` - Posts to you and others (a multiparty conversation)
535- `*` - Posts to a complex audience that doesn't directly include you.
538### Configuration
540#### Set Audience
542`;~ship/circle`
544Set audience to `~ship/circle`.
546#### Set Audience by Glyph
548Syntax: `;[glyph]`
550Set audience to the circle previously bound to the chosen glyph.
552#### Set Audience to Ship
554syntax `;~ship`
556Set audience to another ship.
558#### Set Audience to Own Circle
560Syntax: `;%circle`
562Set audience to a circle on your own ship
564#### Set Audience + Send Message
566Syntax: `;~dannum-mitryl this is a private message`
568Set the audience and send a post in the same line. This works for all of the
569above audience commands.
571Your audience is configured with regard to the following rules (in order):
573- if you manually set the audience, that audience.
574- if you activated a post, the post you activated.
575- audience of the last post sent.
577### Local nicknames
579#### See Nicknames
581Syntax: `;nick`
583List all local nicknames.
585#### Find Nickname
587Syntax: `;nick ~some-urbit`
589Look up a nickname using the known ship-name.
591#### Reverse Find Nickname
593syntax: `;nick plato`
595Find a ship's name using its nickname.
597#### Set Nickname
599Syntax: `;nick ~some-urbit plato`
601Create a new nickname.
603#### Clear Nickname
605Syntax: `;nick ~some-urbit ~`
607Clear an assigned nickname.
609#### Display Nicks, Not Ship-Names
611Syntax: `;set nicks`
613Show nicknames instead of ship-names. If no local nickname is set, uses
614that user's handle. If the user has no handle, just the urbit name.
616#### Display Ship-Names, Not Nicks
618Syntax: `;unset nicks`
620Show ship-names instead of nicknames.
622Nicknames and handles longer than 14 character will be truncated in
623output. Nicknames are strictly local - like the names on entries in a
624phonebook.
626### Miscellaneous configuration
628#### Show Timestamps
630Syntax: `;set showtime`
632Show the timestamp for each message.
634#### Hide Timestamps
636Syntax: `;unset showtime`
638Stop showing the timestamp for each message.
640#### Change Time Zone
642Syntax: `;set timezone [+/-][hours]`
644Adjust the display of the timestamps to a specific timezone. Relative to UTC.
646#### Sound Notification On
648Syntax: `;set notify`
650Emit a terminal bell sound if your six-syllable ship name is mentioned in
651a message.
653#### Sound Notification Off
655Syntax `;unset notify`
657Do not notify when your ship name is mentioned.
659#### Set Width
661Syntax: `;set width [number]`
663Set the rendering width of `:talk` to a specific number of characters.
664(Minimum of 30.)