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-matcheswith{"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 /requestswithreference= booking number and anIdempotency-Keyheader derived from the booking: a double click creates nothing more. - The consent. The app displays
recap, thenconsent.textas 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_changedwebhook (with thereference) updates the booking record:awaiting_confirmation,transmitted,sold, thencalled_backif 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.
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.
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; inend_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.