Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

20.4 KB
Raw Blame
from collections.abc import Mapping
from dataclasses import field
from typing import TYPE_CHECKING, Any, Optional, cast

from products.warehouse_sources.sources.sdk import detect

if TYPE_CHECKING:
    from products.warehouse_sources.sources.sdk import HogFunctionTemplateDC, IntegrationRecord

from temporalio import activity

from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    OAuthMixin,
    PointerPath,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceFieldSwitchGroupConfig,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    WebhookCreationResult,
    WebhookDeletionResult,
    WebhookSource,
    WebhookSourceManager,
    frozen,
)
from products.warehouse_sources.sources.slack._config import SlackSourceConfig
from products.warehouse_sources.sources.slack.settings import ENDPOINTS
from products.warehouse_sources.sources.slack.slack import (
    SlackResumeConfig,
    auth_test_user_id,
    get_channels,
    join_public_channels,
    manual_cache_id,
    slack_source,
    validate_credentials as validate_slack_credentials,
)

# Joining is one rate-limited call per channel, so a large workspace can't finish in one pass. The setup
# wizard and a manual refresh discover schemas inside a web request, which the gateway ends at 120
# seconds. The discovery activity times out at 10 minutes and runs again every few hours.
_REQUEST_JOIN_BUDGET_SECONDS = 30.0
_ACTIVITY_JOIN_BUDGET_SECONDS = 300.0
# Sources made before bring-your-own point at PostHog's shared Slack app with this key. No form field declares it.
_LEGACY_INTEGRATION_KEY = "slack_integration_id"


@frozen
class SlackAccess:
    """Resolved Slack credentials: the token, the user scoping private-channel discovery,
    and the id keying the per-workspace channel-list cache."""

    access_token: str = field(repr=False)  # secret: keep out of repr/logs
    authed_user_id: str | None
    cache_id: str


@SourceRegistry.register
class SlackSource(ResumableSource[SlackSourceConfig, SlackResumeConfig], WebhookSource[SlackSourceConfig], OAuthMixin):
    codebase_detection = detect(
        env=(
            "^SLACK_(BOT|APP|SIGNING|CLIENT)_",
            "^SLACK_WEBHOOK_URL$",
            "^SLACK_TOKEN$",
            "^SLACK_API_TOKEN$",
            "^SLACK_STATE_SECRET$",
            "^SLACK_SCOPES$",
            "^SLACK_USER_SCOPES$",
            "^SLACK_REDIRECT_URI$",
            "^SLACK_REDIRECT_URI_PATH$",
            "^SLACK_INSTALL_PATH$",
            "^SLACK_VERIFICATION_TOKEN$",
            "^SLACK_SERVICE_TOKEN$",
            "^SLACK_CHANNEL_ID$",
            "^HUBOT_SLACK_TOKEN$",
            "^LOG_SLACK_WEBHOOK_URL$",
        ),
        npm=(
            "@slack/web-api",
            "@slack/bolt",
            "@slack/webhook",
            "@slack/socket-mode",
            "@slack/oauth",
            "@slack/rtm-api",
            "@slack/types",
            "@slack/events-api",
            "@slack/interactive-messages",
            "@slack/client",
            "@slack/cli-hooks",
            "@slack/deno-slack-sdk",
            "hubot-slack",
            "@vercel/slack-bolt",
            "@chat-adapter/slack",
        ),
        pypi=("slack-sdk", "slack-bolt", "slackclient", "slackeventsapi", "slack-cli-hooks", "slack-discovery-sdk"),
        cargo=("slack-morphism",),
        composer=("laravel/slack-notification-channel", "jolicode/slack-php-api", "maknz/slack", "alek13/slack"),
        go=("github.com/slack-go/slack", "github.com/nlopes/slack"),
        hex=("slack",),
        maven=(
            "com.slack.api:slack-api-client",
            "com.slack.api:bolt",
            "com.slack.api:bolt-aws-lambda",
            "com.slack.api:bolt-google-cloud-functions",
            "com.slack.api:bolt-helidon",
            "com.slack.api:bolt-http4k",
            "com.slack.api:bolt-jakarta-jetty",
            "com.slack.api:bolt-jakarta-servlet",
            "com.slack.api:bolt-jakarta-socket-mode",
            "com.slack.api:bolt-jetty",
            "com.slack.api:bolt-ktor",
            "com.slack.api:bolt-micronaut",
            "com.slack.api:bolt-servlet",
            "com.slack.api:bolt-socket-mode",
            "com.slack.api:slack-api-client-kotlin-extension",
            "com.slack.api:slack-api-model",
            "com.slack.api:slack-api-model-kotlin-extension",
            "com.slack.api:slack-app-backend",
            "com.slack.api:slack-jakarta-socket-mode-client",
            "com.github.seratch:jslack",
            "com.github.seratch:jslack-api-client",
            "com.github.seratch:jslack-api-model",
            "com.github.seratch:jslack-app-backend",
            "com.github.seratch:jslack-lightning",
        ),
        rubygems=("slack-ruby-client", "slack-notifier", "slack-ruby-bot-server"),
    )
    setup_requires_ui = True

    api_docs_url = "https://api.slack.com/web"

    @property
    def source_type(self) -> ExternalDataSourceType:
        return ExternalDataSourceType.SLACK

    @property
    def webhook_template(self) -> Optional["HogFunctionTemplateDC"]:
        from products.warehouse_sources.sources.slack.webhook_template import template

        return template

    @property
    def webhook_resource_map(self) -> dict[str, str]:
        # Slack channel IDs are used as both schema names and webhook event keys,
        # so this is an identity mapping. We return an empty dict and rely on the
        # fallback in get_or_create_webhook_hog_function that defaults to using
        # the schema name as the object type.
        return {}

    def get_webhook_source_manager(self, inputs: SourceInputs) -> WebhookSourceManager:
        return WebhookSourceManager(inputs, inputs.logger)

    def in_use_oauth_slot(self, job_inputs: Mapping[str, Any]) -> PointerPath | None:
        # The legacy OAuth pointer has no form field. A pasted token wins over it, as in `_resolve_access_token`.
        return None if job_inputs.get("slack_access_token") else (_LEGACY_INTEGRATION_KEY,)

    @property
    def oauth_pointer_paths(self) -> frozenset[PointerPath]:
        return frozenset({(_LEGACY_INTEGRATION_KEY,)})

    @staticmethod
    def _get_authed_user_id(integration: "IntegrationRecord") -> str | None:
        return (integration.config or {}).get("authed_user", {}).get("id")

    def _resolve_access_token(self, config: SlackSourceConfig, team_id: int) -> SlackAccess:
        """Resolve credentials, preferring the bring-your-own bot token.

        - A ``slack_access_token`` means the customer's own Slack app. The token is stored on the
          source itself, so it stays within Slack's API terms for internal apps. ``auth.test`` gives
          the token's own user id and a hash of the token keys the cache. This is the only path new
          sources can configure.
        - Otherwise the source predates bring-your-own and still points at PostHog's shared app
          (legacy OAuth): credentials live on the linked Integration row. Pasting a token converts
          such a source in place — the token takes precedence and the stale integration id is ignored.
        """
        if config.slack_access_token:
            access_token = config.slack_access_token
            return SlackAccess(
                access_token=access_token,
                authed_user_id=auth_test_user_id(access_token),
                cache_id=manual_cache_id(access_token),
            )

        if not config.slack_integration_id:
            raise ValueError("Slack access token not found")

        integration = self.get_oauth_integration(config.slack_integration_id, team_id)
        oauth_token = integration.access_token
        if not oauth_token:
            raise ValueError("Slack access token not found")
        return SlackAccess(
            access_token=oauth_token,
            authed_user_id=self._get_authed_user_id(integration),
            cache_id=str(integration.id),
        )

    def create_webhook(
        self, config: SlackSourceConfig, webhook_url: str, team_id: int, api_version: str | None = None
    ) -> WebhookCreationResult:
        return WebhookCreationResult(
            success=False,
            error="Slack does not support automatic webhook creation. Please follow the manual setup instructions.",
        )

    def delete_webhook(
        self, config: SlackSourceConfig, webhook_url: str, team_id: int, api_version: str | None = None
    ) -> WebhookDeletionResult:
        # Slack does not expose an API to remove an Events API Request URL — the user has to
        # toggle it off manually in the app settings. Returning success lets the HogFunction
        # be cleaned up without showing the user a misleading "deletion failed" error.
        return WebhookDeletionResult(success=True)

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.SLACK,
            category=DataWarehouseSourceCategory.COMMUNICATION,
            caption="""Sync Slack channels, users, and messages into PostHog by connecting your own Slack app.

You create a Slack app in your workspace and paste its bot token here. Using your own app keeps message syncing within Slack's API terms — [read the docs](https://posthog.com/docs/cdp/sources/slack) for the full walkthrough.

**1. Create the app**

Open [Slack apps](https://api.slack.com/apps?new_app=1), click **From a manifest**, pick your workspace, and paste this manifest:

```json
{
    "display_information": {
        "name": "PostHog data warehouse",
        "description": "Sync Slack channels, users, and messages to PostHog data warehouse"
    },
    "oauth_config": {
        "scopes": {
            "bot": [
                "channels:read",
                "channels:join",
                "groups:read",
                "channels:history",
                "groups:history",
                "users:read",
                "users:read.email",
                "reactions:read"
            ]
        }
    },
    "settings": {
        "org_deploy_enabled": false,
        "socket_mode_enabled": false,
        "token_rotation_enabled": false
    }
}
```

**2. Install and copy the token**

Click **Install App > Install to Workspace** and authorize. Copy the **Bot User OAuth Token** (starts with `xoxb-`) and paste it below.

**3. Invite the bot**

Invite the bot to any channel whose messages you want to sync (`/invite @PostHog data warehouse`). After the source is created, follow the webhook steps to start receiving messages.""",
            iconPath="/static/services/slack.png",
            docsUrl="https://posthog.com/docs/cdp/sources/slack",
            releaseStatus=ReleaseStatus.GA,
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="slack_access_token",
                        label="Bot User OAuth Token",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="xoxb-...",
                        caption="Found under **Settings > Install App** in the Slack app you created from the manifest above.",
                        secret=True,
                    ),
                    SourceFieldSwitchGroupConfig(
                        name="join_public_channels",
                        sync_setting=True,
                        label="Automatically join public channels",
                        caption="On by default: the bot joins every public channel so their new messages sync without inviting it to each one. Turn it off to pick channels manually. Private channels always need a manual invite. Uses the `channels:join` scope, which the manifest above already includes.",
                        default=True,
                        fields=cast(list[FieldType], []),
                    ),
                ],
            ),
            webhookManualOnly=True,
            webhookSetupCaption="""Slack delivers new messages to PostHog through your Slack app's Event Subscriptions.

If you connected with your own Slack app (recommended), open that same app and add the Event Subscriptions below. Otherwise create a new app from the manifest.

1. Open your app (or [create one from a manifest](https://api.slack.com/apps?new_app=1))
2. Go to **Event Subscriptions**, toggle it on, and set the **Request URL** to the webhook URL shown below
3. Under **Subscribe to bot events**, add `message.channels` and `message.groups`, then **Save Changes** and reinstall if prompted
4. Open **Basic Information > App Credentials**, copy the **Signing Secret**, and paste it in the form below

Prefer a manifest? Paste this when creating the app — it wires the request URL and events for you:

```json
{
    "display_information": {
        "name": "PostHog data warehouse",
        "description": "Sync Slack channels, users, and messages to PostHog data warehouse"
    },
    "oauth_config": {
        "scopes": {
            "bot": [
                "channels:read",
                "channels:join",
                "groups:read",
                "channels:history",
                "groups:history",
                "users:read",
                "users:read.email",
                "reactions:read"
            ]
        }
    },
    "settings": {
        "event_subscriptions": {
            "request_url": "{webhook_url}",
            "bot_events": [
                "message.channels",
                "message.groups"
            ]
        },
        "org_deploy_enabled": false,
        "socket_mode_enabled": false,
        "token_rotation_enabled": false
    }
}
```""",
            webhookFields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="signing_secret",
                        label="Signing secret",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        secret=True,
                        placeholder="",
                    ),
                ],
            ),
        )

    def get_canonical_descriptions(self) -> CanonicalDescriptions:
        from products.warehouse_sources.sources.slack.canonical_descriptions import CANONICAL_DESCRIPTIONS

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "invalid_auth": "Your Slack token is invalid. Please reconnect the source.",
            "account_inactive": "Your Slack account is inactive. Please reconnect the source.",
            "token_revoked": "Your Slack token has been revoked. Please reconnect the source.",
            "missing_scope": "Your Slack app is missing scopes PostHog needs. Add the bot scopes from the setup manifest, reinstall the app to your workspace, then try again.",
            "not_allowed_token_type": "This Slack token type isn't supported. Please paste the Bot User OAuth Token (starts with xoxb-) from your Slack app's Install App page.",
            "not_in_channel": "The Slack bot is not a member of this channel. Please invite the bot to the channel and try again.",
            "channel_not_found": "This Slack channel was not found. It may have been deleted or the bot lacks permission to access it.",
            "Integration not found": "Your Slack integration was not found. Please reconnect the source.",
            "Slack access token not found": "Your Slack access token is missing. Please reconnect the source.",
        }

    def get_schemas(
        self,
        config: SlackSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        schemas: list[SourceSchema] = [
            SourceSchema(
                name=name,
                supports_incremental=len(endpoint_config.incremental_fields) > 0,
                supports_append=len(endpoint_config.incremental_fields) > 0,
                incremental_fields=endpoint_config.incremental_fields,
            )
            for name, endpoint_config in ENDPOINTS.items()
        ]

        access = self._resolve_access_token(config, team_id)
        # Only the bring-your-own path can auto-join — the legacy shared app lacks channels:join.
        # Joining is idempotent and only touches public channels the bot isn't in, so running it on
        # each discovery/refresh also picks up channels created since the last pass.
        if config.slack_access_token and config.join_public_channels and config.join_public_channels.enabled:
            # The discovery activity runs as soon as a source is created, with the larger budget, so it
            # joins what a request pass leaves.
            join_public_channels(
                access.access_token,
                access.cache_id,
                access.authed_user_id,
                time_budget_seconds=_ACTIVITY_JOIN_BUDGET_SECONDS
                if activity.in_activity()
                else _REQUEST_JOIN_BUDGET_SECONDS,
            )
        channels = get_channels(
            access.cache_id, access.access_token, access.authed_user_id, force_refresh=force_refresh
        )
        for ch in channels:
            if ch["id"] in ENDPOINTS:
                continue
            # Channel message tables are webhook-only: messages arrive via the realtime webhook
            # pipeline, not the polling sync, so incremental/append don't apply and full-refresh
            # would only delete data and reload nothing. Webhook is the only sync method we offer
            # (mirrors the Customer.io webhook schemas).
            schemas.append(
                SourceSchema(
                    name=ch["id"],
                    label=ch["name"],
                    supports_incremental=False,
                    supports_append=False,
                    supports_webhooks=True,
                    webhook_only=True,
                    incremental_fields=[],
                )
            )

        return schemas

    def validate_credentials(
        self, config: SlackSourceConfig, team_id: int, schema_name: Optional[str] = None, api_version: str | None = None
    ) -> tuple[bool, str | None]:
        try:
            access = self._resolve_access_token(config, team_id)

            is_valid, error_code = validate_slack_credentials(access.access_token)
            if is_valid:
                return True, None

            if error_code is None:
                return False, "Couldn't reach Slack to verify your credentials. Please try again in a moment."

            # Reuse the per-error copy already curated for the sync path so create-time and
            # sync-time messages stay consistent (e.g. missing_scope is a re-auth, not a bad token).
            message = self.get_non_retryable_errors().get(error_code)
            if message:
                return False, message
            return False, f"Slack rejected the credentials ({error_code}). Please reconnect the source."
        except Exception as e:
            return False, f"Failed to validate Slack credentials: {str(e)}"

    def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[SlackResumeConfig]:
        return ResumableSourceManager[SlackResumeConfig](inputs, SlackResumeConfig)

    def source_for_pipeline(
        self,
        config: SlackSourceConfig,
        resumable_source_manager: ResumableSourceManager[SlackResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        access = self._resolve_access_token(config, inputs.team_id)

        # For channel schemas, the schema name is the channel ID itself
        channel_id = inputs.schema_name if inputs.schema_name not in ENDPOINTS else None

        webhook_source_manager = self.get_webhook_source_manager(inputs)

        return slack_source(
            access_token=access.access_token,
            cache_id=access.cache_id,
            endpoint=inputs.schema_name,
            team_id=inputs.team_id,
            job_id=inputs.job_id,
            resumable_source_manager=resumable_source_manager,
            should_use_incremental_field=inputs.should_use_incremental_field,
            db_incremental_field_last_value=inputs.db_incremental_field_last_value
            if inputs.should_use_incremental_field
            else None,
            incremental_field=inputs.incremental_field,
            channel_id=channel_id,
            webhook_source_manager=webhook_source_manager,
            authed_user=access.authed_user_id,
        )