@@ -1,680 +0,0 @@
1−+++
2−title = "Messaging"
3−weight = 2
4−template = "doc.html"
5−+++
6−
7−Talk is the built-in frontend for the Urbit messaging and notifications
8−protocol, Hall. Today we use Hall to chat and coordinate, but it's really
9−a general purpose piece of infrastructure.
10−
11−For the time being come join us in `~dopzod/urbit-help` by using the
12−'quickstart' section below. `~dopzod` is the host ship, and `/urbit-help` is the
13−channel on that ship.
14−
15−Today, Hall is sort of like a distributed, encrypted Slack that can be
16−used from the CLI and the browser. There’s no central Hall server.
17−Any urbit can host one.
18−
19−Hall is a general purpose tool for both aggregating and publishing
20−streams of messages. Applications can use Hall as their transport
21−protocol, API connectors can push disparate data sources into Hall,
22−and so on. There are lots of things a distributed message protocol can
23−be used for that we haven't even thought of.
24−
25−Here we'll be discussing how to operate the default CLI frontend, Talk,
26−to send and receive messages. For a more in-depth look at Hall's internals,
27−take a look at its [documentation](@/docs/learn/arvo/hall.md).
28−
29−## Quickstart
30−
31−The most common uses of Talk right now are communicating over a public chat channel called `~dopzod/urbit-help` and sending direct messages. Everyone is more than welcome in `~dopzod/urbit-help`. It's the place to get help, ask questions and chat about Urbit in general.
32−
33−There are two ways of using Talk: from the terminal running the Urbit process, or through the Landscape web UI available at `http://localhost/~~/landscape`.
34−
35−If you're using Landscape for the first time, you'll need to enter a code to gain access. You can obtain this code by running `+code` from the Dojo.
36−
37−### Joining a Channel
38−
39−In Hall, a medium for a message is called a _circle_. There are four types of circles, but we for now we'll be dealing with the _channel_: a publicly accessible chatroom for general use. We'll discuss the other three kinds in the [manual](#manual) section.
40−
41−Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from Dojo to Talk.
42−
43−Then:
44−
45−```
46−~your-urbit:talk> ;join ~dopzod/urbit-help
47−```
48−
49−Scrolling down your terminal window, you'll probably see the playback of
50−previous `~dopzod/urbit-help` messages that you missed.
51−
52−Post a line to `~dopzod/urbit-help:`
53−
54−```
55−~your-urbit:talk= Hello, world!
56−```
57−
58−You'll see your message printed below messages from others that came before it:
59−
60−```
61−~your-urbit= Hello, world!
62−```
63−
64−### Subscribing to a Channel in Landscape
65−
66−In Landscape, you can always navigate to a channel by opening the menu, or using the shortcut `cmd-k`, then typing `go ~host-urbit/channel-name`. However, if you want to see messages in your inbox, you'll need to join from the Talk terminal.
67−
68−Again, that's:
69−
70−```
71−;join ~dopzod/urbit-help
72−```
73−
74−Now, navigate to `localhost/~~/landscape`. You should see recent messages under the "Recent" tab, and if you navigate to the "All" tab, you should see your subscription to `~dopzod/urbit-help` under "Chats".
75−
76−### Direct Messaging
77−
78−To send a direct message to someone, first set your audience:
79−
80−```
81−~your-urbit:talk= ;~talsur-todres
82−```
83−
84−You'll see your prompt change:
85−
86−```
87−~your-urbit:talk[~talsur-todres]
88−```
89−
90−Now you and `~talsur-todres` can exchange messages directly.
91−
92−```
93−~your-urbit:talk[~talsur-todres] Hey buddy!
94−```
95−
96−To set your audience back to `~dopzod/urbit-help`:
97−
98−```
99−~your-urbit:talk[~talsur-todres] ;~dopzod/urbit-help
100−```
101−
102−You'll see your prompt change back:
103−
104−```
105−~your-urbit:talk=
106−```
107−
108−You can also use the ASCII "glyph" assigned to your `~dopzod/urbit-help` circle as a shortcut:
109−
110−```
111−~your-urbit:talk[~talsur-todres] ;=
112−~your-urbit:talk=
113−```
114−
115−(Your ship may have a different glyph than `=` for your circle)
116−
117−Use `;leave` to unsubscribe from a channel:
118−
119−```
120−~your-urbit:talk= ;leave ~dopzod/urbit-help
121−```
122−
123−The web UI ships as compiled JavaScript on your urbit, but has its own
124−source repo [here](https://github.com/urbit/talk).
125−
126−Last, let's create a channel we can invite some friends to:
127−
128−```
129−~your-urbit:talk= ;create channel %my-channel 'Some description.'
130−```
131−
132−Now you can tell your friends to `;join ~your-urbit/my-channel`.
133−
134−---
135−
136−## Manual
137−
138−Hall's design is similar in spirit to
139−[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
140−the underlying protocol for Usenet.
141−
142−Our design is pretty simple: Hall messages are called _posts_. Posts
143−go to _circles_. Any urbit can host or subscribe to any number of circles.
144−
145−There are four kinds of circles: a write-only `%mailbox` for direct
146−messages, an invite-only `%village` for private conversation, a read-only
147−`%journal` for curated content, and a public-access `%channel` for
148−general use.
149−
150−### Posts
151−
152−A post can be a variety of different data structures. Let's look at the
153−ones you can use from within Talk: lines, URLs, Hoon and replies.
154−
155−#### Lines
156−
157−A line is simply a string of text. Depending on the filtering rules set
158−by the circle's host, these may or may not include uppercase and Unicode
159−characters (see [filter](#filter)).
160−
161−If the line starts with `@`, it's an action (like `/me` in IRC).
162−
163−```
164−~your-urbit:talk= @sends a message.
165−```
166−
167−will print as
168−
169−```
170−~your-urbit sends a message.
171−```
172−
173−#### URLs
174−
175−A URL is any valid URL.
176−
177−```
178−~your-urbit:talk= https://example.com/
179−```
180−
181−#### Hoon
182−
183−You can use Talk to evaluate Hoon code and share the result with everyone in a
184−Hall circle. To do so, preface your Hoon with `#`.
185−
186−```
187−~your-urbit:talk= #(add 2 2)
188−```
189−
190−will print as
191−
192−```
193−~your-urbit# (add 2 2)
194−4
195−```
196−
197−#### Replies
198−
199−To indicate what you're saying is in direct response to a specific message, select the message (see Activating Lines below) and type your response.
200−
201−```
202−~some-urbit= Hello! How are you?
203−~your-urbit:talk= ; Well, thanks!
204−```
205−
206−will print as
207−
208−```
209−~your-urbit=^ Well, thanks!
210−```
211−
212−### Activating Lines
213−
214−A line number identifying the **subsequent** line is displayed every 5
215−lines.
216−
217−```
218−---------[0]
219−~your-urbit= This is my message.
220−~your-urbit= This is another message.
221−~your-urbit sends a message.
222−~your-urbit/ http://example.com/
223−~your-urbit# (add 2 2)
224− 4
225−---------[5]
226−~your-urbit=^ That's my message!
227−```
228−
229−You can use a line number to **activate** a line:
230−
231−```
232−~your-urbit:talk= ;5
233−```
234−
235−which prints the number, line identifier, timestamp, sender, audience,
236−and contents:
237−
238−```
239−? 0
240−0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
241−~your-urbit to ~another-urbit
242−in reply to: ~your-urbit:
243−> This is my message.
244−That's my message!
245−```
246−
247−If information got truncated — like what happens for long URLs or expressions,
248−or if there's additional information available — as is the case with
249−replies and attachments (e.g. stack traces) — activating the message will show
250−you all the details.
251−
252−You can also activate the most recent line with `;`, the second-most recent
253−with `;;`, and so on.
254−
255−### Creating and managing circles
256−
257−As mentioned before, any urbit can host any number of circles. Existing circles
258−can be deleted or modified with various commands. All commands in this section
259−shoild be sent from the `talk>` prompt.
260−
261−#### Create
262−
263−Syntax: `;create [type] %name 'description'`
264−
265−Creates and joins a circle, where `[type]` is any of the following:
266−- `channel`: public circle. Has a blacklist for write control.
267−- `village`: invite-only circle.
268−- `journal`: publicly readable, invite-only for writing.
269−- `mailbox`: publicly writeable, can only be read by its host.
270−
271−Let's create an example mailbox:
272−
273−```
274−sampel-palnet:talk> ;create mailbox %coolbox 'cool messages only'
275−```
276−
277−Something like this should print:
278−
279−```
280−--------------| ;create mailbox %coolbox 'cool messages only'
281−--------------| :: onn %coolbox
282−--------------| bound '>' {[hos=~sampel-palnet nom=%coolbox]}
283−--------------| %coolbox: see ~sampel-palnet hear
284−--------------| new > %coolbox
285−--------------| %coolbox: cap: cool messages only
286−--------------| %coolbox: fit: caps:Y unic:â
287−```
288−
289−###### Delete
290−
291−Syntax: `;delete %name 'optional reason'`
292−
293−Deletes a circle. If a reason is specified, that gets sent to all
294−subscribers before the circle gets deleted.
295−
296−To delete our example above:
297−
298−```
299−sampel-palnet:talk> ;delete %coolbox 'people sent uncool messages'
300−```
301−
302−#### Change Description
303−
304−Syntax: `;depict %name 'description'`
305−
306−Changes the description of an existing circle `%name`.
307−
308−For example:
309−
310−```
311−sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'
312−```
313−
314−
315−#### Filter
316−
317−Syntax: `;filter %name [capitals] [unicode]`
318−
319−Configures the message filter for circle `%name`: whether to allow
320−capital and/or unicode characters. `y`/`&`/`true` for allowed,
321−`n`/`|`/`false` for disallowed.
322−
323−So, to allow capital letters and disallow unicode in the circle `%coolbox`:
324−
325−```
326−sampel-palnet:talk> ;filter %coolbox & |
327−```
328−or
329−```
330−sampel-palnet:talk> ;filter %coolbox y n
331−```
332−
333−And we get the output:
334−
335−```
336−--------------| ;filter %coolbox & |
337−--------------| %coolbox: fit: caps:Y unic:n
338−```
339−
340−#### Invite
341−
342−Syntax: `;invite %name ~someone`
343−
344−Invites someone into your circle `%name`. If they were previously banished,
345−removes them from the blacklist.
346−Can also invite multiple ships at once, `~comma, ~separated`.
347−
348−For example:
349−
350−```
351−~sampel-palnet:talk> ;invite %coolbox ~lodleb-ritrul
352−```
353−
354−#### Banish
355−
356−Syntax: `;banish %name ~someone`
357−
358−Removes someone from your circle `%name`. If they were previously invited,
359−removes them from the whitelist.
360−Can also banish multiple ships at once, `~comma, ~separated`.
361−
362−#### Source
363−
364−Syntax: `;source %name ~other/circle`
365−
366−Adds `~other/circle` as a source for circle `%name`. This causes all
367−messages sent to `~other/circle` to also appear in `%name`.
368−
369−For example:
370−
371−```
372−~sampel-palnet:talk> ;source %coolbox ~marzod/urbit-help
373−```
374−
375−#### Unsource
376−
377−Syntax: `;unsource %name ~other/circle`
378−
379−Removes `~other/circle` as a source for circle `%name`.
380−
381−For example:
382−
383−```
384−~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-help
385−```
386−
387−### Circle Membership
388−
389−If you have joined a circle, you can make this information publicly
390−available to help others find that circle as well.
391−
392−#### Show Membership
393−
394−Syntax: `;show ~some/circle`
395−
396−Adds a circle to your public membership list on your Hall profile. Hall profiles
397−are not used yet.
398−
399−#### Hide Membership
400−
401−Syntax: `;hide ~some/circle`
402−
403−Removes a circle from your public membership list on your Hall profile. Hall
404−profiles are not used yet.
405−
406−### Status
407−
408−You'll see status notifications when people enter or leave circles you're
409−subscribed to.
410−
411−#### Notifications Off
412−
413−Syntax: `;set quiet`
414−
415−Turn off status (and config) notifications.
416−
417−#### Notifications On
418−
419−Syntax: `;unset quiet`
420−
421−Turn on status (and config) notifications.
422−
423−#### Who
424−
425−Syntax: `;who`
426−
427−List everyone in all your subscribed circles. Optionally specify a
428−specific circle to list members of just those: `;who ~some/circle`
429−
430−For example:
431−
432−```
433−~sampel-palnet:talk> ;who ~marzod/urbit-help
434−```
435−
436−#### Attend
437−
438−Syntax: `;attend ~some/circle [presence]`
439−
440−Manually set your presence to show up as one of the following. (In the
441−future, a sufficiently advanced client can automatically set these for
442−you.)
443−
444−- `talk` - typing
445−- `hear` - listening
446−- `idle` - inactive
447−- `gone` - not present
448−
449−For example:
450−
451−```
452−~sampel-palnet:talk> ;attend ~marzod/urbit-help idle
453−```
454−
455−#### Set Display Name
456−
457−Syntax: `;name ~some/circle 'my handle'`
458−
459−Set a handle ("name") for yourself in a specific circle. It will display
460−to users who have done `;set nicks`, but gets truncated if it's longer
461−than 14 characters.
462−
463−## Audience
464−
465−An audience consists of one or more messaging targets. These can be
466−circles or ships. (In the latter case, it's secretly the `~ship/inbox`
467−circle.)
468−
469−### Circle Glyphs
470−
471−Glyphs are found at the end of your prompt to as a quick indicator of where
472−your messages will be sent.
473−
474−Glyphs are assigned by circle hash out of the following list:
475−
476−```
477−> = + - } ) , . " ' ^ $ % & @
478−```
479−
480−Alphanumeric characters and `|#;:*~_` are reserved; all others (the
481−above list, and `\/!?({<`) can be manually assigned.
482−
483−For example, `-` the glyph at the end of the prompt below might indicates that
484−messages sent from this prompt will go to some circle with that glyph:
485−
486−```
487−~sampel-palnet:talk-
488−```
489−
490−To see what circle is bound to a glyph, use the `;what` command followed by the
491−glyph in question, or use `;what` without specifying a glyph to see all of your
492−subscriptions which are bound to glyphs. For example, to see `=`:
493−
494−```
495−~sampel-palnet:talk> ;what =
496−~dopzod/urbit-help
497−```
498−
499−To see all of your glyph-bound subscriptions:
500−
501−```
502−~sampel-palnet:talk> ;what
503−> ~paldev/numismatic-forum
504−. ~middev/ny-martians
505−= ~dopzod/urbit-help
506−```
507−
508−Not every audience has a glyph, however. When the audience doesn't have a glyph,
509−such as in the case of direct-messaging a ship, we see their name at the end of
510−the prompt instead. Here we're talking directly to `~dannum-mitryl`:
511−
512−```
513−~sampel-palnet:talk[~dannum-mitryl]
514−```
515−
516−#### Bind
517−
518−Syntax: `;bind [glyph] /circle-name`
519−
520−Assigns the chosen glyph to a circle owned by your ship.
521−
522−For example:
523−
524−```
525−~sampel-palnet:talk> ;bind + /my-circle
526−```
527−
528−#### Unbind
529−
530−Syntax: `;unbind [glyph] /circle-name`
531−
532−Unassigns the chosen glyph from a circle owned by your ship.
533−
534−For example:
535−
536−```
537−~sampel-palnet:talk> ;unbind + /my-circle
538−```
539−
540−### Prefixes
541−
542−Received posts are prefixed with a glyph to let you know what the
543−audience is. You can activate an individual post to see the full
544−audience.
545−
546−There are a few special-purpose glyphs:
547−
548−- `|` - Informational messages
549−- `:` - Posts directly to you
550−- `;` - Posts to you and others (a multiparty conversation)
551−- `*` - Posts to a complex audience that doesn't directly include you.
552−
553−
554−### Configuration
555−
556−#### Set Audience
557−
558−`;~ship/circle`
559−
560−Set audience to `~ship/circle`.
561−
562−#### Set Audience by Glyph
563−
564−Syntax: `;[glyph]`
565−
566−Set audience to the circle previously bound to the chosen glyph.
567−
568−#### Set Audience to Ship
569−
570−syntax `;~ship`
571−
572−Set audience to another ship.
573−
574−#### Set Audience to Own Circle
575−
576−Syntax: `;%circle`
577−
578−Set audience to a circle on your own ship
579−
580−#### Set Audience + Send Message
581−
582−Syntax: `;~dannum-mitryl this is a private message`
583−
584−Set the audience and send a post in the same line. This works for all of the
585−above audience commands.
586−
587−Your audience is configured with regard to the following rules (in order):
588−
589−- if you manually set the audience, that audience.
590−- if you activated a post, the post you activated.
591−- audience of the last post sent.
592−
593−### Local nicknames
594−
595−#### See Nicknames
596−
597−Syntax: `;nick`
598−
599−List all local nicknames.
600−
601−#### Find Nickname
602−
603−Syntax: `;nick ~some-urbit`
604−
605−Look up a nickname using the known ship-name.
606−
607−#### Reverse Find Nickname
608−
609−syntax: `;nick plato`
610−
611−Find a ship's name using its nickname.
612−
613−#### Set Nickname
614−
615−Syntax: `;nick ~some-urbit plato`
616−
617−Create a new nickname.
618−
619−#### Clear Nickname
620−
621−Syntax: `;nick ~some-urbit ~`
622−
623−Clear an assigned nickname.
624−
625−#### Display Nicks, Not Ship-Names
626−
627−Syntax: `;set nicks`
628−
629−Show nicknames instead of ship-names. If no local nickname is set, uses
630−that user's handle. If the user has no handle, just the urbit name.
631−
632−#### Display Ship-Names, Not Nicks
633−
634−Syntax: `;unset nicks`
635−
636−Show ship-names instead of nicknames.
637−
638−Nicknames and handles longer than 14 character will be truncated in
639−output. Nicknames are strictly local - like the names on entries in a
640−phonebook.
641−
642−### Miscellaneous configuration
643−
644−#### Show Timestamps
645−
646−Syntax: `;set showtime`
647−
648−Show the timestamp for each message.
649−
650−#### Hide Timestamps
651−
652−Syntax: `;unset showtime`
653−
654−Stop showing the timestamp for each message.
655−
656−#### Change Time Zone
657−
658−Syntax: `;set timezone [+/-][hours]`
659−
660−Adjust the display of the timestamps to a specific timezone. Relative to UTC.
661−
662−#### Sound Notification On
663−
664−Syntax: `;set notify`
665−
666−Emit a terminal bell sound if your six-syllable ship name is mentioned in
667−a message.
668−
669−#### Sound Notification Off
670−
671−Syntax `;unset notify`
672−
673−Do not notify when your ship name is mentioned.
674−
675−#### Set Width
676−
677−Syntax: `;set width [number]`
678−
679−Set the rendering width of `:talk` to a specific number of characters.
680−(Minimum of 30.)