ig_get_conversations

Instructions

Implementation Reference

• src/tools/instagram/messaging.ts:7-30 (handler)

  The main handler for 'ig_get_conversations' tool. Calls `client.ig()` to fetch conversations from the Instagram Messaging API. Accepts optional `folder`, `limit`, and `after` (pagination cursor) parameters. Returns conversation data with rate limit info.

  server.tool(
    "ig_get_conversations",
    "Get Instagram DM conversations list. Requires 'instagram_manage_messages' permission and the Instagram Messaging API.",
    {
      folder: z.enum(["inbox", "spam"]).optional().describe("Folder to retrieve (default: inbox)"),
      limit: z.number().optional().describe("Number of conversations"),
      after: z.string().optional().describe("Pagination cursor"),
    },
    async ({ folder, limit, after }) => {
      try {
        const params: Record<string, unknown> = {
          platform: "instagram",
          fields: "id,updated_time,participants,messages{id,message,from,created_time}",
        };
        if (folder) params.folder = folder;
        if (limit) params.limit = limit;
        if (after) params.after = after;
        const { data, rateLimit } = await client.ig("GET", `/${client.igUserId}/conversations`, params);
        return { content: [{ type: "text", text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text", text: `Get conversations failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/tools/instagram/messaging.ts:10-14 (schema)

  Zod schema for 'ig_get_conversations' input parameters: `folder` (enum: inbox/spam, optional), `limit` (number, optional), `after` (string, optional).

  {
    folder: z.enum(["inbox", "spam"]).optional().describe("Folder to retrieve (default: inbox)"),
    limit: z.number().optional().describe("Number of conversations"),
    after: z.string().optional().describe("Pagination cursor"),
  },

• src/tools/instagram/messaging.ts:7-30 (registration)

  Registration via `server.tool()` call with the name 'ig_get_conversations' and description string.

  server.tool(
    "ig_get_conversations",
    "Get Instagram DM conversations list. Requires 'instagram_manage_messages' permission and the Instagram Messaging API.",
    {
      folder: z.enum(["inbox", "spam"]).optional().describe("Folder to retrieve (default: inbox)"),
      limit: z.number().optional().describe("Number of conversations"),
      after: z.string().optional().describe("Pagination cursor"),
    },
    async ({ folder, limit, after }) => {
      try {
        const params: Record<string, unknown> = {
          platform: "instagram",
          fields: "id,updated_time,participants,messages{id,message,from,created_time}",
        };
        if (folder) params.folder = folder;
        if (limit) params.limit = limit;
        if (after) params.after = after;
        const { data, rateLimit } = await client.ig("GET", `/${client.igUserId}/conversations`, params);
        return { content: [{ type: "text", text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text", text: `Get conversations failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

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

  Top-level registration: calls `registerIgMessagingTools(server, client)` which registers the tool on the MCP server.

  registerIgMessagingTools(server, client);

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

  The `ig()` method on MetaClient that performs the actual HTTP request to the Instagram Graph API base URL (graph.facebook.com/v25.0). Called by the tool handler.

  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);
  }