Method: projects.locations.apps.generateOnboardingSuggestions

Generates personalized onboarding suggestions for the Arc zero state: classifies the requesting user (new / exploring / returning) from their assistant-session history in the app and returns suggestion chips (resume a session, continue work, or start something new) to render before any message is sent.

HTTP request

POST https://ces.googleapis.com/v1beta/{name=projects/*/locations/*/apps/*}:generateOnboardingSuggestions

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The app whose zero state is being rendered. Format: projects/{project}/locations/{location}/apps/{app}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "maxSuggestions": integer
}
Fields
maxSuggestions

integer

Optional. Maximum number of suggestions to return. Defaults to 4 when unset.

Response body

Response message for SessionService.GenerateOnboardingSuggestions.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "userProfile": enum (GenerateOnboardingSuggestionsResponse.UserProfile),
  "suggestions": [
    {
      object (AssistantSuggestion)
    }
  ],
  "contextToken": string
}
Fields
userProfile

enum (GenerateOnboardingSuggestionsResponse.UserProfile)

Classification of the requesting user's history.
suggestions[]

object (AssistantSuggestion)

Personalized suggestions, ranked most relevant first.
contextToken

string

Opaque token capturing the onboarding snapshot used to generate these suggestions. Clients echo it on the first StreamChatAiAssistantRequest so the server can reuse the snapshot.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • ces.assistantSessions.list

For more information, see the IAM documentation.

GenerateOnboardingSuggestionsResponse.UserProfile

Classification of the requesting user's history with the assistant in this app.

Enums
USER_PROFILE_UNSPECIFIED Unspecified profile.
NEW No assistant sessions containing messages.
EXPLORING One or two assistant sessions containing messages.
RETURNING More than two assistant sessions containing messages.

AssistantSuggestion

A single personalized onboarding suggestion chip for Arc's zero state.

JSON representation 
{
  "suggestionId": string,
  "label": string,
  "rationale": string,
  "icon": enum (AssistantSuggestion.Icon),
  "source": enum (AssistantSuggestion.Source),
  "candidateType": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "seedPrompt": string,
  "loadSession": {
    object (AssistantSuggestion.LoadSession)
  },
  "sendMessage": string
  // End of mutually exclusive fields.
}
Fields
suggestionId

string

Stable identifier for this suggestion, round-tripped by clients in interaction logging.
label

string

Chip label shown to the user (at most 60 characters).
rationale

string

Optional short explanation of why this suggestion is shown (tooltip / rationale popover).
icon

enum (AssistantSuggestion.Icon)

Icon hint for the chip.
source

enum (AssistantSuggestion.Source)

How this suggestion was produced.
candidateType

string

Rule-table candidate type in kebab-case (e.g. "resume-pending-review"), for metrics.
What activating the chip does. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
seedPrompt

string

Prefill the composer with this text; the user reviews and sends.
loadSession

object (AssistantSuggestion.LoadSession)

Open an existing assistant session.
sendMessage

string

Prefill the composer with this text and submit immediately. Only used for quick-reply chips inside an active onboarding conversation.
End of mutually exclusive fields.

AssistantSuggestion.LoadSession

Parameters for the loadSession action.

JSON representation 
{
  "assistantSessionId": string
}
Fields
assistantSessionId

string

Identifier of the assistant session to open (the final segment of the AssistantSession resource name).

AssistantSuggestion.Icon

Icon hint for the chip.

Enums
ICON_UNSPECIFIED Unspecified icon.
RESUME Resume a previous session.
BUILD Build something new.
EVALUATE Evaluation-related suggestion.
DEPLOY Deployment-related suggestion.
EXPLORE Exploration / discovery suggestion.
FIX Fix an error or failing state.

AssistantSuggestion.Source

How this suggestion was produced.

Enums
SOURCE_UNSPECIFIED Unspecified source.
RULE Deterministic rule-table candidate with template phrasing.
LLM_RANKED Rule-table candidate re-ranked and phrased by the LLM phrasing step.