git.iko.soy/urbit.org
on c19bc7a help sign in
urbit.org/docs/using/messaging.udon
684 lines 15 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)
11Talk is the built-in frontend for the Urbit messaging and notifications
12protocol, Hall. Today we use Hall to chat and coordinate, but it's really
13a general purpose piece of infrastructure.
15For the time being come join us in `/urbit-meta` by using the
16'quickstart' section below.
18Today, Hall is sort of like a distributed, encrypted Slack that can be
19used from the CLI and the browser. There’s no central Hall server.
20Any urbit can host one.
22Hall is a general purpose tool for both aggregating and publishing
23streams of messages. Applications can use Hall as their transport
24protocol, API connectors can push disparate data sources into Hall,
25and so on. There are lots of things a distributed message protocol can
26be used for that we haven't even thought of.
28Here we'll be discussing how to operate the default CLI frontend, Talk,
29to send and receive messages. For a more in-depth look at Hall's internals,
30take a look at its [documentation](../../tutorials/hall).
32## Quickstart
34The most common use of talk right now is as a single-instance of Slack: one main
35channel (`/urbit-meta`) and direct messages. Everyone is more than welcome
36in `/urbit-meta`. It's the place to get help, ask questions and chat about
37Urbit in general.
39There are two ways of using Talk: from the terminal running the Urbit process,
40or through a web UI available at `http://localhost:8080/~~/talk`. This
41quick-start guide will cover the first method.
43##### Joining a Channel
45In Hall, a medium for a message is called a _circle_. There are four types of
46circles, but we for now we'll be dealing with the _channel_: a publicly
47accessible chatroom for general use. We'll discuss the other three
48kinds in the [manual](#manual) section.
50Let's join the `/urbit-meta` channel. Use `ctrl-x` to switch from Dojo to Talk.
51Then, :
53```
54~your-urbit:talk> ;join /urbit-meta
55```
57You'll see something like:
59```
60--------------| ;join /urbit-meta
61--------------| :: onn /urbit-meta
62--------------| bound '=' {[hos=~binzod nom=%urbit-meta]}
63--------------| new = /urbit-meta
64--------------| /urbit-meta: cap: For Urbit-related discussion. Politically
65 | correct and safe for work. Don't be rude.
66--------------| /urbit-meta: fit: caps:n unic:n
67~your-urbit:talk=
68```
70Scrolling down your terminal window, you'll probably also see the playback of
71previous `/urbit-meta` messages that you missed.
73Post a line to `/urbit-meta`:
75```
76~your-urbit:talk= Hello, world!
77```
79You'll see your message printed below messages from others that came before it:
81```
82~your-urbit= Hello, world!
83```
85##### Direct Messaging
87To send a direct message to someone, first set your audience:
89```
90~your-urbit:talk= ;~talsur-todres
91```
93You'll see your prompt change:
95```
96~your-urbit:talk[~talsur-todres]
97```
99Now you and `~talsur-todres` can exchange messages directly.
101```
102~your-urbit:talk[~talsur-todres] Hey buddy!
103```
105To set your audience back to `/urbit-meta`:
107```
108~your-urbit:talk[~talsur-todres] ;/urbit-meta
109```
111You'll see your prompt change back:
113```
114~your-urbit:talk=
115```
117You can also use the ASCII "glyph" assigned to your `/urbit-meta` circle as a shortcut:
119```
120~your-urbit:talk[~talsur-todres] ;=
121~your-urbit:talk=
122```
124(Your ship may have a different glyph than `=` for your circle)
126Use `;leave` to unsubscribe from a channel:
128```
129~your-urbit:talk= ;leave /urbit-meta
130```
132The web UI ships as compiled JavaScript on your urbit, but has its own
133source repo [here](https://github.com/urbit/talk).
135Last, let's create a channel we can invite some friends to:
137```
138~your-urbit:talk= ;create channel %my-channel 'Some description.'
139```
141Now you can tell your friends to `;join ~your-urbit/my-channel`.
143---
145;h2
146 ;div(id "manual"): Manual
147==
149Hall's design is similar in spirit to
150[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
151the underlying protocol for Usenet.
153Our design is pretty simple: Hall messages are called _posts_. Posts
154go to _circles_. Any urbit can host or subscribe to any number of circles.
156There are four kinds of circles: a write-only `%mailbox` for direct
157messages, an invite-only `%village` for private conversation, a read-only
158`%journal` for curated content, and a public-access `%channel` for
159general use.
161### Posts
163A post can be a variety of different data structures. Let's look at the
164ones you can use from within Talk: lines, URLs, Hoon and replies.
166##### Lines
168A line is simply a string of text. Depending on the filtering rules set
169by the circle's host, these may or may not include uppercase and Unicode
170characters (see [filter](#filter)).
172If the line starts with `@`, it's an action (like `/me` in IRC).
174```
175~your-urbit:talk= @sends a message.
176```
178will print as
180```
181~your-urbit sends a message.
182```
184##### URLs
186A URL is any valid URL.
188```
189~your-urbit:talk= https://example.com/
190```
192##### Hoon
194You can use Talk to evaluate Hoon code and share the result with everyone in a
195Hall circle. To do so, preface your Hoon with `#`.
197```
198~your-urbit:talk= #(add 2 2)
199```
201will print as
203```
204~your-urbit# (add 2 2)
206```
208##### Replies
210To indicate what you're saying is in direct response to a specific
211message, select the message (see Activating Lines below) and type your
212response.
214```
215~some-urbit= Hello! How are you?
216~your-urbit:talk= ; Well, thanks!
217```
219will print as
221```
222~your-urbit=^ Well, thanks!
223```
225### Activating Lines
227A line number identifying the *subsequent* line is displayed every 5
228lines.
230```
231---------[0]
232~your-urbit= This is my message.
233~your-urbit= This is another message.
234~your-urbit sends a message.
235~your-urbit/ http://example.com/
236~your-urbit# (add 2 2)
237 4
238---------[5]
239~your-urbit=^ That's my message!
240```
242You can use a line number to *activate* a line:
244```
245~your-urbit:talk= ;5
246```
248which prints the number, line identifier, timestamp, sender, audience,
249and contents:
251```
252? 0
2530v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
254~your-urbit to ~another-urbit
255in reply to: ~your-urbit:
256> This is my message.
257That's my message!
258```
260If information got truncated — like what happens for long URLs or expressions,
261or if there's additional information available — as is the case with
262replies and attachments — activating the message will show you all the
263details.
265You can also activate the most recent line with `;`, the second-most recent
266with `;;`, and so on.
268### Creating and managing circles
270As mentioned before, any urbit can host any number of circles. Existing circles
271can be deleted or modified with various commands. All commands in this section
272shoild be sent from the `talk>` prompt.
274###### Create
276Syntax: `;create [type] %name 'description'`
278Creates and joins a circle, where `[type]` is any of the following:
279- `channel`: public circle. Has a blacklist for write control.
280- `village`: invite-only circle.
281- `journal`: publicly readable, invite-only for writing.
282- `mailbox`: publicly writeable, can only be read by its host.
284Let's create an example mailbox:
286```
287sampel-palnet:talk> ;create mailbox %coolbox 'cool messages only'
288```
290Something like this should print:
292```
293--------------| ;create mailbox %coolbox 'cool messages only'
294--------------| :: onn %coolbox
295--------------| bound '>' {[hos=~sampel-palnet nom=%coolbox]}
296--------------| %coolbox: see ~sampel-palnet hear
297--------------| new > %coolbox
298--------------| %coolbox: cap: cool messages only
299--------------| %coolbox: fit: caps:Y unic:✔
300```
302###### Delete
304Syntax: `;delete %name 'optional reason'`
306Deletes a circle. If a reason is specified, that gets sent to all
307subscribers before the circle gets deleted.
309To delete our example above:
311```
312sampel-palnet:talk> ;delete %coolbox 'people sent uncool messages'
313```
315###### Change Description
317Syntax: `;depict %name 'description'`
319Changes the description of an existing circle `%name`.
321For example:
323```
324sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'
325```
327;h6
328 ;div(id "filter"): Filter
329==
331Syntax: `;filter %name [capitals] [unicode]`
333Configures the message filter for circle `%name`: whether to allow
334capital and/or unicode characters. `y`/`&`/`true` for allowed,
335`n`/`|`/`false` for disallowed.
337So, to allow capital letters and disallow unicode in the circle `%coolbox`:
339```
340sampel-palnet:talk> ;filter %coolbox & |
341```
342or
343```
344sampel-palnet:talk> ;filter %coolbox y n
345```
347And we get the output:
349```
350--------------| ;filter %coolbox & |
351--------------| %coolbox: fit: caps:Y unic:n
352```
354###### Invite
356Syntax: `;invite %name ~someone`
358Invites someone into your circle `%name`. If they were previously banished,
359removes them from the blacklist.
360Can also invite multiple ships at once, `~comma, ~separated`.
362For example:
364```
365~sampel-palnet:talk> ;invite %coolbox ~lodleb-ritrul
366```
368###### Banish
370Syntax: `;banish %name ~someone`
372Removes someone from your circle `%name`. If they were previously invited,
373removes them from the whitelist.
374Can also banish multiple ships at once, `~comma, ~separated`.
376###### Source
378Syntax: `;source %name ~other/circle`
380Adds `~other/circle` as a source for circle `%name`. This causes all
381messages sent to `~other/circle` to also appear in `%name`.
383For example:
385```
386~sampel-palnet:talk> ;source %coolbox ~marzod/urbit-meta
387```
389###### Unsource
391Syntax: `;unsource %name ~other/circle`
393Removes `~other/circle` as a source for circle `%name`.
395For example:
397```
398~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-meta
399```
401### Circle Membership
403If you have joined a circle, you can make this information publicly
404available to help others find that circle as well.
406###### Show Membership
408Syntax: `;show ~some/circle`
410Adds a circle to your public membership list on your Hall profile. Hall profiles
411are not used yet.
413###### Hide Membership
415Syntax: `;hide ~some/circle`
417Removes a circle from your public membership list on your Hall profile. Hall
418profiles are not used yet.
420### Status
422You'll see status notifications when people enter or leave circles you're
423subscribed to.
425###### Notifications Off
427Syntax: `;set quiet`
429Turn off status (and config) notifications.
431###### Notifications On
433Syntax: `;unset quiet`
435Turn on status (and config) notifications.
437###### Who
439Syntax: `;who`
441List everyone in all your subscribed circles. Optionally specify a
442specific circle to list members of just those: `;who ~some/circle`
444For example:
446```
447~sampel-palnet:talk> ;who ~marzod/urbit-meta
448```
450###### Attend
452Syntax: `;attend ~some/circle [presence]`
454Manually set your presence to show up as one of the following. (In the
455future, a sufficiently advanced client can automatically set these for
456you.)
458- `talk` - typing
459- `hear` - listening
460- `idle` - inactive
461- `gone` - not present
463For example:
465```
466~sampel-palnet:talk> ;attend ~marzod/urbit-meta idle
467```
469###### Set Display Name
471Syntax: `;name ~some/circle 'my handle'`
473Set a handle ("name") for yourself in a specific circle. It will display
474to users who have done `;set nicks`, but gets truncated if it's longer
475than 14 characters.
477## Audience
479An audience consists of one or more messaging targets. These can be
480circles or ships. (In the latter case, it's secretly the `~ship/inbox`
481circle.)
483#### Circle Glyphs
485Glyphs are found at the end of your prompt to as a quick indicator of where
486your messages will be sent.
488Glyphs are assigned by circle hash out of the following list:
490```
491> = + - } ) , . " ' ^ $ % & @
492```
494Alphanumeric characters and `|#;:*~_` are reserved; all others (the
495above list, and `\/!?({<`) can be manually assigned.
497For example, `-` the glyph at the end of the prompt below might indicates that
498messages sent from this prompt will go to some circle with that glyph:
500```
501~sampel-palnet:talk-
502```
504To see what circle is bound to a glyph, use the `;what` command followed by the
505glyph in question. For example, to see `=`:
507```
508~sampel-palnet:talk> ;what =
509/urbit-meta
510```
512Not every audience has a glyph, however. When the audience doesn't have a glyph,
513such as in the case of direct-messaging a ship, we see their name at the end of
514the prompt instead. Here we're talking directly to `~dannum-mitryl`:
516```
517~sampel-palnet:talk[~dannum-mitryl]
518```
520###### Bind
522Syntax: `;bind [glyph] /circle-name`
524Assigns the chosen glyph to a circle owned by your ship.
526For example:
528```
529~sampel-palnet:talk> ;bind + /my-circle
530```
532###### Unbind
534Syntax: `;unbind [glyph] /circle-name`
536Unassigns the chosen glyph from a circle owned by your ship.
538For example:
540```
541~sampel-palnet:talk> ;unbind + /my-circle
542```
544### Prefixes
546Received posts are prefixed with a glyph to let you know what the
547audience is. You can activate an individual post to see the full
548audience.
550There are a few special-purpose glyphs:
552- `|` - Informational messages
553- `:` - Posts directly to you
554- `;` - Posts to you and others (a multiparty conversation)
555- `*` - Posts to a complex audience that doesn't directly include you.
558### Configuration
560###### Set Audience
562`;~ship/circle`
564Set audience to `~ship/circle`.
566###### Set Audience by Glyph
568Syntax: `;[glyph]`
570Set audience to the circle previously bound to the chosen glyph.
572###### Set Audience to Ship
574syntax `;~ship`
576Set audience to another ship.
578###### Set Audience to Own Circle
580Syntax: `;%circle`
582Set audience to a circle on your own ship
584###### Set Audience + Send Message
586Syntax: `;~dannum-mitryl this is a private message`
588Set the audience and send a post in the same line. This works for all of the
589above audience commands.
591Your audience is configured with regard to the following rules (in order):
593- if you manually set the audience, that audience.
594- if you activated a post, the post you activated.
595- audience of the last post sent.
597### Local nicknames
599###### See Nicknames
601Syntax: `;nick`
603List all local nicknames.
605###### Find Nickname
607Syntax: `;nick ~some-urbit`
609Look up a nickname using the known ship-name.
611###### Reverse Find Nickname
613syntax: `;nick plato`
615Find a ship's name using its nickname.
617###### Set Nickname
619Syntax: `;nick ~some-urbit plato`
621Create a new nickname.
623###### Clear Nickname
625Syntax: `;nick ~some-urbit ~`
627Clear an assigned nickname.
629###### Display Nicks, Not Ship-Names
631Syntax: `;set nicks`
633Show nicknames instead of ship-names. If no local nickname is set, uses
634that user's handle. If the user has no handle, just the urbit name.
636###### Display Ship-Names, Not Nicks
638Syntax: `;unset nicks`
640Show ship-names instead of nicknames.
642Nicknames and handles longer than 14 character will be truncated in
643output. Nicknames are strictly local - like the names on entries in a
644phonebook.
646### Miscellaneous configuration
648###### Show Timestamps
650Syntax: `;set showtime`
652Show the timestamp for each message.
654###### Hide Timestamps
656Syntax: `;unset showtime`
658Stop showing the timestamp for each message.
660###### Change Time Zone
662Syntax: `;set timezone [+/-][hours]`
664Adjust the display of the timestamps to a specific timezone. Relative to UTC.
666###### Sound Notification On
668Syntax: `;set notify`
670Emit a terminal bell sound if your six-syllable ship name is mentioned in
671a message.
673###### Sound Notification Off
675Syntax `;unset notify`
677Do not notify when your ship name is mentioned.
679###### Set Width
681Syntax: `;set width [number]`
683Set the rendering width of `:talk` to a specific number of characters.
684(Minimum of 30.)