# Guide: a concierge app A concierge company manages short-let flats. A leak, a stuck lock, a jammed shutter: in its app, a “Find a professional” button starts the search, and the right person gets a call back from a professional of the right trade. ## The flow - The click. The manager or the guest describes the problem in a few words; the app already knows the flat (town) and the booking. - The trade. `POST /trade-matches` with `{"need": "fuite sous l'évier", "country": "FR"}`: the app offers the first 2 or 3 trades, the person chooses. - The choices. `GET /trades/{trade_id}` gives the services and timings to display as buttons, and the consent text. - The place. `GET /places?q=Créteil` → `fr-creteil-94000`. - The draft. `POST /requests` with `reference` = booking number and an `Idempotency-Key` header derived from the booking: a double click creates nothing more. - The consent. The app displays `recap`, then `consent.text` as is, unticked box; the person who will be called back ticks it. - The confirmation. `POST /requests/{request_id}/confirmation` (`"method": "email"`): the person receives the “Confirm my request” e-mail naming the concierge app; one click, and the request goes to the professionals of the area. - Tracking. The `request.status_changed` webhook (with the `reference`) updates the booking record: `awaiting_confirmation`, `transmitted`, `sold`, then `called_back` if the person confirms they were called back. Who consents? Always the person who will be called back, with their own contact details. The concierge app does not send a third party's details without their consent; the confirmation e-mail guarantees it: nothing goes out without the recipient's click. ## Two ways to integrate | | Lists (deterministic) | Kelki Agent (conversation) | | Routes | `/trade-matches`, `/trades/{trade_id}`, `/places`, `/requests` | `/agent/conversations` then `…/messages` | | Interface | your screens, Kelki's lists | a chat thread, the agent asks the questions | | AI model | none | for free text only | | End | `POST …/confirmation` | `{"consent": true}` at the `recap` step → same request | The flow with the agent: [Agent guide](https://kelki.ai/developers/en/guides/agent/). ## The core of the code (Python, standard library) ``` matches = call("POST", "/trade-matches", {"need": need, "country": "FR", "lang": "fr"}) trade_id = matches["data"][0]["trade"]["id"] # after the person's choice trade = call("GET", f"/trades/{trade_id}?country=FR&lang=fr") place = call("GET", "/places?" + urlencode({"q": flat_city, "country": "FR"}))["data"][0] draft = call("POST", "/requests", { "trade_id": trade_id, "service": chosen_service, "delay": chosen_delay, "place_id": place["id"], "contact": {"name": guest["name"], "phone": guest["phone"], "email": guest["email"]}, "reference": booking_id, }, idem=f"concierge-{booking_id}-draft") # … display draft["recap"] then draft["consent"]["text"], unticked box … call("POST", f"/requests/{draft['id']}/confirmation", {"method": "email", "consent_text_version": draft["consent"]["version"], "consent_given": True}, idem=f"concierge-{booking_id}-confirmation") ``` The `call` function and webhook verification: [code examples](https://kelki.ai/developers/en/examples/). ## Best practices - Keep the key server-side; the mobile or web app talks to your server, not to the Kelki API. - Display Kelki's lists as they are (services, timings): they are the ones professionals receive. - Put your booking identifier in `reference`, never a name or a phone number; in `end_user_ref`, a stable pseudonym of the user. - Plan for `contact_limit_reached` (3 requests per 24 hours for the same person): suggest they confirm those already received by e-mail. ## About this page - URL : https://kelki.ai/developers/en/guides/concierge/ - Language : en - fr : https://kelki.ai/developers/fr/guides/conciergerie/ - en : https://kelki.ai/developers/en/guides/concierge/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt