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.

26.8 KB
Raw Blame
import json
import asyncio
from dataclasses import dataclass, field
from typing import Any

from django.conf import settings

import aiohttp
import structlog
from slack_sdk.errors import SlackApiError
from slack_sdk.web.async_client import AsyncWebClient
from slack_sdk.web.async_slack_response import AsyncSlackResponse

from posthog.dataclasses import frozen
from posthog.integrations import IntegrationManager, IntegrationRecord
from posthog.models.integration import SlackIntegration
from posthog.slack.formatting import channel_id_from_target
from posthog.slack.markdown import slack_rich_text
from posthog.storage import object_storage
from posthog.sync import database_sync_to_async
from posthog.utils import absolute_uri

from products.exports.backend.models.exported_asset import ExportedAsset
from products.slack_app.backend.facade.api import slack_followup_invite, slack_followup_invite_text
from products.subscriptions.backend.logic.subscription_utils import (
    DEBUG_PLACEHOLDER_IMAGE_URL,
    UTM_TAGS_BASE,
    _has_asset_failed,
    failed_asset_details,
    next_delivery_date_display,
    subscription_support_url,
    summary_skipped_over_budget_message,
)
from products.subscriptions.backend.models.subscription import Subscription, SubscriptionResource

logger = structlog.get_logger(__name__)


# Slack API error codes that indicate transient server-side issues — safe to retry.
# These are 5xx-equivalents in Slack's string-coded error model. Permanent errors
# (channel_not_found, invalid_auth, etc.) are NOT in this set and should fail fast.
_RETRYABLE_SLACK_ERRORS = frozenset(
    {
        "internal_error",
        "service_unavailable",
        "fatal_error",
        "request_timeout",
        "ratelimited",
        "rate_limited",
    }
)

# Slack accepts uploads up to 1 GB. This lower cap guards the delivery activity, which holds
# every chart in memory at once, not the Slack API. Keep it well above a normal chart render.
MAX_SLACK_UPLOAD_BYTES = 25 * 1024 * 1024


@dataclass
class SlackMessage:
    channel: str
    blocks: list[dict[str, Any]]
    title: str
    thread_messages: list[dict[str, Any]] = field(default_factory=list)
    # When False, Slack won't auto-unfurl links in the message — set by callers delivering
    # untrusted (e.g. LLM-generated) content to close the server-side link-fetch exfil channel.
    unfurl: bool = True


@frozen
class SlackDeliveryResult:
    main_message_sent: bool
    total_thread_messages: int
    failed_thread_message_indices: list[int]
    undelivered_asset_count: int = 0

    @property
    def is_partial_failure(self) -> bool:
        return self.main_message_sent and not self.is_complete_success

    @property
    def is_complete_success(self) -> bool:
        return (
            self.main_message_sent
            and len(self.failed_thread_message_indices) == 0
            and self.undelivered_asset_count == 0
        )


@frozen
class SlackGallery:
    channel: str
    initial_comment: str
    file_uploads: list[dict[str, Any]] = field(default_factory=list)
    blocks: list[dict[str, Any]] = field(default_factory=list)
    undelivered_asset_count: int = 0


def _ai_data_processing_approved(subscription: Subscription, integration: IntegrationRecord | None) -> bool:
    return integration is not None and bool(subscription.team.organization.is_ai_data_processing_approved)


def _asset_image_bytes(asset: ExportedAsset) -> bytes | None:
    if asset.content:
        return bytes(asset.content)
    if asset.content_location:
        return object_storage.read_bytes(asset.content_location, missing_ok=True)
    return None


def _insight_name(asset: ExportedAsset) -> str:
    return ((asset.insight.name or asset.insight.derived_name) if asset.insight else "Insight") or "Insight"


def _insight_link_block(asset: ExportedAsset) -> dict[str, Any] | None:
    if not asset.insight:
        return None
    return {
        "type": "rich_text",
        "elements": [
            {
                "type": "rich_text_section",
                "elements": [{"type": "link", "url": asset.insight.url, "text": _insight_name(asset)}],
            }
        ],
    }


def _subscription_title(
    subscription: Subscription,
    resource_info: SubscriptionResource,
    is_new_subscription: bool,
    *,
    has_failed_assets: bool = False,
) -> str:
    if subscription.title:
        display_name = f"*{subscription.title}* ({resource_info.kind}: {resource_info.name})"
    else:
        display_name = f"the {resource_info.kind} *{resource_info.name}*"

    if has_failed_assets:
        return f"Your subscription to {display_name} contains insights that could not be generated."

    if is_new_subscription:
        return (
            f"This channel has been subscribed to {display_name} on PostHog! 🎉\n\n"
            f"The next one will be sent on {next_delivery_date_display(subscription)}"
        )
    return f"Your subscription to {display_name} is ready! 🎉"


def _ai_summary_text(change_summary: str) -> str:
    summary_text = f"*AI summary:*\n{change_summary}"
    return summary_text[:2997] + "..." if len(summary_text) > 3000 else summary_text


def _overflow_text(shown_count: int, total_asset_count: int, resource_url: str, utm_tags: str) -> str:
    return (
        f"Showing {shown_count} of {total_asset_count} Insights. <{resource_url}?{utm_tags}|View the rest in PostHog>"
    )


def _subscription_header_blocks(
    subscription: Subscription, resource_info: SubscriptionResource, has_failed_assets: bool
) -> list[dict[str, Any]]:
    name = subscription.title or resource_info.name
    heading = f"Your subscription to {name} is ready! 🎉"
    if has_failed_assets:
        heading = f"⚠️ Your subscription to {name} needs attention"
    resource_icon = "🤖" if resource_info.kind == "AI prompt" else "📊"
    return [
        {"type": "divider"},
        {"type": "header", "text": {"type": "plain_text", "text": heading[:150]}},
        {
            "type": "context",
            "elements": [{"type": "plain_text", "text": f"{resource_icon} {resource_info.kind}: {resource_info.name}"}],
        },
    ]


def _summary_rich_text(summary: str) -> dict[str, Any]:
    return slack_rich_text(summary, allowed_root=absolute_uri("/"))


def _ai_summary_block(change_summary: str) -> dict[str, Any]:
    summary = change_summary
    if len(summary) > 2800:
        summary = summary[:2797] + "..."
    return {
        "type": "container",
        "title": {"type": "plain_text", "text": "✨ AI summary", "emoji": False},
        "has_header_divider": True,
        "width": "full",
        "child_blocks": [_summary_rich_text(summary)],
    }


def _subscription_footer_blocks(
    subscription: Subscription, resource_info: SubscriptionResource, integration: IntegrationRecord | None
) -> list[dict[str, Any]]:
    utm_tags = f"{UTM_TAGS_BASE}&utm_medium=slack"
    action_elements: list[dict] = [
        {
            "type": "button",
            "text": {"type": "plain_text", "text": "View in PostHog"},
            "url": f"{resource_info.url}?{utm_tags}",
        },
        {
            "type": "button",
            "text": {"type": "plain_text", "text": "Manage Subscription"},
            "url": f"{subscription.url}?{utm_tags}",
        },
    ]

    blocks: list[dict[str, Any]] = [
        {"type": "divider"},
        {"type": "actions", "elements": action_elements},
    ]
    ai_enabled = _ai_data_processing_approved(subscription, integration)
    if explore_hint := slack_followup_invite(integration, utm_tags=utm_tags, ai_enabled=ai_enabled):
        blocks.append(explore_hint)

    return blocks


def _prepare_slack_gallery(
    subscription: Subscription,
    assets: list[ExportedAsset],
    total_asset_count: int,
    is_new_subscription: bool = False,
    change_summary: str | None = None,
    summary_skipped_over_budget: bool = False,
    integration: IntegrationRecord | None = None,
) -> SlackGallery:
    utm_tags = f"{UTM_TAGS_BASE}&utm_medium=slack"
    resource_info = subscription.resource_info
    if not resource_info:
        raise NotImplementedError("This type of subscription resource is not supported")

    lines = [
        _subscription_title(
            subscription,
            resource_info,
            is_new_subscription,
            has_failed_assets=any(_has_asset_failed(a) for a in assets),
        )
    ]
    if change_summary:
        lines.append(_ai_summary_text(change_summary))
    elif summary_skipped_over_budget:
        billing_url = f"{absolute_uri('/organization/billing')}?{utm_tags}"
        lines.append(summary_skipped_over_budget_message(billing_url))

    file_uploads: list[dict[str, Any]] = []
    insight_links: list[dict[str, Any]] = []
    failed_names: list[str] = []
    unattached_assets: list[ExportedAsset] = []
    for asset in assets:
        if _has_asset_failed(asset):
            failed_names.append(_insight_name(asset))
            continue
        content = _asset_image_bytes(asset)
        if content is None:
            failed_names.append(_insight_name(asset))
            unattached_assets.append(asset)
            continue
        if len(content) > MAX_SLACK_UPLOAD_BYTES:
            logger.warning(
                "deliver_slack_gallery.asset_too_large",
                subscription_id=subscription.id,
                filename=asset.filename,
                size_bytes=len(content),
            )
            failed_names.append(_insight_name(asset))
            unattached_assets.append(asset)
            continue
        file_uploads.append({"content": content, "filename": asset.filename, "title": _insight_name(asset)})
        if subscription.dashboard_id and asset.insight:
            if insight_links:
                insight_links.append({"type": "text", "text": " · "})
            insight_links.append({"type": "link", "url": asset.insight.url, "text": _insight_name(asset)})

    if failed_names:
        lines.append("_Could not generate: " + ", ".join(failed_names) + "_")
    if total_asset_count > len(assets):
        lines.append(_overflow_text(len(assets), total_asset_count, resource_info.url, utm_tags))
    lines.append(
        f"<{resource_info.url}?{utm_tags}|View in PostHog> · <{subscription.url}?{utm_tags}|Manage subscription>"
    )

    ai_enabled = _ai_data_processing_approved(subscription, integration)
    if explore_hint := slack_followup_invite_text(integration, utm_tags=utm_tags, ai_enabled=ai_enabled):
        lines.append(explore_hint)

    blocks = _subscription_header_blocks(subscription, resource_info, bool(failed_names))
    if is_new_subscription:
        blocks.append({"type": "section", "text": {"type": "mrkdwn", "text": lines[0]}})
    if change_summary:
        blocks.append(_ai_summary_block(change_summary))
    elif summary_skipped_over_budget:
        billing_url = f"{absolute_uri('/organization/billing')}?{utm_tags}"
        blocks.append(
            {"type": "section", "text": {"type": "mrkdwn", "text": summary_skipped_over_budget_message(billing_url)}}
        )
    for asset in assets:
        if _has_asset_failed(asset):
            blocks.extend(_blocks_for_asset(asset, resource_info.url))
    for asset in unattached_assets:
        blocks.append(
            {"type": "section", "text": {"type": "plain_text", "text": f"Could not attach {_insight_name(asset)}"}}
        )
    if total_asset_count > len(assets):
        blocks.append(
            {
                "type": "section",
                "text": {
                    "type": "mrkdwn",
                    "text": _overflow_text(len(assets), total_asset_count, resource_info.url, utm_tags),
                },
            }
        )
    if insight_links:
        blocks.append({"type": "markdown", "text": "### Insights"})
        blocks.append({"type": "rich_text", "elements": [{"type": "rich_text_section", "elements": insight_links}]})
    blocks.extend(_subscription_footer_blocks(subscription, resource_info, integration))

    return SlackGallery(
        channel=channel_id_from_target(subscription.target_value),
        initial_comment="\n\n".join(lines),
        file_uploads=file_uploads,
        blocks=blocks,
        undelivered_asset_count=len(unattached_assets),
    )


def _blocks_for_asset(asset: ExportedAsset, resource_url: str, *, include_insight_link: bool = True) -> list[dict]:
    if _has_asset_failed(asset):
        details = failed_asset_details(asset)
        support_url = subscription_support_url(resource_url)
        error_blocks = [
            {
                "type": "rich_text",
                "elements": [
                    {
                        "type": "rich_text_section",
                        "elements": [
                            {"type": "text", "text": "Error details", "style": {"bold": True}},
                        ],
                    },
                    {
                        "type": "rich_text_preformatted",
                        "elements": [{"type": "text", "text": details.error_text}],
                    },
                ],
            },
            {"type": "divider"},
            {
                "type": "section",
                "text": {
                    "type": "mrkdwn",
                    "text": "*Next steps*\n1. Open the report in PostHog and check the error.\n2. Retry the report. If it still fails, contact support.",
                },
            },
            {
                "type": "actions",
                "elements": [
                    {
                        "type": "button",
                        "text": {"type": "plain_text", "text": "Open report"},
                        "url": resource_url,
                        "style": "primary",
                    },
                    {
                        "type": "button",
                        "text": {"type": "plain_text", "text": "Contact support"},
                        "url": support_url,
                    },
                ],
            },
        ]

        return [
            {
                "type": "container",
                "title": {"type": "plain_text", "text": f"Could not generate {details.insight_name}"[:150]},
                "has_header_divider": True,
                "width": "full",
                "child_blocks": error_blocks,
            }
        ]

    # Normal image block for successful assets
    image_url = asset.get_subscription_delivery_content_url()
    alt_text = None
    if asset.insight:
        alt_text = asset.insight.name or asset.insight.derived_name

    if settings.DEBUG:
        image_url = DEBUG_PLACEHOLDER_IMAGE_URL

    blocks = []
    if include_insight_link:
        if link := _insight_link_block(asset):
            blocks.append(link)
    blocks.append({"type": "image", "image_url": image_url, "alt_text": alt_text})
    return blocks


def get_slack_integration_for_team(team_id: int) -> IntegrationRecord | None:
    """Get Slack integration for a team. Returns None if not found."""
    return IntegrationManager.slack.oauth.find(team_id)


def send_slack_subscription_report(
    subscription: Subscription,
    assets: list[ExportedAsset],
    total_asset_count: int,
    is_new_subscription: bool = False,
) -> None:
    """Send Slack subscription report."""
    integration = get_slack_integration_for_team(subscription.team_id)

    if not integration:
        # TODO: Write error to subscription...
        logger.error("No Slack integration found for team...")
        return

    send_slack_message_with_integration(integration, subscription, assets, total_asset_count, is_new_subscription)


def _prepare_slack_message(
    subscription: Subscription,
    assets: list[ExportedAsset],
    total_asset_count: int,
    is_new_subscription: bool = False,
    change_summary: str | None = None,
    summary_skipped_over_budget: bool = False,
    integration: IntegrationRecord | None = None,
) -> SlackMessage:
    """Prepare Slack message content. Pure function with no side effects."""
    utm_tags = f"{UTM_TAGS_BASE}&utm_medium=slack"

    resource_info = subscription.resource_info
    if not resource_info:
        raise NotImplementedError("This type of subscription resource is not supported")

    channel = channel_id_from_target(subscription.target_value)
    first_asset, *other_assets = assets

    has_failed_assets = any(_has_asset_failed(a) for a in assets)
    title = _subscription_title(subscription, resource_info, is_new_subscription, has_failed_assets=has_failed_assets)

    blocks = _subscription_header_blocks(subscription, resource_info, has_failed_assets)
    if is_new_subscription and not has_failed_assets:
        blocks.append({"type": "section", "text": {"type": "mrkdwn", "text": title}})

    if change_summary:
        blocks.append(_ai_summary_block(change_summary))
    elif summary_skipped_over_budget:
        billing_url = f"{absolute_uri('/organization/billing')}?{utm_tags}"
        notice = summary_skipped_over_budget_message(f"<{billing_url}|Billing settings>")
        blocks.append({"type": "context", "elements": [{"type": "mrkdwn", "text": f"_{notice}_"}]})

    blocks.extend(
        _blocks_for_asset(
            first_asset, resource_url=resource_info.url, include_insight_link=bool(subscription.dashboard_id)
        )
    )

    if other_assets:
        blocks.append(
            {
                "type": "section",
                "text": {"type": "mrkdwn", "text": "_See 🧵 for more Insights_"},
            }
        )

    blocks.extend(_subscription_footer_blocks(subscription, resource_info, integration))

    # Prepare additional messages for thread
    thread_messages = []
    for asset in other_assets:
        asset_blocks = _blocks_for_asset(
            asset, resource_url=resource_info.url, include_insight_link=bool(subscription.dashboard_id)
        )
        thread_messages.append({"blocks": asset_blocks})

    if total_asset_count > len(assets):
        thread_messages.append(
            {
                "blocks": [
                    {
                        "type": "section",
                        "text": {
                            "type": "mrkdwn",
                            "text": _overflow_text(len(assets), total_asset_count, resource_info.url, utm_tags),
                        },
                    }
                ]
            }
        )

    # unfurl=False: the AI summary and explore hint carry links Slack would otherwise fetch,
    # burying the chart under preview cards and handing report content to Slack's link fetcher.
    return SlackMessage(
        channel=channel,
        blocks=blocks,
        title=title,
        thread_messages=thread_messages,
        unfurl=False,
    )


def send_slack_message_with_integration(
    integration: IntegrationRecord,
    subscription: Subscription,
    assets: list[ExportedAsset],
    total_asset_count: int,
    is_new_subscription: bool = False,
) -> None:
    """Send Slack message using provided integration (sync version)."""
    message_data = _prepare_slack_message(
        subscription,
        assets,
        total_asset_count,
        is_new_subscription,
        integration=integration,
    )
    slack_integration = SlackIntegration(integration, source="subscriptions")

    # Send main message
    message_res = slack_integration.client.chat_postMessage(
        channel=message_data.channel,
        blocks=message_data.blocks,
        text=message_data.title,
        unfurl_links=message_data.unfurl,
        unfurl_media=message_data.unfurl,
    )

    thread_ts = message_res.get("ts")
    if thread_ts:
        # Send thread messages
        for thread_msg in message_data.thread_messages:
            slack_integration.client.chat_postMessage(
                channel=message_data.channel,
                thread_ts=thread_ts,
                unfurl_links=message_data.unfurl,
                unfurl_media=message_data.unfurl,
                **thread_msg,
            )


async def _send_slack_message_with_retry(
    client: AsyncWebClient, max_retries: int = 3, **kwargs: Any
) -> AsyncSlackResponse:
    for attempt in range(max_retries):
        try:
            return await client.chat_postMessage(**kwargs)
        except (TimeoutError, SlackApiError) as e:
            if isinstance(e, SlackApiError):
                slack_error = e.response.get("error", "")
                if slack_error == "invalid_blocks":
                    log_event = "_send_slack_message_with_retry.invalid_blocks_retrying"
                elif slack_error in _RETRYABLE_SLACK_ERRORS:
                    log_event = "_send_slack_message_with_retry.transient_error_retrying"
                else:
                    raise
            else:
                log_event = "_send_slack_message_with_retry.timeout_retrying"

            if attempt >= max_retries - 1:
                raise

            logger.warning(
                log_event,
                attempt=attempt + 1,
                max_retries=max_retries,
                channel=kwargs.get("channel"),
                is_thread=bool(kwargs.get("thread_ts")),
                exc_info=True,
            )

            wait_time = 2**attempt
            await asyncio.sleep(wait_time)

    # Every attempt returns or raises, so only a max_retries below 1 gets here.
    raise ValueError(f"max_retries must be at least 1, got {max_retries}")


async def deliver_slack_message_data(
    integration: IntegrationRecord,
    subscription: Subscription,
    message_data: SlackMessage,
) -> SlackDeliveryResult:
    # shared send path: callers build the SlackMessage; retry + partial-failure handling are shared
    slack_integration = SlackIntegration(integration, source="subscriptions")

    async with aiohttp.ClientSession(trust_env=True) as slack_session:
        async_client = slack_integration.async_client(session=slack_session)

        message_res = await _send_slack_message_with_retry(
            async_client,
            channel=message_data.channel,
            blocks=message_data.blocks,
            text=message_data.title,
            unfurl_links=message_data.unfurl,
            unfurl_media=message_data.unfurl,
        )
        logger.info("deliver_slack_message_data.main_message_sent", subscription_id=subscription.id)

        thread_ts = message_res.get("ts")
        failed_thread_messages = []

        if thread_ts:
            for idx, thread_msg in enumerate(message_data.thread_messages):
                try:
                    await _send_slack_message_with_retry(
                        async_client,
                        channel=message_data.channel,
                        thread_ts=thread_ts,
                        unfurl_links=message_data.unfurl,
                        unfurl_media=message_data.unfurl,
                        **thread_msg,
                    )
                except Exception as e:
                    # Thread message failed, continue with others
                    logger.error(
                        "deliver_slack_message_data.slack_thread_message_failed_after_retries",
                        subscription_id=subscription.id,
                        channel=message_data.channel,
                        thread_index=idx,
                        total_thread_messages=len(message_data.thread_messages),
                        thread_ts=thread_ts,
                        error=str(e),
                        exc_info=True,
                    )
                    failed_thread_messages.append(idx)

    return SlackDeliveryResult(
        main_message_sent=True,
        total_thread_messages=len(message_data.thread_messages),
        failed_thread_message_indices=failed_thread_messages,
    )


async def deliver_slack_gallery(
    integration: IntegrationRecord, subscription: Subscription, gallery: SlackGallery
) -> SlackDeliveryResult:
    slack_integration = SlackIntegration(integration, source="subscriptions")
    async with aiohttp.ClientSession(trust_env=True) as slack_session:
        async_client = slack_integration.async_client(session=slack_session)
        if not gallery.file_uploads:
            await _send_slack_message_with_retry(
                async_client,
                channel=gallery.channel,
                text=gallery.initial_comment,
                blocks=gallery.blocks,
                unfurl_links=False,
                unfurl_media=False,
            )
            return SlackDeliveryResult(
                main_message_sent=True,
                total_thread_messages=0,
                failed_thread_message_indices=[],
                undelivered_asset_count=gallery.undelivered_asset_count,
            )

        for attempt in range(3):
            try:
                message_fields: dict[str, Any] = {"channel": gallery.channel}
                if gallery.blocks:
                    message_fields["blocks"] = json.dumps(gallery.blocks)
                else:
                    message_fields["initial_comment"] = gallery.initial_comment
                await async_client.files_upload_v2(
                    file_uploads=gallery.file_uploads,
                    **message_fields,
                )
                break
            except (TimeoutError, SlackApiError) as error:
                if isinstance(error, SlackApiError) and error.response.get("error", "") not in _RETRYABLE_SLACK_ERRORS:
                    raise
                if attempt >= 2:
                    raise
                await asyncio.sleep(2**attempt)

    logger.info(
        "deliver_slack_gallery.uploaded",
        subscription_id=subscription.id,
        file_count=len(gallery.file_uploads),
    )
    return SlackDeliveryResult(
        main_message_sent=True,
        total_thread_messages=0,
        failed_thread_message_indices=[],
        undelivered_asset_count=gallery.undelivered_asset_count,
    )


async def send_slack_message_with_integration_async(
    integration: IntegrationRecord,
    subscription: Subscription,
    assets: list[ExportedAsset],
    total_asset_count: int,
    is_new_subscription: bool = False,
    change_summary: str | None = None,
    summary_skipped_over_budget: bool = False,
) -> SlackDeliveryResult:
    if subscription.delivery_config.get("post_all_insights_in_main_message"):
        gallery = await database_sync_to_async(_prepare_slack_gallery, thread_sensitive=False)(
            subscription,
            assets,
            total_asset_count,
            is_new_subscription,
            change_summary=change_summary,
            summary_skipped_over_budget=summary_skipped_over_budget,
            integration=integration,
        )
        return await deliver_slack_gallery(integration, subscription, gallery)

    # `_prepare_slack_message` reads lazily-loaded ORM relations (e.g. `integration.team.organization`),
    # which Django forbids on the event loop. Build it in a thread before the async Slack send.
    message_data = await database_sync_to_async(_prepare_slack_message, thread_sensitive=False)(
        subscription,
        assets,
        total_asset_count,
        is_new_subscription,
        change_summary=change_summary,
        summary_skipped_over_budget=summary_skipped_over_budget,
        integration=integration,
    )
    return await deliver_slack_message_data(integration, subscription, message_data)