Skip to navigation
API ReferenceMessaging

Update Message Needs Help

Available by Request

Flag or resolve a message’s needs help state. Leslie raises the flag when unable to answer a resident’s question; a Fortress staff member can raise or resolve one too. While any message on the conversation has an open flag, the conversation’s conversationStatus reads NEEDS_HELP regardless of where the underlying workflow stands. Resolving the last open flag returns the conversation to whatever status that workflow currently calls for.

A single PATCH handles both directions: isFlagged: true raises the flag, isFlagged: false resolves it. The response echoes the message plus a rollup of the conversation’s needs-help state, so you don’t need a follow-up GET /conversations to learn whether the thread is still flagged.

The request is idempotent. Flagging an already-flagged message, or resolving one that isn’t flagged, returns 200 with the current state rather than an error — Leslie retrying a request must not have to distinguish a repeat from the original.

This endpoint is part of our evolving API ecosystem. To explore availability for your integration, please contact our team.

Authentication

x-api-keystring
API Key authentication via header

Path parameters

messageIdstringRequired
The id of the message

Request

This endpoint expects an object.
isFlaggedbooleanRequired
True to flag the message as needing help, false to resolve an existing flag.
reasonstringOptional1-500 characters

Free-text reason for the flag. Omit it rather than sending an empty string. Ignored when isFlagged is false.

userIdstringOptionalformat: "uuid"

Attributes the flag or resolution to this Fortress user. Only honoured on requests authenticated with a service x-api-key; a request authenticated with a user token ignores this field and is always attributed to the signed-in user instead.

Response

The updated message, plus a rollup of the conversation’s needs-help state. Returned whether or not this request changed anything.

idstringOptional
Unique identifier for the message.
conversationIdstringOptional
The conversation this message belongs to. Messages to the same recipient from the same property are grouped into a single conversation.
typeenumOptional

Direction and origin of the message. Messages created through POST /messages are always OUTBOUND.

Allowed values:
contentstringOptional
The body of the message. Limited to 1600 characters on send.
messageStatusstringOptional

Current delivery status. Statuses reported by the downstream carrier or email provider are passed through verbatim, so this is an open set rather than a fixed enum.

Statuses set by Fortress: CREATED, PROCESSING, FAILED, INVALID_PHONE_NUMBER, INVALID_EMAIL, RECEIVED, AUTOMATED, MASS_COMMUNICATION.

Statuses reported by the carrier: QUEUED, SENT, DELIVERED, UNDELIVERED, FAILED.

The terminal statuses for SMS are DELIVERED, UNDELIVERED, and FAILED. For email they are DELIVERED, FAILED, and REJECTED.

messageStatusReasonstring or nullOptional
Explanation for the current status. Populated when a message fails to send.
messageSidstringOptional
Identifier assigned by the downstream SMS carrier. Absent until the message has been accepted for delivery.
customerStatusstringOptional
Status of the recipient at the time the message was created, as recorded in Fortress.
idempotencyIdstringOptional

Caller-supplied key that uniquely identifies the send request. Reusing a key returns the original message rather than sending a duplicate.

isAutomatedbooleanOptional
True when the message was generated by a Fortress automation rather than a person.
needsHelpboolean or nullOptional

True while this message has an open needs-help flag. Absent on messages that have never been flagged.

needsHelpDetailsobject or nullOptional

Who raised the needs-help flag, why, and who resolved it. Absent on messages that have never been flagged. The flag details survive resolution, so this still describes the original request after needsHelp returns to false.

subjectstringOptional
Subject line. Email messages only.
emailAddressstringOptional
Recipient email address. Email messages only.
attachmentslist of objectsOptional
Media attached to the message.
metadatamap from strings to anyOptional

Caller-supplied metadata, plus sentAt and sentBy recorded by Fortress at send time.

organizationIdstringOptionalformat: "uuid"
customerIdstringOptionalformat: "uuid"
Set when the recipient is a customer.
prospectIdstringOptionalformat: "uuid"
Set when the recipient is a prospect.
userIdstringOptionalformat: "uuid"
The Fortress user the message was sent on behalf of.
createdAtdatetimeOptional
updatedAtdatetimeOptional
conversationobjectOptional

A rollup of the parent conversation, for confirming its status without a follow-up read.

Errors

400
Bad Request Error
404
Not Found Error