Connect ClickClack to Your AI Agent

Before You Start

This one assumes you already run a ClickClack workspace. If you do not, that is the first job and it is outside what we can help with — everything below starts from an existing server you administer.

Your agent needs to be able to reach that server. If ClickClack runs on a private network, a hosted agent cannot get to it, the same as any other self-hosted integration.

The Fast Route: a Setup Code

In ClickClack, open the workspace integration settings, create a bot, and choose the setup-code option. ClickClack generates a command you paste into your agent's Web Terminal, and that single step claims the code, receives a freshly minted bot token, saves the account and verifies the connection.

Two things about the code: it works once, and it expires after ten minutes. If you get distracted between generating it and pasting it, generate a new one rather than wondering why it failed.

The code itself is never stored — only the token it produces. If your agent was already running, the connection comes up on its own and there is nothing further to do.

If your frontend and API live on different hostnames, or the API is mounted under a path, ClickClack emits a more specific claim endpoint instead. Use whichever one it gives you; the agent works out and stores the right API base either way.

The Manual Route

You can also create a token yourself and configure the agent with the server URL, the token and the workspace. Choose this when you want to own the token lifecycle. The workspace can be given as its id, its slug or its display name — the agent resolves it at startup.

An account only counts as configured when the server URL, a token and a workspace are all present. A missing workspace is the usual reason a setup that looks complete never connects.

Token Scopes

Scopes are enforced by ClickClack, not by the agent, so getting them wrong produces features that silently do nothing.

• Read access covers channels, messages, threads, DMs and the realtime stream.
• Write access adds sending messages, thread replies, DMs, uploads and publishing the command menu. This is what a normal chat agent needs.
• Admin adds creating channels, which is only needed for the discussions feature.
• Live activity rows are a separate scope that is not included in the others. Without it, that feature degrades quietly rather than erroring.

A token created before command menus existed may need the menu scope added or a replacement token.

Auth-Gated Workspaces

A common setup is ClickClack behind something like Cloudflare Access, where browser users authenticate at the edge. That gateway will also block your agent, because the agent is not a browser and cannot complete the interactive login.

The answer is to give the agent a separate internal address for its API and realtime traffic while keeping the public hostname for the links it generates. Users keep clicking public URLs; the agent talks over the internal path. This only applies when the agent and ClickClack are on the same host or network.

Where Messages Go

The agent can send to a workspace channel, open or reuse a direct conversation with a specific person, or reply inside an existing thread. A target with no prefix is treated as a channel.

Outbound images and files upload to ClickClack and attach to the message. There is a 64 MiB per-file limit. Media sends are made durable, so a retry after a restart reuses the same upload instead of posting a duplicate or consuming your storage quota twice — though that recovery depends on your ClickClack server being recent enough to support it. On an older server the agent leaves the delivery unresolved rather than risk a double post, so update ClickClack before you lean on media replies.

Command Menu

At startup the agent publishes its commands into ClickClack's composer autocomplete, labelled with the bot's handle. The set is replaced wholesale each time it starts, so a stale menu clears itself.

Publishing is best effort. A missing scope or a network hiccup logs a warning and does not stop the agent from working. Menus stay visible while the agent is offline and disappear when the bot leaves the workspace.

A Channel Per Session

There is an optional feature worth knowing about: each of your agent's sessions can get its own ClickClack channel, filed under a sidebar section, so a long-running piece of work has a place in chat where your team can watch and steer it.

This needs channel-creation permission — the ordinary write token cannot do it. Enable it on exactly one account; the agent refuses several rather than silently picking one.

Deleting a session archives its channel instead of deleting it, so the history stays readable. The binding is pinned to the specific server, channel and session, which means a reset session cannot inherit an old channel's transcript and two separate agents cannot adopt each other's channels.

Two Reply Modes

By default messages run through the full agent pipeline, with session history and tool policy. There is a lighter mode that skips all that and returns short direct model completions, which suits a bot meant to answer quickly rather than do work.

The lighter mode needs an explicit trust setting enabled, and it bypasses the normal run and session diagnostics — so if you care about tracing what the agent did, stay on the default.

Troubleshooting

• Not configured for the account. One of the server URL, token or workspace is missing.
• Workspace not found. The value does not match an id, slug or name the server recognises.
• No replies at all. Confirm the token has realtime read access. Note the bot ignores its own messages and messages from other bots by design.
• Sends to channels fail. The bot is not a member of the workspace, or lacks write scope.
• No command menu. The feature is off, the token lacks the menu scope, or the server is too old to accept a menu.

Need a Hand?

Contact support from your dashboard. Have your workspace URL ready, and do not paste the bot token into chat — we will tell you where to put it.