instagram

Instagram

通过 Instagram API with Instagram Login（Business Login）管理 Instagram 专业账户的完整技能。涵盖内容发布、消息、评论审核、洞察数据和个人资料管理。

不在范围内 — 转交给其他技能

请求	转交给
Instagram / Facebook 付费广告、推广帖子、Advantage+	meta-ads
在 Meta 广告资料库中研究竞争对手广告	meta-ads-library
发布 TikTok 内容	tiktok
LinkedIn 文档或轮播帖子	linkedin

要求

• 已安装并连接 Hyper MCP。 https://app.hyperfx.ai/mcp
• 已连接 Instagram 集成，地址为 https://app.hyperfx.ai/apps — 此技能使用 Instagram API with Instagram Login（不是较旧的、通过 Facebook Login 使用的 Instagram Graph API）。
• 要代表组织向公司主页发布帖子，已连接的账户必须拥有代表该组织发帖的权限。

如果 search("instagram_current_user_get") 未找到 instagram_current_user_get，请停止并告知用户启用 Hyper MCP 并连接 Instagram。

如何运行此技能中的工具

此技能中的每个工具都以其规范工具名称命名。使用你的交互界面提供的调用方式运行：

界面	查找工具	运行工具
MCP 客户端（Claude、Cursor、Codex、ChatGPT）	search("<what you want to do>")，然后 describe("<name>")	call("<name>", {...})
Hyper CLI	hyperai search "<what you want to do>"，然后 hyperai describe <name>	hyperai call <name> --json '{...}'

如果找不到某个工具，则表示相应集成尚未连接，或未在工作区中启用：请停止并告知用户需要连接哪个集成。

工具一览

工具组	工具
账户	instagram_current_user_get、instagram_users_get（可通过用户名或 ID 查找任意公开 IG 个人资料 — 适用于调查评论者和私信联系人）
发布	instagram_photo_containers_create、instagram_reel_containers_create、instagram_carousel_containers_create、instagram_container_status_check、instagram_media_publish、instagram_publishing_limits_check
媒体库	instagram_media_list、instagram_media_get、instagram_album_children_get、instagram_stories_list、instagram_tagged_media_get
评论	instagram_comments_list、instagram_comments_send、instagram_comments_reply、instagram_comments_hide、instagram_comments_delete、instagram_comments_toggle
私信	instagram_conversations_list、instagram_conversation_messages_get、instagram_messages_get、instagram_messages_send、instagram_media_messages_send、instagram_post_messages_send、instagram_messages_react
洞察数据	instagram_account_insights_get、instagram_media_insights_get

关键规则

关键：此工具包使用 Instagram API with Instagram Login（而非较旧的、通过 Facebook Login 使用的 Instagram Graph API）。指标名称和可用字段与旧版 API 不同。请始终使用此技能中记录的指标名称。

关键：此 API 中不存在 engagement 指标。请改用 likes、comments、shares、total_interactions 等单项指标。

关键：impressions 对账户级洞察无效。请改用 reach 或 views。

关键：发布内容采用两步容器工作流：（1）创建媒体容器；（2）发布媒体。对于视频内容，发布前请轮询容器状态，直到状态为 FINISHED。

关键：Instagram 私信回复必须在用户发送最后一条消息后的 24 小时内发出（标准消息时限）。经批准后，Human Agent 标签可将此时限延长至 7 天。

重要：发布速率限制为每个滚动 24 小时窗口内最多发布 100 条 API 发布的帖子。轮播帖子计为 1 条帖子。批量发布前请务必调用 instagram_publishing_limits_check。

关键：除非用户明确提供经过验证的 Facebook Page ID，否则请勿在照片、Reel 或轮播容器上使用 location_id 参数。此集成使用 Instagram Business Login，无法查询或验证地点 ID。传入无效或猜测的 ID 会导致 400 错误（Param location_id is not a valid location page ID）。如果用户要求标记地点，请说明他们需要提供包含地点数据的 Facebook Page ID。

关键：将媒体 URL（image_url、video_url、cover_url、media_url）传递给任何 Instagram 工具时，请使用来源工具返回的 URL，原样传递——最常见的是 read_file 或 display_file 返回的 url 字段。请勿：

• 重构或缩短 URL。
• 删除、更改或编造任何查询参数（签名、时间戳等）。
• 替换为其他主机。
• 从记忆中复制 URL 或逐字符转录——请改为再次调用 read_file。

Hyper 托管的 CDN URL 会在需要时自动调整大小并重新签名，以供 Meta 使用，因此只需原样传递即可。预签名中的任意一个字符损坏，都会导致 Meta 返回误导性的 9004 / 2207052: Only photo or video can be accepted as media type 错误。

重要：大多数工具会自动对已通过身份验证的账户执行操作——无需传入 user_id。工具包会在内部根据访问令牌解析该值。只有在确实需要向用户显示个人资料详情（用户名、粉丝数等）时，才调用 instagram_current_user_get。只有在查询其他账户时，才使用 instagram_users_get(user_id=...)。

阶段 1：账户查询（可选）

获取已连接账户的个人资料

instagram_current_user_get()

返回：user_id、username、name、account_type、profile_picture_url、followers_count、follows_count、media_count、biography、website。

无需在其他工具调用中传递 user_id——工具会自动解析该值。

阶段 2：内容发布

发布工作流

1. 创建媒体容器（照片、Reel、快拍或轮播）。
2. 检查容器状态（视频 / Reel 必须执行此步骤——持续轮询，直到状态为 FINISHED）。
3. 发布容器。
4. 验证：列出最近的媒体。

发布单张照片

instagram_photo_containers_create(
    image_url="https://example.com/photo.jpg",   # Public JPEG URL, max 8MB
    caption="Your caption here #hashtag",
    alt_text="Accessibility description",
)
# Returns container ID

instagram_media_publish(
    creation_id="<container_id>",
)

Reel（短视频）

instagram_reel_containers_create(
    video_url="https://example.com/video.mp4",   # Public MP4/MOV, max 300MB, 3s-15min
    caption="Reel caption #reels",
    cover_url="https://example.com/cover.jpg",   # Optional cover image
    share_to_feed=True,
)

# MUST poll status for video content
instagram_container_status_check(container_id="<container_id>")
# Wait until status_code == "FINISHED", poll once per minute, max 5 minutes

instagram_media_publish(creation_id="<container_id>")

快拍（24 小时后过期）

**注意：**此 MCP 集成目前尚不支持发布快拍。若要查看当前有效的快拍，请使用：

instagram_stories_list()

如果用户要求发布快拍，请告知他们目前尚无法使用此功能，并建议改为发布 Reel，同时设置 share_to_feed=True。

轮播（2–10 个项目）

# Step 1: create child containers (each with is_carousel_item=True for photos)
instagram_photo_containers_create(
    image_url="https://example.com/photo1.jpg",
    is_carousel_item=True,
)
# Repeat for each image / video

# Step 2: create the carousel container with child IDs
instagram_carousel_containers_create(
    children=["<child_id_1>", "<child_id_2>", "<child_id_3>"],
    caption="Carousel caption",
)

# Step 3: publish
instagram_media_publish(creation_id="<carousel_container_id>")

内容限制

类型	格式	最大大小	时长
照片	JPEG	8MB	—
Reel	MP4 / MOV	300MB	3s – 15min
Story 图片	JPEG	8MB	—
Story 视频	MP4 / MOV	100MB	3s – 60s
说明文字	文本	2200 chars	30 个主题标签，20 个 @标签
轮播内容	混合	2 – 10 个项目	—

阶段 3：评论管理

查看评论

instagram_comments_list(media_id="<media_id>")

发布评论

instagram_comments_send(media_id="<media_id>", message="Great post!")

回复评论

instagram_comments_reply(comment_id="<comment_id>", message="Thanks!")

管理评论

# Hide spam / inappropriate comments
instagram_comments_hide(comment_id="<comment_id>", hide=True)

# Delete a comment (only the media owner can delete)
instagram_comments_delete(comment_id="<comment_id>")

# Toggle comments on / off for a post
instagram_comments_toggle(media_id="<media_id>", comment_enabled=False)

回复提及

**注意：**此 MCP 集成尚不提供专门用于提及的工具（instagram_reply_to_mention、instagram_get_mentioned_media、instagram_get_mentioned_comment）。提及会显示为你媒体内容下的评论——使用 instagram_comments_list 中的评论 ID，通过 instagram_comments_reply 回复。

阶段 4：私信（CRM）

列出对话

instagram_conversations_list()

查看消息

# Get message IDs from a conversation
instagram_conversation_messages_get(conversation_id="<conversation_id>")

# Get full message details (only 20 most recent are queryable)
instagram_messages_get(message_id="<message_id>")

发送消息

# Text message
instagram_messages_send(
    recipient_id="<recipient_igsid>",   # From the message's 'from' field
    text="Thanks for reaching out!",
)

# Media attachment (image, video, audio, PDF)
instagram_media_messages_send(
    recipient_id="<recipient_igsid>",
    media_type="image",                 # image, video, audio, or file
    media_url="https://example.com/photo.jpg",
)

# Share a published post via DM
instagram_post_messages_send(
    recipient_id="<recipient_igsid>",
    post_id="<media_id>",               # Must be your own post
)

# React to a message
instagram_messages_react(
    recipient_id="<recipient_igsid>",
    message_id="<message_id>",
    reaction="love",
)

消息限制

• 接收者必须先发起对话。
• 从用户最后一条消息起，有 24 小时的回复时限（使用 Human Agent 标签时为 7 天）。
• 文本消息：UTF-8，最多 1000 字节。
• 媒体限制：图片（PNG / JPEG，8MB）、视频（MP4 / OGG，25MB）、音频（AAC / WAV，25MB）、文件（PDF，25MB）。

阶段 5：分析与洞察

账户级洞察

instagram_account_insights_get(
    metric=["reach", "profile_views", "follower_count", "accounts_engaged", "total_interactions"],
    period="week",
)

**注意：**部分指标（profile_views、total_interactions、人口统计指标）需要 instagram_business_manage_insights 权限和 Business 账户——对于 Creator 账户，这些指标会被静默省略。如果响应中缺少某项指标，请检查 instagram_current_user_get 返回的账户类型。

有效的账户指标：

指标	说明
reach	看过任何内容的独立账户数。
follower_count	粉丝总数（仅限 lifetime 周期）。
website_clicks	对个人资料中网站链接的点击次数。
profile_views	个人资料页面浏览量。
online_followers	指定时间在线的粉丝数。
accounts_engaged	进行过互动的独立账户数。
total_interactions	点赞、评论、分享、收藏和回复总数。
likes	所有内容的点赞总数。
comments	所有内容的评论总数。
shares	所有内容的分享总数。
saves	所有内容的收藏总数。
replies	回复总数（快拍 / 消息）。
follows_and_unfollows	粉丝数量净变化。
profile_links_taps	对个人资料链接的点击次数。
views	内容总浏览量。
engaged_audience_demographics	互动受众的人口统计信息。
reached_audience_demographics	覆盖受众的人口统计信息。
follower_demographics	粉丝的人口统计信息。

无效的账户指标：impressions、email_contacts、phone_call_clicks、text_message_clicks、get_directions_clicks。

媒体级洞察

instagram_media_insights_get(
    media_id="<media_id>",
    metric=["reach", "likes", "comments", "saved", "shares", "total_interactions"],
)

• 常见指标（所有非 Story 媒体）：reach、saved、likes、comments、shares、total_interactions、views。
• 仅限 Reel 的额外指标（非 Reel 媒体会自动剔除）：ig_reels_avg_watch_time、ig_reels_video_view_total_time、clips_replays_count、ig_reels_aggregated_all_plays_count。
• 仅限 Story 的指标：reach、replies、follows、navigation、profile_visits、profile_activity、views。

**提示：**如果不确定媒体是否为 Reel，只需使用常见指标。发送给非 Reel 媒体的仅限 Reel 指标会被服务自动剔除。

无效的媒体指标：engagement、impressions、plays、saves——对于媒体，请使用 saved（而非 saves；saves 仅适用于账户级指标）。

周期值

周期	说明
day	按日细分。
week	按周细分。
days_28	按 28 天细分。
month	按月细分。
lifetime	全时段（follower_count 必须使用）。

阶段 6：媒体与 Story 管理

浏览媒体库

# List recent posts (up to 10K)
instagram_media_list(limit=25)

# Get details of a specific post
instagram_media_get(media_id="<media_id>")

# Get carousel children
instagram_album_children_get(media_id="<carousel_media_id>")

# List active stories (24h window)
instagram_stories_list()

# Get tagged media
instagram_tagged_media_get()