@humany/widget-callback

@humany/widget-callback

Exposes API for callback/appointment booking within Humany widgets as well as a date picker component to be displayed within contact forms.

This document describes how to create a simple plugin to communicate with the callback platform. The date picker component depends on opening hours data from an external (or mocked) data source.

Access the API

The following example shows the creation of a simple callback plugin that displays dates 30 days forward with 10 minute intervals per hours.

  import { Plugin } from '@humany/widget-core';
  import { CallbackPlatform } from '@humany/widget-callback';

  export class MyCallbackPlugin extend Plugin {
    constructor(container, settings) {
      const callbackPlatformSettings = {
        adapterClientName: 'name.callback',
        maxAvailableDates: 30,
        minuteInterval: 10,
        submit: (data) => { },
        getAvailableHours: (startDate, periodLength, contactMethodSettings) => {}
      }
      this.callbackPlatform = new CallbackPlatform(container, callbackPlatformSettings);
    }
  }

Settings parameters

adapterClientName: string (required)

The client name of the adapter the platform should attach to. This is a string which you configure on the contact method that will serve as a handler for this specific plugin.

maxAvailableDates: int (required)

The maximum amount of days in the future that are available for booking.

minuteInterval: int (required)

Controls the division of minute intervals per hour. A value of 10 would populate the minute dropdown with 10 minute intervals.

submit(data: object): Promise<SubmitResult> (required)

Delegate for handling of form submissions. The component should provide you with at least a phone number and a date, which should be validated within your client application. Parameter names are specified within the Contact Method settings in Humany's admin interface.

The data parameter contains a formData and a settings object. formData holds the form values, while settings contains the contact method's settings.

Note Humany widgets performs basic form validation before the sumbit delegate is called.

Must resolve an object of type SubmitResult.

Example of a basic submit implementation

  import { CallbackPlatform, ResultType } from '@humany/widget-callback';
  ...
  const callbackPlatformSettings = {
    ...
    submit: (data) => {
      const {formData, settings} = data;
      return new Promise((resolve) => {
        httpRequestToExternalApi.createCallback(formData).then((result) => {
          resolve ({
            type: result === 'success' ?  ResultType.success : ResultType.error,
            message: result === 'success' ? 'Success message' : 'Error message'
          });
        });
      });
    }
  }

getAvailableDates(startDate: date, period: number, contactMethodSettings: any): Promise (required)

Delegate for fetching opening hours from an external source. contactMethodSettings contains data from the contact method configuration in Humany admin GUI.

Parameters

startDate: Date (required) The first date to be retrieved (generally today's date) period: number (required) How many future dates to fetch.

The callback platform expects this function to return an array of the following structure

{
  opening: Date,
  closing: Date
}

Example

  const callbackPlatformSettings = {
    ...
    getAvailableDates: (startDate, period) => {
      return new Promise((resolve) => {
        httpRequestToExternalApi.getHours(startDate, period).then((result) => {
          if (result && result.length > 0) {
            resolve(result.map(item => ({opening: item.open, closing: item.close})))
          } else {
            resolve([]);
          }
        })
      })
    }
  }

Types

ResultType

enum ResultType {
  success = 'success',
  error = 'error',
}

SubmitResult

type SubmitResult = {
  type: ResultType,
  message: string
}