Create a chat with a phone number

Opens a chat with a bare phone number, for someone with no tenant, owner, or vendor record. Nothing is sent to the number.

POST

https://api.portal.magicdoor.com/company-app/chats/phone

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.

Body

application/json

phoneNumberstringrequired

The number to open a chat with. Must be a valid phone number.

example: (208) 555-0117

participantNamestring

A name to show for the person. 1 to 100 characters. Falls back to the number itself.

subjectstring

The chat's title. 1 to 200 characters. Falls back to the name, then to the number.

Response

200 · The chat for that number, or the reason there is none.

chatIdstring

The chat to talk to this recipient in. Absent when failureReason explains why no chat could be made.

failureReasonstring

Why no chat could be made. Absent on success.

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

This call creates or finds a chat. It does not message anyone. Nothing reaches the recipient until you post a message to the returned chatId.

If your company already has a chat with that number, its id is returned and participantName and subject are ignored. The chat's type is unknown and its typeKey is the normalised number.

A number MagicDoor cannot parse produces a 200 with no chatId and a failureReason of "Invalid phone number", not an error status. Check chatId before using it.