git.iko.soy/urbit.org
on bfec220 help sign in
urbit.org/using/messaging.md
679 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 `/urbit-help` by using the
11'quickstart' section below.
13Today, Hall is sort of like a distributed, encrypted Slack that can be
14used from the CLI and the browser. There’s no central Hall server.
15Any urbit can host one.
17Hall is a general purpose tool for both aggregating and publishing
18streams of messages. Applications can use Hall as their transport
19protocol, API connectors can push disparate data sources into Hall,
20and so on. There are lots of things a distributed message protocol can
21be used for that we haven't even thought of.
23Here we'll be discussing how to operate the default CLI frontend, Talk,
24to send and receive messages. For a more in-depth look at Hall's internals,
25take a look at its [documentation](../hall).
27## Quickstart
29The most common use of talk right now is as a single-instance of Slack: one main
30channel (`/urbit-help`) and direct messages. Everyone is more than welcome
31in `/urbit-help`. It's the place to get help, ask questions and chat about
32Urbit in general.
34There are two ways of using Talk: from the terminal running the Urbit process,
35or through a web UI available at `http://localhost:8080/~~/talk`. This
36quick-start guide will cover the first method.
38##### Joining a Channel
40In Hall, a medium for a message is called a _circle_. There are four types of
41circles, but we for now we'll be dealing with the _channel_: a publicly
42accessible chatroom for general use. We'll discuss the other three
43kinds in the [manual](#manual) section.
45Let's join the `/urbit-help` channel. Use `ctrl-x` to switch from Dojo to Talk.
46Then, :
48```
49~your-urbit:talk> ;join /urbit-help
50```
52You'll see something like:
54```
55--------------| ;join /urbit-help
56--------------| :: onn /urbit-help
57--------------| bound '=' {[hos=~binzod nom=%urbit-help]}
58--------------| new = /urbit-help
59--------------| /urbit-help: cap: For Urbit-related discussion. Politically
60 | correct and safe for work. Don't be rude.
61--------------| /urbit-help: fit: caps:n unic:n
62~your-urbit:talk=
63```
65Scrolling down your terminal window, you'll probably also see the playback of
66previous `/urbit-help` messages that you missed.
68Post a line to `/urbit-help`:
70```
71~your-urbit:talk= Hello, world!
72```
74You'll see your message printed below messages from others that came before it:
76```
77~your-urbit= Hello, world!
78```
80##### Direct Messaging
82To send a direct message to someone, first set your audience:
84```
85~your-urbit:talk= ;~talsur-todres
86```
88You'll see your prompt change:
90```
91~your-urbit:talk[~talsur-todres]
92```
94Now you and `~talsur-todres` can exchange messages directly.
96```
97~your-urbit:talk[~talsur-todres] Hey buddy!
98```
100To set your audience back to `/urbit-help`:
102```
103~your-urbit:talk[~talsur-todres] ;/urbit-help
104```
106You'll see your prompt change back:
108```
109~your-urbit:talk=
110```
112You can also use the ASCII "glyph" assigned to your `/urbit-help` circle as a shortcut:
114```
115~your-urbit:talk[~talsur-todres] ;=
116~your-urbit:talk=
117```
119(Your ship may have a different glyph than `=` for your circle)
121Use `;leave` to unsubscribe from a channel:
123```
124~your-urbit:talk= ;leave /urbit-help
125```
127The web UI ships as compiled JavaScript on your urbit, but has its own
128source repo [here](https://github.com/urbit/talk).
130Last, let's create a channel we can invite some friends to:
132```
133~your-urbit:talk= ;create channel %my-channel 'Some description.'
134```
136Now you can tell your friends to `;join ~your-urbit/my-channel`.
138---
140;h2
141 ;div(id "manual"): Manual
142==
144Hall's design is similar in spirit to
145[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
146the underlying protocol for Usenet.
148Our design is pretty simple: Hall messages are called _posts_. Posts
149go to _circles_. Any urbit can host or subscribe to any number of circles.
151There are four kinds of circles: a write-only `%mailbox` for direct
152messages, an invite-only `%village` for private conversation, a read-only
153`%journal` for curated content, and a public-access `%channel` for
154general use.
156### Posts
158A post can be a variety of different data structures. Let's look at the
159ones you can use from within Talk: lines, URLs, Hoon and replies.
161##### Lines
163A line is simply a string of text. Depending on the filtering rules set
164by the circle's host, these may or may not include uppercase and Unicode
165characters (see [filter](#filter)).
167If the line starts with `@`, it's an action (like `/me` in IRC).
169```
170~your-urbit:talk= @sends a message.
171```
173will print as
175```
176~your-urbit sends a message.
177```
179##### URLs
181A URL is any valid URL.
183```
184~your-urbit:talk= https://example.com/
185```
187##### Hoon
189You can use Talk to evaluate Hoon code and share the result with everyone in a
190Hall circle. To do so, preface your Hoon with `#`.
192```
193~your-urbit:talk= #(add 2 2)
194```
196will print as
198```
199~your-urbit# (add 2 2)
201```
203##### Replies
205To indicate what you're saying is in direct response to a specific
206message, select the message (see Activating Lines below) and type your
207response.
209```
210~some-urbit= Hello! How are you?
211~your-urbit:talk= ; Well, thanks!
212```
214will print as
216```
217~your-urbit=^ Well, thanks!
218```
220### Activating Lines
222A line number identifying the *subsequent* line is displayed every 5
223lines.
225```
226---------[0]
227~your-urbit= This is my message.
228~your-urbit= This is another message.
229~your-urbit sends a message.
230~your-urbit/ http://example.com/
231~your-urbit# (add 2 2)
232 4
233---------[5]
234~your-urbit=^ That's my message!
235```
237You can use a line number to *activate* a line:
239```
240~your-urbit:talk= ;5
241```
243which prints the number, line identifier, timestamp, sender, audience,
244and contents:
246```
247? 0
2480v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
249~your-urbit to ~another-urbit
250in reply to: ~your-urbit:
251> This is my message.
252That's my message!
253```
255If information got truncated — like what happens for long URLs or expressions,
256or if there's additional information available — as is the case with
257replies and attachments (e.g. stack traces) — activating the message will show
258you all the details.
260You can also activate the most recent line with `;`, the second-most recent
261with `;;`, and so on.
263### Creating and managing circles
265As mentioned before, any urbit can host any number of circles. Existing circles
266can be deleted or modified with various commands. All commands in this section
267shoild be sent from the `talk>` prompt.
269###### Create
271Syntax: `;create [type] %name 'description'`
273Creates and joins a circle, where `[type]` is any of the following:
274- `channel`: public circle. Has a blacklist for write control.
275- `village`: invite-only circle.
276- `journal`: publicly readable, invite-only for writing.
277- `mailbox`: publicly writeable, can only be read by its host.
279Let's create an example mailbox:
281```
282sampel-palnet:talk> ;create mailbox %coolbox 'cool messages only'
283```
285Something like this should print:
287```
288--------------| ;create mailbox %coolbox 'cool messages only'
289--------------| :: onn %coolbox
290--------------| bound '>' {[hos=~sampel-palnet nom=%coolbox]}
291--------------| %coolbox: see ~sampel-palnet hear
292--------------| new > %coolbox
293--------------| %coolbox: cap: cool messages only
294--------------| %coolbox: fit: caps:Y unic:✔
295```
297###### Delete
299Syntax: `;delete %name 'optional reason'`
301Deletes a circle. If a reason is specified, that gets sent to all
302subscribers before the circle gets deleted.
304To delete our example above:
306```
307sampel-palnet:talk> ;delete %coolbox 'people sent uncool messages'
308```
310###### Change Description
312Syntax: `;depict %name 'description'`
314Changes the description of an existing circle `%name`.
316For example:
318```
319sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'
320```
322;h6
323 ;div(id "filter"): Filter
324==
326Syntax: `;filter %name [capitals] [unicode]`
328Configures the message filter for circle `%name`: whether to allow
329capital and/or unicode characters. `y`/`&`/`true` for allowed,
330`n`/`|`/`false` for disallowed.
332So, to allow capital letters and disallow unicode in the circle `%coolbox`:
334```
335sampel-palnet:talk> ;filter %coolbox & |
336```
337or
338```
339sampel-palnet:talk> ;filter %coolbox y n
340```
342And we get the output:
344```
345--------------| ;filter %coolbox & |
346--------------| %coolbox: fit: caps:Y unic:n
347```
349###### Invite
351Syntax: `;invite %name ~someone`
353Invites someone into your circle `%name`. If they were previously banished,
354removes them from the blacklist.
355Can also invite multiple ships at once, `~comma, ~separated`.
357For example:
359```
360~sampel-palnet:talk> ;invite %coolbox ~lodleb-ritrul
361```
363###### Banish
365Syntax: `;banish %name ~someone`
367Removes someone from your circle `%name`. If they were previously invited,
368removes them from the whitelist.
369Can also banish multiple ships at once, `~comma, ~separated`.
371###### Source
373Syntax: `;source %name ~other/circle`
375Adds `~other/circle` as a source for circle `%name`. This causes all
376messages sent to `~other/circle` to also appear in `%name`.
378For example:
380```
381~sampel-palnet:talk> ;source %coolbox ~marzod/urbit-help
382```
384###### Unsource
386Syntax: `;unsource %name ~other/circle`
388Removes `~other/circle` as a source for circle `%name`.
390For example:
392```
393~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-help
394```
396### Circle Membership
398If you have joined a circle, you can make this information publicly
399available to help others find that circle as well.
401###### Show Membership
403Syntax: `;show ~some/circle`
405Adds a circle to your public membership list on your Hall profile. Hall profiles
406are not used yet.
408###### Hide Membership
410Syntax: `;hide ~some/circle`
412Removes a circle from your public membership list on your Hall profile. Hall
413profiles are not used yet.
415### Status
417You'll see status notifications when people enter or leave circles you're
418subscribed to.
420###### Notifications Off
422Syntax: `;set quiet`
424Turn off status (and config) notifications.
426###### Notifications On
428Syntax: `;unset quiet`
430Turn on status (and config) notifications.
432###### Who
434Syntax: `;who`
436List everyone in all your subscribed circles. Optionally specify a
437specific circle to list members of just those: `;who ~some/circle`
439For example:
441```
442~sampel-palnet:talk> ;who ~marzod/urbit-help
443```
445###### Attend
447Syntax: `;attend ~some/circle [presence]`
449Manually set your presence to show up as one of the following. (In the
450future, a sufficiently advanced client can automatically set these for
451you.)
453- `talk` - typing
454- `hear` - listening
455- `idle` - inactive
456- `gone` - not present
458For example:
460```
461~sampel-palnet:talk> ;attend ~marzod/urbit-help idle
462```
464###### Set Display Name
466Syntax: `;name ~some/circle 'my handle'`
468Set a handle ("name") for yourself in a specific circle. It will display
469to users who have done `;set nicks`, but gets truncated if it's longer
470than 14 characters.
472## Audience
474An audience consists of one or more messaging targets. These can be
475circles or ships. (In the latter case, it's secretly the `~ship/inbox`
476circle.)
478#### Circle Glyphs
480Glyphs are found at the end of your prompt to as a quick indicator of where
481your messages will be sent.
483Glyphs are assigned by circle hash out of the following list:
485```
486> = + - } ) , . " ' ^ $ % & @
487```
489Alphanumeric characters and `|#;:*~_` are reserved; all others (the
490above list, and `\/!?({<`) can be manually assigned.
492For example, `-` the glyph at the end of the prompt below might indicates that
493messages sent from this prompt will go to some circle with that glyph:
495```
496~sampel-palnet:talk-
497```
499To see what circle is bound to a glyph, use the `;what` command followed by the
500glyph in question. For example, to see `=`:
502```
503~sampel-palnet:talk> ;what =
504/urbit-help
505```
507Not every audience has a glyph, however. When the audience doesn't have a glyph,
508such as in the case of direct-messaging a ship, we see their name at the end of
509the prompt instead. Here we're talking directly to `~dannum-mitryl`:
511```
512~sampel-palnet:talk[~dannum-mitryl]
513```
515###### Bind
517Syntax: `;bind [glyph] /circle-name`
519Assigns the chosen glyph to a circle owned by your ship.
521For example:
523```
524~sampel-palnet:talk> ;bind + /my-circle
525```
527###### Unbind
529Syntax: `;unbind [glyph] /circle-name`
531Unassigns the chosen glyph from a circle owned by your ship.
533For example:
535```
536~sampel-palnet:talk> ;unbind + /my-circle
537```
539### Prefixes
541Received posts are prefixed with a glyph to let you know what the
542audience is. You can activate an individual post to see the full
543audience.
545There are a few special-purpose glyphs:
547- `|` - Informational messages
548- `:` - Posts directly to you
549- `;` - Posts to you and others (a multiparty conversation)
550- `*` - Posts to a complex audience that doesn't directly include you.
553### Configuration
555###### Set Audience
557`;~ship/circle`
559Set audience to `~ship/circle`.
561###### Set Audience by Glyph
563Syntax: `;[glyph]`
565Set audience to the circle previously bound to the chosen glyph.
567###### Set Audience to Ship
569syntax `;~ship`
571Set audience to another ship.
573###### Set Audience to Own Circle
575Syntax: `;%circle`
577Set audience to a circle on your own ship
579###### Set Audience + Send Message
581Syntax: `;~dannum-mitryl this is a private message`
583Set the audience and send a post in the same line. This works for all of the
584above audience commands.
586Your audience is configured with regard to the following rules (in order):
588- if you manually set the audience, that audience.
589- if you activated a post, the post you activated.
590- audience of the last post sent.
592### Local nicknames
594###### See Nicknames
596Syntax: `;nick`
598List all local nicknames.
600###### Find Nickname
602Syntax: `;nick ~some-urbit`
604Look up a nickname using the known ship-name.
606###### Reverse Find Nickname
608syntax: `;nick plato`
610Find a ship's name using its nickname.
612###### Set Nickname
614Syntax: `;nick ~some-urbit plato`
616Create a new nickname.
618###### Clear Nickname
620Syntax: `;nick ~some-urbit ~`
622Clear an assigned nickname.
624###### Display Nicks, Not Ship-Names
626Syntax: `;set nicks`
628Show nicknames instead of ship-names. If no local nickname is set, uses
629that user's handle. If the user has no handle, just the urbit name.
631###### Display Ship-Names, Not Nicks
633Syntax: `;unset nicks`
635Show ship-names instead of nicknames.
637Nicknames and handles longer than 14 character will be truncated in
638output. Nicknames are strictly local - like the names on entries in a
639phonebook.
641### Miscellaneous configuration
643###### Show Timestamps
645Syntax: `;set showtime`
647Show the timestamp for each message.
649###### Hide Timestamps
651Syntax: `;unset showtime`
653Stop showing the timestamp for each message.
655###### Change Time Zone
657Syntax: `;set timezone [+/-][hours]`
659Adjust the display of the timestamps to a specific timezone. Relative to UTC.
661###### Sound Notification On
663Syntax: `;set notify`
665Emit a terminal bell sound if your six-syllable ship name is mentioned in
666a message.
668###### Sound Notification Off
670Syntax `;unset notify`
672Do not notify when your ship name is mentioned.
674###### Set Width
676Syntax: `;set width [number]`
678Set the rendering width of `:talk` to a specific number of characters.
679(Minimum of 30.)