Date and Birthdate Recognition

Available lang-locales: de (Germany) and en (North America)

This service extension provides more control over parsing dates if given in an unusual format, especially in combination with STT issues.

This advanced service extension significantly enhances the flexibility and accuracy of date parsing, particularly beneficial when handling dates presented in non-standard formats. This is an essential feature for addressing challenges that arise from Speech-to-Text (STT) inaccuracies or unconventional date representations. By leveraging this extension, users can ensure that dates are interpreted correctly, regardless of format peculiarities, leading to more reliable data processing and interpretation outcomes. It is an invaluable tool for projects where precise date recognition and accuracy are critical, making it easier to manage and analyze time-sensitive data accurately.

Example Flow with the Birthday Service

Service Configuration

Branches

• success: A valid result was provided.

• ambiguous: The input had multiple interpretations, resulting in multiple options in resultList.

• invalid: The input could not be identified as a valid date.

Input

• utterance: The raw utterance of the user. You can retrieve this from a Storage block with the variable intent.rawPlatformRequestBody.text (applicable to phoneV2 only).

• slot: The dateTime slot automatically extracted. Make sure it's activated in your speech assets.

• locale: Locale of the input. Currently, only the German locale (de) is supported.

• twoDigitThreshold: This setting enables control over two-digit years. For example, setting it to 20 makes the system interpret '20' as 2020 and '21' as 1921.

• maxYear: Sets the upper limit for valid years. Useful for birthdate verification.

• partialReturn: Enables the system to return just the day and month for dates exceeding maxYear.

• mode: Choose between three modes – birthday, pastdate, and futuredate. The service defaults to birthday.

Output

• result: The first valid result.

• resultList: The full list of valid options in case an ambiguous input is received.

• year: Year of the main result. Empty if partialReturn is active and the input/recognized year is bigger than maxYear.

• month: Month of the main result.

• day: Day of the main result.

Technical Configuration

• URL: https://parloaservices.azurewebsites.net/api/ParseBirthdate?clientId=<CLIENT_ID>

• Header: x-functions-key: <AUTHCODE>

For authentication, replace <AUTHCODE> and <CLIENTID> with the values provided by your Parloa representative.

Dialog Usage

Add the service to your dialog as usual. Below is a sample set of inputs:

Variables Description

Utterance

Use a Storage block to capture raw input and set a variable to intent.rawPlatformRequestBody.text.

Slot

Add the dateTime slot, which must be activated in Speech Assets.

maxYear

Define the maximum valid year according to your needs.

twoDigitThreshold

For birthdates, consider a value like 20; for future dates, a higher value like 99 is suitable.

Service Modes

birthday

This is the default setting for the mode field and controls the general behavior of the Service. With this setting, the Service processes the input date as-is without expecting it to be from the past or the future.

pastdate

Use this mode when you expect the date input to be a past date.

If the input date is from the past, the Service parses it and provides successful output.

Otherwise, the Service returns an invalid result. Incomplete input dates are automatically assumed to be past dates. For example, if the year is missing, the Service fills it in based on the pastdate logic.

futuredate

Use this mode when you expect the date input to be a future date.

If the input date is from the future, the Service parses it and provides successful output.

Otherwise, the Service returns an invalid result. Incomplete input dates are automatically assumed to be future dates. For example, if the year is missing, the Service fills it in based on the futuredate logic.

Examples of Date Parsing Outcomes

Two-Digit Year

Input

Two digit year that the automatic slot turns into a future date:

    "input": {
        "utterance": "Am 4.6. 42",
        "slot": "2042-06-04T00:00:00.000Z",
        "twoDigitThreshold": "19",
        "maxYear": "2006",
        "partialReturn": ""
    }

Output

Year is set to 1942 due to the twoDigitThreshold being set at 19, which is less than 42.

{
    "choice": "success",
    "output": {
        "result": "1942-06-04",
        "year": "1942",
        "month": "06",
        "day": "04"
    }
}

Ambiguous Unformatted Date

Input

Input given either via DTMF or said without delimiters:

    "input": {
        "utterance": "Am 4.6. 42",
        "slot": "2042-06-04T00:00:00.000Z",
        "twoDigitThreshold": "19",
        "maxYear": "2006",
        "partialReturn": ""
    }

Output

Since the month and day are unclear, two date options are returned, 1990-11-01 and 1990-01-11.

{
    "choice": "success",
    "output": {
        "result": "1942-06-04",
        "year": "1942",
        "month": "06",
        "day": "04"
    }
}

Partial Return

Incomplete date is given which is by default assumed to be in the current year (without partialReturn):

    "input": {
        "utterance": "15.10.",
        "slot": "2021-10-15T00:00.000Z",
        "twoDigitThreshold": "19",
        "maxYear": "2006",
        "partialReturn": ""
    }

Output: Invalid since 2021>2006

{
    "choice": "invalid",
    "output": {
        "result": "",
        "year": "",
        "month": "",
        "day": ""
    }
}

The same with partialReturn active:

  "input": {
        "utterance": "15.10.",
        "slot": "2021-10-15T00:00:00.000Z",
        "twoDigitThreshold": "19",
        "maxYear": "2006",
        "partialReturn": "true"
    }

Output: partial date is returned

{
    "choice": "success",
    "output": {
        "result": "10-15",
        "year": "",
        "month": "10",
        "day": "15"
    }
}

Futuredate Mode

1. Month input utterance that the service converts into a future date:

{
    "input": {
        "utterance": "Juli 2024",
        "twoDigitThreshold": "19",
        "maxYear": "2025",
        "mode": "futureDate"
    }
}

Output: Service converts the incomplete date to 24-07-01.

{
    "choice": "success",
    "output": {
        "result": "2024-07-01",
        "year": "2024",
        "month": "07",
        "day": "01"
    }
}

2. The following input utterance is an incomplete date, which the service handles as shown:

{
    "input": {
        "utterance": "11 24",
        "slot": "",
        "twoDigitThreshold": "80",
        "maxYear": "2024",
        "mode": "futureDate"
    }
}

Output: The service can detect from the input utterance:

• Input is given as "mm yy" => converted to 24-11-01

• Input is given as "dm yy" => converted to 24-01-01

{
    "choice": "ambiguous",
    "output": {
        "result": "2024-01-01",
        "year": "2024",
        "month": "01",
        "day": "01",
        "resultList": "2024-01-01,2024-11-01"
    }
}

The "today" date is "10-Jan-23" for both these examples.

Pastdate Mode

Date / Birthdate Recognition

This service extension provides more control over how dates are parsed if they are given in an unusual format, especially in combination with STT issues.Example flow with the birthdate serviceService configurationsuccess : a valid result was returnedambiguous : the input was ambiguous, and resultList contains multiple optionsinvalid: the input could not be mapped to a valid dateutterance: The raw utterance of the user. You can retrieve it in a storage block with intent.rawPlatformRequestBody.text (phoneV2 only) and use the storage variable subsequently in the service call.slot: The automatically extracted dateTime slot (ensure that it is activated in your speech assets).twoDigitThreshold: Configuration parameter that describes when a year is given only as two digits (e.g. 90 instead of 1990), until which number it is assumed to be 19XX vs 20XX. The default behavior of the current slot extraction uses the closest date to today, which makes 60 become 2060. This allows controlling this by setting it to a lower number, e.g. 20, which results in 20 -> 2020 but 21 -> 1921.maxYear: Configuration parameter that describes the maximum year that is considered a valid result. Use if e.g. for birthdate checking, by setting it to the current year if any past date is valid, or to a year that is assumed to be the minimum age of users contacting your bot (e.g., today minus 16 or 18 years: moment().year() - 18).locale: Locale of the input. Currently only de is supported (default: de).partialReturn: Set it to any non-empty value to have the day and month of dates that are beyond the maxYear returned instead of returning an empty result.mode: This optional input field defines which of the 3 possible modes of the Service you choose to use, from the options: birthday, pastdate, futuredate . The default value of the Service is birthday, even when this field is not used/filled. Further usage of pastdate and futuredate modes are explained further below. This input field is case insensitive, as parsing is performed in the service.result: The first valid resultresultList: The full list of valid options in case an ambiguous input is receivedyear: Year of the main result. Empty if partialReturn is active and the input/recognized year is bigger than maxYear.month: Month of the main result.day: Day of the main result.URL: https://parloaservices.azurewebsites.net/api/ParseBirthdate?code=<AUTHCODE>&clientId=<CLIENTID> (you can get your own AUTHCODE and CLIENTID from your Parloa representative)Note that the URL includes the API key to access the function. No separate header is needed.Dialog usageAdd the service to your dialog as usual. A sample input set is shown below:utteranceslotlocaletwoDigitThresholdmaxYearpartialReturnThe raw input of the user, usually obtained by using a storage block before the service call and setting a variable (e.g., utterance ) to the Javascript value of intent.rawPlatformRequestBody.text.Add it to the input by clicking the plus-symbol, or typing "+" and selecting the storage variable set in the previous storage block.

Service modes

birthdaypastdatefuturedateThe futuredate value is used when the input value of the utterance is expected to be in the future.The logic is as follows:

• If the utterance field contains a date in the future, then it is parsed and returned in the respective output fields, with a success branch output.

• Otherwise, an invalid result is returned, with no output in the output fields.

The futuredate mode does not handle only complete dates (e.g. dd-mm-yyyy) as input, rather it analyses the input of the user and it tries to generate valid dates with the input given. In case of incomplete input dates, such as when we don't specify the year, the service will try to complete them as a day in the future. In the other cases where the year is specified, the service will not try to alter the date to convert it to a future date. In ambiguous cases, such as when a number may be interpreted as a month or as a year, the service returns only those dates which are future dates. Further examples are detailed in the following section.

Result examples

Two Digit YearAmbiguous unformattedPartial returnFuturedate modePastdate mode

1. 1.Month input utterance that the service converts into a past date:

{"input": {"utterance": "02 Dezember","twoDigitThreshold": "19","maxYear": "2025","mode": "pastDate"}}Output: Year is set to 2022 because the of the pastdate mode defined{"choice": "success","output": {"result": "2022-12-02","year": "2022","month": "12","day": "02"}}2. The following input utterance is an incomplete date, which the service handles as shown:{"input": {"utterance": "01 11","slot": "","twoDigitThreshold": "80","maxYear": "2024","mode": "pastDate"}}Output: The service can detect from the input utterance:

• Input is given as "dd mm" => converted to 22-11-01

• Input is given as "mm yy" => converted to 11-01-01

{"choice": "ambiguous","output": {"result": "2022-11-01","year": "2022","month": "11","day": "01","resultList": "2022-11-01,2011-01-01"}}The today date is "10-Jan-23" for both these examples​