InsightsService

Provides cohort-level AI insights for campaign planning and optimization — behavioral archetypes, acknowledgment-rate predictions, campaign advisories, and generated narratives. All predictions are aggregate: there is no individual-level profiling. Data is derived from k-anonymized, differential-privacy-noised behavioral features, and every RPC operates within the caller’s organization.

Methods

Method	Description
GetGroupArchetypes	Retrieve behavioral archetypes for a group
PredictCampaignACK	Predict cohort-level ACK rate for a campaign configuration
GetCampaignAdvisory	Get campaign configuration advisory (prediction + escalation suggestion + archetypes)
GetInsightNarrative	Generate an AI narrative summary of a group’s insights
TriggerMLPipeline	Manually trigger the ML training pipeline
TriggerArchetypeClustering	Manually retrigger archetype clustering for a single group
GenerateCampaignBodyDraft	Draft a campaign body targeting a specific archetype

Confidence Levels

Confidence for cohort-level predictions, based on available data volume.

Value	Description
CONFIDENCE_LEVEL_LOW	Fewer than 50 campaigns — predictions based on heuristics/industry benchmarks.
CONFIDENCE_LEVEL_MEDIUM	50–200 campaigns — basic clustering available, wide confidence intervals.
CONFIDENCE_LEVEL_HIGH	200+ campaigns — full ML pipeline, narrow confidence intervals.

GetGroupArchetypes

Retrieve behavioral archetypes for a group based on anonymous feature vectors. Returns empty archetypes if there is insufficient data (cold start); pipeline_state distinguishes why the list is empty.

Authorization: Authenticated member of the organization

Request: GetGroupArchetypesRequest

Field	Type	Description
group_id	string	ID of the group to query archetypes for. Required.

Response: GetGroupArchetypesResponse

Field	Type	Description
archetypes	Archetype[]	Behavioral archetypes for the group (empty if insufficient data).
data_point_count	int32	Number of anonymous feature vectors used for clustering.
pipeline_state	PipelineState	Why archetypes looks the way it does — see below.
confidence_level	ConfidenceLevel	Confidence in the returned archetypes. Always LOW when provisional archetypes are returned.

PipelineState

Value	Description
PIPELINE_STATE_NEVER_RUN	The ML pipeline has never fired for this organization. Archetypes are empty because nothing ran, not because of data shape.
PIPELINE_STATE_BELOW_THRESHOLD	The pipeline ran but the group had fewer than the k-anonymization minimum feature vectors (50), so clustering was skipped.
PIPELINE_STATE_NO_CLUSTERS	The pipeline ran with enough vectors but returned zero clusters — typically the audience is too homogeneous to separate into distinct archetypes.
PIPELINE_STATE_READY	Archetypes are populated and ready to render.

PredictCampaignACK

Predict the cohort-level acknowledgment rate for a campaign targeting a specific group. Returns a confidence interval that narrows as more campaign data accumulates.

Authorization: Authenticated member of the organization

Request: PredictCampaignACKRequest

Field	Type	Description
group_id	string	ID of the target audience group. Required.
template_type	string	Template type (optional, for prediction refinement).
workflow_step_count	int32	Number of workflow steps (optional, for prediction refinement).

Response: PredictCampaignACKResponse

Field	Type	Description
prediction	CohortPrediction	Cohort-level prediction.

GetCampaignAdvisory

Get a campaign configuration advisory combining the ACK prediction, a suggested escalation delay, and the audience’s archetypes. The advisory is informational only — it never drives automated decisions.

Authorization: Authenticated member of the organization

Request: GetCampaignAdvisoryRequest

Field	Type	Description
group_id	string	ID of the target audience group. Required.
template_id	string	Template ID (optional, for advisory context).
template_version	int32	Template version (optional).
workflow_step_count	int32	Number of workflow steps (optional).

Response: GetCampaignAdvisoryResponse

Field	Type	Description
advisory	CampaignAdvisory	Campaign advisory with prediction, suggested escalation, and archetypes.

CampaignAdvisory

Field	Type	Description
predicted_ack	CohortPrediction	Cohort-level ACK prediction for the target audience.
suggested_escalation_delay_minutes	int32	Suggested escalation delay in minutes based on historical cohort patterns. 0 if insufficient data.
archetypes	Archetype[]	Behavioral archetypes for the target audience.

GetInsightNarrative

Generate an AI-powered narrative summary of a group’s insights. Combines archetype, prediction, and campaign data into a human-readable analysis. An unknown prompt_name is rejected with INVALID_ARGUMENT; when no archetypes or predictions exist yet, the narrative addresses the data-sparse case rather than failing.

Authorization: Authenticated member of the organization

Request: GetInsightNarrativeRequest

Field	Type	Description
group_id	string	ID of the group to generate a narrative for. Required.
prompt_name	string	Name of the prompt template to use (e.g. campaign-advisory, archetype-explanation, post-campaign-review).

Response: GetInsightNarrativeResponse

Field	Type	Description
narrative	string	Generated narrative text (Markdown formatted).
generated_at	Timestamp	When the narrative was generated.
model_id	string	Model identifier used for generation.

TriggerMLPipeline

Manually trigger the ML training pipeline for the caller’s organization. Rate-limited per organization (default 3 manual retrains per month, auto-resets). The quota is shared with TriggerArchetypeClustering.

Authorization: Authenticated member of the organization

Request: TriggerMLPipelineRequest

Empty request — the organization is derived from the caller’s session.

Response: TriggerMLPipelineResponse

Field	Type	Description
remaining_this_month	int32	Remaining manual retrains allowed this month.
last_trained_at	Timestamp	Timestamp of the last successful training (unset if never trained).

TriggerArchetypeClustering

Manually retrigger archetype clustering for a single group without rerunning the full training pipeline — the already-deployed clustering model is reused, so this is cheaper than TriggerMLPipeline. Shares the same monthly manual-retrain quota as TriggerMLPipeline.

Authorization: Authenticated member of the organization

Request: TriggerArchetypeClusteringRequest

Field	Type	Description
group_id	string	Group to recluster. The organization is derived from the caller’s session.

Response: TriggerArchetypeClusteringResponse

Field	Type	Description
workflow_id	string	Identifier of the background clustering run — useful for client-side deduplication.
remaining_this_month	int32	Remaining manual retrains allowed this month (shared with TriggerMLPipeline).
last_clustered_at	Timestamp	Timestamp of the last successful archetype clustering for this group, unset if never clustered.

GenerateCampaignBodyDraft

Draft a campaign body for a given archetype, used to pre-fill the campaign creation wizard’s body field from a “target this archetype” flow. A group_id belonging to another organization returns PERMISSION_DENIED; an archetype_label not present in the group’s current archetype set returns NOT_FOUND.

Authorization: Authenticated member of the organization

Request: GenerateCampaignBodyDraftRequest

Field	Type	Description
group_id	string	UUID of the source group whose archetype set the label belongs to.
archetype_label	string	Stable archetype label, e.g. Swift Acknowledger.
lane_action	string	Recommended action copy passed through from the admin (e.g. “Simplify the call-to-action”). Used as a tone hint.

Response: GenerateCampaignBodyDraftResponse

Field	Type	Description
body_markdown	string	Draft Markdown body, 3–5 sentences, authored as if written for the recipient — it does not mention the archetype name.

Types

Archetype

A behavioral archetype describing a cohort pattern — never an individual. Derived from k-anonymized, differential-privacy-noised behavioral feature vectors.

Field	Type	Description
label	string	Human-readable label (e.g. “Swift Acknowledger”, “Thorough Reader”).
description	string	Description of the behavioral pattern this archetype represents.
percentage	float	Proportion of the group that belongs to this archetype (0.0–1.0).
feature_centroid	map<string, double>	Centroid of the behavioral feature vector. Keys are stable dimension names (e.g. tap_density, engagement_depth, scroll_velocity_p50, idle_gap_p75).
feature_breakdown	map<string, DimensionStats>	Per-dimension distribution of the archetype’s members, for rendering percentile bands. Absent until at least k members exist in the cluster. Keys mirror feature_centroid.
tap_heatmap	TapHeatmap	Tap density heatmap aggregated across sessions. Cohort-level only — never per-session timing. Absent when fewer than k sessions have tap data.
forecast	ArchetypeForecast	Forecast of cluster share at fixed horizons (7/14/30/90 days). Absent during cold start.
exemplar_sessions	ExemplarSession[]	Sessions at the median and quartiles of centroid distance, at most three entries. Absent until at least 50 sessions have been scored. Sessions can come from mobile or desktop clients.
screen_dwell	ScreenDwell	Per-screen dwell time distribution from session replay. Absent when fewer than k sessions per screen exist.
response_timeline	ResponseTimeline	End-to-end response latencies (delivered → read → acknowledged) as percentiles. Absent until at least k campaign deliveries have been recorded.
source	ArchetypeSource	Where this archetype came from — see below.

ArchetypeSource

Value	Description
ARCHETYPE_SOURCE_ML	Produced by the trained ML clustering pipeline (k-anonymized, differential-privacy-noised behavioral feature vectors).
ARCHETYPE_SOURCE_PROVISIONAL	Rule-based provisional output derived from coarse delivery/read/ack activity (or a stable starter distribution for sandboxes with no activity). Low confidence, always superseded by ML output once available. Clients must render a low-confidence disclaimer.

DimensionStats

Distribution stats for one feature dimension within an archetype’s cohort, in the same units as feature_centroid.

Field	Type	Description
centroid	double	Centroid value for the dimension.
p25	double	25th percentile across the archetype’s members.
p50	double	Median across the archetype’s members.
p75	double	75th percentile across the archetype’s members.
group_p50	double	Median across the entire group (all archetypes), for “X% above group median” comparisons.

TapHeatmap

A density grid of tap activity for one archetype, normalized to [0.0, 1.0] where 1.0 is the hottest cell in the cohort. Cohort-level only.

Field	Type	Description
width	int32	Width of the density grid in cells.
height	int32	Height of the density grid in cells.
values	double[]	Row-major density values; length equals width * height.
session_count	int32	Number of sessions aggregated.
layers	TapHeatmapLayer[]	Optional per-event-type breakdown (TAP, LONG_PRESS, SCROLL, ACTION_CLICK), each with independently normalized row-major values.

ArchetypeForecast

Field	Type	Description
horizons	ForecastHorizon[]	One entry each for 7, 14, 30, and 90 days, in increasing order.

ForecastHorizon

Field	Type	Description
days	int32	Horizon length in days (one of 7, 14, 30, 90).
predicted_share	double	Predicted fraction of the group in this archetype at the horizon (0.0–1.0).
lower	double	5th-percentile lower bound of the 90% prediction interval.
upper	double	95th-percentile upper bound of the 90% prediction interval.
confidence	ConfidenceLevel	Confidence in this horizon’s prediction.

ExemplarSession

Pointer to a representative session for one archetype, ranked by distance to the archetype centroid.

Field	Type	Description
session_id	string	Session recording ID retrievable via the ReplayService for the same organization.
rank	int32	Quantile rank within the archetype: 25, 50, or 75. At most one session per rank.
distance	double	Distance from the session’s feature vector to the centroid.
duration_seconds	int32	Optional session duration.
platform	string	Optional platform identifier: ios, android, macos, windows, or linux. Unknown values should be rendered verbatim for forward compatibility.

ScreenDwell

Per-screen dwell distribution within an archetype.

Field	Type	Description
entries	ScreenDwellEntry[]	One entry per screen. Screens with fewer than k members in the archetype are dropped from the list.

ScreenDwellEntry

Field	Type	Description
screen_name	string	Stable screen identifier (e.g. MessageDetail, Inbox, ProfileSettings).
median_seconds	double	Median dwell time in seconds for this archetype on this screen.
p75_seconds	double	75th-percentile dwell time in seconds.
session_count	int32	Number of distinct sessions aggregated for this screen.

ResponseTimeline

End-to-end response latencies for members of one archetype, in seconds, computed across qualifying campaign deliveries within the rolling window.

Field	Type	Description
read_after_delivered	LatencyPercentiles	Time from delivered to read.
ack_after_read	LatencyPercentiles	Time from read to acknowledged. Only includes deliveries that were both read and acknowledged.
ack_after_delivered	LatencyPercentiles	End-to-end time from delivered to acknowledged. Only includes deliveries that were acknowledged.
delivery_count	int32	Number of deliveries the timeline is computed over.

LatencyPercentiles

Field	Type	Description
p50	double	Median, in seconds.
p75	double	75th percentile, in seconds.
p95	double	95th percentile, in seconds.

CohortPrediction

A cohort-level prediction for campaign acknowledgment rate. Never targets or scores individuals — always represents an audience aggregate.

Field	Type	Description
predicted_ack_rate	float	Predicted ACK rate for the audience (0.0–1.0).
confidence_low	float	Lower bound of the confidence interval.
confidence_high	float	Upper bound of the confidence interval.
confidence_level	ConfidenceLevel	Confidence level based on available data volume.
data_point_count	int32	Number of anonymous data points used for this prediction.