DmMessage

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/postproxy-dev/json-schema/postproxy-dev-dm-message-schema.json",
  "title": "DmMessage",
  "description": "A direct message (inbound or outbound) in a chat.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/postproxy-dev-openapi.json#/components/schemas/DmMessage",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Message hashid"
    },
    "chat_id": {
      "type": "string",
      "description": "Chat hashid"
    },
    "external_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Platform-native message ID (null while pending)"
    },
    "direction": {
      "type": "string",
      "enum": [
        "inbound",
        "outbound"
      ]
    },
    "body": {
      "type": [
        "string",
        "null"
      ],
      "description": "Message text"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "published",
        "failed_waiting_for_retry",
        "failed",
        "received"
      ],
      "description": "pending/published/failed_waiting_for_retry/failed for outbound, received for inbound"
    },
    "external_comment_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Set when the message was sent as a private reply to a comment"
    },
    "error_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Last error from the platform (when failed)"
    },
    "error_details": {
      "$ref": "#/$defs/PlatformErrorDetails"
    },
    "platform_data": {
      "type": [
        "object",
        "null"
      ],
      "description": "Raw platform webhook payload, passed through unchanged. Shape is platform- and event-specific and may change without notice — prefer the typed fields where available.",
      "additionalProperties": true
    },
    "story_reply": {
      "type": [
        "object",
        "null"
      ],
      "description": "Instagram only. Set on inbound messages that reply to one of your stories. The url is a short-lived Meta link tied to the story's lifetime (typically 24h or less) — not mirrored to Postproxy storage.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Story asset id"
        },
        "url": {
          "type": "string",
          "description": "Meta lookaside CDN URL"
        }
      }
    },
    "external_posted_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 8601 timestamp from the platform"
    },
    "external_delivered_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the platform confirmed delivery (outbound; FB & IG only)"
    },
    "external_read_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the recipient read the message (outbound; FB & IG only)"
    },
    "external_edited_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 8601 timestamp of the most recent edit; body reflects the latest edit"
    },
    "reply_to_external_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Platform message ID this message replies to (inbound replies, outbound reply_to_external_id, or a Telegram callback query's source)"
    },
    "reply_markup": {
      "type": [
        "object",
        "null"
      ],
      "description": "Telegram only — the reply_markup attached to the message",
      "additionalProperties": true
    },
    "quick_replies": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/DmQuickReply"
      },
      "description": "Facebook and Instagram only — the chips sent with the message"
    },
    "buttons": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/DmButton"
      },
      "description": "Facebook and Instagram only — the buttons attached to the message"
    },
    "card": {
      "type": [
        "object",
        "null"
      ],
      "description": "Facebook and Instagram only — the card fields (subtitle, image_url, default_action) sent alongside buttons",
      "additionalProperties": true
    },
    "elements": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/DmCarouselElement"
      },
      "description": "Facebook and Instagram only - the normalized carousel cards sent with elements"
    },
    "tapped_action": {
      "$ref": "#/$defs/DmTappedAction"
    },
    "external_deleted_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the message was deleted/unsent on the platform (treat as redacted)"
    },
    "reactions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DmReaction"
      },
      "description": "Reactions on the message. Reflects the live state."
    },
    "attachments": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DmMessageAttachment"
      },
      "description": "Media attached to the message"
    },
    "is_unsupported": {
      "type": "boolean",
      "description": "true when the platform marked the message as unsupported (e.g. an unprocessable voice clip)"
    },
    "created_at": {
      "type": "string",
      "description": "ISO 8601 timestamp of record creation"
    },
    "template": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "description": "WhatsApp only. The template a message was sent with — id, external_id, name, language, variables."
    },
    "interactive": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "description": "WhatsApp only. Outbound: the interactive object sent. Inbound: the customer’s reply to one — type \"button_reply\" / \"list_reply\" / \"nfm_reply\" with the id and title you assigned."
    },
    "location": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "description": "WhatsApp only. latitude, longitude, name, address — sent or received."
    },
    "source": {
      "type": [
        "string",
        "null"
      ],
      "description": "\"synced\" on an outbound WhatsApp message the team sent from the phone on a coexistence number."
    }
  },
  "$defs": {
    "DmButton": {
      "type": "object",
      "description": "A button attached to the message itself (Facebook and Instagram only). Buttons stay in the thread.",
      "required": [
        "type",
        "title"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "web_url",
            "postback"
          ]
        },
        "title": {
          "type": "string",
          "maxLength": 20,
          "description": "Required, 20 characters or fewer"
        },
        "payload": {
          "type": "string",
          "maxLength": 1000,
          "description": "Required for postback buttons, 1000 characters or fewer"
        },
        "url": {
          "type": "string",
          "description": "Required for web_url buttons, must be an https:// URL"
        }
      }
    },
    "DmCarouselElement": {
      "type": "object",
      "description": "One card of a carousel sent with elements. Needs a title plus at least one of subtitle, image_url, default_action or buttons. Meta has no price field, so prices go in subtitle.",
      "required": [
        "title"
      ],
      "properties": {
        "title": {
          "type": "string",
          "maxLength": 220
        },
        "subtitle": {
          "type": "string",
          "maxLength": 220
        },
        "image_url": {
          "type": "string",
          "description": "Must be an https:// URL"
        },
        "default_action": {
          "type": "object",
          "description": "Action when the card itself is tapped",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "web_url"
              ]
            },
            "url": {
              "type": "string",
              "description": "Must be an https:// URL"
            }
          }
        },
        "buttons": {
          "type": "array",
          "maxItems": 3,
          "items": {
            "$ref": "#/$defs/DmButton"
          },
          "description": "Up to 3 buttons, same shape as DmButton"
        }
      }
    },
    "DmMessageAttachment": {
      "type": "object",
      "description": "Media attached to a message. Inbound media is mirrored from the platform CDN to durable storage; outbound files are uploaded before the send. The url is stable and does not expire.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Attachment hashid"
        },
        "type": {
          "type": "string",
          "enum": [
            "image",
            "video",
            "audio",
            "sticker",
            "file",
            "story_mention"
          ]
        },
        "url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Stable storage URL. While status is pending this may temporarily fall back to the source URL."
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "processed",
            "failed"
          ]
        },
        "external_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Platform-side identifier (e.g. a Messenger sticker ID), when provided"
        }
      }
    },
    "DmQuickReply": {
      "type": "object",
      "description": "A tappable chip shown above the participant's composer (Facebook and Instagram only). Chips disappear once one is tapped.",
      "required": [
        "title",
        "payload"
      ],
      "properties": {
        "title": {
          "type": "string",
          "maxLength": 20,
          "description": "Required, 20 characters or fewer"
        },
        "payload": {
          "type": "string",
          "maxLength": 1000,
          "description": "Required, 1000 characters or fewer"
        },
        "content_type": {
          "type": "string",
          "enum": [
            "text"
          ],
          "description": "Optional; only \"text\" is accepted — Messenger's user_phone_number / user_email chips are not supported"
        }
      }
    },
    "DmReaction": {
      "type": "object",
      "description": "A reaction on a message. Reflects the live state.",
      "properties": {
        "sender_external_id": {
          "type": "string"
        },
        "emoji": {
          "type": "string"
        },
        "reaction": {
          "type": "string"
        },
        "at": {
          "type": "string"
        }
      }
    },
    "DmTappedAction": {
      "type": [
        "object",
        "null"
      ],
      "description": "Set on inbound messages created by a tap of a quick reply, button postback, ice breaker, or Telegram inline-keyboard button. A tap also opens the 24-hour messaging window.",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "quick_reply",
            "postback",
            "callback_query"
          ],
          "description": "quick_reply, postback (Meta buttons and ice breakers), or callback_query (Telegram inline keyboards)"
        },
        "payload": {
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      }
    },
    "PlatformErrorDetails": {
      "type": [
        "object",
        "null"
      ],
      "description": "Structured platform error (omitted when no platform error info is available).",
      "properties": {
        "platform_error_code": {
          "type": [
            "string",
            "null"
          ],
          "description": "Error code returned by the platform API"
        },
        "platform_error_subcode": {
          "type": [
            "string",
            "null"
          ],
          "description": "Error subcode returned by the platform API"
        },
        "platform_error_message": {
          "type": [
            "string",
            "null"
          ],
          "description": "Error message returned by the platform API"
        },
        "postproxy_note": {
          "type": [
            "string",
            "null"
          ],
          "description": "Additional context from Postproxy about the error"
        }
      }
    }
  }
}