git.iko.soy/urbit.org
on 50abe45 help sign in
urbit.org/docs/using/messaging.md
286 lines 8.2 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">
12`:talk` is the Urbit messaging and notifications protocol. Today we use `:talk`
13just to chat and coordinate, but it's really a general purpose piece of
14infrastructure.
16For the time being come join us in `/urbit-meta` by using the
17<a href="#-quickstart">quickstart</a> below.
19Today `:talk` is sort of like a distributed, encrypted Slack that can be used
20from the CLI and the browser. There’s no central `:talk` server. Any Urbit can
21host one.
23`:talk` is a general purpose tool for both aggregating and publishing streams of
24messages. Applications can use `:talk` as their transport protcol, API
25connectors can push disparate data sources into `:talk`, and so on. There are
26lots of things a distributed message protocol can be used for that we haven't
27even thought of.
29</div>
30</div>
31## Quickstart
33For the most part we use `:talk` as a single-instance of Slack: one main channel
34(`/urbit-meta`) and dms. Everyone is more than welcome in `/urbit-meta`. It's
35the place to get help, ask questions and chat about Urbit in general.
37Let's join `/urbit-meta`:
39Use `ctrl-x` to switch from `:dojo` to `:talk`.
41If you're a planet:
43 ~your-urbit:talk> ;join /urbit-meta
45If you're a comet:
47 ~your-really-long-urbit:talk> ;join ~binzod/urbit-meta
49You'll see:
51 ---------:talk| %porch subscribed to /urbit-meta, called `>`
52 ---------:talk| rules of /urbit-meta:
53 ---------:talk| don't be rude
54 ---------:talk| urbit-meta is politically correct and safe for work
55 ~binzod= ~your-urbit admitted to %urbit-meta
56 ~your-urbit:talk>
58Post a line to `/urbit-meta`:
60 ~your-urbit:talk> hello, world
62You'll see, echoed back at you through `~binzod`:
64 ~your-urbit> hello, world
66To send a direct message to someone, first set your audience:
68 ~your-urbit:talk> ;~talsur-todres
70You'll see your prompt change:
72 ~your-urbit:talk[~talsur-todres]
74Now you and `~talsur-todres` can exchange messages directly.
76To set your audience back to `/urbit-meta`:
78 ~your-urbit:talk> ;~binzod/urbit-meta
80Use `;leave` to unsubscribe from a channel:
82 ~your-urbit:talk> ;leave ~binzod/urbit-meta
84There are two ways of using `:talk`: from the CLI or through a web ui available
85at `http://your-urbit.urbit.org/talk` (or `http://localhost:8080/talk`).
87The web ui ships as compiled JavaScript on your Urbit, but has its own source
88repo [here](https://github.com/urbit/talk).
90Last, let's create a channel we can invite some friends to:
92 ~your-urbit:talk> ;create channel %my-channel 'some description'
94Now you can tell your friends to `;join ~your-urbit/my-channel`.
96## Manual
98`:talk`'s design is similar in spirit to
99[nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol), the
100underlying protocol for Usenet.
102Our design is pretty simple: `:talk` messages are called ‘posts’. Posts go to
103‘stations’. Any urbit can host or subscribe to any number of stations.
105There are four kinds of stations: a write-only `%mailbox` for direct messages,
106an invite-only `%party` for private conversation, a read-only `%journal` for
107curated content, and a public-access `%channel` for general use.
109### Posts
111For the time being a post is either a line, a URL or a command.
113#### Lines
115A line is 64 bytes of ASCII lowercase, spaces and punctuation. If the line
116starts with '@', it's an action (IRC `/me`).
118The `:talk` interface will let you keep typing past 64 bytes, but insert a
119Unicode bullet-point character in an appropriate space in your post, to show you
120the prospective linebreak. Your essay will be posted in multiple lines.
122 ~your-urbit:talk> this is a long message, so it will by truncated right at this•spot
124will print as
126 ~your-urbit; this is a long message, so it will by truncated right at this
127 ~your-urbit; spot
129#### URLs
131A URL is any valid URL.
133 ~your-urbit:talk> http://example.com
135### Commands
137A command is a hoon expression, prefaced by '\#'.
139 ~your-urbit:talk> #(add 2 2)
141### Activating Lines
143A line number identifying the *subsequent* line is displayed every 5 lines.
145 ---------[0]
146 ~your-urbit; this is my message
147 ~your-urbit@ this is an @ message
148 ~your-urbit; this is a long message, so it will by truncated right at this
149 ~your-urbit; spot
150 ~your-urbit/ http://example.com/
151 ---------[5]
152 ~your-urbit# (add 2 2) 4
154You can use a line number to *activate* a line:
156 ~your-urbit:talk> ;0
158which prints the number, line identifier, timestamp, sender, audience, and
159contents:
161 ? 0
162 0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
163 ~your-urbit to ~another-urbit
164 this is my message
166Activating a URL will print the full URL (it could have been truncated), and
167activating a command will evaluate it.
169You can activate the most recent line with `;`, the second-most recent with
170`;;`, and so on.
172### Creating and managing stations
174`;create journal %serious-journal 'description'` - Creates a `%journal`, a
175privately writable publicly readable station.
177`;create channel %serious-channel 'description'` - Creates a `%channel`, a
178publicly readable publicly writeable station.
180### Presence
182You'll see presence notifications when people enter or leave stations you're
183subscribed to.
185`;set quiet` - Turn off presence notifications
187`;unset quiet` - Turn on presence notifications
189`;who` - list everyone in all your stations
191### Station Glyphs
193Glyphs are assigned by station hash out of the following list
195 > = + - } ) , . " ' ^ $ % & @
197Alphanumeric characters and `|#;:*~_` are reserved; all others (the above lists,
198and `\/!?({<`) can be manually assigned.
200`;bind > /urbit-test` - assigns the `>` glyph to `/urbit-test`.
202To see what station is bound to a glyph:
204 ;what +
205 {[%.y p=[p=~binzod q=~.urbit-meta]]}
207### Prefixes
209Received posts are prefixed with a glyph to let you know what the audience is.
210You can activate an individual post to see the full audience.
212`|` - Informational messages
214`:` - Posts directly to you
216`;` - Posts to you and others (a multiparty conversation)
218`*` - Posts to a complex audience that doesn't directly include you.
220### Audience
222#### Prompt
224The audience you're sending to is always shown in your prompt. If there's a
225glyph for it, it's shown as the glyph.
227Here we're talking to the station bound to `=`:
229 ~your-urbit:talk=
231Here we're talking directly to `~dannum-mitryl`:
233 ~your-urbit:talk(~dannum-mitryl)
235#### Configuration
237`;~urbit/station` - Set audience to `~urbit/station`
239`;=` - Set audience to the station bound to the `=` glyph
241`;~dannum-mitryl` - Set audience to `~dannum-mitryl` (a direct post).
243`;%station` - Set audience to a station on your own ship
245`;~dannum-mitryl this is a private message` - Set the audience and send a post
246in the same line. This works for all of the above.
248Your audience is configured 'implicitly' with regard to the following rules (in
249order):
251- if you manually locked the audience, that audience.
252- if typing a post, the audience when you started typing.
253- if you activated a post, the post you activated.
254- audience of the last post received.
255- audience of the last post sent.
257Clear any 'implicit' audience setting by moving your cursor to the start of the
258line and pressing backspace (whether the line is empty or not). Posting a line
259clears the typing and activation configurations.
261### Nicknames
263`;nick` - list all nicknames
265`;nick ~your-urbit` - look up a nickname
267`;nick plato` - search in reverse
269`;nick ~your-urbit plato` create a nickname
271`;nick ~your-urbit ~` clear an assigned nickname
273`;set noob` show nicknames instead of urbit names
275`;unset noob` show urbit names instead of nicknames
277All nicknames must be 14 characters or less, lowercase. Nicknames are strictly
278local - like the names on entries in a phonebook. Sometimes in a post you want
279to mention someone you know by a nickname. Just type `~plato`, and `:talk` will
280replace it with `~your-urbit`.
282### Timestamps
284`;set showtime` - Show the timestamp for each message
286`;unset showtime` - Stop showing the timestamp for each message