--- title: "POST /v1/{+parent}/apps" method: POST path: "/v1/{+parent}/apps" tags: ["projects"] --- # POST /v1/{+parent}/apps `POST /v1/{+parent}/apps` Creates a new app in the given project and location. ## Path parameters - `parent` string, required ## Query parameters - `appId` string ## Request body - App — An app serves as a top-level container for a group of agents, including the root agent and its sub-agents, along with their associated configurations. These agents work together to achieve specific goals within the app's context. - `clientCertificateSettings` ClientCertificateSettings — Settings for custom client certificates. - `privateKey` string — Required. The name of the SecretManager secret version resource storing the private key encoded in PEM format. Format: `projects/{project}/secrets/{secret}/versions/{version}` - `tlsCertificate` string — Required. The TLS certificate encoded in PEM format. This string must include the begin header and end footer lines. - `passphrase` string — Optional. The name of the SecretManager secret version resource storing the passphrase to decrypt the private key. Should be left unset if the private key is not encrypted. Format: `projects/{project}/secrets/{secret}/versions/{version}` - `modelSettings` ModelSettings — Model settings contains various configurations for the LLM model. - `temperature` number, double — Optional. If set, this temperature will be used for the LLM model. Temperature controls the randomness of the model's responses. Lower temperatures produce responses that are more predictable. Higher temperatures produce responses that are more creative. - `model` string — Optional. The LLM model that the agent should use. If not set, the agent will inherit the model from its parent agent. - `loggingSettings` LoggingSettings — Settings to describe the logging behaviors for the app. - `audioRecordingConfig` AudioRecordingConfig — Configuration for how the audio interactions should be recorded. - `gcsPathPrefix` string — Optional. The Cloud Storage path prefix for audio recordings. This prefix can include the following placeholders, which will be dynamically substituted at serving time: - $project: project ID - $location: app location - $app: app ID - $date: session date in YYYY-MM-DD format - $session: session ID If the path prefix is not specified, the default prefix `$project/$location/$app/$date/$session/` will be used. - `gcsBucket` string — Optional. The [Cloud Storage](https://cloud.google.com/storage) bucket to store the session audio recordings. The URI must start with "gs://". Please choose a bucket location that meets your data residency requirements. Note: If the Cloud Storage bucket is in a different project from the app, you should grant `storage.objects.create` permission to the CES service agent `service-@gcp-sa-ces.iam.gserviceaccount.com`. - `conversationLoggingSettings` ConversationLoggingSettings — Settings to describe the conversation logging behaviors for the app. - `disableConversationLogging` boolean — Optional. Whether to disable conversation logging for the sessions. - `retentionWindow` string, google-duration — Optional. Controls the retention window for the conversation. If not set, the conversation will be retained for 365 days. - `evaluationAudioRecordingConfig` AudioRecordingConfig — Configuration for how the audio interactions should be recorded. - `gcsPathPrefix` string — Optional. The Cloud Storage path prefix for audio recordings. This prefix can include the following placeholders, which will be dynamically substituted at serving time: - $project: project ID - $location: app location - $app: app ID - $date: session date in YYYY-MM-DD format - $session: session ID If the path prefix is not specified, the default prefix `$project/$location/$app/$date/$session/` will be used. - `gcsBucket` string — Optional. The [Cloud Storage](https://cloud.google.com/storage) bucket to store the session audio recordings. The URI must start with "gs://". Please choose a bucket location that meets your data residency requirements. Note: If the Cloud Storage bucket is in a different project from the app, you should grant `storage.objects.create` permission to the CES service agent `service-@gcp-sa-ces.iam.gserviceaccount.com`. - `redactionConfig` RedactionConfig — Configuration to instruct how sensitive data should be handled. - `deidentifyTemplate` string — Optional. [DLP](https://cloud.google.com/dlp/docs) deidentify template name to instruct on how to de-identify content. Format: `projects/{project}/locations/{location}/deidentifyTemplates/{deidentify_template}` - `enableRedaction` boolean — Optional. If true, redaction will be applied in various logging scenarios, including conversation history, Cloud Logging and audio recording. - `inspectTemplate` string — Optional. [DLP](https://cloud.google.com/dlp/docs) inspect template name to configure detection of sensitive data types. Format: `projects/{project}/locations/{location}/inspectTemplates/{inspect_template}` - `bigqueryExportSettings` BigQueryExportSettings — Settings to describe the BigQuery export behaviors for the app. - `enabled` boolean — Optional. Indicates whether the BigQuery export is enabled. - `dataset` string — Optional. The BigQuery **dataset ID** to export the data to. - `project` string — Optional. The **project ID** of the BigQuery dataset to export the data to. Note: If the BigQuery dataset is in a different project from the app, you should grant `roles/bigquery.admin` role to the CES service agent `service-@gcp-sa-ces.iam.gserviceaccount.com`. - `cloudLoggingSettings` CloudLoggingSettings — Settings to describe the Cloud Logging behaviors for the app. - `enableCloudLogging` boolean — Optional. Whether to enable Cloud Logging for the sessions. - `metricAnalysisSettings` MetricAnalysisSettings — Settings to describe the conversation data collection behaviors for LLM analysis metrics pipeline. - `llmMetricsOptedOut` boolean — Optional. Whether to collect conversation data for llm analysis metrics. If true, conversation data will not be collected for llm analysis metrics; otherwise, conversation data will be collected. - `unredactedBigqueryExportSettings` BigQueryExportSettings — Settings to describe the BigQuery export behaviors for the app. - `enabled` boolean — Optional. Indicates whether the BigQuery export is enabled. - `dataset` string — Optional. The BigQuery **dataset ID** to export the data to. - `project` string — Optional. The **project ID** of the BigQuery dataset to export the data to. Note: If the BigQuery dataset is in a different project from the app, you should grant `roles/bigquery.admin` role to the CES service agent `service-@gcp-sa-ces.iam.gserviceaccount.com`. - `unredactedAudioRecordingConfig` AudioRecordingConfig — Configuration for how the audio interactions should be recorded. - `gcsPathPrefix` string — Optional. The Cloud Storage path prefix for audio recordings. This prefix can include the following placeholders, which will be dynamically substituted at serving time: - $project: project ID - $location: app location - $app: app ID - $date: session date in YYYY-MM-DD format - $session: session ID If the path prefix is not specified, the default prefix `$project/$location/$app/$date/$session/` will be used. - `gcsBucket` string — Optional. The [Cloud Storage](https://cloud.google.com/storage) bucket to store the session audio recordings. The URI must start with "gs://". Please choose a bucket location that meets your data residency requirements. Note: If the Cloud Storage bucket is in a different project from the app, you should grant `storage.objects.create` permission to the CES service agent `service-@gcp-sa-ces.iam.gserviceaccount.com`. - `name` string — Identifier. The unique identifier of the app. Format: `projects/{project}/locations/{location}/apps/{app}` - `description` string — Optional. Human-readable description of the app. - `createTime` string, google-datetime — Output only. Timestamp when the app was created. - `audioProcessingConfig` AudioProcessingConfig — Configuration for how the input and output audio should be processed and delivered. - `bargeInConfig` BargeInConfig — Configuration for how the user barge-in activities should be handled. - `disableBargeIn` boolean — Optional. Deprecated: `disable_barge_in` is deprecated in favor of `disable_barge_in_control` in ChannelProfile. Disables user barge-in while the agent is speaking. If true, user input during agent response playback will be ignored. - `bargeInAwareness` boolean — Optional. If enabled, the agent will adapt its next response based on the assumption that the user hasn't heard the full preceding agent message. This should not be used in scenarios where agent responses are displayed visually. - `inactivityTimeout` string, google-duration — Optional. The duration of user inactivity (no speech or interaction) before the agent prompts the user for reengagement. If not set, the agent will not prompt the user for reengagement. - `synthesizeSpeechConfigs` object — Optional. Configuration of how the agent response should be synthesized, mapping from the language code to SynthesizeSpeechConfig. If the configuration for the specified language code is not found, the configuration for the root language code will be used. For example, if the map contains "en-us" and "en", and the specified language code is "en-gb", then "en" configuration will be used. Note: Language code is case-insensitive. - `ambientSoundConfig` AmbientSoundConfig — Configuration for the ambient sound to be played with the synthesized agent response, to enhance the naturalness of the conversation. - `volumeGainDb` number, double — Optional. Volume gain (in dB) of the normal native volume supported by ambient noise, in the range [-96.0, 16.0]. If unset, or set to a value of 0.0 (dB), will play at normal native signal amplitude. A value of -6.0 (dB) will play at approximately half the amplitude of the normal native signal amplitude. A value of +6.0 (dB) will play at approximately twice the amplitude of the normal native signal amplitude. We strongly recommend not to exceed +10 (dB) as there's usually no effective increase in loudness for any value greater than that. - `gcsUri` string — Optional. Ambient noise as a mono-channel, 16kHz WAV file stored in [Cloud Storage](https://cloud.google.com/storage). Note: Please make sure the CES service agent `service-@gcp-sa-ces.iam.gserviceaccount.com` has `storage.objects.get` permission to the Cloud Storage object. - `prebuiltAmbientNoise` 'PREBUILT_AMBIENT_NOISE_UNSPECIFIED' | 'RETAIL_STORE' | 'CONVENTION_HALL' | 'OUTDOOR' — Optional. Deprecated: `prebuilt_ambient_noise` is deprecated in favor of `prebuilt_ambient_sound`. - `prebuiltAmbientSound` string — Optional. Name of the prebuilt ambient sound. Valid values are: - "coffee_shop" - "keyboard" - "keypad" - "hum" - "office_1" - "office_2" - "office_3" - "room_1" - "room_2" - "room_3" - "room_4" - "room_5" - "air_conditioner" - `etag` string — Output only. Etag used to ensure the object hasn't changed during a read-modify-write operation. If the etag is empty, the update will overwrite any concurrent changes. - `locked` boolean — Optional. Indicates whether the app is locked for changes. If the app is locked, modifications to the app resources will be rejected. - `pinned` boolean — Optional. Whether the app is pinned in the app list. - `languageSettings` LanguageSettings — Language settings of the app. - `defaultLanguageCode` string — Optional. The default language code of the app. - `enableMultilingualSupport` boolean — Optional. Enables multilingual support. If true, agents in the app will use pre-built instructions to improve handling of multilingual input. - `supportedLanguageCodes` string[] — Optional. List of languages codes supported by the app, in addition to the `default_language_code`. - `fallbackAction` string — Optional. Deprecated: This feature is no longer supported. Use `enable_multilingual_support` instead to improve handling of multilingual input. The action to perform when an agent receives input in an unsupported language. This can be a predefined action or a custom tool call. Valid values are: - A tool's full resource name, which triggers a specific tool execution. - A predefined system action, such as "escalate" or "exit", which triggers an EndSession signal with corresponding metadata to terminate the conversation. - `evaluationMetricsThresholds` EvaluationMetricsThresholds — Threshold settings for metrics in an Evaluation. - `goldenHallucinationMetricBehavior` 'HALLUCINATION_METRIC_BEHAVIOR_UNSPECIFIED' | 'DISABLED' | 'ENABLED' — Optional. The hallucination metric behavior for golden evaluations. - `goldenEvaluationMetricsThresholds` EvaluationMetricsThresholdsGoldenEvaluationMetricsThresholds — Settings for golden evaluations. - `toolMatchingSettings` EvaluationMetricsThresholdsToolMatchingSettings — Settings for matching tool calls. - `extraToolCallBehavior` 'EXTRA_TOOL_CALL_BEHAVIOR_UNSPECIFIED' | 'FAIL' | 'ALLOW' — Optional. Behavior for extra tool calls. Defaults to FAIL. - `expectationLevelMetricsThresholds` EvaluationMetricsThresholdsGoldenEvaluationMetricsThresholdsExpectationLevelMetricsThresholds — Expectation level metrics thresholds. - `toolInvocationParameterCorrectnessThreshold` number, float — Optional. The success threshold for individual tool invocation parameter correctness. Must be a float between 0 and 1. Default is 1.0. - `turnLevelMetricsThresholds` EvaluationMetricsThresholdsGoldenEvaluationMetricsThresholdsTurnLevelMetricsThresholds — Turn level metrics thresholds. - `semanticSimilarityChannel` 'SEMANTIC_SIMILARITY_CHANNEL_UNSPECIFIED' | 'TEXT' | 'AUDIO' — Optional. The semantic similarity channel to use for evaluation. - `semanticSimilaritySuccessThreshold` integer — Optional. The success threshold for semantic similarity. Must be an integer between 0 and 4. Default is >= 3. - `overallToolInvocationCorrectnessThreshold` number, float — Optional. The success threshold for overall tool invocation correctness. Must be a float between 0 and 1. Default is 1.0. - `hallucinationMetricBehavior` 'HALLUCINATION_METRIC_BEHAVIOR_UNSPECIFIED' | 'DISABLED' | 'ENABLED' — Optional. Deprecated: Use `golden_hallucination_metric_behavior` instead. The hallucination metric behavior is currently used for golden evaluations. - `scenarioHallucinationMetricBehavior` 'HALLUCINATION_METRIC_BEHAVIOR_UNSPECIFIED' | 'DISABLED' | 'ENABLED' — Optional. The hallucination metric behavior for scenario evaluations. - `deploymentCount` integer — Output only. Number of deployments in the app. - `variableDeclarations` AppVariableDeclaration[] — Optional. The declarations of the variables. - `name` string — Required. The name of the variable. The name must start with a letter or underscore and contain only letters, numbers, or underscores. - `description` string — Required. The description of the variable. - `schema` Schema — Represents a select subset of an OpenAPI 3.0 schema object. - `items` Schema — recursive - `maximum` number, double — Optional. Maximum value for Type.INTEGER and Type.NUMBER. - `prefixItems` Schema[] — Optional. Schemas of initial elements of Type.ARRAY. - `minimum` number, double — Optional. Minimum value for Type.INTEGER and Type.NUMBER. - `required` string[] — Optional. Required properties of Type.OBJECT. - `enum` string[] — Optional. Possible values of the element of primitive type with enum format. Examples: 1. We can define direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]} 2. We can define apartment number as : {type:INTEGER, format:enum, enum:["101", "201", "301"]} - `title` string — Optional. The title of the schema. - `properties` object — Optional. Properties of Type.OBJECT. - `default` unknown - `uniqueItems` boolean — Optional. Indicate the items in the array must be unique. Only applies to TYPE.ARRAY. - `ref` string — Optional. Allows indirect references between schema nodes. The value should be a valid reference to a child of the root `defs`. For example, the following schema defines a reference to a schema node named "Pet": ``` type: object properties: pet: ref: #/defs/Pet defs: Pet: type: object properties: name: type: string ``` The value of the "pet" property is a reference to the schema node named "Pet". See details in https://json-schema.org/understanding-json-schema/structuring. - `maxItems` string, int64 — Optional. Maximum number of the elements for Type.ARRAY. - `anyOf` Schema[] — Optional. The value should be validated against any (one or more) of the subschemas in the list. - `description` string — Optional. The description of the data. - `defs` object — Optional. A map of definitions for use by `ref`. Only allowed at the root of the schema. - `type` 'TYPE_UNSPECIFIED' | 'STRING' | 'INTEGER' | 'NUMBER' | 'BOOLEAN' | 'OBJECT' | 'ARRAY' — Required. The type of the data. - `additionalProperties` Schema — recursive - `nullable` boolean — Optional. Indicates if the value may be null. - `minItems` string, int64 — Optional. Minimum number of the elements for Type.ARRAY. - `timeZoneSettings` TimeZoneSettings — TimeZone settings of the app. - `timeZone` string — Optional. The time zone of the app from the [time zone database](https://www.iana.org/time-zones), e.g., America/Los_Angeles, Europe/Paris. - `toolExecutionMode` 'TOOL_EXECUTION_MODE_UNSPECIFIED' | 'PARALLEL' | 'SEQUENTIAL' — Optional. The tool execution mode for the app. If not provided, will default to PARALLEL. - `errorHandlingSettings` ErrorHandlingSettings — Settings to describe how errors should be handled in the app. - `errorHandlingStrategy` 'ERROR_HANDLING_STRATEGY_UNSPECIFIED' | 'NONE' | 'FALLBACK_RESPONSE' | 'END_SESSION' — Optional. The strategy to use for error handling. - `fallbackResponseConfig` ErrorHandlingSettingsFallbackResponseConfig — Configuration for handling fallback responses. - `maxFallbackAttempts` integer — Optional. The maximum number of fallback attempts to make before the agent emitting EndSession Signal. - `customFallbackMessages` object — Optional. The fallback messages in case of system errors (e.g. LLM errors), mapped by [supported language code](https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/reference/language). - `endSessionConfig` ErrorHandlingSettingsEndSessionConfig — Configuration for ending the session in case of system errors (e.g. LLM errors). - `escalateSession` boolean — Optional. Whether to escalate the session in EndSession. If session is escalated, metadata in EndSession will contain `session_escalated = true`. See https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/deploy/google-telephony-platform#transfer_a_call_to_a_human_agent for details. - `predefinedVariableDeclarations` AppVariableDeclaration[] — Output only. The declarations of predefined variables for the app. - `name` string — Required. The name of the variable. The name must start with a letter or underscore and contain only letters, numbers, or underscores. - `description` string — Required. The description of the variable. - `schema` Schema — Represents a select subset of an OpenAPI 3.0 schema object. - `items` Schema — recursive - `maximum` number, double — Optional. Maximum value for Type.INTEGER and Type.NUMBER. - `prefixItems` Schema[] — Optional. Schemas of initial elements of Type.ARRAY. - `minimum` number, double — Optional. Minimum value for Type.INTEGER and Type.NUMBER. - `required` string[] — Optional. Required properties of Type.OBJECT. - `enum` string[] — Optional. Possible values of the element of primitive type with enum format. Examples: 1. We can define direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]} 2. We can define apartment number as : {type:INTEGER, format:enum, enum:["101", "201", "301"]} - `title` string — Optional. The title of the schema. - `properties` object — Optional. Properties of Type.OBJECT. - `default` unknown - `uniqueItems` boolean — Optional. Indicate the items in the array must be unique. Only applies to TYPE.ARRAY. - `ref` string — Optional. Allows indirect references between schema nodes. The value should be a valid reference to a child of the root `defs`. For example, the following schema defines a reference to a schema node named "Pet": ``` type: object properties: pet: ref: #/defs/Pet defs: Pet: type: object properties: name: type: string ``` The value of the "pet" property is a reference to the schema node named "Pet". See details in https://json-schema.org/understanding-json-schema/structuring. - `maxItems` string, int64 — Optional. Maximum number of the elements for Type.ARRAY. - `anyOf` Schema[] — Optional. The value should be validated against any (one or more) of the subschemas in the list. - `description` string — Optional. The description of the data. - `defs` object — Optional. A map of definitions for use by `ref`. Only allowed at the root of the schema. - `type` 'TYPE_UNSPECIFIED' | 'STRING' | 'INTEGER' | 'NUMBER' | 'BOOLEAN' | 'OBJECT' | 'ARRAY' — Required. The type of the data. - `additionalProperties` Schema — recursive - `nullable` boolean — Optional. Indicates if the value may be null. - `minItems` string, int64 — Optional. Minimum number of the elements for Type.ARRAY. - `metadata` object — Optional. Metadata about the app. This field can be used to store additional information relevant to the app's details or intended usages. - `globalInstruction` string — Optional. Instructions for all the agents in the app. You can use this instruction to set up a stable identity or personality across all the agents. - `updateTime` string, google-datetime — Output only. Timestamp when the app was last updated. - `rootAgent` string — Optional. The root agent is the entry point of the app. Format: `projects/{project}/locations/{location}/apps/{app}/agents/{agent}` - `dataStoreSettings` DataStoreSettings — Data store related settings for the app. - `engines` DataStoreSettingsEngine[] — Output only. The engines for the app. - `name` string — Output only. The resource name of the engine. Format: `projects/{project}/locations/{location}/collections/{collection}/engines/{engine}` - `type` 'TYPE_UNSPECIFIED' | 'ENGINE_TYPE_SEARCH' | 'ENGINE_TYPE_CHAT' — Output only. The type of the engine. - `validationErrors` string[] — Output only. Misconfigurations or warnings in the app. - `displayName` string — Required. Display name of the app. - `defaultChannelProfile` ChannelProfile — A ChannelProfile configures the agent's behavior for a specific communication channel, such as web UI or telephony. - `disableBargeInControl` boolean — Optional. Whether to disable user barge-in control in the conversation. - **true**: User interruptions are disabled while the agent is speaking. - **false**: The agent retains automatic control over when the user can interrupt. - `personaProperty` ChannelProfilePersonaProperty — Represents the persona property of a channel. - `persona` 'UNKNOWN' | 'CONCISE' | 'CHATTY' — Optional. The persona of the channel. - `noiseSuppressionLevel` string — Optional. The noise suppression level of the channel profile. Available values are "low", "moderate", "high", "very_high". - `whatsappConfig` ChannelProfileWhatsAppConfig — Configuration specific to WhatsApp deployments. - `phoneNumber` string — Optional. The phone number in E.164 format. - `phoneNumberId` string — Required. The Meta phone number ID. - `description` string — Output only. The description of the Meta business page or profile. - `displayName` string — Output only. The fetched Meta business page name. - `wabaId` string — Required. The WhatsApp Business Account ID. - `thumbnailUrl` string — Output only. The fetched Meta business profile thumbnail URL. - `webWidgetConfig` ChannelProfileWebWidgetConfig — Message for configuration for the web widget. - `modality` 'MODALITY_UNSPECIFIED' | 'CHAT_AND_VOICE' | 'VOICE_ONLY' | 'CHAT_ONLY' | 'CHAT_VOICE_AND_VIDEO' — Optional. The modality of the web widget. - `theme` 'THEME_UNSPECIFIED' | 'LIGHT' | 'DARK' — Optional. The theme of the web widget. - `webWidgetTitle` string — Optional. The title of the web widget. - `securitySettings` ChannelProfileWebWidgetConfigSecuritySettings — Security settings for the web widget. - `enablePublicAccess` boolean — Optional. Indicates whether public access to the web widget is enabled. If `true`, the web widget will be publicly accessible. If `false`, the web widget must be integrated with your own authentication and authorization system to return valid credentials for accessing the CES agent. - `enableRecaptcha` boolean — Optional. Indicates whether reCAPTCHA verification for the web widget is enabled. - `enableOriginCheck` boolean — Optional. Indicates whether origin check for the web widget is enabled. If `true`, the web widget will check the origin of the website that loads the web widget and only allow it to be loaded in the same origin or any of the allowed origins. - `allowedOrigins` string[] — Optional. The origins that are allowed to host the web widget. An origin is defined by RFC 6454. If empty, all origins are allowed. A maximum of 100 origins is allowed. Example: "https://example.com" - `disableDtmf` boolean — Optional. Whether to disable DTMF (dual-tone multi-frequency). - `instagramConfig` ChannelProfileInstagramConfig — Configuration specific to Instagram deployments. - `instagramAccountId` string — Required. The Instagram Account ID. - `displayName` string — Output only. The fetched Meta business page name. - `thumbnailUrl` string — Output only. The fetched Meta business profile thumbnail URL. - `description` string — Output only. The description of the Meta business page or profile. - `profileId` string — Optional. The unique identifier of the channel profile. - `channelType` 'UNKNOWN' | 'WEB_UI' | 'API' | 'TWILIO' | 'GOOGLE_TELEPHONY_PLATFORM' | 'CONTACT_CENTER_AS_A_SERVICE' | 'CONTACT_CENTER_AS_A_SERVICE_CHAT' | 'FIVE9' | 'CONTACT_CENTER_INTEGRATION' | 'WHATSAPP' | 'INSTAGRAM' — Optional. The type of the channel profile. - `vpcScSettings` VpcScSettings — VPC-SC settings for the app. - `allowedOrigins` string[] — Optional. The allowed HTTP(s) origins that OpenAPI tools in the App are able to directly call when VPC Service Controls are enabled. These strings must match the origin exactly, including the port if specified. For example, "https://example.com" or "https://example.com:443". This list does not yet apply to Python tools that may make direct HTTP calls. - `guardrails` string[] — Optional. List of guardrails for the app. Format: `projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}` ## Response `200` Successful response --- [API](https://skmtc.net/google/apis/ces.md) · [All operations](https://skmtc.net/google/apis/ces/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/ces/versions/429598666166/schema)