Front Desk API
Every conversation a customer had with the shop's AI, on whatever channel it arrived on, and what the AI did about it.
A conversation is one exchange with one customer: a chat on the booking page, or a phone call. The row carries who they were, what they wanted, what the AI did, and the booking it led to if there was one.
Channels
| Channel | What it is |
|---|---|
chat | The AI chat on the shop's booking page |
phone | A call the AI answered |
Outcomes
outcome is the value to branch on. outcome_label is the same thing in the words the shop reads on its own screen, so a dashboard built on this API says what the portal says.
| Outcome | Meaning |
|---|---|
open | Still going, or nothing was concluded |
answered | A question was answered |
booked | It led to a booking |
moved | An existing booking was moved |
canceled | An existing booking was canceled |
link_sent | The customer was texted a link to finish it themselves |
message | A message was taken for the shop |
passed_to_owner | It needs a person |
didnt_know | The AI could not answer, and the shop has been asked |
Waiting on the shop
needs_owner is true from the moment the AI hands a conversation over, and it stays true. waiting_on_you is the one to branch on: it is true only while the AI has handed it over AND nobody has marked it handled yet, which is what every count, filter and pill in the product reads. A client that watches needs_owner alone goes on nagging about something that was dealt with last week.
status_label is the single line to show for a row: "Needs you" while it is waiting, and what the AI did once it is not.
On a message, urgency says how it sounded: normal, urgent or emergency.
Archived conversations are put away rather than deleted. They are out of every list and are the only thing archived=true returns.
Scopes
| Scope | Grants |
|---|---|
frontdesk:read | List conversations, read one with its transcript, read the summary |
frontdesk:write | Mark a conversation handled, re-open it, archive it, put it back |
frontdesk:write covers the state of the conversation. Changing a booking still goes through the Bookings API with bookings:write, so there is one write path for a booking however the request arrived.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /v1/front-desk | List conversations |
| GET | /v1/front-desk/summary | Conversations, bookings, conversion and revenue, per channel |
| GET | /v1/front-desk/{id} | One conversation, with what was said |
| POST | /v1/front-desk/{id}/handled | A person dealt with it |
| POST | /v1/front-desk/{id}/unhandled | Put it back in front of whoever is on |
| POST | /v1/front-desk/{id}/archive | Put it away, without deleting it |
| POST | /v1/front-desk/{id}/unarchive | Put it back on the list |