DmChat

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/postproxy-dev/json-schema/postproxy-dev-dm-chat-schema.json",
  "title": "DmChat",
  "description": "A 1:1 conversation between a profile and a participant.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/postproxy-dev-openapi.json#/components/schemas/DmChat",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Chat hashid"
    },
    "profile_id": {
      "type": "string",
      "description": "Profile hashid this chat belongs to"
    },
    "platform": {
      "type": "string",
      "enum": [
        "facebook",
        "instagram",
        "telegram",
        "bluesky"
      ],
      "description": "Network ID"
    },
    "participant_external_id": {
      "type": "string",
      "description": "Platform-native participant ID"
    },
    "participant_username": {
      "type": [
        "string",
        "null"
      ],
      "description": "Participant's username (when known)"
    },
    "participant_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Participant's display name (when known)"
    },
    "participant_avatar_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Stable storage URL of the participant's profile picture (null until fetched)"
    },
    "external_conversation_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Platform's native conversation ID (when known)"
    },
    "last_inbound_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 8601 timestamp of last inbound message"
    },
    "last_outbound_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 8601 timestamp of last outbound message"
    },
    "last_message_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO 8601 timestamp of last message in either direction"
    },
    "archived": {
      "type": "boolean",
      "description": "Bluesky only — whether the chat is muted/archived"
    },
    "metadata": {
      "$ref": "#/$defs/DmChatMetadata"
    },
    "created_at": {
      "type": "string",
      "description": "ISO 8601 timestamp of chat creation"
    },
    "external_placement_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The placement the chat runs on — the phone number id on WhatsApp, the Page id on Facebook chats that have one. Null otherwise."
    },
    "group": {
      "type": "boolean",
      "description": "True when the chat is a WhatsApp group rather than a 1:1 conversation."
    },
    "within_messaging_window": {
      "type": "boolean",
      "description": "WhatsApp only. Whether a free-form send is currently allowed — true for 24 hours after the customer’s last inbound message or referral. Outside it, send an approved template."
    }
  },
  "$defs": {
    "DmChatMetadata": {
      "type": [
        "object",
        "null"
      ],
      "description": "Platform-specific information about the participant, fetched asynchronously when the chat is first created and refreshed at most once per hour on inbound messages. Keys are only present when the platform returns a value — treat missing keys as unknown, not false.",
      "properties": {
        "page_id": {
          "type": "string",
          "description": "Facebook — Page ID this chat is owned by (required for sending)"
        },
        "participant_fetched_at": {
          "type": "string",
          "description": "ISO 8601 timestamp of the last recipient-info refresh"
        },
        "language_code": {
          "type": "string",
          "description": "Telegram — IETF language tag reported by Telegram for the user"
        },
        "muted": {
          "type": "boolean",
          "description": "Bluesky — whether the conversation is muted/archived"
        },
        "is_verified_user": {
          "type": "boolean",
          "description": "Instagram — participant has a verified account"
        },
        "is_user_follow_business": {
          "type": "boolean",
          "description": "Instagram — participant follows the business profile"
        },
        "is_business_follow_user": {
          "type": "boolean",
          "description": "Instagram — the business profile follows the participant"
        },
        "follower_count": {
          "type": "integer",
          "description": "Instagram — participant's follower count"
        },
        "referral": {
          "type": "object",
          "description": "Latest ig.me / m.me link referral (latest referral wins)",
          "properties": {
            "ref": {
              "type": "string"
            },
            "source": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "received_at": {
              "type": "string"
            }
          }
        },
        "last_referral_at": {
          "type": "string",
          "description": "ISO 8601 timestamp of the latest referral (opens the 24-hour messaging window)"
        },
        "thread_control": {
          "type": "object",
          "description": "Facebook & Instagram — which Meta app controls the conversation, once known. See Thread control.",
          "properties": {
            "owner_app_id": {
              "type": [
                "string",
                "null"
              ],
              "description": "Meta app ID that controls the conversation; null while idle (or when another app took it without Postproxy seeing it)."
            },
            "expires_at": {
              "type": [
                "string",
                "null"
              ],
              "description": "ISO 8601 time the owner's control lapses."
            },
            "updated_at": {
              "type": "string",
              "description": "ISO 8601 time the value was last recorded."
            }
          }
        }
      },
      "additionalProperties": true
    }
  }
}