Slack API Connector Guide

The Slack connector lets Tealfabric workflows send operational messages, retrieve workspace data, and automate communication patterns without custom Slack client code in every process. This guide focuses on a production-ready setup, practical request patterns, and reliability practices so your Slack automation remains clear and maintainable over time.

When to use this connector

Use this connector when your workflow needs to notify teams, post status updates, or pull channel context for follow-up automation. It is especially useful for incident routing, approvals, and customer support coordination where delivery and traceability matter. Keeping Slack methods and payload schemas explicit in your process definitions makes troubleshooting significantly easier.

Prerequisites

Before configuring the integration, create or select a Slack app with the scopes required for your intended methods (for example message posting and conversation reads). You should install the app into the target workspace and confirm channel access for the bot user. Performing these checks first prevents permission-related failures during workflow execution.

Configuration reference

Connector credentials and defaults are stored in integration configuration, not passed in each run payload. Treat tokens as sensitive and rotate them through your secure secret management process.

• bot_token (required for test): Slack Bot User OAuth token (xoxb-...) or user token (xoxp-...).
• timeout_seconds (optional): Request timeout for connector calls (default 30).

test validates required configuration before calling auth.test; other operations rely on the configured token at request time.

Post messages to Slack

The send operation is commonly used with chat.postMessage to publish operational events from ProcessFlow into channels. Pass method arguments in data (or body).

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type SlackSendResult = {
  message_count: number;
  data: { ok?: boolean; channel?: string; ts?: string };
  response: { ok?: boolean; channel?: string; ts?: string };
};

async function postSlackMessage(
  integrationId: string,
  channelId: string
): Promise<SlackSendResult> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "send",
        method: "chat.postMessage",
        data: {
          channel: channelId,
          text: "Deployment completed successfully.",
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as { success?: boolean; data?: SlackSendResult };
  if (!payload.success || !payload.data) throw new Error("Slack send failed");
  return payload.data;
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "send",
    "method": "chat.postMessage",
    "data": {
      "channel": "<CHANNEL_ID>",
      "text": "Deployment completed successfully."
    }
  }'

{
  "success": true,
  "data": {
    "message_count": 1,
    "data": {
      "ok": true,
      "channel": "C01ABCDEF23",
      "ts": "1746707200.345678"
    },
    "response": {
      "ok": true,
      "channel": "C01ABCDEF23",
      "ts": "1746707200.345678"
    }
  }
}

Read channel context for downstream actions

The receive operation invokes Slack Web API list/read methods (default conversations.list). Pass method arguments in query or data. When Slack returns channels, members, or messages arrays, the connector unwraps them into data.data.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type SlackMessage = {
  user?: string;
  text?: string;
  ts?: string;
};

async function getChannelHistory(
  integrationId: string,
  channelId: string
): Promise<SlackMessage[]> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "receive",
        method: "conversations.history",
        data: {
          channel: channelId,
          limit: 20,
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as {
    success?: boolean;
    data?: { data?: SlackMessage[] };
  };
  if (!payload.success || !payload.data?.data) throw new Error("Missing history payload");
  return payload.data.data;
}

{
  "success": true,
  "data": {
    "message_count": 2,
    "data": [
      { "user": "U01ABCDE23", "text": "All clear.", "ts": "1746707200.100000" },
      { "user": "U01ABCDE24", "text": "Acknowledged.", "ts": "1746707201.200000" }
    ],
    "total_size": 2
  }
}

Sync outbound and inbound legs

Use sync when a workflow should post a message and read channel state in one connector call. Each leg is skipped when PHP empty() would treat it as empty (for example an empty object). Nested outbound/inbound results use legacy-flat leg payloads (success, message_count, data, response or total_size).

{
  "operation": "sync",
  "outbound": {
    "method": "chat.postMessage",
    "data": { "channel": "C01ABCDEF23", "text": "Sync started." }
  },
  "inbound": {
    "method": "conversations.history",
    "data": { "channel": "C01ABCDEF23", "limit": 5 }
  }
}

Batch send and receive operations

batch runs multiple send or receive Web API calls sequentially. Each result entry uses the same legacy-flat shape as standalone operations.

{
  "operation": "batch",
  "operations": [
    {
      "operation": "send",
      "data": {
        "method": "chat.postMessage",
        "data": { "channel": "C01ABCDEF23", "text": "Batch item 1" }
      }
    },
    {
      "operation": "receive",
      "data": {
        "method": "conversations.list",
        "data": { "limit": 10 }
      }
    }
  ]
}

Validate connectivity and handle failures

Run test after token rotation or permission changes so failures appear before critical workflows run. test validates bot_token format and calls auth.test. Most production issues come from scope mismatches, revoked tokens, or method-level rate limiting. Use bounded retries for temporary errors and log execution identifiers to speed up troubleshooting across Tealfabric and Slack audit trails.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "test"
  }'

{
  "success": true,
  "data": {
    "message": "Slack API connection test successful",
    "details": {
      "api_base_url": "https://slack.com/api",
      "user_id": "U01ABCDE23",
      "team": "Example Workspace"
    }
  }
}

Additional references

Slack API capabilities evolve regularly, so keep method payloads aligned with current Slack documentation: Slack API methods and Slack authentication and token types. A periodic review of scopes and message formatting keeps your integration secure and user-friendly.