Opening Hours

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

The Opening Hours service extension enables the user to retrieve information about a business's or a branch's working hours for a given date and time. It provides flexibility in querying opening hours based on a calendar configuration. Additionally, you can specify hours for specific departments to obtain more precise information for the caller.

Service Configuration

Branches

• success : Confirms valid retrieval of opening hours.

• fail: Signals unsuccessful retrieval of opening hours.

Input

• config: A text-based configuration for the calendar. Each line represents a new day or date with its opening and closing hours or a dash if it's a non-working day. Reasons for closure can be included in round brackets.​

• configJSON: A structured way to input the calendar configuration as a JSON string, represented as an array of objects containing Date, Department, Start, End, Reason & Timezone(optional). A list of available Timezones. Default is Europe/Berlin

• dateTime: A formatted string for the date and time to search in the calendar configuration. It follows the format YYYY-MM-DDTHH:mm:ss.SSSZ. For more information, you may refer to the Dialog Usage section.

• department: A comma-separated list of departments to search for in the calendar. This is an optional field and can be empty if not needed.

• oneDict: An optional field used for configuration purposes and applies when searching for a single department. When searching for multiple departments, the oneDict field becomes inactive. If you are searching for just one department, leaving oneDict empty will result in an empty output object, with the remaining fields showing the search results you requested. If you set a value for oneDict, the output object will contain the search results.

• locale: An optional field determining the language used for date transformation in the config parameter. Currently, only German (de) & English (en) is supported for the config parameter. Default is en

• configTimezone: An optional field determining the timezone of the opening hours. This will only work when using the single line config variant and NOT the JSON configuration. A list of available Timezones. Default is Europe/Berlin

Note: You can use either config or configJSON as an input to a service, not both.

Output

• result: The object which contains all the fields below, in case we are returning with oneDict activated, or in case we have searched for multiple departments. Otherwise will be an empty object.

• openNow: true or false, indicating whether the calendar configuration shows open hours for the specified date and time.

• closedReason: The reason configured on the calendar for specific days and dates.

• nextDate: The next open day of the department if it is closed; otherwise, it returns the current date.

• nextHoursStart: The opening time on the next date.

• nextHoursEnd: The closing time on the next date.

• errorMsg: The reason for any service operation failure; empty if no errors occurred.

Technical Configuration

• URL: https://parloaservices.azurewebsites.net/api/OpeningHours?clientId=<CLIENTID>

• 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. A sample input set is shown below:

When creating opening hours configurations inside a JavaScript block, make sure to use JSON.stringify(<yourObject>) before you pass it into the Service!

config

The simple method of calendar configuration. Separate each day or date with a newline. Reasons for being open/closed can be added in round brackets in the end of each day/date. Does not support configuration of departments. An example of the object inside the Service field config is given below:

Montag: 8:00 - 16:00 
Dienstag: 10:00 - 20:00 
Mittwoch: 8:00 - 18:00 
Donnerstag: 8:00 - 18:00
Freitag: 8:00 - 18:00
Samstag: 10:00 - 16:00 
Sonntag: 
24.12.2022: - (Weihnachten)

configJSON

The calendar configuration, in this case in the JSON format, is formed as an array of objects, where each object is given as an example below:

jsonCopy code[{
    "Date": "Montag,Dienstag,Mittwoch,Donnerstag,Freitag",
    "Department": "*",
    "Start": "8",
    "End": "20",
    "Reason": null,
    "Timezone": "Europe/Berlin"
}]

The * in the configJSON is a hardcoded placeholder that functions as the default department whenever no specific department match is found.

dateTime

If the date is taken as input from the caller, the variable in which the date is stored can be used as the input for dateTime here. In this case it is automatically transformed into date-time format which is decided by the moment-js library. Otherwise, the function below can be used to input the current date and time to a storage variable in a block before, and then transferred to dateTime :

moment();

department

A comma separated list of strings which is passed as department input. For each of the departments the dateTime value will be queried. An example of the input value inside the Service field departments is given below:

Customer Success, Product Team, Sales 

oneDict

Set it to any value if you want the output to be in the result dictionary or leave it empty to heave the output in the separate variables. Only valid when there is 0 or 1 department input.

Result Examples

Text config example

Basic request with text config field and no department:

config

Montag: 8:00 - 16:00 
Dienstag: 10:00 - 20:00 
Mittwoch: 8:00 - 18:00 
Donnerstag: 8:00 - 18:00 
Freitag: 8:00 - 18:00 
Samstag: 10:00 - 16:00 
Sonntag: 
24.12.2022: - (Weihnachten)

dateTime

2022-12-26T11:59:00.000+02:00

Output: Everything is stored outside the object result

"choice": "success",
"output": {
    "result": {},
    "openNow": "true",
    "closedReason": "",
    "nextDate": "2022-12-26",
    "nextHoursStart": "08:00",
    "nextHoursEnd": "16:00"
}

Simple request example

Basic request with one department and oneDict as True:

configJSON

[{
   "Date": "Montag,Dienstag,Mittwoch,Donnerstag,Freitag",
   "Department": "Vertrieb",
   "Start": "8",
   "End": "20",
   "Reason": null,
   "Timezone": "Europe/Berlin"
}]

dateTime

2022-07-21T17:35:00.000+02:00

department

Vertrieb

oneDict

True

Output: Everything is stored inside the object result

"choice": "success",
"output": {
    "result": {
        "Vertrieb": {
            "openNow": "true",
            "closedReason": "",
            "nextDate": "2022-07-21",
            "nextHoursStart": "08:00",
            "nextHoursEnd": "18:00",
            "timeZone": "Europe/Berlin"
        }
    },
    "openNow": "",
    "closedReason": "",
    "nextDate": "",
    "nextHoursStart": "",
    "nextHoursEnd": ""
}
Basic request with one department and oneDict as empty:

Simple request example without dictionary

configJSON

[{
   "Date": "Montag,Dienstag,Mittwoch,Donnerstag,Freitag",
   "Department": "Vertrieb",
   "Start": "8",
   "End": "20",
   "Reason": null
}]

dateTime

2022-07-21T17:35:00.000+02:00

department

Vertrieb

Output: Everything is stored in separate variables and the result object is empty

"choice": "success",
"output": {
    "result": {},
    "openNow": "true",
    "closedReason": "",
    "nextDate": "2022-07-21",
    "nextHoursStart": "08:00",
    "nextHoursEnd": "18:00"
}

Multiple department request

Request with two departments :

configJSON

[{
  "Date": "Montag,Dienstag,Mittwoch,Donnerstag,Freitag",
  "Department": "Kundenservice",
  "Start": "8",
  "End": "20",
  "Reason": null
},
{
  "Date": "Montag, Dienstag, Mittwoch, Donnerstag, Freitag",
  "Department": "Vertrieb",
  "Start": "9",
  "End": "18",
  "Reason": null
}]

dateTime

2022-07-21T18:35:00.000+02:00 

department

Vertrieb, Kundenservice

Output: result object populated with output of both departments

"choice": "success",
"output": {
    "result": {
        "Vertrieb": {
            "openNow": "false",
            "closedReason": "",
            "nextDate": "2022-07-22",
            "nextHoursStart": "09:00",
            "nextHoursEnd": "18:00",
            "timeZone": "Europe/Berlin"
        },
        "Kundenservice": {
            "openNow": "true",
            "closedReason": "",
            "nextDate": "2022-07-21",
            "nextHoursStart": "08:00",
            "nextHoursEnd": "20:00",
            "timeZone": "Europe/Berlin"
        }
    },
    "openNow": "",
    "closedReason": "",
    "nextDate": "",
    "nextHoursStart": "",
    "nextHoursEnd": ""
}

Holiday Request

            {
            "Date": "12/23/2024",
            "Department": "Kundenbetreuung",
            "Start": "-",
            "End": "-",
            "Reason": "Kurz vor Weinachten"
             }

Sample CURL Requests for Postman

For configJSON:

curl --location 'https://parloaservices.azurewebsites.net/api/OpeningHours?clientId=<CLIENTID>' \
--header 'x-functions-key: <your-auth-code>' \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "config": "[{\n   \"Date\": \"Montag, Dienstag, Mittwoch, Donnerstag, Freitag\",\n   \"Department\": \"Vertrieb\",\n   \"Start\": \"8\",\n   \"End\": \"20\",\n   \"Reason\": null\n}]",
        "dateTime": "2023-12-23T10:59:00.000+01:00",
        "department": "Vertrieb"
    }
}'

For config:

curl --location 'https://parloaservices.azurewebsites.net/api/OpeningHours?clientId=<CLIENTID>' \
--header 'Content-Type: application/json' \
--header 'x-functions-key: <your-auth-code>' \
--data '{
    "input": {
        "config": "Montag: 8:00 - 16:00\nDienstag: 10:00 - 20:00 \nMittwoch: 8:00 - 18:00\nDonnerstag: 8:00 - 18:00\nFreitag: 8:00 - 18:00\nSamstag: 10:00 - 16:00 \nSonntag:\n24.12.2022: - (Weihnachten)\n12-24-2023: - (Weihnachten)",
        "dateTime": "2023-12-24T10:00:36.853+01:00",
        "department": "Kundenbetreuung",
        "locale": "de"
    }
}'

Output Usage

Dictionary Storage

The following example shows a way which can be used to retrieve the result data from the output. In the case of a successful response, the output is stored in 6 separate variables inside the service output. We don't need to use any other block to control the variables of our output.

The following image shows how the result can be used from the service variable openNow ,assigned to storage variable VertriebOpenNowto control a Condition Block. In this case we have two branches which decide the flow of the dialog in depending on the result.

Individual Storage

The following example shows a way which can be used to retrieve the result data from the output. In the case of a successful response, it is stored in the dictionary result. We can use the values of the storage variable result immediately.

The following image shows how the result can be used from the storage variable result to control a Condition Block. In this case we have two branches which use the openNow property of each department Vertrieb.