A Slack app lane is the route Slack events and Slack API calls take between your workspace and your deployment. Where a channel grant decides which Agent may answer a message, a lane decides who owns the Slack app and what sits in the path. This page covers the two lanes, what the shared gateway holds, how delivery recovers after an outage, and how to choose.
Add to Slack
Add to Slack installs Chickpea’s shared, unlisted Slack app through a private gateway that Chickpea operates. You supply no configuration token, client secret, signing secret, public Events URL, app-level token, or bot token.
The deployment creates a signed one-time claim from its own P-256 key and hands you off to Slack. The gateway binds the installed workspace to that exact deployment, then the deployment opens an authenticated outbound session and keeps it renewed. Slack sends its events to the gateway, which offers them over that session.
Slack credentials stay inside the gateway. The gateway never returns a Slack bot, signing, app-secret, access, or identity token to the deployment, and the deployment keeps only its tenant-bound gateway identity and workspace binding. Outbound calls travel as signed, tenant-bound requests against a fixed allowlist of 33 Slack operations, from auth.test and chat.postMessage through usergroups.create and files.uploadV2.
The gateway your deployment talks to is set by CHICKPEA_GATEWAY_URL, which must be an HTTPS origin. The default is the Chickpea-operated service. Override it only for a compatible private gateway your own organization runs.
Use your own Slack app
Use your own Slack app creates a customer-owned app in your workspace from Chickpea’s reviewed manifest. Slack then posts events straight to https://<your-deployment>/channels/slack/events, and the deployment calls Slack with its own bot token. This lane never loads the gateway client.
Setup asks for a short-lived Slack App Configuration access token. Chickpea sends that token to Slack once and never stores it. Slack also shows an xoxe- refresh token, which Chickpea does not need. If you cannot create a configuration token, /admin/setup/manual walks through the manifest, Event Subscriptions, and app credentials by hand. That page accepts App ID, Client ID, Client Secret, Signing Secret, and the exported JSON manifest, and never a pasted bot token.
Submitted credentials are AES-GCM encrypted in TAG_STATE under an independent versioned keyring. Before Chickpea promotes a credential revision, the app must pass a signed Events API challenge. A manifest or a successful auth.test is not enough to report Connected: the actual grants and live HTTP Events behaviour have to pass.
What the shared gateway holds
This table applies to Add to Slack only. The customer-owned lane has none of it.
| Held where | What | Retention |
|---|---|---|
| Gateway request handling | The Slack request body, in transient process memory only | Never written to storage, logs, or analytics |
| Gateway installation state | Workspace, app, bot, installer, deployment, and binding identifiers, encrypted Slack installation tokens, granted scopes, health and session timestamps | Until the workspace disconnects or Slack revokes the installation |
| Gateway retry-notice suppression | Workspace and channel identifiers, plus Slack event_id. No content |
5 minutes and 25 hours respectively |
| Your deployment’s inbox | The event envelope needed to process one delivery | Scrubbed on completion, after the retry limit, or on recovery. An abandoned active delivery is scrubbed after at most 7 days |
| Your deployment’s deduplication record | Delivery, binding, and workspace IDs, event kind, status, attempt count, timestamps, a bounded reason code. No message body | 48 hours after the row becomes terminal |
| Gateway logs | Bounded reason codes and retry numbers, such as session_missing or receipt_timeout |
Operator log-retention policy |
The short version, from the README: the gateway does not durably store Slack message or event bodies. Model traffic and durable Agent state stay in the deployment and provider accounts you chose, in either lane.
Delivery and recovery
On Cloudflare, the shared lane trades a durable queue for a live receipt.
- Slack sends the event to the gateway, which verifies Slack’s signature and offers it to the bound deployment’s session.
- The deployment writes the delivery to its own durable inbox, then answers
acceptedorduplicate. The live receipt times out after 2 seconds. - Only then does the gateway acknowledge Slack. If no session is available, the receipt times out, or admission is rejected, the gateway returns a failure instead of acknowledging and discarding.
- Slack retries. By default Slack does not deliver events more than two hours late. With the shared app’s Delayed Events setting on, retries continue hourly for 24 hours.
- The deployment deduplicates on Slack’s event identity, so a late retry recovers the event without a second Agent run or a second reply.
That is a 24-hour recovery window, not an exactly-once guarantee. Slack owns the event while it waits to retry, and Slack interactivity requests are not covered by the window. Up to 1,000,000 deduplication rows are protected; when that bound is full, Chickpea rejects new admission rather than deleting an unexpired record.
Admin reads live inbound-session health. A stored healthy value is shown as Needs attention when the current session is offline or belongs to an older Worker version. On a late retry, Chickpea may post one content-neutral offline notice, suppressed once per channel for 5 minutes and once per event for 25 hours.
On Node
Node connects to the shared gateway, but it does not advertise durable admission, so the durable-inbox and 48-hour deduplication contract above is Cloudflare only. Use your own Slack app for reliable Node ingress. Node also keeps an ordinary WebSocket for the outbound session, where Cloudflare rotates its socket before the platform’s outbound lifetime ceiling.
Choosing a lane
You pick a lane once, on the private setup page, before anything else is configured. Agent behaviour is the same in both.
| Question | Add to Slack | Use your own Slack app |
|---|---|---|
| Who owns the Slack app | Chickpea, unlisted and shared | You |
| Secrets you handle | None | Configuration token once, then app credentials |
| Who holds the Slack tokens | The private gateway | Your deployment, encrypted in TAG_STATE |
| Third party in the event path | The Chickpea gateway | None |
| Durable event admission | Cloudflare only | Not applicable, Slack calls you directly |
| Setup time | Minutes | Longer, more steps |
Pick Add to Slack when you want the fastest working install and the gateway’s contract is acceptable. Pick Use your own Slack app when policy requires an app you own, when you want no third party in the event path, or when you are running on Node.
Why it works this way
The gateway exists so an operator can install Chickpea without creating a Slack app, which is the longest and most error-prone part of setup. Making it a routing and credential service rather than a queue keeps the privacy claim simple: it holds credentials and identifiers, not conversations. The cost of that choice is the live receipt. Because the gateway keeps no copy of an event, Slack has to be the retry source, and recovery depends on Slack’s retry policy rather than on Chickpea’s storage.
Both lanes end at the same place. Each binds one exact Slack workspace, validates the issued bot capabilities, and hands the runtime one Slack contract, so product code never learns which lane it is on.
What is not covered
- There is no lane switch. The choice is made on the setup page, which needs the capability minted by the deploy and expires 24 hours later. Moving to the other lane is a fresh deployment.
- One deployment currently serves one Slack workspace. A second workspace is a second deployment.
- Delayed Events is a Slack app setting, not a code path. Until it is enabled on the shared app, the 24-hour recovery window is shorter than described.
- Neither lane changes Agent behaviour. Handles, channel grants, memory, and connections work the same either way.
Next steps
- Get started on Cloudflare: deploy, then choose a lane on the setup page.
- In Slack: the rest of this section, including how to set up your own Slack app.
- Security model: the guarantees behind the credential and authority claims above.
- Operate: running, upgrading, and watching a deployment on each target.