Skip to main content
Glama

Postkey: Instagram DM Automation and Comment-to-DM

Create a DM automation from a template

postkey_create_automation

Postkey: Builds a new DRAFT Instagram DM automation from a template and returns its automation_id, for example comment-to-DM: send a link by DM when someone comments a keyword. It is made the same way as on Postkey's New automation screen. Use it for a new automation; to change one that exists use postkey_update_automation. It is not switched on: nobody gets a message until postkey_publish_automation (preview that first). Pass keyword and link_url when the template's needs_keyword or needs_link is true. The answer says back runs_on and followers_only (follow_note when follow-gated). Flow Builder templates come with SAMPLE words, listed in messages: rewrite them with postkey_update_automation messages before the preview. Refused before anything is made: no Instagram connected for DMs (needs_a_person: give the person the link in the message), an X account or one not connected for DMs (invalid_arguments), and a follow-gated automation on a Facebook Page (not_on_this_network). template_key x_comment_reply drafts replies to comments on X: pass keyword, link_url, one X account in social_account_ids, optionally replies and post_id. The answer has replies_preview, daily_ceiling, and needs_consent with consent_url if a person must first agree to replies on that account (only they can).

Input Schema

NameRequiredDescriptionDefault
dmsNox_comment_reply only: DM each commenter instead of replying. 3-10 clearly different wordings; every {a|b} version needs a STOP line ("Reply STOP and I won't message you again."), max 50 versions. {{link}}, {{name}} work. Needs post_id of a post saying "Comment WORD and I'll DM you", and DMs turned on for that X account by the person in Postkey. replies become the fallback for closed DMs.
nameNoA name for it, at most 120 characters. Left out: the template's own name.
keywordNoThe word people comment or send to start it, for example "GUIDE". At most 60 characters.
post_idNotemplate x_comment_reply only: one post, as a post_id from postkey_list_posts or the link of a post on X. Left out: any post with this keyword.
repliesNotemplate x_comment_reply only: the fixed replies, up to 10, in the order they rotate. Each carries the link: put {{link}} where it goes, or it is added at the end. No other variable works, and nothing is written per comment. Left out on create: the account's saved voice, or Postkey's suggestions.
link_urlNoThe link it hands out, https://...
template_keyYesThe template's key from postkey_list_automation_templates, for example comment_to_link. An unknown or unavailable key is refused.
followers_onlyNoWhether only followers get the link. People who have not messaged the account before first get a short "follow, then tap" message; followers then get the link, anyone else is asked to follow and tap again. false sends it to everyone. Left out: the account's default for new automations (on unless the account switched it off). Instagram only: true is refused for a Facebook Page (not_on_this_network).
social_account_idsNoThe accounts it runs on, by id from postkey_list_social_accounts (accounts used for DMs: dms in used_for in postkey_get_started), up to 10. Left out: the profile's first active account connected for DMs, which may be a Facebook Page (a follow-gated template there is refused, code refused): pass an Instagram id to be sure. An X account, or one not used for DMs, is refused invalid_arguments.

Output Schema

NameRequiredDescriptionDefault
okYesfalse: refused (isError; code, message, guide_topic, url); no change.
urlNoWhere a person opens it in Postkey.
noteNoThe next steps.
limitNoThe plan's limit on automations switched on at once; null: none or not known.
statusNodraft.
runs_onNoThe accounts it runs on: platform, handle.
live_nowNoAutomations switched on now.
messagesNoA Flow Builder template: its sample messages (step, kind, says, buttons, cards). Rewrite them with postkey_update_automation messages.
connect_urlNoWhen no social account is connected: where the person connects one.
follow_noteNoWhen follow-gated: where it runs, and that a Facebook Page cannot check follows.
switched_onNoAlways false.
connect_noteNoWhen no social account is connected: why it cannot go live yet.
automation_idNoThe new automation's id.
followers_onlyNotrue: only followers get the link.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / ok / description
      Previous value: -"false: refused (isError true; code, message, guide_topic, url), nothing changed."New value: +"false: refused (isError; code, message, guide_topic, url); no change."
  2. Changed1 schema field changed
    • changedOutput schema / properties / messages / description
      Previous value: -"A Flow Builder template: its sample messages (step, kind, says, buttons). Rewrite them with postkey_update_automation messages."New value: +"A Flow Builder template: its sample messages (step, kind, says, buttons, cards). Rewrite them with postkey_update_automation messages."
  3. Changed1 schema field changed
    • addedOutput schema / properties / messages
      Added value: +{
      +  "description": "A Flow Builder template: its sample messages (step, kind, says, buttons). Rewrite them with postkey_update_automation messages.",
      +  "items": {
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  4. Changed1 schema field changed
    • addedInput schema / properties / dms
      Added value: +{
      +  "description": "x_comment_reply only: DM each commenter instead of replying. 3-10 clearly different wordings; every {a|b} version needs a STOP line (\"Reply STOP and I won't message you again.\"), max 50 versions. {{link}}, {{name}} work. Needs post_id of a post saying \"Comment WORD and I'll DM you\", and DMs turned on for that X account by the person in Postkey. replies become the fallback for closed DMs.",
      +  "items": {
      +    "maxLength": 1000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "type": "array"
      +}
  5. Changed2 schema fields changed
    • addedInput schema / properties / post_id
      Added value: +{
      +  "description": "template x_comment_reply only: one post, as a post_id from postkey_list_posts or the link of a post on X. Left out: any post with this keyword.",
      +  "maxLength": 300,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / replies
      Added value: +{
      +  "description": "template x_comment_reply only: the fixed replies, up to 10, in the order they rotate. Each carries the link: put {{link}} where it goes, or it is added at the end. No other variable works, and nothing is written per comment. Left out on create: the account's saved voice, or Postkey's suggestions.",
      +  "items": {
      +    "maxLength": 1000,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "type": "array"
      +}
  6. Changed2 schema fields changed
    • addedOutput schema / properties / connect_note
      Added value: +{
      +  "description": "When no social account is connected: why it cannot go live yet.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / connect_url
      Added value: +{
      +  "description": "When no social account is connected: where the person connects one.",
      +  "type": "string"
      +}
  7. Changed7 schema fields changed
    • changedInput schema / properties / followers_only / description
      Previous value: -"Whether only followers get the link. People who have not messaged the account before first get a short \"follow, then tap\" message; followers then get the link, anyone else is asked to follow and tap again. false sends it to everyone. Left out: the account's default for new automations (on unless the account switched it off). Instagram only: true is refused for a Facebook Page."New value: +"Whether only followers get the link. People who have not messaged the account before first get a short \"follow, then tap\" message; followers then get the link, anyone else is asked to follow and tap again. false sends it to everyone. Left out: the account's default for new automations (on unless the account switched it off). Instagram only: true is refused for a Facebook Page (not_on_this_network)."
    • changedInput schema / properties / keyword / description
      Previous value: -"The word that starts it, when the template needs one."New value: +"The word people comment or send to start it, for example \"GUIDE\". At most 60 characters."
    • changedInput schema / properties / link_url / description
      Previous value: -"The link it hands out (https://...), when the template needs one."New value: +"The link it hands out, https://..."
    • changedInput schema / properties / name / description
      Previous value: -"A name for it. Left out: the template's own name."New value: +"A name for it, at most 120 characters. Left out: the template's own name."
    • changedInput schema / properties / social_account_ids / description
      Previous value: -"The accounts it runs on, by id from postkey_list_social_accounts (accounts used for DMs). Left out: the profile's first active account connected for DMs."New value: +"The accounts it runs on, by id from postkey_list_social_accounts (accounts used for DMs: dms in used_for in postkey_get_started), up to 10. Left out: the profile's first active account connected for DMs, which may be a Facebook Page (a follow-gated template there is refused, code refused): pass an Instagram id to be sure. An X account, or one not used for DMs, is refused invalid_arguments."
    • changedInput schema / properties / template_key / description
      Previous value: -"The template's key from postkey_list_automation_templates."New value: +"The template's key from postkey_list_automation_templates, for example comment_to_link. An unknown or unavailable key is refused."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "automation_id": {
      +      "description": "The new automation's id.",
      +      "type": "string"
      +    },
      +    "follow_note": {
      +      "description": "When follow-gated: where it runs, and that a Facebook Page cannot check follows.",
      +      "type": "string"
      +    },
      +    "followers_only": {
      +      "description": "true: only followers get the link.",
      +      "type": "boolean"
      +    },
      +    "limit": {
      +      "description": "The plan's limit on automations switched on at once; null: none or not known.",
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "live_now": {
      +      "description": "Automations switched on now.",
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "note": {
      +      "description": "The next steps.",
      +      "type": "string"
      +    },
      +    "ok": {
      +      "description": "false: refused (isError true; code, message, guide_topic, url), nothing changed.",
      +      "type": "boolean"
      +    },
      +    "runs_on": {
      +      "description": "The accounts it runs on: platform, handle.",
      +      "items": {
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "status": {
      +      "description": "draft.",
      +      "type": "string"
      +    },
      +    "switched_on": {
      +      "description": "Always false.",
      +      "type": "boolean"
      +    },
      +    "url": {
      +      "description": "Where a person opens it in Postkey.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "ok"
      +  ],
      +  "type": "object"
      +}
  8. Changed1 schema field changed
    • addedInput schema / properties / social_account_ids
      Added value: +{
      +  "description": "The accounts it runs on, by id from postkey_list_social_accounts (accounts used for DMs). Left out: the profile's first active account connected for DMs.",
      +  "items": {
      +    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "type": "array"
      +}
  9. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only say this is a non-read-only, non-destructive call; the description goes well beyond by disclosing that the result is a DRAFT that messages nobody until publish, the exact refusal codes and preconditions (needs_a_person when no Instagram is connected for DMs, invalid_arguments for an X account not connected, not_on_this_network for follow-gated automations on a Facebook Page), and template-specific side effects such as sample words needing rewrite and needs_consent/consent_url.

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

Conciseness3/5

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

Purpose, alternatives, and draft-state warning are front-loaded, which is good, but the single block runs long and packs refusal codes, follow-gating behavior, sample-word caveats, and an x_comment_reply sub-spec into an undifferentiated wall. Some clauses restate the schema (parameter names and counts), which costs scanability for a caller that already has the schema.

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 9-parameter creation tool with refusal paths and template variants, the description covers preconditions, draft state, the publish next step, template-conditional parameters, and per-template response fields (runs_on, followers_only, follow_note, replies_preview, daily_ceiling, needs_consent). An output schema exists, so the return-value detail is supplementary rather than required, but nothing an agent needs to call this correctly is missing.

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%, so the baseline would be 3, but the description adds conditional logic the schema cannot express: 'Pass keyword and link_url when the template's needs_keyword or needs_link is true', and the x_comment_reply-only bundle (keyword, link_url, one X account, optionally replies and post_id). It stops short of 5 because that packet largely restates per-parameter conditions already spelled out in the schema descriptions.

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 and resource: 'Builds a new DRAFT Instagram DM automation from a template and returns its automation_id', then illustrates with a concrete comment-to-DM example. It explicitly distinguishes itself from postkey_update_automation (change existing) and postkey_publish_automation (switch on), so an agent can place it among siblings without opening a schema.

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?

Gives explicit when-to-use ('Use it for a new automation'), names the alternative for the other case ('to change one that exists use postkey_update_automation'), and states the follow-on step ('not switched on ... until postkey_publish_automation (preview that first)'). It also names the prerequisite tool for the template key (postkey_list_automation_templates) and the account source (postkey_list_social_accounts).

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources