- [HTTP request](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#body.response_body)
  - [JSON representation](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#body.GenerateOnboardingSuggestionsResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#body.aspect)
- [IAM Permissions](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#body.aspect_1)
- [GenerateOnboardingSuggestionsResponse.UserProfile](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#GenerateOnboardingSuggestionsResponse.UserProfile)
- [AssistantSuggestion](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#AssistantSuggestion)
  - [JSON representation](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#AssistantSuggestion.SCHEMA_REPRESENTATION)
- [AssistantSuggestion.LoadSession](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#AssistantSuggestion.LoadSession)
  - [JSON representation](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#AssistantSuggestion.LoadSession.SCHEMA_REPRESENTATION)
- [AssistantSuggestion.Icon](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#AssistantSuggestion.Icon)
- [AssistantSuggestion.Source](https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#AssistantSuggestion.Source)

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](https://google.aip.dev/127) 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 `https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#google.cloud.ces.v1beta.SessionService.GenerateOnboardingSuggestions`.

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

| JSON representation |
|---|
| ``` { "userProfile": enum (`https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#GenerateOnboardingSuggestionsResponse.UserProfile`), "suggestions": [ { object (`https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#AssistantSuggestion`) } ], "contextToken": string } ``` |

| Fields ||
|---|---|
| `userProfile` | ``enum (`https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#GenerateOnboardingSuggestionsResponse.UserProfile`)`` Classification of the requesting user's history. |
| `suggestions[]` | ``object (`https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#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](https://docs.cloud.google.com/docs/authentication#authorization-gcp).

### IAM Permissions

Requires the following [IAM](https://cloud.google.com/iam/docs) permission on the `name` resource:

- `ces.assistantSessions.list`

For more information, see the [IAM documentation](https://cloud.google.com/iam/docs).

## 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 (`https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#AssistantSuggestion.Icon`), "source": enum (`https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#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 (`https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#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 (`https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#AssistantSuggestion.Icon`)`` Icon hint for the chip. |
| `source` | ``enum (`https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#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 (`https://docs.cloud.google.com/gemini-enterprise-cx/cx-agent-studio/reference/rest/v1beta/projects.locations.apps/generateOnboardingSuggestions#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. |