git.iko.soy/urbit.org
on 424cd14 help sign in
urbit.org/docs/using/messaging.md
188 lines 6.3 kB history raw
1---
2next: true
3sort: 4
4title: Messaging (:talk)
5---
7# Messaging (`:talk`)
9<div class="row">
10<div class="col-md-8">
12`: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.
14For the time being come join us in `/urbit-meta` by using the <a href="#-quickstart">quickstart</a> below.
16Today `: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.
18`: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.
20</div>
21</div>
23## Quickstart
25For 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.
27Let's join `/urbit-meta`:
29 ~your-urbit: ;join ~doznec/urbit-meta
31You'll see:
33 ---------:talk| %porch subscribed to /urbit-meta, called `>`
34 ---------:talk| rules of /urbit-meta:
35 ---------:talk| don't be rude
36 ---------:talk| urbit-meta is politically correct and safe for work
37 ~doznec= ~your-urbit admitted to %urbit-meta
38 ~your-urbit:talk>
40Post a line to `/urbit-meta`:
42 ~your-urbit:talk> hello, world
44You'll see, echoed back at you through `~doznec`:
46 ~your-urbit> hello, world
48To send a direct message to someone, first set your audience:
50 ~your-urbit:talk> ;~talsur-todres
52You'll see your prompt change:
54 ~your-urbit:talk[~talsur-todres]
56Now you and `~talsur-todres` can exchange messages directly.
58To set your audience back to `/urbit-meta`:
60 ~your-urbit:talk> ;~doznec/urbit-meta
62There 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`).
64The web ui ships as compiled JavaScript on your Urbit, but has its own source repo [here](https://github.com/urbit/talk).
66## Manual
68`:talk`s design is similar in spirit to [nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol) the underlying protocol for Usenet.
70Our design is pretty simple: `:talk` messages are called ‘posts’. Posts go to ‘stations’. Any urbit can host or subscribe to any number of stations.
72There 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 `%board` for general use.
74### Posts
76For the time being a post is either a line, a URL or a command.
78#### Lines
80A line is 64 bytes of ASCII lowercase and spaces. If the line
81starts with '@', it's an action (IRC `/me`).
83The `:talk` interface will let you keep typing past 64 bytes, but
84insert a Unicode bullet-point character in an appropriate space
85in your post, to show you the prospective linebreak. Your essay
86will be posted in multiple lines.
88#### URLs
90A URL is any valid URL.
92### Commands
94A command is any line starting with `;`.
96### Creating and managing stations
98`;create journal %serious-journal 'description'` - Creates a `%journal`, a privately writable publicly readable station.
100`;create channel %serious-journal 'description'` - Creates a `%channel`, a publicly readable publicly writeable station.
102### Presence
104You'll see presence notifications when people enter or leave
105stations you're subscribed to.
107`;who` - list everyone in all your stations
109`;who station` - list everyone in that station
111### Station Glyphs
113Glyphs are assigned by station hash out of the following list
115 > = + - } ) , . " ' ^ $ % & @
117Alphanumeric characters and `|#;:*~_` are reserved; all others (the above lists, and `\/!?({<`) can be manually assigned.
119`;bind > /urbit-test` - assigns the `>` glyph to `/urbit-test`.
121### Prefixes
123Received 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.
125`|` - Informational messages
127`:` - Posts directly to you
129`;` - Posts to you and others (a multiparty conversation)
131`*` - Posts to a complex audience that doesn't directly include you are.
133### Audience
135#### Prompt
137The audience you're sending to is always shown in your prompt. If there's a glyph for it, it's shown as the glyph.
139Here we're talking to the station bound to `=`:
141 ~your-urbit:talk=
143Here we're talking directly to `~dannum-mitryl`:
145 ~your-urbit:talk(~dannum-mitryl)
147#### Configuration
149`;~urbit/station` - Set audience to `~urbit/station`
151`;=` - Set audience to the station bound to the `=` glyph
153`;~dannum-mitryl` - Set audience to `~dannum-mitryl` (a direct post).
155`;%station` - Set audience to a station on your own ship
157`;~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.
159Your audience is configured 'implicitly' with regard to the following rules:
161- if typing a post, the audience when you started typing.
162- if you activated a post, the post you activated.
163- if you manually locked the audience, that audience.
164- audience of the last post received.
165- audience of the last post sent.
167Clear any 'implicit' audience setting by moving your cursor to
168the start of the line and pressing backspace (whether the line is
169empty or not). Posting a line clears the typing and activation
170configurations.
172### Nicknames
174`;nick` - list all nicknames
176`;nick ~your-urbit` - look up a nickname
178`;nick plato` - search in reverse
180`;nick ~your-urbit plato` create a nickname
182`;nick ~your-urbit ~` clear an assigned nickname
184`;set noob` show nicknames instead of urbit names
186`;unset noob` show urbit names instead of nicknames
188All 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`.