VoiceBot
API docs by Redocly

VoiceBot Integration v1.0 (1.0.0)

E-mail: support@terminbooker.de Terms of Service

This is documentation for the API endpoint for the webhooks the VoiceBot will call in order to retrieve appointment typtes, availability and perform booking, modification and cancellations of appointments.

General Workflow

The VoiceBot will make the following call sequence upons receiving and answering a call:

First, getEntityForSipId will be called with the sipId of the phone number the VoiceBot agent answers the call. This function as a kind of router in case there are multiple phone numbers calls are received on mapping to different business entities. The returned entityId will be used for all subsequent requests in the call session.

With the retrieved business entity, a second request getBusinessName is being made in order to retrieve a human/official name of the business for the greeter to the caller.

A business

Webhook

getEntityForSipId Webhook

Requests an entityId based on the provided telephony endpoint / the number that has been called.

Request Body schema: application/json
action
string
Value: "getEntityForSipId"

Action/operation type of the webhook.

sipId
string

Unique id that for the telephony endpoint / the number that has been called.

Responses

Request samples

Content type
application/json
{
  • "action": "getEntityForSipId",
  • "sipId": "phoneSipId12345678"
}

Response samples

Content type
application/json
{
  • "entityId": "xyzBusinessEntityId"
}

getBusinessName Webhook

Requests an entityId based on the provided telephony endpoint / the number that has been called. This maps a number that a called has been received for and the voice bot of the business entity that should respond to that particular called phone number.

Request Body schema: application/json
action
string
Value: "getBusinessName"

Action/operation type of the webhook.

entityId
string

Unique id that represents the business entity.

Responses

Request samples

Content type
application/json
{
  • "action": "getBusinessName",
  • "entityId": "xyzBusinessEntityId"
}

Response samples

Content type
application/json
{
  • "name": "Physiotherapie Gleichgewicht"
}

getAppointmentTypes Webhook

Requests all available appointment types that can be booked by the customer for the given business entity.

Request Body schema: application/json
action
string
Value: "getAppointmentTypes"

Action/operation type of the webhook.

entityId
string

Unique id that represents the business entity.

Responses

Request samples

Content type
application/json
{
  • "action": "getAppointmentTypes",
  • "entityId": "xyzBusinessEntityId"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

getAppointmentTypesWithProducts Webhook

Retrieves all appointment types and associated product that can be booked by the customer.

Request Body schema: application/json
action
string
Value: "getAppointmentTypes"

Action/operation type of the webhook.

entityId
string

Unique Id that represents the business/gp/studio

Responses

Request samples

Content type
application/json
{
  • "action": "getAppointmentTypes",
  • "entityId": "xyzBusinessEntityId"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

getProducts Webhook

Retrieves all available products for the specified appointment type.

Request Body schema: application/json
action
string
Value: "getProducts"

Action/operation type of the webhook.

appointmentTypeId
string

Unique id of the appointment type to retrieve the available products

Responses

Request samples

Content type
application/json
{
  • "action": "getProducts",
  • "appointmentTypeId": "abcAppointmentTypeId"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

getSlots Webhook

Retrieves available slots for the specified appointment type and product.

Request Body schema: application/json
action
string
Value: "getSlots"

Action/operation type of the webhook.

appointmentTypeId
string

Unique id of the appointment type to retrieve the available time slots for.

productId
string

Unique id of the product to retrieve the available time slots for.

dateTime
string

Starting date time timestamp (in ISO 8601 format) or time slot query.

timezone
string

Timezone to format the returned time slots.

Responses

Request samples

Content type
application/json
{
  • "action": "getSlots",
  • "appointmentTypeId": "abcAppointmentTypeId",
  • "productId": "abcProductTypeId",
  • "dateTime": "2024-09-16",
  • "timezone": "Europe/Berlin"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

queryRequiredInfo Webhook

Retrieves what fields such as firstname, lastname etc. should be queried when booking the selected product. Each product might require different information in order to be booked. This webhook will request a list of required information to be queried from the user in order to fullflill the booking.

Request Body schema: application/json
action
string
Value: "queryRequiredInfo"

Action/operation type of the webhook.

productId
string

Unique id of the product to retrieve the required user information for.

Responses

Request samples

Content type
application/json
{
  • "action": "queryRequiredInfo",
  • "productId": "abcProductTypeId"
}

Response samples

Content type
application/json
{
  • "bookerInfo": [
    ],
  • "participantInfo": [
    ]
}

bookAppointment Webhook

Submits the information to book the appointment. The submitted information contains the chosen appointment type and product, the selected timeslot as well as particpiant information.

Request Body schema: application/json
action
string
Value: "bookAppointment"

Action/operation type of the webhook.

appointmentTypeId
string

Unique id of the appointment type chosen for the booking.

productId
string

Unique id of the chosen product for the booking.

slotId
string

Unique id of the chosen slot for the booking.

start
string

Starting date time timestamp (in ISO 8601 format) of the timeslot.

object (User)

The user record of the booking person.

object (User)

The user record of the participant person.

Responses

Request samples

Content type
application/json
{
  • "action": "bookAppointment",
  • "appointmentTypeId": "abcAppointmentTypeId",
  • "productId": "abcProductTypeId",
  • "slotId": "abcProductTypeId",
  • "start": "2024-09-16T08:30:00.000+02:00",
  • "booker": {
    },
  • "participant": {
    }
}

modifyAppointment Webhook

Submits the information to modify a previously booked appointment. The submitted information contains the newly chosen time slot if the user/participant required to modify ist.

Request Body schema: application/json
action
string
Value: "modifyAppointment"

Action/operation type of the webhook.

bookingId
string

Unique id of booking record.

slotIdOld
string

Unique id of the chosen slot that needs to be cancelled.

slotIdNew
string

Unique id of the newly chosen slot for the booking.

start
string

Starting date time timestamp (in ISO 8601 format) of the new timeslot.

Responses

Request samples

Content type
application/json
{
  • "action": "modifyAppointment",
  • "bookingId": "abcBookingId",
  • "slotIdOld": "abcSlotIdOld",
  • "slotIdNew": "abcSlotIdNew",
  • "start": "2024-09-16T08:30:00.000+02:00"
}

cancelAppointment Webhook

Submits the information to cancel a previously booked appointment. The submitted information contains the booking and slot that requires cancellation.

Request Body schema: application/json
action
string
Value: "cancelAppointment"

Action/operation type of the webhook.

bookingId
string

Unique id of booking record.

slotId
string

Unique id of the chosen slot that needs to be cancelled.

start
string

Starting date time timestamp (in ISO 8601 format) of the timeslot to be cancelled.

Responses

Request samples

Content type
application/json
{
  • "action": "cancelAppointment",
  • "bookingId": "abcBookingId",
  • "slotId": "abcSlotId",
  • "start": "2024-09-16T08:30:00.000+02:00"
}

findExistingUser Webhook

Queries for existing users in the system. The submitted information contains partial information such as firstname, lastname to find existing users for previous bookings.

Request Body schema: application/json
action
string
Value: "findExistingUser"

Action/operation type of the webhook.

object (User)

The provided user data to find existing bookings.

Responses

Request samples

Content type
application/json
{
  • "action": "findExistingUser",
  • "participant": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

findExistingBooking Webhook

Submits the information contains the userId of the previously identified user. The submitted information contains the userId of users that have bookings with the system.

Request Body schema: application/json
action
string
Value: "findExistingBooking"

Action/operation type of the webhook.

id
string

The userId of the identified user.

Responses

Request samples

Content type
application/json
{
  • "action": "findExistingBooking",
  • "id": "abcUserId"
}

Response samples

Content type
application/json
[
  • {
    }
]