Skip to main content

Act on a Conversation

Four things a person can do about a conversation: say it has been dealt with, put it back, file it away, and take it out of the file again.

POST /v1/front-desk/{id}/handled
POST /v1/front-desk/{id}/unhandled
POST /v1/front-desk/{id}/archive
POST /v1/front-desk/{id}/unarchive

Authentication​

All four require a valid API key with frontdesk:write scope.

These change the state of the conversation, never a booking. Moving, canceling or paying for a booking the AI created goes through the Bookings API with bookings:write, so there is one write path for a booking however the request arrived.

Mark it handled​

A person dealt with it, so it stops waiting on anyone. The row keeps saying the AI handed it over, because that is what happened. What changes is waiting_on_you, which every count and filter reads.

curl -X POST "https://app.equipdash.com/api/v1/front-desk/1182/handled" \
  -H "Authorization: Bearer eqd_live_your_api_key"
{
  "data": {
    "id": 1182,
    "needs_owner": true,
    "waiting_on_you": false,
    "handled_at": "2026-09-19T09:40:11+00:00",
    "archived_at": null,
    "status_label": "Passed to you"
  },
  "meta": {}
}

The whole conversation comes back, so a client can repaint the row without asking for the list again.

Re-open it​

It was not dealt with after all. Only a conversation the AI handed over can be re-opened, so this cannot invent a job out of one that was finished.

curl -X POST "https://app.equipdash.com/api/v1/front-desk/1182/unhandled" \
  -H "Authorization: Bearer eqd_live_your_api_key"

handled_at comes back null, waiting_on_you true, and status_label reads "Needs you".

Archive it​

Put it away. Nothing is deleted: an archived conversation leaves the list and is the only thing archived=true shows, so nothing a customer said is lost.

curl -X POST "https://app.equipdash.com/api/v1/front-desk/1182/archive" \
  -H "Authorization: Bearer eqd_live_your_api_key"

Put it back on the list​

curl -X POST "https://app.equipdash.com/api/v1/front-desk/1182/unarchive" \
  -H "Authorization: Bearer eqd_live_your_api_key"

When it does nothing​

Each act applies to one state, and asking for it twice answers 422 rather than quietly stamping the row again.

CodeMeans
not_waitingMarking one that was not waiting on anyone
not_handledRe-opening one that was not marked handled
already_archivedArchiving one that is already archived
not_archivedRestoring one that is not archived
{
  "error": {
    "code": "not_waiting",
    "message": "That conversation was not waiting on anyone."
  },
  "meta": {}
}

A conversation belonging to another account returns 404, and an API key without frontdesk:write returns 403.