Skip to main content
Glama
Sign In

Postproxy

by dev.postproxy
OverviewDiscussionsAdmin

dm_message_send

Destructive

Send an outbound direct message. Provide EXACTLY ONE of body (text), media (a single attachment), or — on WhatsApp — template, interactive, location or contacts. The message is queued and delivered asynchronously (returns status: pending). Outside Meta's 24h messaging window, a human agent replying to the participant's own inquiry can pass tag: HUMAN_AGENT (Facebook/Instagram only) — never for promotional or automated content. On WhatsApp the window is re-opened only by sending an approved template (or a text with category: utility); free-form sends outside it return 422. reply_markup is Telegram-only; reply_to_external_id works on Telegram, WhatsApp and Instagram; quick_replies, buttons and card are the Facebook/Instagram interactive primitives and are rejected elsewhere — WhatsApp uses interactive (Meta-shaped) instead.

Input Schema

NameRequiredDescriptionDefault
tagNoMessage tag for sending outside the 24h window — extends it to 7 days from the participant's last inbound message. Facebook and Instagram only; ignored on Telegram and Bluesky. Meta's policy restricts it to a human agent replying to the participant's own inquiry: using it for marketing, offers, or automated re-engagement can get that Page / Instagram account's messaging capability suspended. Past 7 days Meta rejects the send and the message lands in status: failed with the platform error in error_details.
bodyNoMessage text. Required when media is empty (provide body OR media, not both).
cardNoFacebook and Instagram only. Extra generic-template fields for the card that carries buttons — requires buttons. Renders a richer product-style card.
mediaNoUp to one media attachment as a URL or local file path (absolute /path/to/file.jpg, relative ./image.png, or ~/Pictures/photo.jpg). Max 1 attachment. Not supported on Bluesky. WhatsApp limits: image 5MB jpeg/png, video 16MB mp4/3gpp, audio 16MB, document 100MB; on WhatsApp body may accompany media as its caption.
buttonsNoFacebook and Instagram only. Up to 3 buttons attached to the message itself, which stay in the thread. Sent as a Meta generic template whose element title is your body — so body is required and capped at 80 characters, and buttons cannot be combined with media. A postback tap arrives as an inbound message carrying tapped_action.payload.
chat_idYesChat hashid OR external_conversation_id
categoryNoWhatsApp only. Mark a plain text send as a utility Direct Send so it can go outside the 24h window without a template. Text only — cannot be combined with media, template, interactive, location or contacts. Meta reviews and bills these as utility conversations.
contactsNoWhatsApp only. Contact cards in Meta's contacts shape, e.g. [{ name: { formatted_name, first_name }, phones: [{ phone, type }] }].
filenameNoWhatsApp only. Display filename for a document attachment; defaults to the uploaded file's name.
locationNoWhatsApp only. Send a map pin.
templateNoWhatsApp only. Send an APPROVED message template (see whatsapp_templates_list). The only way to message a participant outside the 24h window or to open a brand-new conversation. Cannot be combined with body or media. variables fill the positional placeholders in order: header text vars first, then body vars, then dynamic URL button vars — the count must match the template's variable_count.
voice_noteNoWhatsApp only. Deliver an audio attachment as a voice note (renders with the waveform player). The file must be OGG with the Opus codec.
interactiveNoWhatsApp only. Meta-shaped interactive message object passed through unchanged — reply buttons (type: button, up to 3), list (type: list, up to 10 rows), cta_url, product / product_list, flow, location_request_message. Must carry type. A tap comes back as an inbound message whose body is the tapped title, with the reply id in platform_data.interactive. Session message: only inside the 24h window.
link_previewNoWhatsApp only. Set false to suppress the URL preview on a text message (default true).
reply_markupNoTelegram only. reply_markup payload — inline keyboard, custom reply keyboard, force-reply, or remove-keyboard.
quick_repliesNoFacebook and Instagram only. Up to 13 tappable chips shown above the participant's composer; they disappear once one is tapped. A tap arrives as an inbound message carrying tapped_action.payload. On Instagram, quick replies only work on a plain-text message — not with media and not with buttons (both are accepted on Facebook).
reply_to_external_idNoTelegram, WhatsApp and Instagram. Platform message id — the message's external_id (Telegram message_id, WhatsApp wamid, Instagram mid) — of the message to quote / thread under. On Instagram the target can be inbound or outbound; if Instagram rejects it (deleted, too old, not in this chat) the send fails rather than going out without the quote. Rejected on Facebook.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / reply_to_external_id / description
      Previous value: -"Telegram and WhatsApp. Platform message id (Telegram message_id or WhatsApp wamid) of the message to quote / thread under."New value: +"Telegram, WhatsApp and Instagram. Platform message id — the message's external_id (Telegram message_id, WhatsApp wamid, Instagram mid) — of the message to quote / thread under. On Instagram the target can be inbound or outbound; if Instagram rejects it (deleted, too old, not in this chat) the send fails rather than going out without the quote. Rejected on Facebook."
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare this as non-read-only, destructive, open-world and non-idempotent. The description adds important behavior beyond annotations: asynchronous queuing with status: pending, 24h-window failures, HUMAN_AGENT policy restrictions and suspension risk, and platform-level rejection behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence identifies the core operation immediately, and the paragraph is appropriately dense for a 17-parameter multi-platform send tool. It is somewhat run-on in the platform-primitive sentence and repeats a few schema points, but there is little pure filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex multi-platform send operation with 17 parameters, the description covers async delivery, the WhatsApp 24h window, HUMAN_AGENT restrictions, content exclusivity, platform-specific primitives, and failure behavior. Although there is no output schema, it still mentions returned status values and failure details, so an agent has enough context to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already carries most parameter-level detail. The description still adds useful cross-parameter semantics: the 'exactly one content' rule, platform applicability for tag/reply_markup/reply_to_external_id, and the Facebook/Instagram vs WhatsApp interactive distinction. It slightly oversimplifies WhatsApp caption behavior, but the schema clarifies that edge case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Send an outbound direct message.' It clearly distinguishes this from sibling message tools such as dm_message_edit, dm_message_get and dm_messages_list, and it routes template discovery to whatsapp_templates_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit content-selection rules ('EXACTLY ONE of body, media, or platform-specific template/interactive/location/contacts'), names the approved-template alternative, and states when HUMAN_AGENT is allowed and when free-form WhatsApp sends outside the 24h window return 422. It also spells out platform-specific exclusions for reply_markup, quick_replies, buttons, card and interactive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Postproxy toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources