@@ -11,23 +11,27 @@ title: Messaging (:talk)
12<div class="col-md-8">
12<div class="col-md-8">
14−`:talk` is the Urbit messaging and notifications protocol. Today we use
14+`:talk` is the built-in frontend for the Urbit messaging and notifications
15−`:talk` just to chat and coordinate, but it's really a general purpose
15+protocol, `:hall`. Today we use `:hall` just to chat and coordinate, but
16−piece of infrastructure.
16+it's really a general purpose piece of infrastructure.
18For the time being come join us in `/urbit-meta` by using the
18For the time being come join us in `/urbit-meta` by using the
19<a href="#-quickstart">quickstart</a> below.
19<a href="#-quickstart">quickstart</a> below.
21−Today `:talk` is sort of like a distributed, encrypted Slack that can be
21+Today `:hall` is sort of like a distributed, encrypted Slack that can be
22−used from the CLI and the browser. There’s no central `:talk` server.
22+used from the CLI and the browser. There’s no central `:hall` server.
23Any Urbit can host one.
23Any Urbit can host one.
25−`:talk` is a general purpose tool for both aggregating and publishing
25+`:hall` is a general purpose tool for both aggregating and publishing
26−streams of messages. Applications can use `:talk` as their transport
26+streams of messages. Applications can use `:hall` as their transport
27−protcol, API connectors can push disparate data sources into `:talk`,
27+protocol, API connectors can push disparate data sources into `:hall`,
28and so on. There are lots of things a distributed message protocol can
28and so on. There are lots of things a distributed message protocol can
29be used for that we haven't even thought of.
29be used for that we haven't even thought of.
31+Here we'll be discussing how to operate the default CLI frontend, `:talk`,
32+to send and receive messages. For a more in-depth look at `:hall`'s
33+internals, take a look at its [documentation](#TODO).
@@ -35,36 +39,29 @@ be used for that we haven't even thought of.
35## Quickstart
39## Quickstart
37For the most part we use `:talk` as a single-instance of Slack: one main
41For the most part we use `:talk` as a single-instance of Slack: one main
38−channel (`/urbit-meta`) and dms. Everyone is more than welcome in
42+channel (`/urbit-meta`) and direct messages. Everyone is more than welcome
39−`/urbit-meta`. It's the place to get help, ask questions and chat about
43+in `/urbit-meta`. It's the place to get help, ask questions and chat about
40Urbit in general.
44Urbit in general.
42Let's join `/urbit-meta`:
46Let's join `/urbit-meta`:
44Use `ctrl-x` to switch from `:dojo` to `:talk`.
48Use `ctrl-x` to switch from `:dojo` to `:talk`.
48− ~your-urbit:talk> ;join /urbit-meta
50+To join `/urbit-meta`:
52− ~your-really-long-urbit:talk> ;join ~binzod/urbit-meta
52+ ~your-urbit:talk[] ;join /urbit-meta
54You'll see:
54You'll see:
56− ---------:talk| %porch subscribed to /urbit-meta, called `>`
56+ --------------| ;join /urbit-meta
57− ---------:talk| rules of /urbit-meta:
57+ --------------| new glyph '>'
58− ---------:talk| don't be rude
59− ---------:talk| urbit-meta is politically correct and safe for work
60− ~binzod= ~your-urbit admitted to %urbit-meta
61 ~your-urbit:talk>
58 ~your-urbit:talk>
63Post a line to `/urbit-meta`:
60Post a line to `/urbit-meta`:
65 ~your-urbit:talk> hello, world
62 ~your-urbit:talk> hello, world
67−You'll see, echoed back at you through `~binzod`:
64+You'll see, echoed back at you:
69 ~your-urbit> hello, world
66 ~your-urbit> hello, world
@@ -80,11 +77,11 @@ Now you and `~talsur-todres` can exchange messages directly.
81To set your audience back to `/urbit-meta`:
78To set your audience back to `/urbit-meta`:
83− ~your-urbit:talk> ;~binzod/urbit-meta
80+ ~your-urbit:talk> ;/urbit-meta
85Use `;leave` to unsubscribe from a channel:
82Use `;leave` to unsubscribe from a channel:
87− ~your-urbit:talk> ;leave ~binzod/urbit-meta
84+ ~your-urbit:talk> ;leave /urbit-meta
89There are two ways of using `:talk`: from the CLI or through a web ui
86There are two ways of using `:talk`: from the CLI or through a web ui
90available at `http://your-urbit.urbit.org/talk` (or
87available at `http://your-urbit.urbit.org/talk` (or
@@ -101,51 +98,67 @@ Now you can tell your friends to `;join ~your-urbit/my-channel`.
104−`:talk`'s design is similar in spirit to
101+`:hall`'s design is similar in spirit to
105[nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
102[nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
106the underlying protocol for Usenet.
103the underlying protocol for Usenet.
108−Our design is pretty simple: `:talk` messages are called ‘posts’. Posts
105+Our design is pretty simple: `:hall` messages go to ‘circles’. Any urbit
109−go to ‘stations’. Any urbit can host or subscribe to any number of
106+can host or subscribe to any number of circles.
112−There are four kinds of stations: a write-only `%mailbox` for direct
108+There are four kinds of circles: a write-only `%mailbox` for direct
113−messages, an invite-only `%party` for private conversation, a read-only
109+messages, an invite-only `%village` for private conversation, a read-only
114`%journal` for curated content, and a public-access `%channel` for
110`%journal` for curated content, and a public-access `%channel` for
115general use.
111general use.
119−For the time being a post is either a line, a URL or a command.
115+A post can be a variety of different data structures. Let's look at the
116+ones you can use from within `:talk`: lines, URLs, expressions and
121#### Lines
119#### Lines
123−A line is 64 bytes of ASCII lowercase, spaces and punctuation. If the
121+A line is simply a string of text. Depending on the filtering rules set
122+by the circle's host, these may or may not include uppercase and Unicode
124−line starts with '@', it's an action (IRC `/me`).
124+If the line starts with `@`, it's an action (IRC `/me`).
126−The `:talk` interface will let you keep typing past 64 bytes, but insert
127−a Unicode bullet-point character in an appropriate space in your post,
128−to show you the prospective linebreak. Your essay will be posted in
131− ~your-urbit:talk> this is a long message, so it will by truncated right at this•spot
126+ ~your-urbit:talk> @sends a message
133will print as
128will print as
135− ~your-urbit; this is a long message, so it will by truncated right at this
130+ ~your-urbit sends a message
140A URL is any valid URL.
134A URL is any valid URL.
142− ~your-urbit:talk> http://example.com
136+ ~your-urbit:talk> http://example.com/
140+Expressions can be used to show and evaluate Hoon code. Send an expression
141+by prefacing your message with `#`.
143+ ~your-urbit:talk> #(add 1 2)
147+ ~your-urbit# (add 1 2)
144−### Commands
150+### Replies
146−A command is a hoon expression, prefaced by '\#'.
152+To indicate what you're saying is in direct response to a specific
153+message, select the message (see Activating Lines below) and type your
156+ ~some-urbit> hello! how are you?
148− ~your-urbit:talk> #(add 2 2)
157+ ~your-urbit:talk> ; good, thanks!
161+ ~your-urbit>^ good, thanks!
150### Activating Lines
163### Activating Lines
@@ -153,17 +166,18 @@ A line number identifying the *subsequent* line is displayed every 5
155 ---------[0]
168 ---------[0]
156− ~your-urbit; this is my message
169+ ~your-urbit> this is my message
157− ~your-urbit@ this is an @ message
170+ ~your-urbit> this is another message
158− ~your-urbit; this is a long message, so it will by truncated right at this
171+ ~your-urbit sends a message
160 ~your-urbit/ http://example.com/
172 ~your-urbit/ http://example.com/
173+ ~your-urbit# (add 1 2)
161 ---------[5]
175 ---------[5]
162− ~your-urbit# (add 2 2) 4
176+ ~your-urbit>^ that's my message!
164You can use a line number to *activate* a line:
178You can use a line number to *activate* a line:
166− ~your-urbit:talk> ;0
180+ ~your-urbit:talk> ;5
168which prints the number, line identifier, timestamp, sender, audience,
182which prints the number, line identifier, timestamp, sender, audience,
169and contents:
183and contents:
@@ -171,64 +185,132 @@ and contents:
172 0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
186 0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
173 ~your-urbit to ~another-urbit
187 ~your-urbit to ~another-urbit
188+ in reply to: ~your-urbit:
174− this is my message
189+ > this is my message
176−Activating a URL will print the full URL (it could have been truncated),
192+If information got truncated — like happens for long URLs or expressions —
177−and activating a command will evaluate it.
193+or if there's additional information available — as is the case with
194+replies and attachments — activating the message will show you all the
179You can activate the most recent line with `;`, the second-most recent
197You can activate the most recent line with `;`, the second-most recent
180with `;;`, and so on.
198with `;;`, and so on.
182−### Creating and managing stations
200+### Creating and managing circles
202+`;create [type] %name 'description'`
203+Creates and joins a circle, where `[type]` is any of the following:
204+- `channel`: public circle. Has a blacklist for write control.
205+- `village`: invite-only circle.
206+- `journal`: publicly readable, invite-only for writing.
207+- `mailbox`: publicly writeable, can only be read by its host.
209+`;delete %name 'optional reason'`
210+Deletes a circle. If a reason is specified, that gets sent to all
211+subscribers before the circle gets deleted.
213+`;depict %name 'description'`
214+Changes the description of circle `%name`.
216+`;filter %name [capitals] [unicode]`
217+Configures the message filter for circle `%name`: whether to allow
218+capital and/or unicode characters. `y`/`&`/`true` for allowed,
219+`n`/`|`/`false` for disallowed.
221+`;invite %name ~someone`
222+Invite someone into your circle `%name`. If they were previously banished,
223+removes them from the blacklist.
224+Can also invite multiple ships at once, `~comma, ~separated`.
226+`;banish %name ~someone`
227+Banish someone from your circle `%name`. If they were previously invited,
228+removes them from the whitelist.
229+Can also banish multiple ships at once, `~comma, ~separated`.
184−`;create journal %serious-journal 'description'` - Creates a `%journal`,
231+`;source %name ~other/circle`
185−a privately writable publicly readable station.
232+Adds `~other/circle` as a source for circle `%name`. This causes all
233+messages sent to `~other/circle` to also appear in `%name`.
187−`;create channel %serious-channel 'description'` - Creates a `%channel`,
235+`;unsource %name ~other/circle`
188−a publicly readable publicly writeable station.
236+Removes `~other/circle` as a source for circle `%name`.
240+If you have joined a circle, you can make this information publicly
241+publicly available to help others find that circle as well.
244+Adds a circle to your public membership list.
247+Removes a circle from your public membership list.
190### Presence
249### Presence
192You'll see presence notifications when people enter or leave stations
251You'll see presence notifications when people enter or leave stations
193you're subscribed to.
252you're subscribed to.
195−`;set quiet` - Turn off presence notifications
255+Turn off presence notifications
258+Turn on presence notifications
197−`;unset quiet` - Turn on presence notifications
260+`;who`
261+List everyone in all your subscribed circles. Optionally specify a
262+specific circle to list members of just those.
264+`;attend ~some/circle [presence]`
265+Manually set your presence to show up as one of the following. (In the
266+future, a sufficiently advanced client can automatically set these for
271+- `gone` - not present
273+`;name ~some/circle 'my nickname'`
274+Set a nickname for yourself in a specific circle. It will display to users
275+who have done `;set nick`.
199−`;who` - list everyone in all your stations
279+An audience consists of one or more messaging targets. These can be
280+circles or ships. (In the latter case, it's secretly the `~ship/inbox`
201−### Station Glyphs
283+### Circle glyphs
203−Glyphs are assigned by station hash out of the following list
285+Glyphs are assigned by circle hash out of the following list
205 > = + - } ) , . " ' ^ $ % & @
287 > = + - } ) , . " ' ^ $ % & @
207Alphanumeric characters and `|#;:*~_` are reserved; all others (the
289Alphanumeric characters and `|#;:*~_` are reserved; all others (the
208−above lists, and `\/!?({<`) can be manually assigned.
290+above list, and `\/!?({<`) can be manually assigned.
292+`;bind + /urbit-test`
210−`;bind > /urbit-test` - assigns the `>` glyph to `/urbit-test`.
293+Assigns the `+` glyph to `/urbit-test`.
295+`;unbind + /urbit-test`
296+Unassigns the `+` glyph from `/urbit-test`.
212−To see what station is bound to a glyph:
298+To see what circle is bound to a glyph:
215− {[%.y p=[p=~binzod q=~.urbit-meta]]}
301+ /urbit-test
217### Prefixes
303### Prefixes
219Received posts are prefixed with a glyph to let you know what the
305Received posts are prefixed with a glyph to let you know what the
220audience is. You can activate an individual post to see the full
306audience is. You can activate an individual post to see the full
221−audience.
307+audience.
222−
308+There are a few special-purpose glyphs.
223−`|` - Informational messages
225−`:` - Posts directly to you
310+- `|` - Informational messages
311+- `:` - Posts directly to you
227−`;` - Posts to you and others (a multiparty conversation)
312+- `;` - Posts to you and others (a multiparty conversation)
229−`*` - Posts to a complex audience that doesn't directly include you.
313+- `*` - Posts to a complex audience that doesn't directly include you.
233#### Prompt
315#### Prompt
@@ -241,20 +323,24 @@ Here we're talking to the station bound to `=`:
242Here we're talking directly to `~dannum-mitryl`:
324Here we're talking directly to `~dannum-mitryl`:
244− ~your-urbit:talk(~dannum-mitryl)
326+ ~your-urbit:talk[~dannum-mitryl]
246#### Configuration
328#### Configuration
248−`;~urbit/station` - Set audience to `~urbit/station`
331+Set audience to `~urbit/station`.
250−`;=` - Set audience to the station bound to the `=` glyph
334+Set audience to the station bound to the `=` glyph.
252−`;~dannum-mitryl` - Set audience to `~dannum-mitryl` (a direct post).
337+Set audience to `~dannum-mitryl` (a direct post).
254−`;%station` - Set audience to a station on your own ship
340+Set audience to a station on your own ship.
256−`;~dannum-mitryl this is a private message` - Set the audience and send
342+`;~dannum-mitryl this is a private message`
257−a post in the same line. This works for all of the above.
343+Set the audience and send a post to it. This works for all of the above.
259Your audience is configured 'implicitly' with regard to the following
345Your audience is configured 'implicitly' with regard to the following
260rules (in order):
346rules (in order):
@@ -269,29 +355,48 @@ Clear any 'implicit' audience setting by moving your cursor to the start
269of the line and pressing backspace (whether the line is empty or not).
355of the line and pressing backspace (whether the line is empty or not).
270Posting a line clears the typing and activation configurations.
356Posting a line clears the typing and activation configurations.
272−### Nicknames
358+### Local nicknames
361+List all local nicknames.
274−`;nick` - list all nicknames
369+`;nick ~your-urbit plato`
276−`;nick ~your-urbit` - look up a nickname
372+`;nick ~your-urbit ~`
373+Clear an assigned nickname.
278−`;nick plato` - search in reverse
375+`;set nicks`
376+Show nicknames instead of urbit names. If no local nickname is set, uses
377+that user's self-set name.
280−`;nick ~your-urbit plato` create a nickname
379+`;unset nicks`
380+Show urbit names instead of nicknames.
282−`;nick ~your-urbit ~` clear an assigned nickname
382+Nicknames longer than 14 character will be truncated in output. Nicknames
383+are strictly local - like the names on entries in a phonebook.
284−`;set noob` show nicknames instead of urbit names
385+### Miscellaneous configuration
286−`;unset noob` show urbit names instead of nicknames
387+`;set showtime`
388+Show the timestamp for each message.
288−All nicknames must be 14 characters or less, lowercase. Nicknames are
390+`;unset showtime`
289−strictly local - like the names on entries in a phonebook. Sometimes in
391+Stop showing the timestamp for each message.
290−a post you want to mention someone you know by a nickname. Just type
291−`~plato`, and `:talk` will replace it with `~your-urbit`.
293−### Timestamps
393+`;set notify`
394+Emit a terminal bell sound if your six-syllable ship name is mentioned in
295−`;set showtime` - Show the timestamp for each message
397+`;unset notify`
398+Do not notify when your ship name is mentioned.
297−`;unset showtime` - Stop showing the timestamp for each message
400+`;set width [number]`
401+Set the rendering width of `:talk` to a specific number of characters.