Build the connection.
Then add the conversation.

One setup. Six finished milestones.

Choose one first result: an existing price calculation, a published catalog item or another read your application already supports. Use the same target application and identifiers through every step.

No Buffaly installation yet? Follow the platform installation guide first and verify that your operator can run the chosen model provider. The platform installer and the website-chat/application packages are separate release inputs; obtain a compatible set for this installation before proceeding.

1. 1 / Business owner + application developer

   Choose the job and its source

   Name the customer question, the operation that answers it and the native record or calculator result you will compare. Obtain the supplied connector's supported request/response contract.

   For cleaning, use a known home/service combination. For property, use an actual published project and model. Keep booking or customer-record writes as a separate, confirmed workflow.

   Done when: the operation exists, the expected result is known and the connector matches it. Work through the application guide →

2. 2 / Buffaly operator

   Activate the assistant and registration

   Install the compatible shared Chat module and supplied application-specific agent/connector. Register the application, its API destination, allowed website and staff identities. Do not point the website at an employee agent.

   Use the package procedure and binding reference. Confirm what is actively loaded, not just what the package catalog says is installed.

   Done when: the intended project, agent and connector resolve and the operator returns the non-secret handoff below.

3. 3 / Public gateway + staff host operators

   Connect the visitor and staff entry points

   Deploy the PublicChat gateway, configure its route and public-service credential, and persist its key ring. Install the staff adapter/UI, configure its application binding and authorize a manager and test staff user.

   Prepare both hosts before using the manager settings screen. Follow the gateway and staff-host instructions; use the worksheet to generate matching files.

   Done when: the HTTPS gateway is reachable and the authorized manager can load this application's current settings.

4. 4 / Integration manager + website developer

   Publish settings and add the embed

   Load current settings, set the welcome, business instructions and exact website origins, validate, publish the revision and reload it. Copy the returned hosted URL into the embed builder.

   Install the generated snippet once on the actual allowed website. Test there, rather than in a CMS editor with a different origin.

   Done when: a new visitor conversation opens with the intended welcome, and appears in the staff Inbox.

5. 5 / Application developer + test staff member

   Prove the useful answer and handoff

   Ask the Step 1 question. Compare the returned fact or calculation against the native application. Then take over, send a staff reply, send a visitor message during staff control and return control to AI.

   The next new visitor message should receive a history-aware answer. Messages sent during staff ownership must not replay as fresh AI work.

   Done when: the native answer matches and the customer/staff exchange is present in one conversation. Run the complete checklist →

6. 6 / Business owner + operators

   Hand over a working installation

   Record the active versions, published revision, website URL, staff access, supported operations, verification evidence and who operates each service. Test the agreed refresh/reopen behavior and failure messages.

   If bookings, callbacks or another business write are in scope, require its native saved-record proof before offering it. A passing read does not establish a write.

   Done when: the website owner has the embed and settings instructions, staff can run the conversation, and the promised workflows have their own results.

The operator handoff

Keep this compact receipt with the installation. It lets the website and staff operators finish without inventing identifiers or exchanging secrets in a chat.

The instructions below describe the existing operator-assisted installation. The settings UI maintains a registration; it does not install the agent or create accounts. Package versions, active-release receipts and exact delivery/profile identities come from your target release, not from a guessed example.

Collect the deployment values

Use four separate role references: staff-service, public-service, delivery-gateway and business API. Provision secret values out of band. Neither the embed nor the manager settings API should return them.

1. Activate compatible packages

1. Verify the chosen Buffaly core supports the supplied chat package’s prepared-input/profile-admission hooks. Pin the matching core/SDK/package versions from the release manifest.
2. Install Buffaly.Chat, then the supplied application connector/profile, using the target’s registered extension installation/release workflow.
3. Deploy the separate Buffaly.PublicChat.Web gateway and the selected staff adapter/UI. The Feeding Frenzy reference uses FeedingFrenzy.Chat.Admin with its compiled descriptor/client packaging.
4. Verify active loaded packages and imported profile/project artifacts, not just desired or Installed catalog labels. A pending WebModule activation may need the target’s approved controlled restart window.

No loose-DLL copying into the Buffaly host, update-all operation or arbitrary host changes are required by this guide. Use your environment’s approved lifecycle procedure; installing an extension is not an instruction to rebuild core.

2. Configure the shared registry and bootstrap

On the Buffaly server, the runtime reads <BUFFALY_INSTALL_ROOT>/config/chat/runtime.json. The web and worker processes must initialize the same bindings and control-state root. The full registry document is an array of AppBinding revisions.

[
  {
    "InstallationKey": "your-installation",
    "ApplicationKey": "website-assistant",
    "PublicAgentKey": "website-assistant",
    "ProjectName": "YOUR_REGISTERED_PROJECT",
    "AgentName": "YOUR_SUPPLIED_AGENT_NAME",
    "ConnectorKey": "YOUR_INSTALLED_CONNECTOR",
    "ReconcilePrototypeName": "YOUR_SUPPLIED_RECONCILE_IDENTITY",
    "Revision": 1,
    "Enabled": true,
    "PromptText": "Use the registered application tools and approved business guidance.",
    "Introduction": "Hi! How can I help?",
    "Origins": ["https://www.example.com"],
    "HostOrigin": "https://staff.example.com",
    "StaffSubjects": ["101"],
    "ManagerSubjects": ["101"],
    "ChannelAccountKeys": ["your-unique-web-account"],
    "BuffalyBaseUrl": "https://agent.example.com",
    "PublicChatBaseUrl": "https://chat.example.com/public-chat",
    "DeliveryUrl": "https://delivery.example.com/YOUR_REGISTERED_ROUTE",
    "ModuleTokenEnvironmentKey": "SITE_CHAT_STAFF",
    "PublicTokenEnvironmentKey": "SITE_CHAT_PUBLIC",
    "GatewayTokenEnvironmentKey": "SITE_CHAT_DELIVERY",
    "ApplicationApiBaseUrl": "https://api.example.com",
    "AllowedApiOrigins": ["https://api.example.com"],
    "ApiTokenEnvironmentKey": "SITE_CHAT_API",
    "PublishCommandKey": null
  }
]

Registered origin fields are exact HTTPS origins: no path, query, fragment or user info. PublicChatBaseUrl is different: it includes the gateway path base. The business API base may include a supported path; its HTTPS origin must be in AllowedApiOrigins. Preserve exact key casing. Public keys and channel-account bindings must be unique; installation/application/revision triples must be unique.

{
  "BindingsFile": "D:/ServiceData/WebsiteChat/bindings.json",
  "StateRoot": "D:/ServiceData/WebsiteChat/control",
  "Credentials": {
    "SITE_CHAT_STAFF": "PROVISION_DISTINCT_STAFF_SECRET_OUT_OF_BAND",
    "SITE_CHAT_PUBLIC": "PROVISION_DISTINCT_PUBLIC_SECRET_OUT_OF_BAND",
    "SITE_CHAT_DELIVERY": "PROVISION_DISTINCT_DELIVERY_SECRET_OUT_OF_BAND",
    "SITE_CHAT_API": "PROVISION_LEAST_PRIVILEGE_APPLICATION_SECRET_OUT_OF_BAND"
  }
}

The runtime requires explicit absolute file/state paths and exactly the credential references named by the bindings. The staff/public/delivery role credentials must be nonempty and distinct across current applications. Do not use these placeholder strings as real credentials. Protect the file from public serving, commits and exports.

Bootstrap is one-time per process. Apply changes through the target’s approved activation/reload procedure; changing a file alone does not demonstrate that existing workers loaded it. The conversation text remains in Buffaly’s canonical session/message store—StateRoot holds control metadata and references, not a replacement transcript.

3. Route the public gateway

The current shared mode reads configuration under PublicChat. It does not use the older README’s StagingBuffalyPublicAgent section. Shared integration takes precedence over staging/demo mode.

{
  "PublicChat": {
    "UseSharedIntegration": true,
    "UseStagingBackend": false,
    "IntegrationRoutesFile": "D:/ServiceData/PublicChat/routes.json",
    "PathBase": "/public-chat",
    "DataProtectionApplicationName": "YourCompany.PublicChat",
    "DataProtectionKeysPath": "D:/ServiceData/PublicChat/keys"
  }
}

[
  {
    "PublicAgentKey": "website-assistant",
    "ApplicationKey": "website-assistant",
    "BuffalyBaseUrl": "https://agent.example.com",
    "CredentialEnvironmentKey": "SITE_CHAT_PUBLIC"
  }
]

Make SITE_CHAT_PUBLIC available in the gateway process environment with the same public-service credential registered on Buffaly. Never send it to the browser. Match the public/application keys and Buffaly origin exactly.

Configure your approved reverse proxy/IIS host for public HTTPS, the correct /public-chat base and forwarding behavior. Verify the actual external path reaches the app; UsePathBase does not configure your proxy. Check trusted proxy configuration in your deployment.

Persist the Data Protection key ring and keep the application name stable across deployments. Loss of the key ring makes existing browser capabilities unreadable. A shared key ring alone does not prove multi-replica usage accounting or recovery; the current turn counter is process-local.

Verify /public-chat/health, assets and /public-chat/ externally. The health endpoint reports process health only; a real open/send/refresh test must separately prove backend connectivity. Ensure the gateway/proxy permits authorized website framing and the parent website’s CSP allows it.

4. Connect the staff workspace

For the Feeding Frenzy adapter, set the existing Chat.IntegrationFile app setting to an absolute server file containing this HostBinding shape:

{
  "ApplicationKey": "website-assistant",
  "HostOrigin": "https://staff.example.com",
  "BuffalyBaseUrl": "https://agent.example.com",
  "StaffCredentialEnvironmentKey": "SITE_CHAT_STAFF",
  "UserIDs": [101]
}

Make the registered staff-service credential available in the staff process environment. A staff member must be enabled/unlocked, in UserIDs, and currently an Administrator or Sales Representative. Settings require an Administrator and the corresponding registered manager subject. The adapter sends the current trusted numeric user ID as a string subject; do not accept it from the browser.

Write commands require the staff request’s exact Origin to match HostOrigin. Preserve normal and legacy server authorization; a hidden link is not a permission boundary. Include the compiled adapter and its generated JsonWs descriptor/client using the staff application’s normal package/import route—not a new controller or tenant-specific host startup reference.

The shared Buffaly.Chat.Admin.UI component supplies Inbox and Chatbot settings. The Feeding Frenzy reference mounts it in its existing staff page; the optional ASP.NET Core adapter is a different host choice, not a verified drop-in replacement for that reference.

5. Publish the settings and prove the connection

1. Load current settings as the registered manager; confirm the bound connector, public key, website origins and API base.
2. Change permitted welcome/instruction/origin/enabled values, validate, and publish. Confirm the revision through readback.
3. Copy the generated iframe to an allowed website and open a fresh conversation.
4. Run the customer/staff launch checklist. Independently read the canonical conversation and verify exactly one published staff reply.
5. Run a connector-approved read-only business request. If writes are required, validate each owning workflow with approved test effects and independent native readbacks.
6. Check denial from an unregistered website and an unauthorized staff user without changing customer records.

The gateway uses a protected browser capability; server-to-server ChatClient calls use /web-modules/Buffaly.Chat/integrations/v3/. The browser-facing API and shared integration API are separate boundaries. Do not expose the internal staff/connector credential as a public API key.

Keep the installation reproducible

• Record committed package/core versions, installed and active receipts, route/binding revision and authorized deployment target.
• Back up canonical Buffaly sessions/messages, chat control state, immutable registry revisions and the Data Protection key ring as a coherent restore set.
• Monitor public open/send errors, worker completion and review-required operations with nonsecret correlation identifiers.
• Test intended continuity after gateway/worker restart and history compaction; these are not established by the reference’s basic handoff test.
• Preserve configuration ownership: manager revisions change permitted application settings; operator package/profile/credential changes have their own activation path.

Enter the connection once

Build matching configuration files.

This worksheet prepares the five files for the shared Chat + PublicChat + Feeding Frenzy integration below. It keeps application keys, origins, user IDs and credential references consistent across servers. Use it for a new application, not to overwrite an existing registry.

This prepares configuration; it does not install or provision services. Use your real deployment values and the identities from the supplied connector release. Never enter credentials here. The generated runtime file deliberately has empty secret values and cannot activate until your operator fills them on the protected server.