git.iko.soy/urbit.org
on b5debf2 help sign in
urbit.org/docs/using/messaging.md
242 lines 7.9 kB history raw
1---
2navhome: /docs
3next: true
4sort: 4
5title: Messaging (:talk)
6---
8# Messaging (`:talk`)
10<div class="row">
11<div class="col-md-8">
13`:talk` is the Urbit messaging and notifications protocol. Today we use `:talk` just to chat and coordinate, but it's really a general purpose piece of infrastructure.
15For the time being come join us in `/urbit-meta` by using the <a href="#-quickstart">quickstart</a> below.
17Today `:talk` is sort of like a distributed, encrypted Slack that can be used from the CLI and the browser. There’s no central `:talk` server. Any Urbit can host one.
19`:talk` is a general purpose tool for both aggregating and publishing streams of messages. Applications can use `:talk` as their transport protcol, API connectors can push disparate data sources into `:talk`, and so on. There are lots of things a distributed message protocol can be used for that we haven't even thought of.
21</div>
22</div>
24## Quickstart
26For the most part we use `:talk` as a single-instance of Slack: one main channel (`/urbit-meta`) and dms. Everyone is more than welcome in `/urbit-meta`. It's the place to get help, ask questions and chat about Urbit in general.
28Let's join `/urbit-meta`:
30Use `ctrl-x` to switch from `:dojo` to `:talk`, then:
32 ~your-urbit:talk> ;join ~doznec/urbit-meta
34You'll see:
36 ---------:talk| %porch subscribed to /urbit-meta, called `>`
37 ---------:talk| rules of /urbit-meta:
38 ---------:talk| don't be rude
39 ---------:talk| urbit-meta is politically correct and safe for work
40 ~doznec= ~your-urbit admitted to %urbit-meta
41 ~your-urbit:talk>
43Post a line to `/urbit-meta`:
45 ~your-urbit:talk> hello, world
47You'll see, echoed back at you through `~doznec`:
49 ~your-urbit> hello, world
51To send a direct message to someone, first set your audience:
53 ~your-urbit:talk> ;~talsur-todres
55You'll see your prompt change:
57 ~your-urbit:talk[~talsur-todres]
59Now you and `~talsur-todres` can exchange messages directly.
61To set your audience back to `/urbit-meta`:
63 ~your-urbit:talk> ;~doznec/urbit-meta
65Use `;leave` to unsubscribe from a channel:
67 ~your-urbit:talk> ;leave ~doznec/urbit-meta
69There are two ways of using `:talk`: from the CLI or through a web ui available at `http://your-urbit.urbit.org/talk` (or `http://localhost:8080/talk`).
71The web ui ships as compiled JavaScript on your Urbit, but has its own source repo [here](https://github.com/urbit/talk).
73Last, let's create a channel we can invite some friends to:
75 ~your-urbit:talk> ;create channel %my-channel 'some description'
77Now you can tell your friends to `;join ~your-urbit/my-channel`.
79## Manual
81`:talk`'s design is similar in spirit to [nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol), the underlying protocol for Usenet.
83Our design is pretty simple: `:talk` messages are called ‘posts’. Posts go to ‘stations’. Any urbit can host or subscribe to any number of stations.
85There are four kinds of station: a write-only `%mailbox` for direct messages, an invite-only `%party` for private conversation, a read-only `%journal` for curated content, and a public-access `%channel` for general use.
87### Posts
89For the time being a post is either a line, a URL or a command.
91#### Lines
93A line is 64 bytes of ASCII lowercase, spaces and punctuation. If the line starts with '@', it's an action (IRC `/me`).
95The `:talk` interface will let you keep typing past 64 bytes, but
96insert a Unicode bullet-point character in an appropriate space
97in your post, to show you the prospective linebreak. Your essay
98will be posted in multiple lines.
100 ~your-urbit:talk> this is a long message, so it will by truncated right at this•spot
102will print as
104 ~your-urbit; this is a long message, so it will by truncated right at this
105 ~your-urbit; spot
107#### URLs
109A URL is any valid URL.
111 ~your-urbit:talk> http://example.com
113### Commands
115A command is a hoon expression, prefaced by '#'.
117 ~your-urbit:talk> #(add 2 2)
119### Activating Lines
121A line number identifying the *subsequent* line is displayed every 5 lines.
123 ---------[0]
124 ~your-urbit; this is my message
125 ~your-urbit@ this is an @ message
126 ~your-urbit; this is a long message, so it will by truncated right at this
127 ~your-urbit; spot
128 ~your-urbit/ http://example.com/
129 ---------[5]
130 ~your-urbit# (add 2 2) 4
132You can use a line number to *activate* a line:
134 ~your-urbit:talk> ;0
136which prints the number, line identifier, timestamp, sender, audience,
137and contents:
139 ? 0
140 0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
141 ~your-urbit to ~another-urbit
142 this is my message
144Activating a URL will print the full URL (it could have been truncated),
145and activating a command will evaluate it.
147You can activate the most recent line with `;`, the second-most recent with
148`;;`, and so on.
150### Creating and managing stations
152`;create journal %serious-journal 'description'` - Creates a `%journal`, a privately writable publicly readable station.
154`;create channel %serious-channel 'description'` - Creates a `%channel`, a publicly readable publicly writeable station.
156### Presence
158You'll see presence notifications when people enter or leave
159stations you're subscribed to.
161`;who` - list everyone in all your stations
163`;who station` - list everyone in that station
165### Station Glyphs
167Glyphs are assigned by station hash out of the following list
169 > = + - } ) , . " ' ^ $ % & @
171Alphanumeric characters and `|#;:*~_` are reserved; all others (the above lists, and `\/!?({<`) can be manually assigned.
173`;bind > /urbit-test` - assigns the `>` glyph to `/urbit-test`.
175### Prefixes
177Received posts are prefixed with a glyph to let you know what the audience is. You can activate an individual post to see the full audience.
179`|` - Informational messages
181`:` - Posts directly to you
183`;` - Posts to you and others (a multiparty conversation)
185`*` - Posts to a complex audience that doesn't directly include you.
187### Audience
189#### Prompt
191The audience you're sending to is always shown in your prompt. If there's a glyph for it, it's shown as the glyph.
193Here we're talking to the station bound to `=`:
195 ~your-urbit:talk=
197Here we're talking directly to `~dannum-mitryl`:
199 ~your-urbit:talk(~dannum-mitryl)
201#### Configuration
203`;~urbit/station` - Set audience to `~urbit/station`
205`;=` - Set audience to the station bound to the `=` glyph
207`;~dannum-mitryl` - Set audience to `~dannum-mitryl` (a direct post).
209`;%station` - Set audience to a station on your own ship
211`;~dannum-mitryl this is a private message` - Set the audience and send a post in the same line. This works for all of the above.
213Your audience is configured 'implicitly' with regard to the following rules (in order):
215- if you manually locked the audience, that audience.
216- if typing a post, the audience when you started typing.
217- if you activated a post, the post you activated.
218- audience of the last post received.
219- audience of the last post sent.
221Clear any 'implicit' audience setting by moving your cursor to
222the start of the line and pressing backspace (whether the line is
223empty or not). Posting a line clears the typing and activation
224configurations.
226### Nicknames
228`;nick` - list all nicknames
230`;nick ~your-urbit` - look up a nickname
232`;nick plato` - search in reverse
234`;nick ~your-urbit plato` create a nickname
236`;nick ~your-urbit ~` clear an assigned nickname
238`;set noob` show nicknames instead of urbit names
240`;unset noob` show urbit names instead of nicknames
242All nicknames must be 14 characters or less, lowercase. Nicknames are strictly local - like the names on entries in a phonebook. Sometimes in a post you want to mention someone you know by a nickname. Just type `~plato`, and `:talk` will replace it with `~your-urbit`.