Skip to main content
Glama

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 and WhatsApp; quick_replies, buttons and card are the Facebook/Instagram interactive primitives and are rejected elsewhere — WhatsApp uses interactive (Meta-shaped) instead.

Input Schema

TableJSON 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 and WhatsApp. Platform message id (Telegram message_id or WhatsApp wamid) of the message to quote / thread under.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare the mutation/safety profile, and the description adds substantial context beyond them: asynchronous queueing with status: pending, the 422 on free-form sends outside the 24h window, tag extending the window to 7 days, and the suspension risk from misuse. This is exactly the operational context an agent needs before calling a destructive send.

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?

Front-loaded with the core action and the exclusivity rule, and every sentence carries real information for a 17-param multi-platform tool. It reads as a dense wall of text in one paragraph, which slightly hurts scannability, but nothing is wasted.

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?

Covers async delivery, platform support boundaries, window/permission rules, and even return-state behavior (status: pending, status: failed with error_details) despite having no output schema. For a tool this complex, the description is complete enough to call 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 coverage is 100% and the schema already labels each param's platform, so baseline is 3. The description adds genuine cross-parameter value the schema lacks: the one-of exclusivity between body/media/template/interactive/location/contacts, the WhatsApp window mechanics, and the note that quick_replies/buttons/card are rejected outside Facebook/Instagram.

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?

States a specific verb+resource ('Send an outbound direct message') with clear scope (outbound, asynchronous). The platform-specific detail makes it unmistakable versus siblings like dm_message_edit or dm_message_react.

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?

Explicit exclusivity rule ('Provide EXACTLY ONE of body, media, or — on WhatsApp — template, interactive, location or contacts') plus when-to-use guidance for templates, tag:HUMAN_AGENT, and category:utility. States when-not (never for promotional/automated content) and names the alternative route for re-opening the window.

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