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.

feat(slack_app): start the slack onboarding on a person's first mention (#129895)

Vojta Bartošb77958c87c13
diff --git a/docs/internal/slack-local-setup-guide.md b/docs/internal/slack-local-setup-guide.md
index 775b603262b4..7e3e59d92a8a 100644
--- a/docs/internal/slack-local-setup-guide.md
+++ b/docs/internal/slack-local-setup-guide.md
@@ -141,7 +141,7 @@ Django must be up at that moment.
> otherwise) and the coding agent doesn't use it.
> The `app_home` block + `app_home_opened` bot event power the App Home tab. With the
-> `slack-app-onboarding` flag on, the same event, an install, a reinstall and a `team_join` start the
+> `slack-app-onboarding` flag on, the same event, an install, a reinstall, a `team_join` and a person's first `@PostHog` mention start the
> `slack-app-onboarding` Temporal workflow, which posts a person's onboarding thread in the PostHog DM
> once. It needs the Temporal worker running. The thread checks each step again before it shows it,
> so a person who already linked their account or chose a model sees that step as already set.
diff --git a/products/slack_app/backend/api.py b/products/slack_app/backend/api.py
index 287c1faff66a..4ad91054844d 100644
--- a/products/slack_app/backend/api.py
+++ b/products/slack_app/backend/api.py
@@ -79,6 +79,7 @@ from products.slack_app.backend.services import (
)
from products.slack_app.backend.services.commands import SLASH_COMMAND_PREFIX, mention_command_redirect
from products.slack_app.backend.services.integration_resolver import (
+ ResolutionResult,
UserResolutionFailure,
load_integrations,
pick_a_project_message,
@@ -3077,6 +3078,7 @@ def route_posthog_code_event_to_relevant_region(
posthog_user=attributed_user,
**unresolved_user_properties(resolution, probe),
)
+ _start_onboarding_on_mention(event, slack_team_id, workspace_result)
return ROUTE_HANDLED_LOCALLY
posthog_user = resolution.user
@@ -3157,9 +3159,10 @@ def route_posthog_code_event_to_relevant_region(
candidate_count=len(candidates),
picker_shown=picker_shown,
)
+ _start_onboarding_on_mention(event, slack_team_id, workspace_result)
return ROUTE_HANDLED_LOCALLY
- return _dispatch_mention_to_target(
+ route = _dispatch_mention_to_target(
event,
mention_target,
slack_team_id,
@@ -3169,6 +3172,8 @@ def route_posthog_code_event_to_relevant_region(
is_ext_shared_channel=is_ext_shared_channel,
awaited_request_reply=awaited_request_reply,
)
+ _start_onboarding_on_mention(event, slack_team_id, workspace_result)
+ return route
if event_type == "member_joined_channel":
return _route_member_joined_channel(
@@ -4909,6 +4914,18 @@ def _report_slack_mention_dropped(
)
+def _start_onboarding_on_mention(event: dict, slack_team_id: str, workspace_result: ResolutionResult) -> None:
+ """Someone who only tags PostHog in channels may never open its DM, so their mention starts the onboarding.
+ It runs after the mention is handled, so a slow onboarding start never delays the answer. A guest from
+ another workspace in a shared channel gets no onboarding, because it would come from this workspace's app."""
+ slack_user_id = event.get("user")
+ if event.get("type") != "app_mention" or event.get("user_team", slack_team_id) != slack_team_id:
+ return
+ integration = workspace_result.resolved_or_first()
+ if integration is not None and isinstance(slack_user_id, str) and slack_user_id:
+ request_onboarding(integration, slack_user_id, may_start=True, start_only=True)
+
+
def _start_mention_workflow(
event: dict,
integration: WorkspaceIntegration,
diff --git a/products/slack_app/backend/logic/onboarding/dispatch.py b/products/slack_app/backend/logic/onboarding/dispatch.py
index 2aadef335ace..51e6f8e2611a 100644
--- a/products/slack_app/backend/logic/onboarding/dispatch.py
+++ b/products/slack_app/backend/logic/onboarding/dispatch.py
@@ -20,14 +20,21 @@ BURST_WINDOW_SECONDS = 60 * 60
def request_onboarding(
- integration: WorkspaceIntegration, slack_user_id: str, *, may_start: bool, spread_burst: bool = False
+ integration: WorkspaceIntegration,
+ slack_user_id: str,
+ *,
+ may_start: bool,
+ spread_burst: bool = False,
+ start_only: bool = False,
) -> None:
"""Start the person's onboarding, or refresh the one in progress. Only a ``may_start`` trigger can start
- one, and only for a person with no onboarding state. Never raises: the onboarding catches up on the next trigger."""
+ one, and only for a person with no onboarding state. A ``start_only`` trigger stops once the thread exists, so
+ a busy path does not wait for Temporal on each call, but a start that failed is tried again. Never raises: the
+ onboarding catches up on the next trigger."""
try:
slack_workspace_id = integration.integration_id
state = resolve_onboarding(slack_workspace_id, slack_user_id)
- if state is not None and state.completed:
+ if state is not None and (state.completed or (start_only and state.root_ts is not None)):
return
start_delay_seconds = 0
if state is None:
diff --git a/products/slack_app/backend/tests/logic/onboarding/test_thread.py b/products/slack_app/backend/tests/logic/onboarding/test_thread.py
index 3d01672e0fb6..2ad1310d4093 100644
--- a/products/slack_app/backend/tests/logic/onboarding/test_thread.py
+++ b/products/slack_app/backend/tests/logic/onboarding/test_thread.py
@@ -276,17 +276,21 @@ def test_a_model_that_cannot_be_saved_tells_the_person_why(org_team_user) -> Non
@pytest.mark.django_db
@pytest.mark.parametrize(
- "stored, may_start, flag_on, starts",
+ "stored, may_start, flag_on, start_only, starts",
[
- ("none", True, True, True),
- ("none", True, False, False),
- ("none", False, True, False),
- ("open", False, False, True),
- ("completed", True, True, False),
+ ("none", True, True, False, True),
+ ("none", True, False, False, False),
+ ("none", False, True, False, False),
+ ("open", False, False, False, True),
+ ("completed", True, True, False, False),
+ ("none", True, True, True, True),
+ ("open", True, True, True, False),
+ # A start that failed after the state was stored has no thread yet, so the next mention tries again.
+ ("failed_start", True, True, True, True),
],
)
def test_only_people_with_onboarding_left_start_the_workflow(
- stored: str, may_start: bool, flag_on: bool, starts: bool, org_team_user
+ stored: str, may_start: bool, flag_on: bool, start_only: bool, starts: bool, org_team_user
) -> None:
_, team, _ = org_team_user
integration = _install(team)
@@ -294,12 +298,14 @@ def test_only_people_with_onboarding_left_start_the_workflow(
update_onboarding(SLACK_TEAM_ID, SLACK_USER_ID, root=("D1", "100.1"))
elif stored == "completed":
update_onboarding(SLACK_TEAM_ID, SLACK_USER_ID, completed_reason="finished")
+ elif stored == "failed_start":
+ update_onboarding(SLACK_TEAM_ID, SLACK_USER_ID, start=True)
with (
patch.object(dispatch, "is_slack_app_onboarding_enabled", return_value=flag_on),
patch.object(dispatch, "_signal_with_start") as start,
):
- dispatch.request_onboarding(integration, SLACK_USER_ID, may_start=may_start)
+ dispatch.request_onboarding(integration, SLACK_USER_ID, may_start=may_start, start_only=start_only)
assert start.called is starts
if stored == "none":
diff --git a/products/slack_app/backend/tests/test_posthog_code_event_handler.py b/products/slack_app/backend/tests/test_posthog_code_event_handler.py
index ea7483f7ce75..47fb2ac56498 100644
--- a/products/slack_app/backend/tests/test_posthog_code_event_handler.py
+++ b/products/slack_app/backend/tests/test_posthog_code_event_handler.py
@@ -593,6 +593,40 @@ class TestRoutePostHogCodeEventToRelevantRegion(TestCase):
mock_sync_connect.return_value.start_workflow.assert_called_once()
assert awaited_request_from("T12345", "C001", message_ts, now=now) is None
+ @parameterized.expand(
+ [
+ ("unlinked_member", "[email protected]", {}, True),
+ ("known_member", "[email protected]", {}, True),
+ ("other_workspace_guest", "[email protected]", {"user_team": "T_OTHER"}, False),
+ ]
+ )
+ @patch("products.slack_app.backend.api.request_onboarding")
+ @patch("products.slack_app.backend.api._post_slack_user_feedback")
+ @patch("products.slack_app.backend.api.asyncio.run")
+ @patch("products.slack_app.backend.api.sync_connect")
+ @override_settings(DEBUG=False, CLOUD_DEPLOYMENT="US")
+ def test_a_mention_starts_the_onboarding_after_the_mention_is_handled(
+ self, _name, email, extra, starts, sync_connect, _asyncio_run, _post_feedback, request_onboarding
+ ):
+ SlackUserProfileCache.objects.filter(slack_user_id="U123").delete()
+ self._seed_slack_user_cache("U123", email)
+ calls = MagicMock()
+ calls.attach_mock(sync_connect, "mention_workflow")
+ calls.attach_mock(request_onboarding, "onboarding")
+
+ from products.slack_app.backend.api import route_posthog_code_event_to_relevant_region
+
+ request = self.factory.post("/slack/event-callback/", HTTP_HOST="us.posthog.com")
+ route_posthog_code_event_to_relevant_region(request, {**self.event, **extra}, "T12345")
+
+ assert request_onboarding.called is starts
+ if starts:
+ assert request_onboarding.call_args.args[1] == "U123"
+ assert request_onboarding.call_args.kwargs == {"may_start": True, "start_only": True}
+ # A slow onboarding start must not delay the answer, so it runs after the mention's own workflow start.
+ order = [call[0] for call in calls.mock_calls if call[0] in ("mention_workflow", "onboarding")]
+ assert order[-1] == "onboarding"
+
@patch("products.slack_app.backend.api.posthoganalytics.capture")
@patch("products.slack_app.backend.api._post_slack_user_feedback")
@patch("products.slack_app.backend.api.asyncio.run")