MagicDoorAPI
SupportOpen MagicDoor
Chats

Send a chat message

Posts a message into a chat as your company, optionally delivering it by SMS and email as well. Every participant in the chat receives it.

POST
https://api.portal.magicdoor.com/company-app/chats/{chatId}/messages

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

chatIdstringrequired

The chat to post into.

example: 1830472847398404096

Body

application/json

Send at least one of message or uploadSessionIds.

messagestring

The message text. Up to 30,000 characters.

example: The plumber is booked for Thursday between 9 and 11.
uploadSessionIdsstring[]

Upload sessions to attach, from the chat attachment upload session endpoint. At most 20.

sendTextboolean

Also send the message as an SMS to every participant with a phone number. Ignored when texting is switched off for the company.

default: false
sendEmailboolean

Also send the message as an email to every participant with an email address.

default: false
aiEnhancedboolean

Record that the text came from the AI suggestion endpoint. It does not rewrite the text.

default: false

Response

200 · The message as it was recorded. The `textStatus` and `emailStatus` fields describe delivery so far.

idstring

The message.

chatIdstring

The chat the message belongs to.

messageTypeenum<string>

Who the message came from. participant is the tenant, owner, or vendor; propertyManager is someone on your team; bot is the MagicDoor AI; announcement is a message posted by an announcement.

participantpropertyManagerbotannouncement
sourceenum<string>

How the message arrived. app is the portal or this API, text is an inbound SMS, email an inbound email, system and notification are generated by MagicDoor.

appemailtextsystemnotification
participantIdstring

The participant who sent it, matching participants[].id on the chat. For a property-manager message this is the property manager's id.

messagestring

The message text as written.

messageLanguagestring

ISO 639-1 code MagicDoor detected for message.

translatedMessagestring

The message translated into the other side's language. Absent when no translation was needed.

translatedMessageLanguagestring

ISO 639-1 code translatedMessage is written in.

translatedFailedboolean

Whether translation was attempted and did not succeed.

aiEnhancedboolean

Whether the text was rewritten by the AI before sending.

sentAtstring · date-time

When the message was recorded.

filesChatMessageFile[]

Files attached to the message.

readboolean

Whether your company has read this message.

readAtstring · date-time

When your company read it. Absent while unread.

sendTextboolean

Whether MagicDoor was asked to deliver this message as an SMS.

textStatusenum<string>

How the SMS went. disabled means texting is switched off for the company, noRecipients that nobody in the chat had a usable phone number.

notSentdisablednoRecipientssentdeliveredfailed
textSentAtstring · date-time

When the SMS was handed to the carrier.

textDeliveredAtstring · date-time

When the carrier confirmed delivery.

textSendStatusesobject

Per-phone-number delivery state, keyed by phone number.

textFailedReasonstring

Why the SMS failed, when it did.

sendEmailboolean

Whether MagicDoor was asked to deliver this message as an email.

emailStatusenum<string>

How the email went, including bounces and complaints reported afterwards.

notSentdisablednoRecipientssentdeliveredbouncecomplaintdeliveryDelayrejectfailed
emailSentAtstring · date-time

When the email was handed to the mail provider.

emailDeliveredAtstring · date-time

When the mail provider confirmed delivery.

aiProcessingStatusenum<string>

Where the message sits in AI handling. manual means the AI handed it to a person and it is waiting to be dealt with.

pendinginProgressmanualprocessed
aiProcessedAtstring · date-time

When AI handling finished.

handledByPropertyManagerIdstring

The property manager who marked the message handled.

handledByPropertyManagerAtstring · date-time

When it was marked handled.

401 · The access token is missing, expired, or not valid.

404 · No chat with that id belongs to your company.

422 · The company has all outbound communications switched off, so no message was recorded and nothing was sent.

This delivers a message to a real person

The message is added to the chat, where its participants see it. If you set sendText it is also sent as an SMS to every participant's phone; if you set sendEmail it is also emailed to them. On a lease or group chat that is every participant, not one person.

This endpoint and the multipart one below share a URL. MagicDoor picks between them on the request's Content-Type: send application/json to reach this one.

Attaching files

Ask for an upload session first, upload the bytes to the endpoint it gives you, then pass the sessionId here in uploadSessionIds.

Archived chats

Posting to an archived chat reopens it and the message goes out as normal.