Update Message Needs Help

{
  "attachments": [
    {
      "key": "key",
      "bucket": "bucket",
      "type": "type",
      "url": "url"
    }
  ],
  "content": "content",
  "conversation": {
    "id": "id",
    "conversationStatus": "NEEDS_HELP",
    "needsHelpMessageIds": [
      "needsHelpMessageIds"
    ]
  },
  "conversationId": "conversationId",
  "createdAt": "2024-01-15T09:30:00Z",
  "customerId": "customerId",
  "customerStatus": "customerStatus",
  "emailAddress": "emailAddress",
  "id": "id",
  "idempotencyId": "idempotencyId",
  "isAutomated": true,
  "messageSid": "messageSid",
  "messageStatus": "messageStatus",
  "messageStatusReason": "messageStatusReason",
  "metadata": {
    "key": "value"
  },
  "needsHelp": true,
  "needsHelpDetails": {
    "reason": "reason",
    "flaggedByType": "agent",
    "flaggedById": "flaggedById",
    "flaggedAt": "2024-01-15T09:30:00Z",
    "resolvedByType": "agent",
    "resolvedById": "resolvedById",
    "resolvedAt": "2024-01-15T09:30:00Z"
  },
  "organizationId": "organizationId",
  "prospectId": "prospectId",
  "subject": "subject",
  "type": "OUTBOUND",
  "updatedAt": "2024-01-15T09:30:00Z",
  "userId": "userId"
}

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.

<Badge>Available by Request</Badge> 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. <Note> This endpoint is part of our evolving API ecosystem. To explore availability for your integration, please contact our team. </Note>

Path parameters

messageIdstringRequired

The id of the message

Request

This endpoint expects an object.

Response

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

attachmentslist of objectsOptional

Media attached to the message.

contentstringOptional

The body of the message. Limited to 1600 characters on send.

conversationobjectOptional

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

conversationIdstringOptional

The conversation this message belongs to. Messages to the same recipient from the same property are grouped into a single conversation.

createdAtdatetimeOptional

customerIdstringOptionalformat: "uuid"

Set when the recipient is a customer.

customerStatusstringOptional

Status of the recipient at the time the message was created, as recorded in Fortress.

emailAddressstringOptional

Recipient email address. Email messages only.

idstringOptional

Unique identifier for the message.

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.

messageSidstringOptional

Identifier assigned by the downstream SMS carrier. Absent until the message has been accepted for delivery.

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.

messageStatusReasonstringOptional

Explanation for the current status. Populated when a message fails to send.

metadatamap from strings to anyOptional

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

needsHelpbooleanOptional

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

needsHelpDetailsobjectOptional

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.

organizationIdstringOptionalformat: "uuid"

prospectIdstringOptionalformat: "uuid"

Set when the recipient is a prospect.

subjectstringOptional

Subject line. Email messages only.

typeenumOptional

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

updatedAtdatetimeOptional

userIdstringOptionalformat: "uuid"

The Fortress user the message was sent on behalf of.

Errors

400

Update Message Needs Help Request Bad Request Error

404

Update Message Needs Help Request Not Found Error

Available by Request

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

$	curl -X PATCH https://api.fortresstech.io/v1/messages/messageId/needsHelp \
>	-H "Content-Type: application/json" \
>	-d '{
>	"isFlagged": true
>	}'