---
navhome: '/docs'
next: True
sort: 4
title: Messaging (:talk)
---

# Messaging (`:talk`)

<div class="row">

<div class="col-md-8">

`:talk` is the built-in frontend for the Urbit messaging and notifications
protocol, `:hall`. Today we use `:hall` just to chat and coordinate, but
it's really a general purpose piece of infrastructure.

For the time being come join us in `/urbit-meta` by using the
<a href="#-quickstart">quickstart</a> below.

Today `:hall` is sort of like a distributed, encrypted Slack that can be
used from the CLI and the browser. There’s no central `:hall` server.
Any Urbit can host one.

`:hall` is a general purpose tool for both aggregating and publishing
streams of messages. Applications can use `:hall` as their transport
protocol, API connectors can push disparate data sources into `:hall`,
and so on. There are lots of things a distributed message protocol can
be used for that we haven't even thought of.

Here we'll be discussing how to operate the default CLI frontend, `:talk`,
to send and receive messages. For a more in-depth look at `:hall`'s
internals, take a look at its [documentation](#TODO).

</div>

</div>

## Quickstart

For the most part we use `:talk` as a single-instance of Slack: one main
channel (`/urbit-meta`) and direct messages. Everyone is more than welcome
in `/urbit-meta`. It's the place to get help, ask questions and chat about
Urbit in general.

Let's join `/urbit-meta`:

Use `ctrl-x` to switch from `:dojo` to `:talk`.

To join `/urbit-meta`:

    ~your-urbit:talk[] ;join /urbit-meta

You'll see:

    --------------| ;join /urbit-meta
    --------------| new glyph '>'
    ~your-urbit:talk>

Post a line to `/urbit-meta`:

    ~your-urbit:talk> hello, world

You'll see, echoed back at you:

    ~your-urbit> hello, world

To send a direct message to someone, first set your audience:

    ~your-urbit:talk> ;~talsur-todres

You'll see your prompt change:

    ~your-urbit:talk[~talsur-todres]

Now you and `~talsur-todres` can exchange messages directly.

To set your audience back to `/urbit-meta`:

    ~your-urbit:talk> ;/urbit-meta

Use `;leave` to unsubscribe from a channel:

    ~your-urbit:talk> ;leave /urbit-meta

There 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`).

The web ui ships as compiled JavaScript on your Urbit, but has its own
source repo [here](https://github.com/urbit/talk).

Last, let's create a channel we can invite some friends to:

    ~your-urbit:talk> ;create channel %my-channel 'some description'

Now you can tell your friends to `;join ~your-urbit/my-channel`.

## Manual

`:hall`'s design is similar in spirit to
[nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
the underlying protocol for Usenet.

Our design is pretty simple: `:hall` messages go to ‘circles’. Any urbit
can host or subscribe to any number of circles.

There are four kinds of circles: a write-only `%mailbox` for direct
messages, an invite-only `%village` for private conversation, a read-only
`%journal` for curated content, and a public-access `%channel` for
general use.

### Posts

A post can be a variety of different data structures. Let's look at the
ones you can use from within `:talk`: lines, URLs, expressions and
replies.

#### Lines

A line is simply a string of text. Depending on the filtering rules set
by the circle's host, these may or may not include uppercase and Unicode
characters.  
If the line starts with `@`, it's an action (IRC `/me`).

    ~your-urbit:talk> @sends a message

will print as

    ~your-urbit sends a message

#### URLs

A URL is any valid URL.

    ~your-urbit:talk> http://example.com/

### Expressions

Expressions can be used to show and evaluate Hoon code. Send an expression
by prefacing your message with `#`.

    ~your-urbit:talk> #(add 1 2)

will print as

    ~your-urbit# (add 1 2)
                 3

### Replies

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.

    ~some-urbit> hello! how are you?
    ~your-urbit:talk> ; good, thanks!

will print as

    ~your-urbit>^ good, thanks!

### Activating Lines

A line number identifying the *subsequent* line is displayed every 5
lines.

    ---------[0]
    ~your-urbit> this is my message
    ~your-urbit> this is another message
    ~your-urbit sends a message
    ~your-urbit/ http://example.com/
    ~your-urbit# (add 1 2)
                 3
    ---------[5]
    ~your-urbit>^ that's my message!

You can use a line number to *activate* a line:

    ~your-urbit:talk> ;5

which prints the number, line identifier, timestamp, sender, audience,
and contents:

    ? 0
      0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
      ~your-urbit to ~another-urbit
    in reply to: ~your-urbit:
    > this is my message
    that's my message!

If information got truncated — like happens for long URLs or expressions —
or if there's additional information available — as is the case with
replies and attachments — activating the message will show you all the
details.

You can activate the most recent line with `;`, the second-most recent
with `;;`, and so on.

### Creating and managing circles

`;create [type] %name 'description'`  
Creates and joins a circle, where `[type]` is any of the following:  
- `channel`: public circle. Has a blacklist for write control.
- `village`: invite-only circle.
- `journal`: publicly readable, invite-only for writing.
- `mailbox`: publicly writeable, can only be read by its host.

`;delete %name 'optional reason'`  
Deletes a circle. If a reason is specified, that gets sent to all
subscribers before the circle gets deleted.

`;depict %name 'description'`  
Changes the description of circle `%name`.

`;filter %name [capitals] [unicode]`  
Configures the message filter for circle `%name`: whether to allow
capital and/or unicode characters. `y`/`&`/`true` for allowed,
`n`/`|`/`false` for disallowed.

`;invite %name ~someone`  
Invite someone into your circle `%name`. If they were previously banished,
removes them from the blacklist.  
Can also invite multiple ships at once, `~comma, ~separated`.

`;banish %name ~someone`  
Banish someone from your circle `%name`. If they were previously invited,
removes them from the whitelist.  
Can also banish multiple ships at once, `~comma, ~separated`.

`;source %name ~other/circle`  
Adds `~other/circle` as a source for circle `%name`. This causes all
messages sent to `~other/circle` to also appear in `%name`.

`;unsource %name ~other/circle`  
Removes `~other/circle` as a source for circle `%name`.

### Membership

If you have joined a circle, you can make this information publicly
available to help others find that circle as well.

`;show ~some/circle`  
Adds a circle to your public membership list.

`;hide ~some/circle`  
Removes a circle from your public membership list.

### Status

You'll see status notifications when people enter or leave stations
you're subscribed to.

`;set quiet`  
Turn off status (and config) notifications.

`;unset quiet`  
Turn on status (and config) notifications.

`;who`  
List everyone in all your subscribed circles. Optionally specify a
specific circle to list members of just those.

`;attend ~some/circle [presence]`  
Manually set your presence to show up as one of the following. (In the
future, a sufficiently advanced client can automatically set these for
you.)  
- `talk` - typing
- `hear` - listening
- `idle` - inactive
- `gone` - not present

`;name ~some/circle 'my handle'`  
Set a handle ("name") for yourself in a specific circle. It will display
to users who have done `;set nicks`, but gets truncated if it's longer
than 14 characters.

### Audience

An audience consists of one or more messaging targets. These can be
circles or ships. (In the latter case, it's secretly the `~ship/inbox`
circle.)

### Circle glyphs

Glyphs are assigned by circle hash out of the following list

    > = + - } ) , . " ' ^ $ % & @

Alphanumeric characters and `|#;:*~_` are reserved; all others (the
above list, and `\/!?({<`) can be manually assigned.

`;bind + /urbit-test`
Assigns the `+` glyph to `/urbit-test`.

`;unbind + /urbit-test`
Unassigns the `+` glyph from `/urbit-test`.

To see what circle is bound to a glyph:

    ;what +  
    /urbit-test

### Prefixes

Received 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.  
There are a few special-purpose glyphs.

- `|` - Informational messages
- `:` - Posts directly to you
- `;` - Posts to you and others (a multiparty conversation)
- `*` - Posts to a complex audience that doesn't directly include you.

#### Prompt

The audience you're sending to is always shown in your prompt. If
there's a glyph for it, it's shown as the glyph.

Here we're talking to the station bound to `=`:

    ~your-urbit:talk=

Here we're talking directly to `~dannum-mitryl`:

    ~your-urbit:talk[~dannum-mitryl]

#### Configuration

`;~urbit/station`  
Set audience to `~urbit/station`.

`;=`  
Set audience to the station bound to the `=` glyph.

`;~dannum-mitryl`  
Set audience to `~dannum-mitryl` (a direct post).

`;%station`  
Set audience to a station on your own ship.

`;~dannum-mitryl this is a private message`  
Set the audience and send a post to it. This works for all of the above.

Your audience is configured with regard to the following rules (in order):

-   if you manually set the audience, that audience.
-   if you activated a post, the post you activated.
-   audience of the last post sent.

### Local nicknames

`;nick`  
List all local nicknames.

`;nick ~some-urbit`  
Look up a nickname.

`;nick plato`  
Search in reverse.

`;nick ~some-urbit plato`  
Create a nickname.

`;nick ~some-urbit ~`  
Clear an assigned nickname.

`;set nicks`  
Show nicknames instead of urbit names. If no local nickname is set, uses
that user's handle. If the user has no handle, just the urbit name.

`;unset nicks`  
Show urbit names instead of nicknames.

Nicknames and handles longer than 14 character will be truncated in
output. Nicknames are strictly local - like the names on entries in a
phonebook.

### Miscellaneous configuration

`;set showtime`  
Show the timestamp for each message.

`;unset showtime`  
Stop showing the timestamp for each message.

`;set timezone [+/-][hours]`  
Adjust the display of the timestamps to a specific timezone. Relative to UTC.

`;set notify`  
Emit a terminal bell sound if your six-syllable ship name is mentioned in
a message.

`;unset notify`  
Do not notify when your ship name is mentioned.

`;set width [number]`  
Set the rendering width of `:talk` to a specific number of characters.
(Minimum of 30.)