AI Maintenance Chat Agent

The AI maintenance chat agent lets owners and occupants submit maintenance requests through a guided, conversational interface — no portal login required. It is powered by OpenAI gpt-4o-mini and runs as a stateless public endpoint.

How It Works

The agent conducts a structured conversation in six stages:

Stage	What Happens
1. Greeting	Agent introduces itself and asks for the caller's name and email
2. Verification	System matches name + email against the owners table
3. Unit selection	Auto-selects if the owner has one unit; asks to choose if they have multiple
4. Issue capture	Agent asks what the problem is, its location, and urgency
5. Confirmation	Agent summarises the issue and asks for confirmation
6. Submission	Maintenance request is created with a works order reference

For genuine emergencies, the agent instructs the caller to dial 999 / 112 before capturing any further details.

---

Public Chat Page

Agencies can link owners directly to the standalone chat page:

https://<your-domain>/maintenance-chat?org=<orgId>

The page displays the organisation name, the inline chat widget, and emergency contact information. No authentication is required to access the page — identity is verified through the conversation itself.

---

Embedding the Chat Widget

The MaintenanceChatWidget React component supports two display modes:

Bubble mode

A floating chat bubble anchored to the bottom-right corner of the page. Suitable for embedding on an agency website alongside other content.

<MaintenanceChatWidget orgId="<orgId>" mode="bubble" />

Inline mode

A full-width chat panel rendered in place. Suitable for dedicated maintenance-request pages.

<MaintenanceChatWidget orgId="<orgId>" mode="inline" />

Widget features:

• Real-time conversation UI with a typing indicator
• Owner verification badge displayed once identity is confirmed
• Markdown rendering for agent responses
• Session state maintained client-side (no server-side session storage)

---

API Reference

POST /api/portal/maintenance-chat

Public endpoint. No session cookie required.

Start a new session

Send orgId with no message and no session to receive the initial greeting and a session object.

Request

{
  "orgId": "<orgId>"
}

Response

{
  "message": "Hi! I'm the maintenance assistant for Acme Property Management...",
  "session": { "orgId": "<orgId>", "messages": [...], ... },
  "done": false
}

Continue a conversation

Request

{
  "orgId": "<orgId>",
  "message": "The hallway light on the second floor is flickering.",
  "session": { ... }
}

Response

{
  "message": "Thanks — is this urgent, or can it wait for a scheduled visit?",
  "session": { ... },
  "done": false
}

When the request is successfully created, the response includes done: true and the works order reference:

{
  "message": "Your request has been logged. Reference: WO-2026-0042.",
  "session": { ... },
  "done": true,
  "worksOrderRef": "WO-2026-0042"
}

Error responses

Status	Condition
400	Missing orgId, or message is empty
400	Session orgId does not match request orgId
404	Organisation not found
500	Unexpected server error

---

POST /api/portal/maintenance

Token-authenticated public endpoint for the owner portal maintenance form.

Request

{
  "token": "<portal-access-token>",
  "unitId": "<unitId>",
  "title": "Broken window latch in bedroom",
  "description": "The latch on the main bedroom window does not close properly.",
  "category": "general_repair",
  "locationDescription": "Main bedroom, first floor",
  "isUrgent": false
}

Required fields: token, unitId, title

Valid categories: general_repair, electrical, plumbing, structural, fire_safety, lift, grounds, cleaning, pest_control, security, access_control, intercom, roof, drainage, heating, other

Response (success)

{
  "success": true,
  "id": "<requestId>",
  "worksOrderRef": "WO-2026-0001"
}

Error responses

Status	Condition
400	Missing token, unitId, or title
403	Invalid or expired portal token
403	Owner does not have an active ownership of the specified unit
404	Unit not found
500	Unexpected server error

---

Security

• Owner identity is verified by matching the name and email provided during the conversation against the owners table — no credentials are stored in the chat session.
• No sensitive data (PPS numbers, bank details) is requested at any point.
• Session state is stateless: the client sends the full conversation context with each request; the server does not store sessions.
• All chat-submitted maintenance requests create an audit log entry tagged with source ai_chat_agent.
• Rate limiting is provided by OpenAI's API-level rate limits.

---

Environment Variables

Variable	Required	Description
OPENAI_API_KEY	Yes	OpenAI API key used for gpt-4o-mini chat completions. If not set, users see a fallback message prompting them to use the standard form.

---

Works Order Reference Format

Every submitted request receives a reference in the format:

WO-<year>-<4-digit-sequence>

Example: WO-2026-0042

The sequence is calculated from the total count of existing maintenance requests for the organisation, incremented by one.