> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Add agents to Slack

Add agents to Slack [#add-agents-to-slack]

A Slack installation connects one Slack workspace to an Alomana workspace. People in Slack mention `@Alomana` or message it directly, pick an agent, and the thread continues with that agent. Each person is matched to their Alomana account by their Slack profile email.

Endpoints [#endpoints]

Every route needs `X-Space-Slug`.

| Method   | URL                                                     | Does                                                                 | Auth          |
| -------- | ------------------------------------------------------- | -------------------------------------------------------------------- | ------------- |
| `POST`   | `/api/v1/integrations/slack/oauth/init/`                | Start the install from `{redirect_uri}`; returns `{auth_url, state}` | Bearer only   |
| `POST`   | `/api/v1/integrations/slack/oauth/callback/`            | Finish it with `{code, state}`; returns the installation             | Bearer only   |
| `GET`    | `/api/v1/integrations/installations/?provider=slack`    | Installations available in this workspace                            | Key or bearer |
| `PATCH`  | `/api/v1/integrations/installations/{installation_id}/` | Change `display_name` or `status`                                    | Key or bearer |
| `DELETE` | `/api/v1/integrations/installations/{installation_id}/` | Remove the installation; `204`                                       | Key or bearer |

Responses never include the Slack bot token: `credentials` is `null`.

Install Slack [#install-slack]

Bearer only: run these steps as the signed-in user installing the app.

1. Start the flow with the URL Slack should return to:

   ```bash
   curl -X POST "$CENTRAL_HUB_URL/api/v1/integrations/slack/oauth/init/" \
     -H "Authorization: Bearer $ALO_TOKEN" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"redirect_uri": "https://your-app.example.com/slack/callback"}'
   ```

   ```json
   {"auth_url": "https://slack.com/oauth/v2/authorize?client_id=…", "state": "RS_mm…YmM"}
   ```

2. A Slack admin opens `auth_url` in a browser and approves the app.

3. Slack redirects to `redirect_uri` with `code`. Send it with the `state` from step 1, as the same user:

   ```bash
   curl -X POST "$CENTRAL_HUB_URL/api/v1/integrations/slack/oauth/callback/" \
     -H "Authorization: Bearer $ALO_TOKEN" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"code": "<code from the redirect>", "state": "<state from init>"}'
   ```

4. The response is the installation, with `provider: "slack"`, `display_name` and `access_space_slug`, the workspace it serves.

Errors [#errors]

| Response                                | Cause                                                         |
| --------------------------------------- | ------------------------------------------------------------- |
| `400` `Invalid or expired OAuth state.` | `state` is wrong, already used, or from another user's `init` |
| `422` `redirect_uri` `Field required`   | `init` without `redirect_uri`                                 |