DmMessageSendRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/postproxy-dev/json-schema/postproxy-dev-dm-message-send-request-schema.json",
  "title": "DmMessageSendRequest",
  "description": "Payload for sending an outbound message. Each send accepts either text (body) or a single attachment (media), never both. On WhatsApp exactly one payload per send: one of body, media, template, interactive, location or contacts. Carousels are sent with elements instead of body/buttons/card.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/postproxy-dev-openapi.json#/components/schemas/DmMessageSendRequest",
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "description": "Message text. Required when media and elements are empty; not allowed with elements. Capped at 220 characters when buttons are present."
    },
    "media": {
      "type": "array",
      "maxItems": 1,
      "description": "A single media attachment. Accepts the same shapes as the Posts API — a multipart upload, a public URL, a base64 data URI, or a base64 hash. Currently one attachment per send (Meta Send API limit); passing more returns 422. Not supported on Bluesky (422).",
      "items": {
        "description": "A media attachment in any of the shapes accepted by the Posts API (public URL, base64 data URI, base64 hash, or multipart upload reference)."
      }
    },
    "tag": {
      "type": "string",
      "enum": [
        "HUMAN_AGENT"
      ],
      "description": "Message tag for sending outside the 24-hour window. Facebook and Instagram only — ignored on Telegram. Extends the reply window to 7 days from the participant's last inbound message; for a human resolving the participant's own inquiry only, never promotional content. Rejected on WhatsApp, which has no HUMAN_AGENT tag — use a template or category \"utility\" instead."
    },
    "reply_to_external_id": {
      "type": "string",
      "description": "Telegram, WhatsApp and Instagram. Platform message ID (the message's external_id) to reply to — Telegram message_id, WhatsApp wamid, Instagram mid. On WhatsApp and Instagram the send quotes that message. On Instagram the target can be inbound or outbound; if Instagram rejects it (deleted, too old, or not in this chat) the send fails with message.failed instead of going out without the quote. Rejected with 422 on Facebook and Bluesky."
    },
    "reply_markup": {
      "type": "object",
      "description": "Telegram only. Inline keyboard (inline_keyboard), custom reply keyboard (keyboard, with one_time_keyboard / resize_keyboard), force_reply, or remove-keyboard payload — passed through to Telegram unchanged.",
      "additionalProperties": true
    },
    "quick_replies": {
      "type": "array",
      "maxItems": 13,
      "items": {
        "$ref": "#/$defs/DmQuickReply"
      },
      "description": "Facebook and Instagram only. Up to 13 tappable chips shown above the participant's composer. On Instagram, delivered only on a plain-text message (not combinable with media or buttons)."
    },
    "buttons": {
      "type": "array",
      "maxItems": 3,
      "items": {
        "$ref": "#/$defs/DmButton"
      },
      "description": "Facebook and Instagram only. Up to 3 buttons attached to the message. Requires body (capped at 220 characters); cannot be combined with media."
    },
    "card": {
      "$ref": "#/$defs/DmCard"
    },
    "elements": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10,
      "items": {
        "$ref": "#/$defs/DmCarouselElement"
      },
      "description": "Facebook and Instagram only. 1-10 cards delivered as a swipeable carousel (Meta's generic template with several elements). Stands in for body, buttons and card: it cannot be combined with any of them or with media. On Instagram it cannot be combined with quick_replies."
    },
    "template": {
      "$ref": "#/$defs/WhatsAppTemplateSend"
    },
    "interactive": {
      "type": "object",
      "additionalProperties": true,
      "description": "WhatsApp only. Meta’s interactive object unchanged — reply buttons (type \"button\"), lists (\"list\"), call-to-action URLs (\"cta_url\"), catalog products (\"product\" / \"product_list\") or Flows (\"flow\"). Session message: needs an open messaging window and cannot be sent to a group."
    },
    "location": {
      "$ref": "#/$defs/WhatsAppLocation"
    },
    "contacts": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "description": "WhatsApp only. Array of Meta contact objects (name, phones, emails, …)."
    },
    "category": {
      "type": "string",
      "enum": [
        "utility"
      ],
      "description": "WhatsApp only. \"utility\" sends a plain text outside the 24-hour window via Meta’s Direct Send, where the account is eligible. Valid only alongside body; with any other payload returns 422."
    },
    "link_preview": {
      "type": "boolean",
      "description": "WhatsApp only. Render a preview for a link in body."
    },
    "voice_note": {
      "type": "boolean",
      "description": "WhatsApp only. Send an audio attachment as a voice note."
    },
    "filename": {
      "type": "string",
      "description": "WhatsApp only. Filename shown for a document attachment."
    }
  },
  "$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"
        }
      }
    },
    "DmCard": {
      "type": "object",
      "description": "Extra fields for the card carrying buttons — renders a richer, product-style card. Requires buttons.",
      "properties": {
        "subtitle": {
          "type": "string",
          "maxLength": 220,
          "description": "Capped at 220 characters"
        },
        "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"
            }
          }
        }
      }
    },
    "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"
        }
      }
    },
    "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"
        }
      }
    },
    "WhatsAppLocation": {
      "type": "object",
      "description": "A WhatsApp location message.",
      "required": [
        "latitude",
        "longitude"
      ],
      "properties": {
        "latitude": {
          "type": "number"
        },
        "longitude": {
          "type": "number"
        },
        "name": {
          "type": "string"
        },
        "address": {
          "type": "string"
        }
      }
    },
    "WhatsAppTemplateSend": {
      "type": "object",
      "description": "WhatsApp only. Sends an approved message template instead of body. Works inside or outside the 24-hour window and re-opens it.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Template hashid or Meta id. Either id or name is required."
        },
        "name": {
          "type": "string",
          "description": "Template name. Add language when the name exists in several languages, otherwise 409."
        },
        "language": {
          "type": "string",
          "description": "Meta language code, e.g. en_US."
        },
        "variables": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Values as strings, in order: header text variables, then body variables, then one value per dynamic URL button. For POSITIONAL templates the count must equal the template’s variable_count."
        },
        "button_params": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "Overrides for buttons needing runtime parameters — each { index, sub_type, parameters } in Meta’s shape. sub_type is url, copy_code, flow, quick_reply or voice_call."
        },
        "header_media": {
          "type": "object",
          "additionalProperties": true,
          "description": "{ \"link\": \"https://…\" } or { \"id\": \"<meta media id>\" } for templates with an IMAGE, VIDEO or DOCUMENT header."
        },
        "header_location": {
          "$ref": "#/$defs/WhatsAppLocation"
        }
      }
    }
  }
}