A handle is an Agent’s address in Slack: a user group with zero members, like @support. Where a handle says how to reach an Agent, a channel grant says where that Agent may answer. This page covers how a handle is made, what a grant stores, how publishing differs between public and private channels, who can DM an Agent, and what Slack can refuse.
How a handle is made
Chickpea creates the user group when it reconciles the Agent’s Slack presence, using the handle you asked for or, if you asked for none, the Agent’s name. The group takes the Agent’s name and description, or <Name> Agent when the Agent has no description. Nobody is ever added to the group, so mentioning an Agent notifies no person.
The requested text is normalized before Slack sees it. Chickpea trims it, lowercases it, replaces every run of characters outside a-z, 0-9, _, and - with a single -, strips leading and trailing -, and truncates to 80 characters. A value that normalizes to nothing becomes agent.
| You ask for | The handle becomes |
|---|---|
Support |
support |
Data Team |
data-team |
#Ops!! |
ops |
| an emoji only | agent |
Slack handles are workspace-global across members and user groups, so a name a person already holds is a collision. Chickpea keeps the Agent, reports @<handle> is already in use., and offers unused alternatives with a numeric suffix starting at -2.
The name chickpea is reserved. Chickpea refuses it as an Agent id, name, or handle, and it compares after Unicode normalization with punctuation removed, so Chick-Pea and chick.pea are refused too.
What replies look like
The Slack app requests chat:write.customize, so every reply is posted under the Agent’s own name and avatar rather than the app’s. The same scope list carries usergroups:read and usergroups:write, which is how handles are created and updated.
A new Agent gets one of twelve shipped avatars, drawn from the least-used images so a workspace sees all twelve before any one repeats. Uploading an image replaces it, and the record then reads uploaded instead of generated. Each avatar is published at an immutable revision URL, so a change never rewrites the image an old message points at.
What a channel grant is
A grant is one stored record joining a workspace, a channel, and an Agent. It holds a status (pending, active, or needs_attention), the membership that created it, the channel’s label, and whether the channel is private. Routing reads active grants: an Agent mentioned in a channel it has no active grant for gets no reply.
Grants are additive. Publishing one Agent to a channel never displaces another, and a channel can carry several Agents. A grant carries no behaviour of its own: the Agent keeps the same instructions, memory, connections, skills, and schedules in every channel it works in.
Publishing an Agent to a channel hands that channel’s members everything the Agent can do and reach. Every member can mention it, and every mention runs with the Agent’s connected accounts.
Two checks run before a grant becomes active. You must be allowed to edit the Agent, which means you are an Owner or Admin, the Agent’s creator, or any member when the Agent’s edit policy is all_workspace_members. You must also be in the channel yourself: Slack channel membership is an independent ceiling that Admin authority cannot bypass, and the refusal reads Join the Slack Channel before adding this Agent.
In Admin, an Agent’s Slack channels live on its own page under Slack channels, with Add to channels; the workspace-wide view is Destinations. Removing a channel there deletes the grant.
Public channels and private channels
In a public channel, Chickpea writes the grant as pending, joins the channel itself, reconciles the handle, then flips the grant to active. Nobody has to invite the app first.
Slack does not let apps join private channels on their own. Chickpea saves the grant as pending, keeps the Agent, and returns Invite Chickpea to the private Slack Channel before retrying. Someone in that channel runs /invite @Chickpea, and Retry finishes publishing it. The grant stays pending until then.
Archived Agents cannot be published at all. Archiving disables the Agent’s user group in Slack; restoring re-enables it.
Who can DM an Agent
Where an Agent is published decides who can message it directly and who sees it in the App Home tab. Chickpea derives that audience from the Agent’s active grants and the channels Slack can still verify.
| Where the Agent is published | Who can DM it |
|---|---|
| At least one public channel | Any full workspace member |
| Private channels only | Members of those private channels |
| Nowhere | Its creator only |
Slack guests are not full members, so they are denied in every row. When Slack cannot confirm where an Agent is published, access resolves to unavailable rather than open. Admin states the answer in one line, for example All workspace members can DM this Agent.
When Slack refuses a handle
Every refusal keeps the Agent. The handle is the only part that failed, and Admin shows the reason next to the action that fixes it.
| Refusal | What it means | What fixes it |
|---|---|---|
paid_plan_required |
Slack user groups require a paid Slack plan | Upgrade the workspace, then Retry |
user_group_policy_denied |
The workspace lets only Owners and Admins create user groups | Widen the policy, then Retry |
two_factor_required |
Slack wants 2FA from the acting member first | Complete 2FA, then Retry |
handle_collision |
A member or user group already holds the handle | Pick another handle or one of the suggestions |
rate_limited |
Slack is throttling handle changes | Retry in a moment |
slack_reconnect_required |
The workspace authorization is no longer valid | Reconnect Slack as a current Slack Owner or Admin |
The policy refusal is the common one on a new workspace. A Slack Workspace Owner or Admin opens Roles & permissions → Account types at slack.com/admin, chooses Edit permission next to Create and edit user groups, adds Members, and saves. On Enterprise Grid an Org Owner sets the same permission under Organization settings → Roles & permissions. Widening the policy lets human members manage user groups too, so say that before you ask for it. Reconnecting Slack cannot repair a policy, and Chickpea does not suggest it.
A generic slack.com/admin link can open a different signed-in workspace, so confirm the workspace name before changing anything.
Why it works this way
A handle is a real Slack user group because that makes an Agent a real Slack address. Slack’s mention picker finds it, autocomplete completes it, and the mention renders like any other. There is no Chickpea-specific syntax to teach, and no bot that answers to several names.
Reach lives in stored grants rather than in the conversation because the conversation is the one thing an outsider can write to. Authority comes from stored grants and saved instructions, read from stored state and re-checked at the moment of each use, never from anything produced during the turn. Nobody talks an Agent into a channel.
Channel membership is a ceiling on publishing for the same reason. If you cannot see a channel, you cannot hand its members an Agent and the accounts behind it.
What is not covered
@Chickpeahas no handle of its own. It is the Slack app’s bot user, and the system Agent deliberately cannot receive user-Agent channel grants.- A fresh deployment has no channel reach. No Agent of your own is seeded, and the first teammate you create answers in direct messages until someone publishes it to a channel.
- A grant is reach, not isolation. One memory, one instruction set, and one set of connections travel with the Agent into every channel it is granted.
- Handles need Slack, not Chickpea. A paid Slack plan and the workspace user-group policy are Slack’s requirements, and no manifest field can grant them.
- Grants do not decide who may edit an Agent. That is the Agent’s edit policy, which is separate.
Next steps
- How Chickpea works: one mention followed from Slack to the reply.
- In Slack: conversations, replies, and managing Chickpea by asking.
- What an Agent is: what else an Agent carries besides a handle and its channels.
- Authority and confirmation: the authority model behind grants and confirmations.