# How to send a Slack message - Slack

You will create a Slack app with a bot user, install it in your workspace, add its bot token into Batch, and finally configure a Universal step that posts a message via the Slack Web API (`chat.postMessage`).

### **When to use Slack via Universal Channel**

Slack via Universal Channel is for **internal team communication**, not end-user messaging. Common use cases:

* **Operational visibility** - get notified when a profile reaches a key step (churn risk segment, lead qualification, onboarding completed)
* **Debug and QA** - mirror an automation to a Slack channel to validate branches and triggers before going live

Not for customer messaging (your users are not in your workspace) or high-volume broadcasts to one channel (Slack rate-limits `chat.postMessage` at \~1 message/second/channel).

{% hint style="info" %}
**Prerequisite - workspace admin approval may be required**\
Many Slack workspaces (especially on Business+ and Enterprise plans) restrict app installation. If your workspace has this restriction enabled:

* The **Install to Workspace** button (Step 2 below) will appear as **Request to Install**
* A workspace **Owner** or **Admin** must approve the request before you can retrieve the bot token
* No bot token will be generated until approval is granted

Confirm with your Slack admin before starting if you are not sure of your workspace's policy. The whole setup is blocked at Step 2 otherwise. 
{% endhint %}

{% stepper %}
{% step %}

### **Step 1 - Create a Slack app and add bot scopes**

Start in Slack.\
You need a Slack app with a bot user that has permission to post messages.

**What to do**

1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Click **Create New App** → **From scratch**
3. Give the app a name (e.g., "Batch Universal Channel") and select your Slack workspace, then click **Create App**
4. In the left menu, open **OAuth & Permissions**
5. Scroll to **Scopes → Bot Token Scopes** and add:
   * `chat:write` - allows the bot to post messages in channels it has been added to
   * `chat:write.public` - allows the bot to post in any public channel without being invited
   * `chat:write.customize` *(optional)* - allows the bot to override its display name and avatar per message

> **Note:**\
> Adding scopes after the app is installed requires reinstalling it for the new permissions to take effect.
> {% endstep %}

{% step %}

### **Step 2 - Install the app to your workspace**

This is the step where workspace admin approval kicks in if restrictions are enabled.

**What to do**

1. Scroll back to the top of the **OAuth & Permissions** page
2. Click **Install to Workspace**
3. Review the requested permissions and click **Allow**

{% hint style="warning" %}
**If you see "Request to Install" instead of "Install to Workspace":**

Your workspace requires admin approval for new apps.

1. Click **Request to Install**
2. Optionally add a justification message for the admin
3. Submit the request
4. A workspace **Owner** or **Admin** will receive a notification in Slack and must approve
5. Once approved, return to the **OAuth & Permissions** page to complete installation and retrieve the token 
   {% endhint %}

After installation (or admin approval), Slack will display a **Bot User OAuth Token** that starts with `xoxb-`. Keep this page open, you will copy the token in the next step.
{% endstep %}

{% step %}

### **Step 3 - Add the Slack bot token into Batch**

Batch needs the bot token to authenticate every call to the Slack API.

**In Slack**

From the **OAuth & Permissions** page, copy the full **Bot User OAuth Token** starting with `xoxb-`.

**In Batch**

1. Go to **Settings → Channels → Universal**
2. Click **New Credential Headers**
3. Choose a name (e.g., "SLACK")
4. **Key** → `Authorization`
5. **Value** → `Bearer xoxb-your-token-here`
6. Save

> **Note:**\
> If you create multiple automations sending messages to the same Slack workspace, they will all use the same token. You only need to add the credential once in Batch.
> {% endstep %}

{% step %}

### **Step 4 - Get the Slack channel ID (or user ID for a DM)**

You will need the Slack ID of the destination in the JSON body of the Universal step.

**For a channel**

1. In Slack, open the channel where Batch should post
2. Click the channel name at the top to open **Channel details**
3. Scroll to the bottom of the **About** tab
4. Copy the **Channel ID** (e.g., `C0123ABCD`)

**For a Direct Message**

1. Open the user's profile in Slack
2. Click the **three dots** menu → **Copy member ID**
3. The user ID looks like `U0123ABCD`

{% hint style="info" %}
**Public vs private channels**

* For **public channels**, the `chat:write.public` scope (added in Step 1) lets the bot post without being invited
* For **private channels**, the bot must first be invited explicitly: in the channel, type `/invite @your-bot-name` 
  {% endhint %}
  {% endstep %}

{% step %}

### **Step 5 - Configure the Universal step in Batch**

In this step, you will add the Universal step in your Batch automation and configure it to post a message to Slack.

**Add the Universal Step**

1. Open the Batch automation where you want to trigger a Slack message
2. Click the **+** button
3. Select **Universal**

This opens the Universal step configuration screen.

***

**Configure the Slack request**

Fill in the fields using the information below:

**1. Destination URL**

Paste the Slack API endpoint:

```
https://slack.com/api/chat.postMessage
```

**2. Headers**

* Select the credential header you created in Step 3 (e.g., **SLACK**)

**3. JSON Body**

Provide the Slack channel (or user ID) from Step 4 and the message text. You can personalize the message with Batch attributes:

```json
{
  "channel": "C0123ABCD",
  "text": "The profile {{ b.custom_id }}  was in the automation {{b.campaign_token}} at {{now}}"
}
```

{% endstep %}

{% step %}

### **Step 6 - Test the connection**

Once your Universal Step is configured, you can test it directly from Batch.

**How to test**

1. In the Universal Step, click **Test API**
2. If your JSON body includes personalization (e.g., `{{b.first_name}}`), choose a **test profile** so Batch can fill in real data
3. Click to send the test request

**What Batch validates**

Batch will display whether the request was **successfully delivered** to Slack or if something needs fixing.

**Slack always returns HTTP 200**

`chat.postMessage` returns `200 OK` even on business errors (channel not found, missing scope, invalid token). The actual outcome is in the JSON response body:

* `"ok": true` → message posted
* `"ok": false, "error": "..."` → something is wrong; the `error` field tells you what

Batch reports **Delivered** as long as the call returns 2xx, so for debugging a missing message, check the Slack response payload or your Slack app logs.

Common `error` values:

| Error               | Meaning                                                                         |
| ------------------- | ------------------------------------------------------------------------------- |
| `not_authed`        | No token detected. Check the `Bearer` prefix in Step 3.                         |
| `invalid_auth`      | Token is malformed, revoked, or expired.                                        |
| `channel_not_found` | The channel ID is wrong, or the bot has not been invited to a private channel.  |
| `missing_scope`     | The bot is missing one of the scopes from Step 1. Add it and reinstall the app. |
| {% endstep %}       |                                                                                 |

{% step %}

### **Step 7 - Activate your Batch automation**

When the test is successful, you can turn your Batch automation live.

**To activate**

1. Review your workflow, including the Universal step
2. Run your automation

**Once live**

* Every time a profile moves through this step in your automation, Batch will send the API request to Slack
* Slack will post the message in the configured channel or DM
  {% endstep %}
  {% endstepper %}

**Additional Universal steps**

If you want to trigger multiple Slack messages (e.g., a follow-up message, a notification to a different channel, or a DM to a manager), you can add more Universal Steps within the same Batch automation or in a new one by following these steps again (Step 3 can be skipped, the credential is shared).

**Good to know - rate limits**

Slack applies a rate limit of approximately **one message per second per channel** on `chat.postMessage` ([Slack rate limits doc](https://api.slack.com/apis/rate-limits)). Universal Channel suits journey-based, per-profile triggers and is not designed for bulk broadcasts to a single channel.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.batch.com/integrations/universal-channel/how-to-send-a-slack-message-slack.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.