This
[prebuilt component](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component.md.txt)
captures and validates a date of birth by collecting the month, date, and year.

## Limitations

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

- This component does not support verifying the user's date of birth by comparing it with the user's ID.

## Recommended agent settings

[Enable DTMF](https://docs.cloud.google.com/dialogflow/cx/docs/concept/parameter.md.txt#dtmf) to let users input
numeric values using the telephone keypad.

## Additional features

This prebuilt component provides the following additional features:

- [Repeat](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component.md.txt#repeat-functionality)
- [Waiting room](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component.md.txt#waiting-room-functionality)
- [Playback](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component.md.txt#playback-functionality)

## Sample dialogs

The sample dialogs show common scenarios that this prebuilt component handles.
They demonstrate behavior when the user calls the component using telephony,
which triggers the Default Welcome Intent and the first agent response at the
start of the conversation.

### Full date of birth

1. The user provides the complete date of birth in one turn.
2. The agent successfully accepts it.

| User Input | Agent Response |
|---|---|
|   | Please provide your date of birth. Please say your birth month, followed by your birth day, and then your birth year. |
| September 9th 1995 |   |
|   | Okay, your birthdate is September 9, 1995. Is that correct? |
| yes |   |
|   | Great, I've collected your birthdate. |

### Partial date of birth

1. The user provides the date of birth by saying the month first, followed by the date and year.
2. The agent successfully accepts it.

| User Input | Agent Response |
|---|---|
|   | Please provide your date of birth. Please say your birth month, followed by your birth day, and then your birth year. |
| March |   |
|   | What day were you born on? |
| 12 |   |
|   | What year were you born in? |
| 1999 |   |
|   | Okay, your birthdate is March 12, 1999. Is that correct? |
| yes |   |
|   | Great, I've collected your birthdate. |

### Future date validation

This scenario assumes that the current date is March 22, 2023:

1. The user provides a future date of birth.
2. The agent validates it and prompts the user to provide the correct date of birth.

| User Input | Agent Response |
|---|---|
|   | Please provide your date of birth. Please say your birth month, followed by your birth day, and then your birth year. |
| September 9th 2023 |   |
|   | What year were you born in? |
| 2023 |   |
|   | Okay, your birthdate is September 9, 2023. Is that correct? |
| yes |   |
|   | Sorry, you have provided a future date. Let's start again. Which month were you born in? |
| March |   |
|   | What day were you born on? |
| 12 |   |
|   | What year were you born in? |
| 1999 |   |
|   | Okay, your birthdate is March 12, 1999. Is that correct? |
| yes |   |
|   | Great, I've collected your birthdate. |

### Invalid date

1. The user provides an invalid date of birth, for example, February 30, 1999, or April 31, 1999.
2. The agent validates it and prompts the user to provide the correct date of birth.

| User Input | Agent Response |
|---|---|
|   | Please provide your date of birth. Please say your birth month, followed by your birth day, and then your birth year. |
| February 30th 1999 |   |
|   | Okay, your birthdate is February 30, 1999. Is that correct? |
| yes |   |
|   | The date you have provided is invalid. Let's start again. Which month were you born in? |
| March |   |
|   | What day were you born on? |
| 12 |   |
|   | What year were you born in? |
| 1999 |   |
|   | Okay, your birthdate is March 12,1999. Is that correct? |
| yes |   |
|   | Great, I've collected your birthdate. |

### Unrecognized input

Component exits the flow after the user provides unrecognized input three times.

| User Input | Agent Response |
|---|---|
|   | Please provide your date of birth. Please say your birth month, followed by your birth day, and then your birth year. |
| It's fine |   |
|   | Sorry, I didn't get that. Can you please say or enter your date of birth again? |
| nice |   |
|   | Sorry I didn't get your date of birth. Let's start with month. Please say which month were you born in? |
| good |   |
|   | Sorry, I didn't get that. Can you please say or enter the month number again? |
| nice |   |
|   | Hmm, I still wasn't able to get that. Make sure you're saying the month. If I am having trouble hearing you, you can also use the keypad to enter the month number. |
| nice |   |
|   | Sorry, I'm having difficulty understanding your response. |

## Date of birth validation

This prebuilt component uses the
[IS_DATE](https://docs.cloud.google.com/dialogflow/cx/docs/reference/system-functions.md.txt#func-isdate) and
[IS_FUTURE_DATE](https://docs.cloud.google.com/dialogflow/cx/docs/reference/system-functions.md.txt#func-isfuturedate)
system functions to check whether a collected date is valid and in the past.

In addition:

- Inputs such as "this month", "next month", or "last month" are converted into the appropriate months. For example, if you interact with the agent in March, then "this month", "next month", and "last month" are converted into "March", "April", and "February" respectively.
- The component validates that the year has four digits. If the year input contains only two digits, the component converts it into a four-digit year. For example, "98" is converted to "1998".
- Inputs such as "this Thursday", "last Thursday", and "next Thursday" are captured as the appropriate month and day, and the agent prompts you to provide the year. For example, if you interact with the agent on March 22, 2023, which is a Wednesday, then "this Thursday", "last Thursday", and "next Thursday" are converted into "March 23", "March 16", and "March 30" respectively.

## Naming conventions

This prebuilt component uses the following naming conventions:

| Feature | Format | Example |
|---|---|---|
| Flow | \[Component Name\] | DOB Collection |
| Component Specific Intent | prebuilt_components_\[component_name\]_\[intent_name\] | prebuilt_components_dob_collection_collect_month |
| Parameter | \[param_name\] | dob |
| Entity Type | prebuilt_components_\[component_name\]_\[entity_type\] | prebuilt_components_dob_collection_dob_day |

## Output parameters

Output parameters are session parameters that 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 |
|---|---|---|
| dob_collection_dob | This parameter returns an object containing date of birth elements: day, month and year | ``` { "year": integer, "month": integer, "day": integer } ``` |

## Basic setup

To set up this prebuilt component, you can
[Import the prebuilt component](https://docs.cloud.google.com/dialogflow/cx/docs/concept/prebuilt-component.md.txt#import).

### Complete

The prebuilt component is now set up and ready to test.