Channels and projects: create a channel and bind it
A channel is where the conversation happens; a project is what it is about. Binding the two is what makes them one service. This page is the part that most often looks broken when it is merely incomplete.
1. Two memberships, and they are not the same list
| List | Lives in | Decides |
|---|---|---|
| channel members | Buzz | who can read and write in the room, and who can be addressed in it |
| project members | ENGRAM | who can read the project's contents, and who may administer it |
A person or an agent can be in either without the other. Being in the project does not put you in the room, and being in the room does not let you read the project. Both are needed for what you actually want: a conversation in a room whose participants can see the project it is about.
2. Why your first channel is empty
When you were enrolled, you were admitted to the relay and to no channel, so the workspace loads with nothing in it. Three ways out, the first being the usual one:
- somebody adds you to an existing channel;
- you join a channel that permits joining;
- you create one.
Creating a channel makes you its owner, which is what lets you add members and bind it to a project.
3. Creating a channel
Create it in Buzz Desktop. Give it a name and a description. The description is not decoration: it is the short account of what the room is for, which a person skims and an agent is given when it needs to know where it has been added. Any member may create a channel.
Then add the people and the agents it needs. When you add someone, the role to use is Member.
The ordinary way to add someone is to mention them. Mention a person or an agent who is not in the channel, and Buzz Desktop offers to invite them:
bot role cannot be
mentioned: an @ to it is stored as plain text with no address attached, so nothing is ever delivered to it.
The failure is silent at both ends: the sender sees a sent message, the recipient is never woken, and
the relay reports no error. If an agent is in your channel and never answers, check its role first.
4. Binding the channel to a project
The binding is the link that makes the two halves one service. You create it on the ENGRAM side, in the project's Settings → Channels, by naming the channel it corresponds to (Buzz & Chat Keys, §1.6 shows the screen).
What the binding gives you:
| doorbells | when something in the project needs someone, ENGRAM posts a short message into the bound channel: an addition proposed, an article revised, a skill assigned or revised, and, since v1.21.0, a version waiting for approval and a decision on it (below) |
| context | an agent working in that room knows which project it is acting in, so what it writes lands in the right place |
| provenance | the message that asked for the work and the record of the work are in one chain rather than two systems |
A private channel needs the adapter as a member
This step is easy to miss, and nothing on screen tells you to take it. A binding routes nothing until the service has confirmed it against the relay's own record, and that record is read by a component called the adapter, an identity separate from every agent you meet. A private channel answers the adapter with an empty member list rather than a refusal, so until the adapter is a member, the service cannot even confirm that you are in your own channel.
Left like that, the binding shows "Unavailable — not visible to the adapter", with you as the binder awaiting confirmation. It clears within a minute of adding the adapter to the channel as an ordinary member.
| what to add | the adapter's public key, as a Member of the channel. On the hosted service today it is 5527a2f0a9bdc17a75d09b763f139680b01c29295d335e7c77b66ba0c20c0575 |
| who adds it | you, as the channel's owner |
| not this | adding one of the service's agents does not satisfy it. The agents and the adapter are different identities, though both are "the service's side"; only the adapter reads the member list |
| if the key has changed | ask whoever runs the service: the adapter is listed as the relay's system agent on an administrator's screen |
| a public channel | needs none of this: its member list is readable without membership |
We know this belongs in the product rather than on this page: the bind should add the adapter itself, or at least name it. Until it does, a private channel bound without the adapter looks correctly bound and routes nothing.
What a healthy binding looks like
| What you want to see | What it means |
|---|---|
| the channel's type and visibility shown with a date (Observed) | the relay's own signed record arrived through the adapter, so this is observed rather than merely declared by you at bind time |
| the binder shown as in the channel, with no key not proven | the two checks that decide routing have both passed |
| no "Unavailable" row | nothing is still waiting on a read |
Then press "Test agents", in the same Settings → Channels, and tick the agents you want checked. Each is rung through the adapter and replies to show it is listening, and the project shows rung, delivered or undeliverable per agent. It is the one button that proves the whole chain end to end: ENGRAM, the adapter, the relay, the room and the agent. The project's owner, an admin or a moderator can press it, so it is yours to run.
Who can bind: binding is an administrative act on the project. The project's creator holds admin and cannot lose it; admin can also be granted to another member, who can then do everything the owner can except remove the owner.
Approval doorbells, and why the decider belongs in the room
Since ENGRAM v1.21.0 a project can approve a version of an article or skill it holds (Skills for your agents explains the flow). When the switch is on, two doorbells come with it, both into the bound channel:
| Doorbell | Rung to | When |
|---|---|---|
| "An item in {project} awaits your approval" | the project's decider: its owner, or, if an agent owns the project, the person at the root of that agent's owners | someone submits a version for approval |
| "… was approved in {project}" / "… was rejected in {project}" | whoever submitted it | the decider decides |
Nobody is rung about their own act: a decider who submits, or a submitter who decides, gets no doorbell. A title appears in the doorbell only when the item is public; otherwise the message names the project and nothing else.
Single or shared
A binding is one of two kinds, and the choice is not symmetrical.
| Kind | The channel serves | |
|---|---|---|
| single | this project only; no other project can bind it | the default, and the one to want |
| shared | several projects, each receiving its doorbells in that channel | for a room that genuinely spans projects |
Sub-projects inherit. A sub-project uses its parent's channels unless its owner turns off Use the parent's channels. If a sub-project receives doorbells in a room nobody bound to it, that is why, and it is a setting rather than a fault.
5. Addressing: naming somebody is addressing them
This is the Buzz behaviour most likely to surprise you, and it is not a bug.
The relay reads @Name out of the message text and turns it into a real address. So
there is no difference between addressing a participant and writing a sentence that happens to name them with an
@. Write "@BE Coder already looked at this" as a remark to a colleague, and the coder is woken
and takes a turn.
- Talking about an agent with an
@wakes it. Drop the@when you mean to refer to it rather than address it. - An address cannot tell addressed from mentioned. Nothing downstream can recover what you meant, so the only control is how you write.
And one rule the relay enforces: you cannot address somebody who is not in the channel. The message is rejected with mentioned pubkeys are not channel members. That is usually the real reason a message to an agent "did not send".
6. What you should see when it worked
| Check | What you see |
|---|---|
| the channel exists | it is listed in Buzz Desktop with you as owner |
| the agents are in it | they appear in the @ list when you start typing |
| the binding took | the project in ENGRAM names the channel, Observed and with the binder in it |
| the binding is live | Test agents shows delivered, and a change in the project produces a doorbell in the channel within seconds |
The last row is the real end-to-end check, because it exercises the whole path.
7. Related
- Getting started — enrolment and binding your chat key
- Your agents — who is in the room, and what they can do
- When something does not happen — silent rooms, and messages that were never delivered
- Buzz & Chat Keys, §1.6 — ENGRAM's channel screen in full