git.iko.soy/urbit.org
on 68b401c help sign in
urbit.org/docs/using/messaging.md
286 lines 8.0 kB history raw
1---
2navhome: '/docs'
3next: True
4sort: 4
5title: Messaging (:talk)
6---
8# Messaging (`:talk`)
10<div class="row">
12<div class="col-md-8">
14`:talk` is the Urbit messaging and notifications protocol. Today we use
15`:talk` just to chat and coordinate, but it's really a general purpose
16piece of infrastructure.
18For the time being come join us in `/urbit-meta` by using the
19<a href="#-quickstart">quickstart</a> below.
21Today `:talk` is sort of like a distributed, encrypted Slack that can be
22used from the CLI and the browser. There’s no central `:talk` server.
23Any Urbit can host one.
25`:talk` is a general purpose tool for both aggregating and publishing
26streams of messages. Applications can use `:talk` as their transport
27protcol, API connectors can push disparate data sources into `:talk`,
28and so on. There are lots of things a distributed message protocol can
29be used for that we haven't even thought of.
31</div>
33</div>
35## Quickstart
37For the most part we use `:talk` as a single-instance of Slack: one main
38channel (`/urbit-meta`) and dms. Everyone is more than welcome in
39`/urbit-meta`. It's the place to get help, ask questions and chat about
40Urbit in general.
42Let's join `/urbit-meta`:
44Use `ctrl-x` to switch from `:dojo` to `:talk`.
46If you're a planet:
48 ~your-urbit:talk> ;join /urbit-meta
50If you're a comet:
52 ~your-really-long-urbit:talk> ;join ~binzod/urbit-meta
54You'll see:
56 ---------:talk| %porch subscribed to /urbit-meta, called `>`
57 ---------:talk| rules of /urbit-meta:
58 ---------:talk| don't be rude
59 ---------:talk| urbit-meta is politically correct and safe for work
60 ~dozbud= ~your-urbit admitted to %urbit-meta
61 ~your-urbit:talk>
63Post a line to `/urbit-meta`:
65 ~your-urbit:talk> hello, world
67You'll see, echoed back at you through `~dozbud`:
69 ~your-urbit> hello, world
71To send a direct message to someone, first set your audience:
73 ~your-urbit:talk> ;~talsur-todres
75You'll see your prompt change:
77 ~your-urbit:talk[~talsur-todres]
79Now you and `~talsur-todres` can exchange messages directly.
81To set your audience back to `/urbit-meta`:
83 ~your-urbit:talk> ;~dozbud/urbit-meta
85Use `;leave` to unsubscribe from a channel:
87 ~your-urbit:talk> ;leave ~dozbud/urbit-meta
89There are two ways of using `:talk`: from the CLI or through a web ui
90available at `http://your-urbit.urbit.org/talk` (or
91`http://localhost:8080/talk`).
93The web ui ships as compiled JavaScript on your Urbit, but has its own
94source repo [here](https://github.com/urbit/talk).
96Last, let's create a channel we can invite some friends to:
98 ~your-urbit:talk> ;create channel %my-channel 'some description'
100Now you can tell your friends to `;join ~your-urbit/my-channel`.
102## Manual
104`:talk`'s design is similar in spirit to
105[nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
106the underlying protocol for Usenet.
108Our design is pretty simple: `:talk` messages are called ‘posts’. Posts
109go to ‘stations’. Any urbit can host or subscribe to any number of
110stations.
112There are four kinds of station: a write-only `%mailbox` for direct
113messages, an invite-only `%party` for private conversation, a read-only
114`%journal` for curated content, and a public-access `%channel` for
115general use.
117### Posts
119For the time being a post is either a line, a URL or a command.
121#### Lines
123A line is 64 bytes of ASCII lowercase, spaces and punctuation. If the
124line starts with '@', it's an action (IRC `/me`).
126The `:talk` interface will let you keep typing past 64 bytes, but insert
127a Unicode bullet-point character in an appropriate space in your post,
128to show you the prospective linebreak. Your essay will be posted in
129multiple lines.
131 ~your-urbit:talk> this is a long message, so it will by truncated right at this•spot
133will print as
135 ~your-urbit; this is a long message, so it will by truncated right at this
136 ~your-urbit; spot
138#### URLs
140A URL is any valid URL.
142 ~your-urbit:talk> http://example.com
144### Commands
146A command is a hoon expression, prefaced by '\#'.
148 ~your-urbit:talk> #(add 2 2)
150### Activating Lines
152A line number identifying the *subsequent* line is displayed every 5
153lines.
155 ---------[0]
156 ~your-urbit; this is my message
157 ~your-urbit@ this is an @ message
158 ~your-urbit; this is a long message, so it will by truncated right at this
159 ~your-urbit; spot
160 ~your-urbit/ http://example.com/
161 ---------[5]
162 ~your-urbit# (add 2 2) 4
164You can use a line number to *activate* a line:
166 ~your-urbit:talk> ;0
168which prints the number, line identifier, timestamp, sender, audience,
169and contents:
171 ? 0
172 0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
173 ~your-urbit to ~another-urbit
174 this is my message
176Activating a URL will print the full URL (it could have been truncated),
177and activating a command will evaluate it.
179You can activate the most recent line with `;`, the second-most recent
180with `;;`, and so on.
182### Creating and managing stations
184`;create journal %serious-journal 'description'` - Creates a `%journal`,
185a privately writable publicly readable station.
187`;create channel %serious-channel 'description'` - Creates a `%channel`,
188a publicly readable publicly writeable station.
190### Presence
192You'll see presence notifications when people enter or leave stations
193you're subscribed to.
195`;set quiet` - Turn off presence notifications
197`;unset quiet` - Turn on presence notifications
199`;who` - list everyone in all your stations
201### Station Glyphs
203Glyphs are assigned by station hash out of the following list
205 > = + - } ) , . " ' ^ $ % & @
207Alphanumeric characters and `|#;:*~_` are reserved; all others (the
208above lists, and `\/!?({<`) can be manually assigned.
210`;bind > /urbit-test` - assigns the `>` glyph to `/urbit-test`.
212### Prefixes
214Received posts are prefixed with a glyph to let you know what the
215audience is. You can activate an individual post to see the full
216audience.
218`|` - Informational messages
220`:` - Posts directly to you
222`;` - Posts to you and others (a multiparty conversation)
224`*` - Posts to a complex audience that doesn't directly include you.
226### Audience
228#### Prompt
230The audience you're sending to is always shown in your prompt. If
231there's a glyph for it, it's shown as the glyph.
233Here we're talking to the station bound to `=`:
235 ~your-urbit:talk=
237Here we're talking directly to `~dannum-mitryl`:
239 ~your-urbit:talk(~dannum-mitryl)
241#### Configuration
243`;~urbit/station` - Set audience to `~urbit/station`
245`;=` - Set audience to the station bound to the `=` glyph
247`;~dannum-mitryl` - Set audience to `~dannum-mitryl` (a direct post).
249`;%station` - Set audience to a station on your own ship
251`;~dannum-mitryl this is a private message` - Set the audience and send
252a post in the same line. This works for all of the above.
254Your audience is configured 'implicitly' with regard to the following
255rules (in order):
257- if you manually locked the audience, that audience.
258- if typing a post, the audience when you started typing.
259- if you activated a post, the post you activated.
260- audience of the last post received.
261- audience of the last post sent.
263Clear any 'implicit' audience setting by moving your cursor to the start
264of the line and pressing backspace (whether the line is empty or not).
265Posting a line clears the typing and activation configurations.
267### Nicknames
269`;nick` - list all nicknames
271`;nick ~your-urbit` - look up a nickname
273`;nick plato` - search in reverse
275`;nick ~your-urbit plato` create a nickname
277`;nick ~your-urbit ~` clear an assigned nickname
279`;set noob` show nicknames instead of urbit names
281`;unset noob` show urbit names instead of nicknames
283All nicknames must be 14 characters or less, lowercase. Nicknames are
284strictly local - like the names on entries in a phonebook. Sometimes in
285a post you want to mention someone you know by a nickname. Just type
286`~plato`, and `:talk` will replace it with `~your-urbit`.