Appointments overview
Appointments is available on Enterprise plans only, added on request. Until it's on for your
organization, every Appointments endpoint answers 403 APT_001.
Keep your bookings in your own system and let customers book on WhatsApp. DutiesBook sends the customer a booking form and fills its lists from your API while they pick. When they confirm, it sends you the booking to save and tells them what you answered. After that, it keeps you told about everything the customer does.
Before you start
Section titled “Before you start”- Appointments is on for your organization. It’s an Enterprise add-on; ask your DutiesBook contact.
- Settings › Booking is set to “In your own booking system”. An organization takes bookings one way only: in DutiesBook, or in your system. Until an admin chooses yours, the API answers
APT_010. - The WhatsApp setup on that page is finished. It makes the booking form and the message templates on your appointments number, in Arabic and English.
- You have an API key with the Appointments permission. If the key is limited to some channels, the appointments number must be one of them; otherwise every call answers
AUTH_008. - Your webhook URL is set in Settings › Booking. DutiesBook sends every booking and every event to that one URL. Until an admin sets it, nothing can be booked: booking requests answer
APT_011.
How a booking works
Section titled “How a booking works”- You connect once. DutiesBook checks your
GET /auth/verifyand gives you a signing secret. - You send a customer the booking form.
- The customer opens the form on WhatsApp. Each screen asks your API for its list: locations, services, providers, dates, times.
- The customer taps Confirm. DutiesBook posts the booking to your webhook URL and waits for your answer:
201books it,409sends the customer back to pick another time. - DutiesBook sends the customer their confirmation, then the reminders and the Cancel and Reschedule buttons.
- You manage the appointment (accept, reject, cancel, move), and DutiesBook tells you what the customer, and your team in DutiesBook, does.
You call DutiesBook
Section titled “You call DutiesBook”Base URL https://app.dutiesbook.com/api/external/v1, with the usual authentication headers.
| Method | Endpoint | Description |
|---|---|---|
| POST | /appointments/connection | Connect, or reconnect, your booking system |
| DELETE | /appointments/connection | Disconnect it |
| POST | /appointments/booking-requests | Send a customer the booking form |
| GET | /appointments | Your appointments, as DutiesBook has them |
| GET | /appointments/{id} | One appointment |
| POST | /appointments/{id}/accept | Accept a pending booking |
| POST | /appointments/{id}/reject | Reject a pending booking |
| POST | /appointments/{id}/cancel | Cancel an appointment |
| POST | /appointments/{id}/reschedule | Ask the customer for a new time, or move it |
| PATCH | /appointments/{id} | Another provider, same time |
DutiesBook calls you
Section titled “DutiesBook calls you”The lists on the baseUrl you connect with; bookings and events on the webhook URL set in Settings › Booking. All with Authorization: Bearer <your token>.
| Method | Endpoint | Description |
|---|---|---|
| GET | /auth/verify | Checks the connection |
| GET | /locations | The form’s locations |
| GET | /services | Services and sub-services at a location |
| GET | /providers | Providers for a location and sub-service |
| GET | /dates | Days with a free time |
| GET | /times | Free times on a day |
| POST | {webhookUrl} | Every booking (live) and every event |
Conventions
Section titled “Conventions”| Topic | Rule |
|---|---|
| IDs | Locations, services, providers and appointments use your IDs: any string. DutiesBook passes them back to you unchanged. |
| Language | Every list request carries language (en or ar). Return names in that language. |
| Dates and times | YYYY-MM-DD and HH:mm (24-hour), always in the location’s own timezone. |
| Timeouts | Lists answer within 2.5 s (WhatsApp gives a screen 10 s in all). The booking answers within 5 s, because the customer is waiting. |
| Messages | DutiesBook sends the customer every message: confirmations, reminders (unless you send them: see reminders on connect), and the changes you make. |
DutiesBook keeps a copy
Every booking you accept is kept in DutiesBook too, so your team sees it in the inbox and on the Appointments page, and the customer’s buttons keep working.
Your team in DutiesBook
Section titled “Your team in DutiesBook”Staff can book, move, cancel and accept your appointments from DutiesBook too. Your system stays in charge of the free times and the catalog: staff pick from your lists and never edit your locations, services or providers.
| Staff do | What you get |
|---|---|
| Book, or send the booking form | The booking, with bookedBy: "staff" (or "customer" for the form). Nothing is kept until you answer. |
| Move to a time they pick | The booking for the new time, with previousAppointmentId. |
| Ask the customer to choose a new time | appointment.cancelled with rescheduleRequested: true, then the customer’s booking naming it. |
| Cancel | appointment.cancelled with cancelledBy: "staff" and their reason. |
| Accept a pending booking | appointment.accepted. |
Rejecting a pending booking stays in your system.