Website chat · Application developer

Your application does the work.

Let visitors ask naturally. Keep prices, availability, permissions and saved records in the system that already owns them.

Start with one useful connection

Choose an operation that is easy to prove: retrieve published information, calculate a price using your existing calculator, or read available appointment slots. Connect an installed application-specific package whose supported contract matches your API.

Name the source of truth. Which existing endpoint or function owns the answer?
Match the connector. Check its request/response types and supported operations, not just its base URL.
Provision the server credential. Restrict it to the intended application/tenant and operations.
Prove a read. Compare the tool result with the native application.
Add confirmed writes only where needed. Prove saved records and failure recovery separately.

The manager settings screen chooses the registered connector and approved connection values. It does not generate tools from OpenAPI, install a new agent, or grant arbitrary API access. Connector/agent authoring is supplied separately and is outside this documentation.

Configure the server-owned connection

The shared binding supplies ConnectorKey, ApplicationApiBaseUrl, AllowedApiOrigins and ApiTokenEnvironmentKey. The installed connector owns the actual API path and request/response contract.

The common API client requires an operator-approved HTTPS origin, sends a Bearer credential from the server environment, disables redirects and has a 20-second timeout. The model cannot supply a replacement destination, credential or header. Your API must still authorize tenant, subject and operation; an allowed hostname is not business authorization.

Use the complete server binding example. Do not put a business token into the iframe URL or website JavaScript.

Return facts, not guesses

Use the actual business calculator for quotes. Do not reimplement its formula inside the prompt.
Read current prices, catalog and availability when the visitor asks for current information; a previous conversation result does not establish freshness.
Distinguish no matches, missing required records and API failure. A timeout must not become an invented empty answer.
Return the selected, permitted fields needed for the conversation. An anonymous website visitor must not gain private customer data by typing a name or identifier.

The CFL reference uses rendered published website information and the website’s existing calculator. A connector for a different business should bind that business’s own supported sources, not assume the CFL implementation is a universal crawler or tool generator.

Confirm the action. Then report its result.

Collect the required details and present the exact intended action to the customer.
Require the owning workflow’s actual customer confirmation before a save, booking or cancellation.
Recheck staff/AI ownership and application authorization at execution.
Use a stable operation identity where the native workflow supports it. Keep the same identity and body after an uncertain response.
Report success only from an authoritative receipt and saved record identity.
For Pending or Unknown, check the original operation through its supported status/readback path. If no reliable path exists, hold for staff review; do not create a second booking to see whether it works.

Business authorization, persistence and notifications stay in explicit owning application operations. Do not use database triggers, duplicate business records or a chat-side transcript table to create the workflow. In a RooTrax/Metabase application, extend the owning generated/custom business and repository patterns and regenerate its descriptor/client through the normal pipeline; do not add a parallel controller/DTO/ORM stack to bypass them.

Apply the pattern to your business

Service business

Explain service options, collect the inputs for your existing estimate calculator, and return its result. Staff can join when the visitor needs personal help.

Property business

Connect a published property catalog so visitors can ask about models, prices and financing. Add visit availability and confirmed bookings when those native operations are ready.

Your own workflow

Start with the endpoint that already owns a useful answer. Use the supplied connector’s exact types and permissions rather than recreating business logic in chat.

The integration checklist for a booking

Your application supplies availability, the selected slot, customer confirmation, the saved booking identity and an original-operation status check. Its own business operation remains responsible for permissions and notifications. Match the connector’s release contract and test against the real application before enabling that action.

Worked connection / Real estate

From published projects to a confirmed visit.

The Javier connector is a useful example of an assistant using a real application contract. The buyer can move from project information to qualification and a visit; each step calls a named operation with explicit inputs. The application still owns the records.

Customer's job	Connector's job	Application's result
Explore what is available	Read published projects, then models for the selected project.	Project/model IDs, names, published facts, prices and inventory status.
Understand financing	Read the selected project's published financing.	Currency, reservation, payment schedule, terms version and stated exceptions.
Describe what they need	Save confirmed contact details and source-backed qualification fields.	A linked contact and qualification record, with an authoritative operation receipt.
Arrange a viewing	Read available slots, show the selection and obtain customer confirmation before requesting a booking.	The accepted slot and booking identity, or a rejected/pending result—not an invented appointment.
Change that viewing	Use the booking already linked to this conversation and require the customer's confirmation.	A cancellation receipt for that specific booking.

The current connector does not expose an arbitrary property-search endpoint. It reads published projects and their models. Contact access is limited to a contact successfully linked through this conversation; cancellation is limited to a booking linked through it. A typed name, phone number or booking ID is not permission to retrieve another customer's records.

Developer reference: the eleven native operations

These are the operations expected by the current real-estate connector beneath /integrations/real-estate/v2. Match them to the actual native application before activation. This API is separate from Buffaly's shared conversation route.

Method	Relative path	Purpose and important inputs
GET	`/projects`	Published projects; returns `Project[]`.
GET	`/projects/{ProjectID}/models`	Models for one returned project; `Model[]`.
GET	`/projects/{ProjectID}/financing`	Published `Financing` for that project.
GET	`/projects/{ProjectID}/slots`	`FromUtc` and `ToUtc`; returns slots with timezone and `AvailabilityVersion`.
GET	`/contacts/{ContactID}/bookings`	Bookings for the conversation-linked contact.
POST	`/contacts`	Confirmed contact details and conversation/operation identity.
PUT	`/contacts/{ContactID}/qualification`	Project/model, budget, bedrooms, timeframe, financing need and purpose, with canonical customer source-message keys.
POST	`/bookings`	Linked contact, project, returned slot, availability version and customer confirmation.
POST	`/bookings/{BookingID}/cancel`	Linked booking/contact, confirmed customer message and reason.
POST	`/followups`	Contact when known, conversation, reason, request time and preferred contact time.
GET	`/operations/{OperationKey}`	Resolve the original operation after a pending or uncertain response.

Use the supplied package's PortalContracts.cs for complete field names and types. Money contains Currency and Amount strings. A project has a source version and update time. A model has its own inventory status and availability-as-of timestamp. Preserve those distinctions instead of treating all facts as timeless text.

Trace a booking without duplicating it

Read a native project's slots. Retain the selected SlotID, TimeZone and AvailabilityVersion.
Use the contact already linked by a successful confirmed contact operation. Present the selected visit to the customer.
The customer confirms. The connector requires CustomerConfirmed and a ConfirmedMessageKey that identifies an actual customer message.
The connector attaches its stable OperationKey and conversation/generation context. The model does not choose that identity or the server URL.
The native booking operation checks authorization and availability and returns its operation receipt. On success, report the saved RecordID and the accepted details.
If the response is Pending or Unknown, look up that same operation. Do not turn a missing response into a second booking request with a new identity.

A receipt contains OperationKey, Outcome, optional RecordType/RecordID, ErrorCode, Result and CompletedUtc. The contract's outcomes are Succeeded, Rejected, Pending and Unknown. The native application must implement the contract; the chat integration does not manufacture these guarantees.

This is a source-verified connector example. Native Javier integration and saved-record acceptance remain distinct from the recorded CFL website/calculator/staff proof. Use the same mapping process for your application, rather than changing a base URL and assuming the operations exist.

What proves a connection works?

Case	Required result
Supported read	The tool result matches the owning application’s current value.
Unauthorized record/tenant	Denied server-side; no private record returned.
Missing/invalid data or unavailable API	Explicit, correct error—not invented success or a normalized empty record.
Confirmed write	The native saved record and receipt match the customer’s confirmed details.
Response lost after save	Original operation resolved without another record or notification; otherwise held for staff review.
Staff takeover	Retired AI work cannot publish a stale answer or start a newly disallowed action; an already completed effect is reported honestly.

Keep those tests distinct from a chat-window test. A working conversation is the integration surface; your application’s native readback proves its business result.