The account balance
[prebuilt component](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component)
checks a customer's authentication level and provides account balance
information to an authenticated customer. If the customer has multiple accounts,
the component confirms the specific account for which the customer wants to
retrieve the account balance. This component uses the
[Authentication](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication)
prebuilt component to authenticate users.

## Limitations

In addition to the
[common prebuilt component limitations](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component#limits),
this prebuilt component has the following limitations:

- This component doesn't encrypt any data.

## Sample dialogs

These sample dialogs illustrate common scenarios that this prebuilt component
handles. They show behavior when you call the component using telephony, which
triggers the Default Welcome Intent and the first agent response at the start of
the conversation.

### Single account

The user has a single account and is provided with the account balance.

| User Input | Agent Response |
|---|---|
|   | *The agent authenticates the user using [Authentication](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication) prebuilt component.* |
|   | Thank you, you've been successfully authenticated. |
|   | Please wait while account details are fetched. Your balance associated with the account ending in 4567 is $50.00. |

### Multiple accounts

If the user has multiple accounts, the agent requests and confirms the last four
digits of the account number and provides the account balance for that account.

| User Input | Agent Response |
|---|---|
|   | *The agent authenticates the user using [Authentication](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication) prebuilt component.* |
|   | Thank you, you have been successfully authenticated. |
|   | Please wait while we are fetching your account details. We have found that there are 2 accounts associated with your number. Can you please help us with the last 4 digits of the account you are referring to? |
| 2002 |   |
|   | The last four digits of the account number that we got are 2002, is that correct? |
| yes |   |
|   | Your balance associated with the account number ending with 2002 is $5000. |

### Multiple accounts with context

If the user has multiple accounts, the referenced account number is retained
from the previous intent, and the user is provided with the account balance.

| User Input | Agent Response |
|---|---|
|   | Please wait while we are fetching your account details. We have found that there are 3 accounts associated with your number. Are you looking for the account number ending with 4567? |
| Yes |   |
|   | Your balance associated with the account number ending with 4567 is $50. |

## Naming conventions

This prebuilt component uses the following naming conventions:

| Feature | Format | Example |
|---|---|---|
| Flow | Component Name | Account Balance |
| Component Specific Intent | prebuilt_components_\[component_name\]_\[intent_name\] | prebuilt_components_account_number_collection_four_digit_account_number |
| Webhook | prebuilt_components_\[component_name\]:\[webhook_action\] | prebuilt_components_account_balance:get_account_balance |

## Input parameters

Input parameters configure specific behaviors of the component. One or more
conditions within the flow use the parameters to determine how the component
behaves. The user must configure flow-scoped parameters on the start page of the
component as described in the following table. The user can also set
session-scoped parameters either by a calling flow or on the start page of this
component.

This prebuilt component accepts the following input parameters:

| Parameter Name | Description | Input Format |
|---|---|---|
| $session.params.auth_level | (optional) Indicates the [authentication level](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-levels) of the caller. | integer |
| $session.params.auth_level_req | Indicates the [level of authentication](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-levels) needed before a user can access their account balance. This value is configured in the [parameter presets](https://docs.cloud.google.com/dialogflow/cx/docs/concept/fulfillment#param-preset) of the [page entry fulfillment](https://docs.cloud.google.com/dialogflow/cx/docs/concept/fulfillment#use) in the `check auth level` page. By default this value is `1`. | integer |
| $session.params.account_auth_enabled | Indicates whether the user should be authenticated as an account holder as described in [Authentication types](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-types). This value is configured in the [parameter presets](https://docs.cloud.google.com/dialogflow/cx/docs/concept/fulfillment#param-preset) of the [page entry fulfillment](https://docs.cloud.google.com/dialogflow/cx/docs/concept/fulfillment#use) in the `check auth level` page. By default this value is `true`. | boolean |
| $session.params.card_auth_enabled | Indicates whether the user should be authenticated as a card holder as described in [Authentication types](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-types). This value is configured in the [parameter presets](https://docs.cloud.google.com/dialogflow/cx/docs/concept/fulfillment#param-preset) of the [page entry fulfillment](https://docs.cloud.google.com/dialogflow/cx/docs/concept/fulfillment#use) in the `check auth level` page. By default this value is `false`. | boolean |
| $session.params.phone_number | (optional) Customer's registered phone number used for authentication. | string |
| $session.params.account_count | (optional) Number of accounts associated with the authenticated user. | integer |
| $session.params.last_four_digit_of_account_number | (optional) Last four digits of the customer account number for which the balance needs to be provided. If the customer has a single account, this information is retrieved automatically after authentication. If the customer has multiple accounts, the specific account number is collected from the customer. | string |
| $flow.max_retry_acc_number | Specifies the number of retries allowed when collecting the last four digits of the user's account number. The default value is `3`. | integer |

#### To configure the input parameters for this component, expand for instructions.

1. Open the [Dialogflow CX console](https://dialogflow.cloud.google.com/cx/projects).
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the **Build** tab.
5. Click the imported component in the **Flows** section.
6. Click the Start Page in the **Pages** section.
7. Click the **true** Route in the Start Page.
8. In the Route window, edit the **Parameter Presets** values as needed.
9. Click **Save**.

## Output parameters

Output parameters are session parameters that remain active after the user exits
the component. These parameters contain important information that the component
collects.

This prebuilt component provides values for the following output parameters:

| Parameter Name | Description | Output Format |
|---|---|---|
| auth_level | Indicates the [authentication level](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#authentication-levels) of the caller. | integer |
| phone_number | The local phone number of the caller, without the country code, used to identify the user. | string |
| account_count | The number of accounts associated with the registered telephone number. These accounts include self-accounts and accounts for which the user has power of attorney. | integer |
| last_four_digit_of_account_number | If a user has a single account, the last four digits of the account number are returned. If a user has more than one account, the value of this parameter is the last four digits of the account number the user selected to receive account balance information for. | string |
| transfer_reason | This parameter indicates the reason the flow exited, if it was not successful. The returned value is one of: `agent`: the user requested a human agent at some point during the conversation. `denial_of_information`: the user declined to share information requested by the component. `max_no_input`: the conversation reached the maximum number of retries for no-input events. See [no-input built-in events](https://docs.cloud.google.com/dialogflow/cx/docs/concept/handler#event-built-in). `max_no_match`: the conversation reached the maximum number of retries for no-match events. See [no-match built-in events](https://docs.cloud.google.com/dialogflow/cx/docs/concept/handler#event-built-in). `webhook_error`: a webhook error occurred. See [webhook.error built-in event](https://docs.cloud.google.com/dialogflow/cx/docs/concept/handler#event-built-in). `webhook_not_found`: a webhook URL was unreachable. See [webhook.error.not-found built-in event](https://docs.cloud.google.com/dialogflow/cx/docs/concept/handler#event-built-in). | string |

## Basic setup

To set up the prebuilt component, complete the following steps:

1. [Import the prebuilt component](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component#import).
2. Configure the provided [flexible webhooks](https://docs.cloud.google.com/dialogflow/cx/docs/concept/webhook#flexible) with settings describing your external services. For more information, see the [Webhook setup](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/account-balance#webhook-setup) section.

## Webhook setup

To use this component, you must configure the included
[flexible webhooks](https://docs.cloud.google.com/dialogflow/cx/docs/concept/webhook#flexible) to retrieve
needed information from your external services.

### Authentication

If you haven't previously configured external services required for
authentication, configure them to enable authentication of users for this
component. For more information about webhook setup, see
[Authentication webhook setup](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/authentication#webhook-setup).

### Validate account

The component uses the `prebuilt_components_account_services:validate_account`
webhook to verify that an account exists based on the user's registered phone
number and the last four digits of the account number provided. The webhook
also returns the account balance if an account exists.

#### API request parameters

The component provides the following parameters as inputs to the API request:

| Parameter Name | Description | Input Format |
|---|---|---|
| $session.params.phone_number | The local phone number of the caller, without the country code, used to identify the user. | string |
| $session.params.last_four_digit_of_account_number | The last four digits of the account number the user selected and confirmed to receive account balance information for. | string |

#### API response parameters

The component pulls the following parameters from the API response:

| Parameter Name | Description | Output Format |
|---|---|---|
| account_found | Indicates whether an account with the provided last four digits exists for the user's registered account. | boolean |
| balance | The amount of the current balance on the account, if it exists. | number |

#### To configure the Validate account webhook for this component, expand for instructions.

1. Open the [Dialogflow CX console](https://dialogflow.cloud.google.com/cx/projects).
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the **Manage** tab.
5. Click **Webhooks**.
6. Select the prebuilt_components_account_services:validate_account webhook.
7. Replace the URL in the Dialogflow CX **Webhook URL** field with the endpoint for the service you want to integrate with. Select the proper **Method** in the dropdown.
8. Review and update the **Request body** to form the proper request format for your webhook.
9. Review and update the **Response configuration** to extract specific fields from your webhook's response. Do not modify the parameter names, as these are required by the component to access the returned field values.
10. Review and update the **Authentication** settings as needed.
11. Click **Save**.

### Complete

The prebuilt component and its webhooks are now set up and ready to test.