Channels
Group contents
Channels
Table of Contents
Introduction
This document covers the scries, pokes, and subscriptions for Tlon’s chat, notebook, and gallery channel backend.
Agents
Tlon’s channels are implemented through two agents, %channels and %channels-server. These both communicate with each other, and %channels also communicates with frontends and third-party agents.
%channels-server is intended for internal use by %channels. As such, we will not be elaborating on its API here.
%channels, on the other hand, is there precisely to facilitate use by frontend clients and third-party agents. Its API is made up primarily of two types:
Actions describe user actions, like creating a channel or sending a message. Actions types are prefixed with $a-.
Responses describe changes made to channels. Response types are prefixed with $r-
Code examples
To use these code examples in the dojo, import the types with =c -build-file /=groups=/sur/channel/hoon
To use these code examples in an agent, replace any instance of/=groups= with /(scot %p our.bowl)/groups/(scot %da now.bowl) and import the types with /- c=channel
You’ll also need a group to put channels in. Use this code snippet in your dojo to create one:
=g -build-file /=groups=/sur/groups/hoon
=create :*
name=%mygroup
title='My group'
description='This is my group'
image=''
cover=''
cordon=`cordon:g`[%open ban=[ships=~ ranks=~]]
members=`(jug ship sect:g)`(~(put ju *(jug ship sect:g)) our %admin)
secret=%.n
==
:groups &group-create create
Scries
| Path | Mark | Description | Example |
|---|---|---|---|
/x/channels |
channel-channels | Get known channels and their contents. Returns $channels | .^(channels:c %gx /=channels=/channels/channel-channels) |
/x/unreads |
channel-unreads | Get unread information for the channels our ship is in. Returns $unreads | .^(unreads:c %gx /=channels=/unreads/channel-unreads) |
/x/init |
noun | Combination of /channels and /unreads. Returns [$unreads $channels] |
.^([unreads:c channels:c] %gx /=channels=/init/noun) |
/x/pins |
channel-pins | Get pinned channels. Returns (list $nest) | .^((list nest:c) %gx /=channels=/pins/channel-pins) |
/x/[kind]/[ship]/[name]/perm |
channel-perm | Get permissions for a channel. Returns $perm | .^(perm:c %gx /=channels=/chat/~sampel-palnet/mychat/perm/channel-perm) |
/x/[kind]/[ship]/[name]/search/text/[skip=@]/[count=@]/[nedl=@] |
channel-scan | Search for text. Returns $scan | .^(scan:c %gx /=channels=/chat/~sampel-palnet/mychat/search/text/0/10/‘foo bar’) |
/x/[kind]/[ship]/[name]/search/mention/[skip=@]/[count=@]/[nedl=@] |
channel-scan | Search for a mention. Returns $scan | .^(scan:c %gx /=channels=/chat/~sampel-palnet/mychat/search/text/0/10/~mister-hidden) |
/x/[kind]/[ship]/[name]/posts/... |
channel-posts | Get posts from a channel. This can be called with a large variety of arguments, found here. Returns paged-posts | .^(scan:c %gx /=channels=/chat/~sampel-palnet/mychat/posts/newest/10/post |
/u/[kind]/[ship]/[name] |
loob | Check the existence of a channel | .^(? %gu /=channels=/chat/~sampel-palnet/mychat/loob) |
Pokes
All pokes here have the channel-action mark.
Channels
| Description | Example |
|---|---|
Create a channel. This also updates the metadata in the %groups agent. See $create-channel |
=create-channel :* %chat %mychat [our %mygroup] title=‘My chat channel’ description=‘Chat about things’ readers=~ writers=~==:channels &channel-action [%create create-channel] |
Join a channel. In this example, ~sogrup is the group host and ~hoster is the channel host. |
=nest [%chat ~hoster %mychat]=action [%join group=[~sogrup %mygroup]]:channels &channel-action [%channel nest action] |
| Leave a channel | =nest [%chat ~hoster %mychat]=action [%leave ~]:channels &channel-action [%channel nest action] |
| Set the display format for a channel. See $view | =nest [%chat our %mychat]=action [%view %grid]:channels &channel-action [%channel nest action] |
| Set the sorting mechanism for a channel. See $sort | =nest [%chat our %mychat]=action [%sort %alpha]:channels &channel-action [%channel nest action] |
| Set manual post ordering for a channel. See $arranged-posts | =nest [%chat our %mychat]=action [%set-order `~[~2023.1.1 ~2023.2.2]]:channels &channel-action [%channel nest action] |
| Allow writing to a channel for certain roles. | =nest [%chat our %mychat]=action [%add-writers (sy ~[%role1 %role2])]:channels &channel-action [%channel nest action] |
| Disallow writing to a diary for a certain set of roles. | =nest [%chat our %mychat]=action [%del-writers (sy ~[%role1 %role2])]:channels &channel-action [channel nest action] |
| Pin channels | =pins ~[[%chat ~pinner %mychat]]:channels &channel-action [%pin pins] |
Unreads
| Description | Example |
|---|---|
| Mark a channel as read. | =nest [%chat our %mychat]=action [%read ~]:channels &channel-action [%channel nest action] |
| Mark a channel as read up to a certain time. | =nest [%chat our %mychat]=action [%read-at now]:channels &channel-action [%channel nest action] |
| Currently unused: Watch a channel for unreads. | =nest [%chat our %mychat]=action [%watch ~]:channels &channel-action [%channel nest action] |
| Currently unused: Stop watching a channel for unreads. | =nest [%chat our %mychat]=action [%unwatch ~]:channels &channel-action [%channel nest action] |
Posts
| Description | Example |
|---|---|
| Add a post to a channel. See $post. | =nest [%chat our %mychat]=memo :* ~[[%inline ~[‘hello world!’]]] author=our sent=now===kind-data [%chat ~]=essay [memo kind-data]=post-action [%add essay]=action [%post post-action]:channels &channel-action [%channel nest action] |
| Edit a post in a channel. See $post. | =nest [%chat our %mychat]=memo :* ~[[%inline ~[‘howdy world!’]]] author=our sent=now===kind-data [%chat ~]=essay [memo kind-data]=post-action [%edit ~2023.1.1 essay]=action [%post post-action]:channels &channel-action [%channel nest action] |
| Delete a post. | =nest [%chat our %mychat]=post-action [%del ~2023.1.1]=action [%post post-action]:channels &channel-action [%channel nest action] |
| Add a reaction to a post. | =nest [%chat our %mychat]=post-action [%add-react ~2023.1.1 our %’:grinning:’]=action [%post post-action]:channels &channel-action [%channel nest action] |
| Remove a reaction from a post | =nest [%chat our %mychat]=post-action [%del-react ~2023.1.1 our]=action [%post post-action]:channels &channel-action [%channel nest action] |
Replies
| Description | Example |
|---|---|
| Add a reply to a post. See $post. | =nest [%chat our %mychat]=memo :* ~[[%inline ~[‘howdy world!’]]] author=our sent=now===reply-action [%add memo]=post-action [%reply ~2023.1.1 reply-action]=action [%post post-action]:channels &channel-action [%channel nest action] |
| Delete a reply from a post. | =nest [%chat our %mychat]=reply-action [%del ~2023.2.2]=post-action [%reply ~2023.1.1 reply-action]=action [%post post-action]:channels &channel-action [%channel nest action] |
| Add a reaction to a reply | =nest [%chat our %mychat]=reply-action [%add-react ~2023.2.2 our %’:grinning:’]=post-action [%reply ~2023.1.1 reply-action]=action [%post post-action]:channels &channel-action [%channel nest action] |
| Delete a reaction from a reply | =nest [%chat our %mychat]=reply-action [%del-react ~2023.2.2 our]=post-action [%reply ~2023.1.1 reply-action]=action [%post post-action]:channels &channel-action [%channel nest action] |
Subscriptions
| Path | Marks | Description |
|---|---|---|
/unreads |
channel-unread-update | Unread information. See $unread |
/ |
channel-response | “Everything” subscription path. See $r-channels |
/[kind]/[ship]/[name] |
channel-response | Similar to /, but limited to a certain channel. See $r-channels |
/said/[kind]/[ship]/[name]/post/[time]/[(unit reply)] |
channel-said or channel-denied | Read a reference. A %channel-denied fact means you cannot view the channel. See $said |