: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
"""
Emit PostHog analytics events for ticket and message state changes.
These events power workflow triggers (e.g. "if ticket pending for X days, resolve it").
Staff/system actions use the actor's distinct_id; customer actions use the ticket's distinct_id.
Events are sent to the customer's PostHog project via their team's API token.
"""
import uuid
from collections.abc import Mapping
from datetime import datetime
from typing import Literal
from django.utils import timezone
import structlog
from posthog.api.capture import capture_internal
from posthog.clickhouse.query_tagging import Feature, Product, tags_context
from posthog.event_usage import groups as build_groups
from posthog.models.group.util import get_groups_by_identifiers
from posthog.models.group_type_mapping import get_group_types_for_project
from posthog.models.organization import OrganizationMembership
from posthog.models.person.person import Person
from posthog.models.person.util import get_persons_by_distinct_ids
from posthog.models.team import Team
from posthog.models.user import User
from posthog.personhog_client.caller_tag import personhog_caller_tag
from posthog.settings import SITE_URL
from products.access_control.backend.models.role import Role
from products.cdp.backend.internal_events import InternalEventEvent, produce_internal_event
from products.conversations.backend.cache import get_cached_resolved_groups, set_cached_resolved_groups
from products.conversations.backend.models import Ticket, TicketAssignment
from products.conversations.backend.models.constants import Channel, OrganizationIdSource
logger = structlog.get_logger(__name__)
EVENT_SOURCE = "conversations_events"
# Fixed namespace so a retried reply produces the same internal event uuid.
_TEAM_REPLY_INTERNAL_EVENT_NAMESPACE = uuid.UUID("3f6c2a8e-5b1d-4e7a-9c0f-2d8b7e4a1c6f")
# Events that can carry message text or a customer email. The ticket purge files
# an event-removal request for this set, scoped to one ticket id.
CONVERSATION_ANALYTICS_EVENTS = (
"$conversation_ticket_created",
"$conversation_ticket_status_changed",
"$conversation_ticket_priority_changed",
"$conversation_ticket_assigned",
"$conversation_message_sent",
"$conversation_private_message_sent",
"$conversation_message_received",
)
ActorType = Literal["user", "system", "external", "customer"]
def _get_actor_properties(actor: User | None, actor_type: ActorType) -> dict:
"""Build actor-related properties for an event."""
return {
"actor_type": actor_type,
"actor_id": actor.id if actor else None,
"actor_email": actor.email if actor else None,
}
def _get_actor_distinct_id(
ticket: Ticket,
actor: User | None,
actor_type: ActorType,
) -> str:
"""Determine the distinct_id based on who performed the action.
User actions are attributed to the staff member.
System/external/customer actions are attributed to the customer.
"""
if actor_type == "user" and actor and actor.distinct_id:
return actor.distinct_id
return ticket.distinct_id or ticket.channel_source or "unknown"
# A resolved ``$groups`` describes the customer, never us: these events are captured into the
# support team's own project, so its uuid as the `project` group mis-attributes every ticket.
# Channels whose customer email is tied to a provider-verified identity and is therefore safe
# to use for organization attribution.
_EMAIL_FALLBACK_CHANNELS = frozenset({Channel.EMAIL.value, Channel.SLACK.value, Channel.TEAMS.value})
# Latest organization/customer group keys from the customer's recent events. We read the
# dedicated $group_N columns (set on every event that carries $groups) rather than filtering on
# $groupidentify events: posthog.group(type, key) called without properties associates the group
# with all subsequent events but emits no $groupidentify (the documented SDK behavior), and even
# newer SDKs only re-emit it for newly-seen groups. A $groupidentify filter would therefore
# silently miss exactly the cross-region customers this fallback exists for — those whose apps
# don't pass group properties, or whose last group identify predates the 30-day window.
# {org_col}/{project_col}/{customer_select} are interpolated from this project's own group-type indexes
# (see _resolve_groups_from_analytics); column names can't be HogQL placeholders. One argMax over both
# group columns pairs an organization with the project it was seen with, never with an older one.
GROUPS_FROM_EVENTS_QUERY = """
SELECT
argMax(tuple({org_col}, {project_col}), timestamp),
{customer_select}
FROM events
WHERE distinct_id IN {{distinct_ids}}
AND timestamp >= now() - INTERVAL 30 DAY
AND {org_col} != ''
"""
def _resolve_groups_from_analytics(team: Team, distinct_ids: list[str]) -> dict | None:
"""Resolve ``$groups`` from the customer's recent analytics events in ClickHouse.
Fallback for when the ``OrganizationMembership`` lookup misses: that join runs
against this region's Postgres only, so accounts registered in another region
(e.g. an EU user filing a ticket against a US project) are invisible to it.
Their identified app sessions, however, stamp ``$group_N`` onto every event
captured into this project, which is cross-region by construction.
Event-supplied groups are captured with the project's public token and are
therefore spoofable — fine for analytics enrichment (same trust level as
``$identify``), never for authorization. ``instance`` is rebuilt server-side;
``project`` is the customer's own project group, read from the same event as the
organization.
"""
if not distinct_ids:
return None
cached = get_cached_resolved_groups(team.id, distinct_ids)
if cached is not None:
return cached or None # {} is the negative-cache sentinel
# The $group_N column index is per-project, so resolve the org/customer indexes from this
# project's group-type mapping. Doubles as a cheap guard: bail (and negative-cache) for
# projects without an organization group type before touching ClickHouse.
group_type_index = {
gtm["group_type"]: gtm["group_type_index"] for gtm in get_group_types_for_project(team.project_id)
}
org_index = group_type_index.get("organization")
if org_index is None:
set_cached_resolved_groups(team.id, distinct_ids, None)
return None
customer_index = group_type_index.get("customer")
project_index = group_type_index.get("project")
# Indexes are trusted ints (0-4) from the project's own mapping; safe to interpolate.
org_col = f"`$group_{org_index}`"
customer_select = (
f"argMaxIf(`$group_{customer_index}`, timestamp, `$group_{customer_index}` != '')"
if customer_index is not None
else "''"
)
project_col = f"`$group_{project_index}`" if project_index is not None else "''"
query = GROUPS_FROM_EVENTS_QUERY.format(org_col=org_col, project_col=project_col, customer_select=customer_select)
# Deferred: hogql.query pulls the whole query-runner layer, and this module loads
# at django.setup() via the conversations signal wiring.
from posthog.hogql import ast # noqa: PLC0415
from posthog.hogql.query import execute_hogql_query # noqa: PLC0415
with tags_context(product=Product.CONVERSATIONS, feature=Feature.QUERY):
response = execute_hogql_query(
query,
placeholders={"distinct_ids": ast.Constant(value=distinct_ids)},
team=team,
query_type="conversations_groups_lookup",
)
groups: dict | None = None
if response.results:
(org_key, project_key), customer_key = response.results[0]
if org_key:
groups = {"instance": SITE_URL, "organization": org_key}
if customer_key:
groups["customer"] = customer_key
if project_key:
groups["project"] = project_key
set_cached_resolved_groups(team.id, distinct_ids, groups)
return groups
def _resolve_groups_from_person_properties(team: Team, person: Person) -> dict | None:
"""Resolve ``$groups`` from the person's own ``organization_id`` profile property.
Fallback for when both the membership lookup and the analytics fallback miss:
app instrumentation commonly stamps the org id onto the person profile via
``$identify``, and the profile persists even when the person's last identified
session predates the analytics fallback's 30-day event window.
Person properties are client-supplied — the same trust level as the analytics
fallback (enrichment, never authorization). The value only counts when it names
an organization group that already exists in this project, so a team whose
``organization_id`` person property follows a different convention than its
organization group keys can't stamp bogus group keys onto events. A value that
coincidentally matches an unrelated org group key (e.g. small-integer keys) can
still mis-enrich — same collision class as event-supplied ``$groups``.
"""
org_id = (person.properties or {}).get("organization_id")
if not org_id or not isinstance(org_id, str):
return None
group_type_index = {
gtm["group_type"]: gtm["group_type_index"] for gtm in get_group_types_for_project(team.project_id)
}
org_index = group_type_index.get("organization")
if org_index is None:
return None
if not get_groups_by_identifiers(team.id, org_index, [org_id]):
return None
return {"instance": SITE_URL, "organization": org_id}
def _requester_project(membership: OrganizationMembership) -> Team | None:
"""The requester's own project for the ``project`` group, or ``None`` when it can't be named.
``current_team`` follows the project switcher, so it names the project the requester worked
in last — usually the one they filed the ticket from. Read the field directly rather than
``user.team``, which backfills and saves a project for users who have none.
A multi-org requester can have a current project outside the organization this membership
resolved, and an organization and a project from two different organizations would enrich
the event with a contradiction. Leave ``project`` unset in that case.
"""
current_team = membership.user.current_team
if current_team is None or current_team.organization_id != membership.organization_id:
return None
return current_team
def _org_groups_for_person(ticket: Ticket, team: Team, person: Person, distinct_ids: list[str]) -> dict | None:
"""Resolve org ``$groups`` for an already-resolved person: membership, then analytics
events, then the person's own profile.
Each lookup hits a different subsystem (Postgres, ClickHouse, personhog), so failures
are isolated per step: the created event is emitted exactly once, and a transient error
in one source must degrade to the next fallback rather than permanently losing the
ticket's attribution (which downstream SLA/tagging workflows key off).
"""
if distinct_ids:
try:
membership = (
OrganizationMembership.objects.select_related("organization", "user__current_team")
.filter(user__distinct_id__in=distinct_ids)
.first()
)
if membership:
return build_groups(membership.organization, _requester_project(membership))
except Exception:
logger.exception("ticket_org_membership_lookup_failed", team_id=team.id, ticket_id=str(ticket.id))
# Membership rows are region-local: accounts registered in another region
# never appear in this Postgres. Fall back to the $groups their sessions
# stamped onto this project's analytics events.
try:
groups = _resolve_groups_from_analytics(team, distinct_ids)
if groups:
return groups
except Exception:
logger.exception("ticket_org_analytics_lookup_failed", team_id=team.id, ticket_id=str(ticket.id))
# Their events may have aged out of the analytics window; the profile they
# identified with is still the same person's own claim about their org.
try:
return _resolve_groups_from_person_properties(team, person)
except Exception:
logger.exception("ticket_org_person_properties_lookup_failed", team_id=team.id, ticket_id=str(ticket.id))
return None
def _has_unverified_relayed_identity(ticket: Ticket) -> bool:
return (ticket.anonymous_traits or {}).get("email_relayed") is True and ticket.identity_verified is not True
def _identified_person_for_ticket(ticket: Ticket, team: Team) -> tuple[Person, str] | None:
if not ticket.distinct_id:
return None
try:
# Only is_identified and properties are read, and the membership lookup keys off
# the ticket's own distinct_id, so skip fetching the person's distinct_ids.
with personhog_caller_tag("conversations/ticket-event-person"):
persons = get_persons_by_distinct_ids(team.id, [ticket.distinct_id], distinct_id_limit=0)
except Exception:
# A failed lookup is not "no identified person": the caller still tries the email path
# instead of losing attribution to a transient personhog error.
logger.exception("ticket_org_person_lookup_failed", team_id=team.id, ticket_id=str(ticket.id))
return None
identified_person = next((person for person in persons if person.is_identified), None)
return (identified_person, ticket.distinct_id) if identified_person is not None else None
def _resolve_person_org_groups(ticket: Ticket, team: Team) -> tuple[bool, dict | None]:
"""Resolve the customer organization's ``$groups`` from the requester's identity.
Returns ``(process_person, groups)``. ``groups`` is ``None`` when the
customer can't be tied to a PostHog organization.
The web widget sets ``ticket.distinct_id`` to a real PostHog distinct_id,
so the membership is found directly. Other channels (Slack, Email, MS
Teams) set ``distinct_id`` to the customer email (or empty), so we fall
back to looking the person up by ``properties.email`` in ClickHouse and
resolving the membership through that person's real distinct_ids. Either
way, the person's own ``organization_id`` profile property is the last
resort when the membership and analytics lookups both miss.
"""
if _has_unverified_relayed_identity(ticket):
return False, None
# An identified person is authoritative. If they have no org membership, do not guess
# via email because a shared address could resolve to a different person's org.
identified_identity = _identified_person_for_ticket(ticket, team)
if identified_identity is not None:
identified_person, distinct_id = identified_identity
groups = _org_groups_for_person(ticket, team, identified_person, [distinct_id])
if groups:
return True, groups
return False, None
# 2. Email fallback, restricted to channels with a provider-verified email identity.
# Never trust the public widget's attacker-controlled anonymous_traits.email here.
if ticket.channel_source not in _EMAIL_FALLBACK_CHANNELS:
return False, None
email = (ticket.anonymous_traits or {}).get("email") or ticket.email_from
if email:
# person_lookup pulls the HogQL query layer; this module loads at django.setup()
# via the conversations signal wiring, so import it lazily.
from products.conversations.backend.person_lookup import _get_persons_by_email # noqa: PLC0415
person: Person | None = None
try:
person = _get_persons_by_email(team, [email]).get(email.lower())
except Exception:
# Same isolation as above: a failed email lookup still leaves the
# Slack-channel fallback in _resolve_org_groups a chance to attribute.
logger.exception("ticket_org_email_person_lookup_failed", team_id=team.id, ticket_id=str(ticket.id))
if person is not None:
groups = _org_groups_for_person(ticket, team, person, person.distinct_ids or [])
if groups:
return True, groups
return False, None
def _resolve_groups_from_slack_channel(team: Team, slack_channel_id: str) -> dict | None:
"""Attribute the ticket to the customer analytics account bound to its Slack channel.
Last-resort fallback when the requester can't be tied to an organization: a
dedicated support channel maps to one account, and that account's ``external_id``
is the group key at the team's configured account group type. Channel-level
evidence only — it says which account the ticket belongs to, not who sent it.
"""
group_type_index = team.customer_analytics_config.account_group_type_index
if group_type_index is None:
return None
group_type_name = next(
(
gtm["group_type"]
for gtm in get_group_types_for_project(team.project_id)
if gtm["group_type_index"] == group_type_index
),
None,
)
if group_type_name is None:
return None
# The facade pulls the workflows/notebooks facades with it; keep that off the
# django.setup() path this module loads on via the conversations signal wiring.
from products.customer_analytics.backend.facade import api as customer_analytics # noqa: PLC0415
account = customer_analytics.get_account_ref_by_slack_channel_id(team.id, slack_channel_id)
if account is None or not account.external_id:
return None
return {"instance": SITE_URL, group_type_name: account.external_id}
def _resolve_org_groups(ticket: Ticket, team: Team) -> tuple[bool, dict | None, str | None]:
"""Resolve a ticket's ``$groups``, preferring the requester's identity.
Returns ``(process_person, groups, source)`` where ``source`` is an
``OrganizationIdSource`` value recording how ``groups`` was resolved, or
``None`` when nothing resolved. Slack tickets that can't be attributed
through the person fall back to the customer analytics account associated
with the ticket's Slack channel.
"""
process_person, groups = _resolve_person_org_groups(ticket, team)
if groups is not None:
return process_person, groups, OrganizationIdSource.PERSON
# Deliberately no analytics fallback keyed on the bare ticket distinct_id here: for
# email/Slack/Teams that value is the raw customer email, and events under it are
# captured with the public project token, so anyone who knows the email can plant a
# $groups value. identity_verified only attests the ticket's sender, not who captured
# historical events under that key. Event-derived attribution is only trusted when
# anchored to a resolved person (see _org_groups_for_person).
if ticket.channel_source == Channel.SLACK.value and ticket.slack_channel_id:
groups = _resolve_groups_from_slack_channel(team, ticket.slack_channel_id)
if groups is not None:
return process_person, groups, OrganizationIdSource.SLACK_CHANNEL_ACCOUNT
return process_person, None, None
def _groups_from_org_id(organization_id: str) -> dict:
"""Rebuild minimal $groups from a stored org id, skipping the expensive resolver."""
return {"instance": SITE_URL, "organization": organization_id}
def _get_ticket_base_properties(ticket: Ticket) -> dict:
return {
"ticket_id": str(ticket.id),
"ticket_number": ticket.ticket_number,
"channel_source": ticket.channel_source,
"channel_detail": ticket.channel_detail,
"status": ticket.status,
"priority": ticket.priority,
}
def _is_customer_email_verified(ticket: Ticket, customer_email: str) -> bool:
# A server check attests one identity on a verified ticket: the signed widget distinct_id, the
# authenticated sender in email_from, or the platform user's email in distinct_id on Slack and
# Teams. An outbound email ticket keeps the recipient's analytics ID in distinct_id, so email
# tickets use email_from. The widget form can supply any email, so the email counts as verified
# only when it is that attested identity.
if ticket.channel_source == Channel.EMAIL:
attested_identity = ticket.email_from or ticket.distinct_id
else:
attested_identity = ticket.distinct_id
return (
ticket.identity_verified is True
and bool(customer_email)
and customer_email.lower() == (attested_identity or "").lower()
)
def _get_customer_properties(ticket: Ticket, *, include_distinct_id: bool = False) -> dict:
"""Customer identity on the ticket, for workflow filters and analytics."""
traits = ticket.anonymous_traits or {}
# The ticket update API stores traits as any JSON value, so the email trait can be a non-string.
trait_email = traits.get("email")
customer_email = (trait_email if isinstance(trait_email, str) else "") or ticket.email_from or ""
properties = {
"customer_name": traits.get("name", ""),
"customer_email": customer_email,
"customer_email_verified": _is_customer_email_verified(ticket, customer_email),
}
if include_distinct_id:
properties["customer_distinct_id"] = ticket.distinct_id or ""
return properties
def _message_author_identity(ticket: Ticket, item_context: Mapping[str, object]) -> str:
# The ticket's attested identity belongs to the person who opened it, but other Slack or Teams
# thread members, other email senders, and an unsigned widget session can add messages to it.
author: object = None
if ticket.channel_source == Channel.EMAIL:
if item_context.get("email_sender_authenticated") is True:
author = item_context.get("email_from")
elif ticket.channel_source == Channel.SLACK:
author = item_context.get("slack_author_email")
elif ticket.channel_source == Channel.TEAMS:
author = item_context.get("teams_author_email")
elif ticket.channel_source == Channel.WIDGET:
if item_context.get("distinct_id_verified") is True:
author = item_context.get("distinct_id")
return author if isinstance(author, str) else ""
def _get_assignment_properties(ticket: Ticket) -> dict:
"""Current assignment on the ticket, so workflows can route a single team's tickets.
`assignee_type` is "user", "role", or None (unassigned). `assignee_role_name` is set only for
role assignments, letting filters target a team by name instead of its UUID.
"""
assignment = TicketAssignment.objects.select_related("role").filter(ticket_id=ticket.id).first()
if assignment is None:
return {"assignee_type": None, "assignee_id": None, "assignee_role_name": None}
if assignment.user_id is not None:
return {"assignee_type": "user", "assignee_id": str(assignment.user_id), "assignee_role_name": None}
if assignment.role_id is not None:
return {
"assignee_type": "role",
"assignee_id": str(assignment.role_id),
"assignee_role_name": assignment.role.name if assignment.role else None,
}
return {"assignee_type": None, "assignee_id": None, "assignee_role_name": None}
def _role_name_for_assignee(ticket: Ticket, assignee_type: str | None, assignee_id: str | None) -> str | None:
"""Look up a role's name for the assignment event; None for user or empty assignees."""
if assignee_type != "role" or not assignee_id:
return None
return (
Role.objects.filter(id=assignee_id, organization_id=ticket.team.organization_id)
.values_list("name", flat=True)
.first()
)
def _get_sla_properties(ticket: Ticket, now: datetime) -> dict:
"""SLA state at the moment of the event.
Stamped on events (rather than derived later) so attainment metrics reflect the
deadline that was in force at the time, even if the SLA is reset afterwards.
`sla_delta_seconds` is positive when past due, negative when time remains.
"""
if ticket.sla_due_at is None:
return {"sla_due_at": None, "sla_active": False, "sla_breached": False, "sla_delta_seconds": None}
delta_seconds_float = (now - ticket.sla_due_at).total_seconds()
return {
"sla_due_at": ticket.sla_due_at.isoformat(),
"sla_active": True,
"sla_breached": delta_seconds_float > 0,
"sla_delta_seconds": int(delta_seconds_float),
}
def capture_ticket_created(ticket: Ticket) -> None:
properties = _get_ticket_base_properties(ticket)
properties.update(_get_customer_properties(ticket))
# Only the customer's own event joins their session; later ticket events come from staff, hours after it.
if ticket.session_id:
properties["$session_id"] = ticket.session_id
team = ticket.team
team_id = team.id
process_person = False
try:
process_person, groups, groups_source = _resolve_org_groups(ticket, team)
if groups is not None:
properties["$groups"] = groups
org_id = groups.get("organization")
if org_id and not ticket.organization_id:
Ticket.objects.filter(id=ticket.id).update(organization_id=org_id, organization_id_source=groups_source)
ticket.organization_id = org_id
ticket.organization_id_source = groups_source
except Exception:
logger.exception("ticket_created_person_lookup_failed", team_id=team_id, ticket_id=str(ticket.id))
capture_internal(
token=team.api_token,
event_name="$conversation_ticket_created",
event_source=EVENT_SOURCE,
distinct_id=ticket.distinct_id or ticket.channel_source or "unknown",
timestamp=None,
properties=properties,
process_person_profile=process_person,
)
def capture_ticket_status_changed(
ticket: Ticket,
old_status: str,
new_status: str,
actor: User | None = None,
actor_type: ActorType = "system",
) -> None:
properties = _get_ticket_base_properties(ticket)
properties["old_status"] = old_status
properties["new_status"] = new_status
properties.update(_get_actor_properties(actor, actor_type))
properties.update(_get_customer_properties(ticket, include_distinct_id=True))
capture_internal(
token=ticket.team.api_token,
event_name="$conversation_ticket_status_changed",
event_source=EVENT_SOURCE,
distinct_id=_get_actor_distinct_id(ticket, actor, actor_type),
timestamp=None,
properties=properties,
)
def capture_ticket_priority_changed(
ticket: Ticket,
old_priority: str | None,
new_priority: str | None,
actor: User | None = None,
actor_type: ActorType = "system",
) -> None:
properties = _get_ticket_base_properties(ticket)
properties["old_priority"] = old_priority
properties["new_priority"] = new_priority
properties.update(_get_actor_properties(actor, actor_type))
properties.update(_get_customer_properties(ticket, include_distinct_id=True))
capture_internal(
token=ticket.team.api_token,
event_name="$conversation_ticket_priority_changed",
event_source=EVENT_SOURCE,
distinct_id=_get_actor_distinct_id(ticket, actor, actor_type),
timestamp=None,
properties=properties,
)
def capture_ticket_assigned(
ticket: Ticket,
assignee_type: str | None,
assignee_id: str | None,
actor: User | None = None,
actor_type: ActorType = "system",
) -> None:
properties = _get_ticket_base_properties(ticket)
properties["assignee_type"] = assignee_type
properties["assignee_id"] = assignee_id
properties["assignee_role_name"] = _role_name_for_assignee(ticket, assignee_type, assignee_id)
properties.update(_get_actor_properties(actor, actor_type))
properties.update(_get_customer_properties(ticket, include_distinct_id=True))
capture_internal(
token=ticket.team.api_token,
event_name="$conversation_ticket_assigned",
event_source=EVENT_SOURCE,
distinct_id=_get_actor_distinct_id(ticket, actor, actor_type),
timestamp=None,
properties=properties,
)
def _team_message_properties(ticket: Ticket, message_id: str, author: User | None) -> dict:
properties = _get_ticket_base_properties(ticket)
properties["message_id"] = message_id
properties["author_type"] = "team"
properties.update(_get_actor_properties(author, "user"))
properties.update(_get_customer_properties(ticket, include_distinct_id=True))
properties.update(_get_assignment_properties(ticket))
properties.update(_get_sla_properties(ticket, timezone.now()))
return properties
def _capture_team_message(ticket: Ticket, properties: dict, author: User | None, event_name: str) -> None:
capture_internal(
token=ticket.team.api_token,
event_name=event_name,
event_source=EVENT_SOURCE,
distinct_id=_get_actor_distinct_id(ticket, author, "user"),
timestamp=None,
properties=properties,
)
def _produce_team_reply_internal_event(ticket: Ticket, properties: dict, author: User | None) -> None:
"""Emit the reply as an internal event, so a workflow can trust it.
Anyone with the public project token can capture `$conversation_message_sent` with any
properties, so a workflow that emails the customer must not trigger on that analytics event.
Only the server writes to the internal events topic. The reply body stays out, so the payload
holds nothing that the analytics event does not already show to project members.
"""
try:
produce_internal_event(
ticket.team_id,
InternalEventEvent(
event="$conversation_message_sent",
distinct_id=_get_actor_distinct_id(ticket, author, "user"),
properties=properties,
uuid=str(
uuid.uuid5(_TEAM_REPLY_INTERNAL_EVENT_NAMESPACE, f"{ticket.team_id}:{properties['message_id']}")
),
),
)
except Exception:
# The reply is already saved, and a workflow that misses one notification is better than a failed reply.
logger.exception("conversations_team_reply_internal_event_failed", ticket_id=str(ticket.id))
def capture_message_sent(
ticket: Ticket,
message_id: str,
message_content: str,
author: User | None = None,
) -> None:
"""Team member sent a public reply on a ticket."""
properties = _team_message_properties(ticket, message_id, author)
_capture_team_message(
ticket,
{**properties, "message_content": (message_content or "")[:1000]},
author,
"$conversation_message_sent",
)
_produce_team_reply_internal_event(ticket, properties, author)
def capture_private_message_sent(
ticket: Ticket,
message_id: str,
author: User | None = None,
) -> None:
"""Team member sent a private internal note on a ticket.
Deliberately a separate event from `$conversation_message_sent`: existing
workflows trigger on that event to notify customers, and private notes must
never flow through those.
The note body is deliberately omitted. Analytics events are queryable by any
project member, so including it would bypass ticket-level access controls.
"""
_capture_team_message(
ticket, _team_message_properties(ticket, message_id, author), author, "$conversation_private_message_sent"
)
def capture_message_received(
ticket: Ticket, message_id: str, message_content: str, item_context: Mapping[str, object] | None = None
) -> None:
"""Customer sent a message on a ticket."""
properties = _get_ticket_base_properties(ticket)
properties["message_id"] = message_id
properties["message_content"] = (message_content or "")[:1000]
properties["author_type"] = "customer"
customer_properties = _get_customer_properties(ticket)
author_identity = _message_author_identity(ticket, item_context or {})
customer_properties["customer_email_verified"] = (
customer_properties["customer_email_verified"]
and author_identity.lower() == customer_properties["customer_email"].lower()
)
properties.update(customer_properties)
properties.update(_get_assignment_properties(ticket))
team = ticket.team
process_person = False
try:
if ticket.organization_id:
properties["$groups"] = _groups_from_org_id(ticket.organization_id)
# Only a person-resolved org attests the sender (legacy rows without a source
# were person-resolved); a channel-inferred org says nothing about them, so
# don't create a person profile for it. Allowlist rather than blocklist so a
# future non-person source defaults to no person processing.
process_person = ticket.organization_id_source in (OrganizationIdSource.PERSON, None, "")
else:
process_person, groups, groups_source = _resolve_org_groups(ticket, team)
if groups is not None:
properties["$groups"] = groups
org_id = groups.get("organization")
if org_id:
# Persist like capture_ticket_created does, so later messages take the
# stored-org fast path instead of re-running the resolver. First write
# wins: only mirror to the in-memory ticket when this update landed,
# so a concurrent handler's value isn't shadowed.
rows_updated = Ticket.objects.filter(id=ticket.id, organization_id__isnull=True).update(
organization_id=org_id, organization_id_source=groups_source
)
if rows_updated:
ticket.organization_id = org_id
ticket.organization_id_source = groups_source
except Exception:
logger.exception("message_received_person_lookup_failed", team_id=team.id, ticket_id=str(ticket.id))
capture_internal(
token=team.api_token,
event_name="$conversation_message_received",
event_source=EVENT_SOURCE,
distinct_id=ticket.distinct_id or ticket.channel_source or "unknown",
timestamp=None,
properties=properties,
process_person_profile=process_person,
)