The arrange appointment
[prebuilt component](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component)
lets new and existing customers book appointments. This component uses a
customized version of the
[Date of birth collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/date-of-birth-collection)
prebuilt component to collect appointment dates, and uses the
[Telephone number collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/telephone-number-collection)
and [Zip code collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/zip-code-collection)
prebuilt components to collect information about the user and appointment
location.

## Appointment reasons and types

This component supports several categories of appointment reasons and offers
different types of appointments based on the reason that the user selects.

| Appointment Reason | Available Appointment Types |
|---|---|
| Loans | In-person, virtual, phone |
| Mortgages | In-person, virtual, phone |
| Wealth management | In-person, virtual, phone |
| Credit cards | Virtual, phone |
| Other | Phone |

Appointment categories can be modified by updating the
`prebuilt_components_arrange_appt_reason` custom entity. Available appointment
types for each category can be configured by updating the
[input parameters](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/arrange-appointment#input-parameters)
for each appointment type.

## 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 demonstrate common scenarios that this prebuilt component
handles when calls come in using telephony, which triggers the Default Welcome
Intent and the first agent response at the start of the conversation.

### Existing user books in-person appointment

1. The agent identifies that the user has been authenticated as an existing user.
2. The user gives the reason for their appointment and selects to book an in-person appointment.
3. The agent confirms that the user wants to go to the branch closest to their registered address, and confirms that their preferred date and time are available.
4. The agent confirms the time and place and schedules the appointment.

| User Input | Agent Response |
|---|---|
|   | Before scheduling an appointment, we will ask you a few questions. Can you tell us the reason for your appointment? |
| I want to talk to someone about wealth management |   |
|   | Are you looking for a phone, video call or in-person appointment at one of our branches? |
| I'd like to go in person |   |
|   | Okay, do you want to schedule an appointment in the branch located at 1600 Amphitheatre Pkwy, Mountain View, CA 94043? |
| Yes |   |
|   | Please provide your preferred appointment date. Please say your preferred month, followed by day and then year. Remember that our branches are open from Monday to Friday: 9 AM to 5 PM, Saturday: 9 AM to 1 PM. |
|   | *The agent collects the user's preferred appointment date using [Date of birth collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/date-of-birth-collection) prebuilt component.* |
|   | Great, we are done with collecting your preferred date. Please provide your preferred time slot. |
| 10 AM |   |
|   | You have selected 10:00 AM. To proceed further with the selected appointment time, say yes. |
| Yes |   |
|   | We will schedule an appointment at bank's address 1600 Amphitheatre Pkwy, Mountain View, CA 94043 on 2023-09-23 at 10:00 AM. Is that correct? |
| Yes |   |
|   | Okay, we have scheduled the appointment. Your confirmation number is 818452. Do you want to book another appointment? |
| No that's all |   |
|   | Thanks for connecting with us. Have a nice day! |

### New customer books multiple appointments

1. The agent identifies that the user hasn't been previously authenticated and collects the user's telephone number.
2. The user requests a virtual appointment to discuss loans.
3. If the user's first preference for date and time isn't available, the agent offers available time slots to them.
4. The user selects an available time slot and the appointment is scheduled.
5. If the user wants to book a second appointment, the agent schedules it and confirms the details.

| User Input | Agent Response |
|---|---|
|   | *The agent collects the user's telephone number using [Telephone number collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/telephone-number-collection) prebuilt component.* |
|   | Great, we are done collecting the telephone number. Before scheduling an appointment, we will ask you a few questions. Can you tell us the reason for your appointment? |
| I want to get a loan |   |
|   | Are you looking for a phone, video call or in-person appointment at one of our branches? |
| Virtual appointment is fine |   |
|   | Please provide your preferred appointment date. Please say your preferred month, followed by day and then year. Remember that our branches are open from Monday to Friday: 9 AM to 5 PM, Saturday: 9 AM to 1 PM. |
|   | *The agent collects the user's preferred appointment date using [Date of birth collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/date-of-birth-collection) prebuilt component.* |
|   | Great, we are done with collecting your preferred date. Please provide your preferred time slot. |
| 3:00 would be good for me |   |
|   | You have selected 03:00 PM. To proceed further with the selected appointment time, say yes. |
| Yes |   |
|   | We will schedule an appointment with our advisor on 2023-10-03 at 03:00 PM. Is that correct? |
| Yes please |   |
|   | Okay, we have scheduled the appointment. Your confirmation number is 754731. Do you want to book another appointment? |
| Yeah |   |
|   | Before scheduling an appointment, we will ask you a few questions. Can you tell us the reason for your appointment? |
| I need an appointment for my credit card |   |
|   | Are you looking for a phone or video call appointment with one of our branch representatives? |
| Phone |   |
|   | Please provide your preferred appointment date. Please say your preferred month, followed by day and then year. Remember that our branches are open from Monday to Friday: 9 AM to 5 PM, Saturday: 9 AM to 1 PM. |
|   | *The agent collects the user's preferred appointment date using [Date of birth collection](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/date-of-birth-collection) prebuilt component.* |
|   | Great, we are done with collecting your preferred date. Please provide your preferred time slot. |
| Does 8 AM work? |   |
|   | You have selected 08:00 AM. To proceed further with the selected appointment time, say yes. |
| Yes |   |
|   | Sorry, the selected time slot is not available. We have availability for 11:30 AM, 12:30 PM, 01:30 PM, and 03:00 PM on 2023-10-06. Would you like to change the time slot or schedule an appointment on a different date? |
| Ok let's do 1:30 then |   |
|   | You have selected 01:30 PM. To proceed further with the selected appointment time, say yes. |
| Yes |   |
|   | We will schedule an appointment with our advisor on 2023-10-06 at 01:30 PM. Is that correct? |
| Yep |   |
|   | Okay, we have scheduled the appointment. Your confirmation number is 714637. Do you want to book another appointment? |
| No that's it |   |
|   | Thanks for connecting with us. Have a nice day! |

## Naming conventions

This prebuilt component uses the following naming conventions:

| Feature | Format | Example |
|---|---|---|
| Flow | \[Component Name\] | Arrange Appointment |
| Component Specific Intent | prebuilt_components_\[component_name\]_\[intent_name\] | prebuilt_components_arrange_appt_change_date_slot |
| Entity Type | prebuilt_components_\[component_name\]_\[entity_type\] | prebuilt_components_arrange_appt_reason |
| Webhook | prebuilt_components_\[component_name\]:\[webhook_action\] | prebuilt_components_arrange_appointment:submit_appointment |

## Input parameters

Input parameters configure component behaviors. Conditions within the flow use
these parameters to determine component behavior. You can set flow-scoped
parameters on the start page of the component, and you can set
session-scoped parameters either through a calling flow or on the start page.

This prebuilt component accepts the following input parameters:

| Parameter Name | Description | Input Format |
|---|---|---|
| $session.params.phone_number | (optional) Customer's registered phone number used for authentication. | string |
| $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 |
| $flow.all_appointment_type | Specifies the list of [appointment reasons](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/arrange-appointment#reasons-and-types) for which all types of appointments are available. The default value is `["loans", "wealth"]`. | List (string) |
| $flow.video_phone_appointment_type | Specifies the list of [appointment reasons](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/arrange-appointment#reasons-and-types) for which all types of appointments are available. The default value is `["cards"]`. | List (string) |
| $flow.appointment_services | Specifies the list of [appointment types](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/arrange-appointment#reasons-and-types) for which branch location is not required and will not be collected from the user. The default value is `["video", "phone"]`. | List (string) |
| $flow.working_hours | Specifies the opening hours of the branch, for example `"Monday to Friday: 9 AM to 5 PM, Saturday: 9 AM to 1 PM"`. | string |
| $session.params.arrange_appointment_max_days | Specifies the maximum number of days after the current date allowed for an appointment booking. By default, this value is `90`, indicating that appointment dates may be booked no more than 90 days after the current date. This parameter is set in the start page `true` route. | integer |
| flow.max_retry_count | Specifies the number of retries allowed when collecting information from the user. 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 will remain active after exiting
the component. These parameters contain important information collected by the
component. This prebuilt component provides values for the following output
parameters:

| Parameter Name | Description | Output Format |
|---|---|---|
| phone_number | User's local phone number, without the country code, used to identify the user. | 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 this prebuilt component:

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 that describe your external services. See [Webhook setup](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/arrange-appointment#webhook-setup).

## 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
the necessary information from your external services.

### Get account

The `prebuilt_components_arrange_appointment:get_account` webhook lets you
retrieve account details for a provided phone number if a registered 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 | User's local phone number, without the country code, used to identify the user. | string |

#### API response parameters

The component pulls the following parameters from the API response:

| Parameter Name | Description | Output Format |
|---|---|---|
| account_count | Number of accounts associated with the registered phone number. | integer |
| cards_count | Number of cards associated with the registered phone number. | integer |
| loans_count | Number of loans associated with the registered phone number. | integer |
| mortgage_count | Number of mortgages associated with the registered phone number. | integer |
| branch_code | Branch code associated with the registered phone number, used to identify a unique branch location. | string |

#### To configure the Get 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_arrange_appointment:get_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**.

### Get branch

The `prebuilt_components_arrange_appointment:get_branch` webhook retrieves
information about a branch location by using a branch code.

#### API request parameters

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

| Parameter Name | Description | Input Format |
|---|---|---|
| $flow.branch_code | Branch code identifying a unique branch location. | string |

#### API response parameters

The component pulls the following parameters from the API response:

| Parameter Name | Description | Output Format |
|---|---|---|
| branch_address | Address of the branch. | string |

#### To configure the Get branch 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_arrange_appointment:get_branch 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**.

### Available branch

The `prebuilt_components_arrange_appointment:available_branch` webhook retrieves
the nearest branch location by using a zip code.

#### API request parameters

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

| Parameter Name | Description | Input Format |
|---|---|---|
| $flow.zip_code | Zip code provided by the user. | string |

#### API response parameters

The component pulls the following parameters from the API response:

| Parameter Name | Description | Output Format |
|---|---|---|
| branch_address | Address of the branch. | string |

#### To configure the Available branch 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_arrange_appointment:available_branch 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**.

### Get available slots

The `prebuilt_components_arrange_appointment:get_available_slots` webhook checks
available time slots for a user's preferred date and appointment type.

#### API request parameters

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

| Parameter Name | Description | Input Format |
|---|---|---|
| $flow.preferred_date | Preferred date for the appointment provided by the user in "YYYY-MM-DD" format. | string |
| $flow.appointment_type | The [appointment type](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/arrange-appointment#reasons-and-types) of the appointment. | string |
| $flow.branch_code | Branch code identifying the unique branch location selected by the user. | string |

#### API response parameters

The component pulls the following parameters from the API response:

| Parameter Name | Description | Output Format |
|---|---|---|
| available_slots | List of available appointment times for the specified date, in "HH:MM XM" format, for example `["09:00 AM", "2:30 PM"]`. If there are no available slots this parameter is an empty list `[]`. | List (string) |

#### To configure the Get available slots 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_arrange_appointment:get_available_slots 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**.

### Submit appointment

The `prebuilt_components_arrange_appointment:submit_appointment` webhook
lets the user schedule an appointment for their selected date, time, branch,
appointment reason, and appointment type.

#### 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 user, without the country code, used to identify the user and associate the appointment with their account. | string |
| $flow.preferred_date | Preferred date for the appointment provided by the user in "YYYY-MM-DD" format. | string |
| $flow.preferred_slot | Preferred time for the appointment provided by the user in "HH:MM XM" format. | string |
| $flow.appointment_reason | The [appointment reason](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/arrange-appointment#reasons-and-types) for the appointment. | string |
| $flow.appointment_type | The [appointment type](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component/arrange-appointment#reasons-and-types) of the appointment. | string |
| $flow.branch_code | Branch code identifying the unique branch location provided by the user, if required. | string |

#### API response parameters

The component pulls the following parameters from the API response:

| Parameter Name | Description | Output Format |
|---|---|---|
| request_number | The request number for the scheduled appointment. | integer |

#### To configure the Submit appointment 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_arrange_appointment:submit_appointment 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

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