Skip to content
KelkiDevelopers

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

  1. The click. The manager or the guest describes the problem in a few words; the app already knows the flat (town) and the booking.
  2. 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.
  3. The choices. GET /trades/{trade_id} gives the services and timings to display as buttons, and the consent text.
  4. The place. GET /places?q=Créteil → fr-creteil-94000.
  5. The draft. POST /requests with reference = booking number and an Idempotency-Key header derived from the booking: a double click creates nothing more.
  6. The consent. The app displays recap, then consent.text as is, unticked box; the person who will be called back ticks it.
  7. 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.
  8. 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
Interfaceyour screens, Kelki's listsa chat thread, the agent asks the questions
AI modelnonefor free text only
EndPOST …/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