Open the chat on a maintenance request

Returns the id of the chat attached to a maintenance request, creating it first if there is none. The chat's participants are the tenants on the request's lease who have not moved out. Calling it twice is safe — the second call returns the same chat. Requires the maintenance_requests:read permission.

POST

https://services.magicdoor.com/maintenance/company-portal/maintenance-requests/{maintenanceRequestId}/chat

Authorization

Authorizationstringrequired

Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Path parameters

maintenanceRequestIdstringrequired

The maintenance request whose chat you want. A Snowflake id, sent as a decimal string.

example: 1841003948572119040

Response

200 · Either a chat id, or a reason why no chat could be opened. Exactly one of the two properties is present — a request whose lease has no tenant still on it gets `failureReason` and no `chatId`, not an error.

chatIdstring

The chat carrying this maintenance request's conversation. Absent when the chat could not be opened.

failureReasonstring

Why no chat could be opened, in plain English. Absent on success. The only reason the service produces today is that the lease has no tenant who is still living there or due to move in.

401 · The request carried no valid access token.

403 · The token is not a property manager token, or it lacks the `maintenance_requests:read` permission.

404 · No such maintenance request, or it belongs to another company.

Reopening a closed chat

The endpoint checks the stored chat before handing it back. If the chat has been closed, or the id now points at a different maintenance request's conversation, a fresh chat is created and the maintenance request is repointed at it. So the id you get back is always a chat you can post to — but it is not guaranteed to be the same id you saw last time.