using/messaging.md · urbit.org

git.iko.soy/urbit.org

on ea58a74 help sign in

urbit.org/using/messaging.md

680 lines 16 kB history raw

1+++

2title = "Messaging"

3weight = 2

4template = "doc.html"

5+++

7Talk is the built-in frontend for the Urbit messaging and notifications

8protocol, Hall. Today we use Hall to chat and coordinate, but it's really

9a general purpose piece of infrastructure.

11For the time being come join us in `~dopzod/urbit-help` by using the

12'quickstart' section below. `~dopzod` is the host ship, and `/urbit-help` is the

13channel on that ship.

15Today, Hall is sort of like a distributed, encrypted Slack that can be

16used from the CLI and the browser. There’s no central Hall server.

17Any urbit can host one.

19Hall is a general purpose tool for both aggregating and publishing

20streams of messages. Applications can use Hall as their transport

21protocol, API connectors can push disparate data sources into Hall,

22and so on. There are lots of things a distributed message protocol can

23be used for that we haven't even thought of.

25Here we'll be discussing how to operate the default CLI frontend, Talk,

26to send and receive messages. For a more in-depth look at Hall's internals,

27take a look at its [documentation](@/docs/learn/arvo/hall.md).

29## Quickstart

31The most common uses of Talk right now are communicating over a public chat channel called `~dopzod/urbit-help` and sending direct messages. Everyone is more than welcome in `~dopzod/urbit-help`. It's the place to get help, ask questions and chat about Urbit in general.

33There are two ways of using Talk: from the terminal running the Urbit process, or through the Landscape web UI available at `http://localhost/~~/landscape`.

35If you're using Landscape for the first time, you'll need to enter a code to gain access. You can obtain this code by running `+code` from the Dojo.

37### Joining a Channel

39In Hall, a medium for a message is called a _circle_. There are four types of circles, but we for now we'll be dealing with the _channel_: a publicly accessible chatroom for general use. We'll discuss the other three kinds in the [manual](#manual) section.

41Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from Dojo to Talk.

43Then:

45```

46~your-urbit:talk> ;join ~dopzod/urbit-help

47```

49Scrolling down your terminal window, you'll probably see the playback of

50previous `~dopzod/urbit-help` messages that you missed.

52Post a line to `~dopzod/urbit-help:`

54```

55~your-urbit:talk= Hello, world!

56```

58You'll see your message printed below messages from others that came before it:

60```

61~your-urbit= Hello, world!

62```

64### Subscribing to a Channel in Landscape

66In Landscape, you can always navigate to a channel by opening the menu, or using the shortcut `cmd-k`, then typing `go ~host-urbit/channel-name`. However, if you want to see messages in your inbox, you'll need to join from the Talk terminal.

68Again, that's:

70```

71;join ~dopzod/urbit-help

72```

74Now, navigate to `localhost/~~/landscape`. You should see recent messages under the "Recent" tab, and if you navigate to the "All" tab, you should see your subscription to `~dopzod/urbit-help` under "Chats".

76### Direct Messaging

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

80```

81~your-urbit:talk= ;~talsur-todres

82```

84You'll see your prompt change:

86```

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

88```

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

92```

93~your-urbit:talk[~talsur-todres] Hey buddy!

94```

96To set your audience back to `~dopzod/urbit-help`:

98```

99~your-urbit:talk[~talsur-todres] ;~dopzod/urbit-help

100```

101

102You'll see your prompt change back:

103

104```

105~your-urbit:talk=

106```

107

108You can also use the ASCII "glyph" assigned to your `~dopzod/urbit-help` circle as a shortcut:

109

110```

111~your-urbit:talk[~talsur-todres] ;=

112~your-urbit:talk=

113```

114

115(Your ship may have a different glyph than `=` for your circle)

116

117Use `;leave` to unsubscribe from a channel:

118

119```

120~your-urbit:talk= ;leave ~dopzod/urbit-help

121```

122

123The web UI ships as compiled JavaScript on your urbit, but has its own

124source repo [here](https://github.com/urbit/talk).

125

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

127

128```

129~your-urbit:talk= ;create channel %my-channel 'Some description.'

130```

131

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

133

134---

135

136## Manual

137

138Hall's design is similar in spirit to

139[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),

140the underlying protocol for Usenet.

141

142Our design is pretty simple: Hall messages are called _posts_. Posts

143go to _circles_. Any urbit can host or subscribe to any number of circles.

144

145There are four kinds of circles: a write-only `%mailbox` for direct

146messages, an invite-only `%village` for private conversation, a read-only

147`%journal` for curated content, and a public-access `%channel` for

148general use.

149

150### Posts

151

152A post can be a variety of different data structures. Let's look at the

153ones you can use from within Talk: lines, URLs, Hoon and replies.

154

155#### Lines

156

157A line is simply a string of text. Depending on the filtering rules set

158by the circle's host, these may or may not include uppercase and Unicode

159characters (see [filter](#filter)).

160

161If the line starts with `@`, it's an action (like `/me` in IRC).

162

163```

164~your-urbit:talk= @sends a message.

165```

166

167will print as

168

169```

170~your-urbit sends a message.

171```

172

173#### URLs

174

175A URL is any valid URL.

176

177```

178~your-urbit:talk= https://example.com/

179```

180

181#### Hoon

182

183You can use Talk to evaluate Hoon code and share the result with everyone in a

184Hall circle. To do so, preface your Hoon with `#`.

185

186```

187~your-urbit:talk= #(add 2 2)

188```

189

190will print as

191

192```

193~your-urbit# (add 2 2)

1944

195```

196

197#### Replies

198

199To indicate what you're saying is in direct response to a specific message, select the message (see Activating Lines below) and type your response.

200

201```

202~some-urbit= Hello! How are you?

203~your-urbit:talk= ; Well, thanks!

204```

205

206will print as

207

208```

209~your-urbit=^ Well, thanks!

210```

211