ig_send_message

Instructions

Implementation Reference

• src/tools/instagram/messaging.ts:56-76 (handler)

  The 'ig_send_message' tool handler. Calls Meta API POST to /{igUserId}/messages with recipient_id and message text. Uses client.ig() to send via Instagram Graph API.

  // ─── ig_send_message ─────────────────────────────────────────
  server.tool(
    "ig_send_message",
    "Send a DM to a user. Requires 'instagram_manage_messages' permission. Can only message users who have messaged you first (24hr window for standard, 7-day for human agent).",
    {
      recipient_id: z.string().describe("Instagram-scoped user ID of the recipient"),
      message: z.string().describe("Message text to send"),
    },
    async ({ recipient_id, message }) => {
      try {
        const { data, rateLimit } = await client.ig("POST", `/${client.igUserId}/messages`, {
          recipient: JSON.stringify({ id: recipient_id }),
          message: JSON.stringify({ text: message }),
          messaging_type: "RESPONSE",
        });
        return { content: [{ type: "text", text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text", text: `Send message failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/tools/instagram/messaging.ts:60-63 (schema)

  Input schema for ig_send_message using Zod: recipient_id (string) and message (string).

  {
    recipient_id: z.string().describe("Instagram-scoped user ID of the recipient"),
    message: z.string().describe("Message text to send"),
  },

• src/tools/instagram/messaging.ts:56-76 (registration)

  Tool registration via server.tool('ig_send_message', ...) inside registerIgMessagingTools().

  // ─── ig_send_message ─────────────────────────────────────────
  server.tool(
    "ig_send_message",
    "Send a DM to a user. Requires 'instagram_manage_messages' permission. Can only message users who have messaged you first (24hr window for standard, 7-day for human agent).",
    {
      recipient_id: z.string().describe("Instagram-scoped user ID of the recipient"),
      message: z.string().describe("Message text to send"),
    },
    async ({ recipient_id, message }) => {
      try {
        const { data, rateLimit } = await client.ig("POST", `/${client.igUserId}/messages`, {
          recipient: JSON.stringify({ id: recipient_id }),
          message: JSON.stringify({ text: message }),
          messaging_type: "RESPONSE",
        });
        return { content: [{ type: "text", text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text", text: `Send message failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/index.ts:48-48 (registration)

  Registration call: registerIgMessagingTools(server, client) in the main entry point.

  registerIgMessagingTools(server, client);

• src/services/meta-client.ts:76-85 (helper)

  MetaClient.ig() helper method that performs the HTTP request to the Instagram Graph API base URL (graph.facebook.com/v25.0) with the Instagram access token.

  async ig(
    method: string,
    path: string,
    params?: Record<string, unknown>
  ): Promise<ClientResponse> {
    if (!this.config.instagramAccessToken) {
      throw new Error("INSTAGRAM_ACCESS_TOKEN is not configured.");
    }
    return this.request(IG_BASE, this.config.instagramAccessToken, method, path, params);
  }