Funnel Step Sessions

Instructions

Implementation Reference

• src/tools/funnels.ts:160-221 (registration)

  Registration of the tool 'rybbit_get_funnel_step_sessions' via server.registerTool() with its inputSchema (siteId, stepNumber, mode, steps, dates, filters, pagination) and annotations.

  server.registerTool(
    "rybbit_get_funnel_step_sessions",
    {
      title: "Funnel Step Sessions",
      description:
        "Get the sessions that reached (or dropped off at) a specific funnel step. Useful for drilling into why users drop off at a particular funnel step.",
      annotations: {
        readOnlyHint: true,
        idempotentHint: true,
        openWorldHint: true,
        destructiveHint: false,
      },
      inputSchema: {
        siteId: siteIdSchema,
        stepNumber: z
          .number()
          .int()
          .min(1)
          .describe("The funnel step number to get sessions for (1-indexed)"),
        mode: z
          .enum(["reached", "dropped"])
          .describe("'reached' = sessions that made it to this step, 'dropped' = sessions that dropped off at this step"),
        startDate: z
          .string()
          .optional()
          .describe("Start date (YYYY-MM-DD)"),
        endDate: z
          .string()
          .optional()
          .describe("End date (YYYY-MM-DD)"),
        timeZone: z
          .string()
          .optional()
          .describe("IANA timezone (default UTC)"),
        filters: z
          .array(filterSchema)
          .optional()
          .describe("Filters to apply"),
        pastMinutesStart: z
          .number()
          .optional()
          .describe("Minutes ago start"),
        pastMinutesEnd: z
          .number()
          .optional()
          .describe("Minutes ago end"),
        steps: z
          .array(
            z.object({
              value: z.string().describe("Page path or event name"),
              type: z.enum(["page", "event"]).describe("Step type"),
              name: z
                .string()
                .optional()
                .describe("Display name for the step"),
            })
          )
          .min(2)
          .describe("The funnel steps definition (same as used in rybbit_analyze_funnel)"),
        ...paginationSchema,
      },
    },

• src/tools/funnels.ts:222-262 (handler)

  Handler function that executes the tool logic: destructures args, builds analytics params with mode, POSTs to /sites/{siteId}/funnels/{stepNumber}/sessions with steps body, and returns truncated response.

    async (args) => {
      try {
        const { siteId, stepNumber, mode, steps, ...rest } = args as {
          siteId: string;
          stepNumber: number;
          mode: "reached" | "dropped";
          steps: FunnelStep[];
          startDate?: string;
          endDate?: string;
          timeZone?: string;
          filters?: Array<{
            parameter: string;
            type: string;
            value: (string | number)[];
          }>;
          pastMinutesStart?: number;
          pastMinutesEnd?: number;
          page?: number;
          limit?: number;
        };
  
        const params = client.buildAnalyticsParams({ ...rest, page: rest.page ?? 1 });
        params.mode = mode;
  
        const data = await client.post(
          `/sites/${siteId}/funnels/${stepNumber}/sessions`,
          { steps },
          params
        );
        return {
          content: [{ type: "text" as const, text: truncateResponse(data) }],
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `Error: ${message}` }],
          isError: true,
        };
      }
    }
  );

• src/tools/funnels.ts:172-220 (schema)

  Input schema for the tool: siteId, stepNumber (int min 1), mode (reached/dropped), startDate, endDate, timeZone, filters array, pastMinutesStart, pastMinutesEnd, steps array (min 2 of value/type/name), and pagination (page/limit).

  inputSchema: {
    siteId: siteIdSchema,
    stepNumber: z
      .number()
      .int()
      .min(1)
      .describe("The funnel step number to get sessions for (1-indexed)"),
    mode: z
      .enum(["reached", "dropped"])
      .describe("'reached' = sessions that made it to this step, 'dropped' = sessions that dropped off at this step"),
    startDate: z
      .string()
      .optional()
      .describe("Start date (YYYY-MM-DD)"),
    endDate: z
      .string()
      .optional()
      .describe("End date (YYYY-MM-DD)"),
    timeZone: z
      .string()
      .optional()
      .describe("IANA timezone (default UTC)"),
    filters: z
      .array(filterSchema)
      .optional()
      .describe("Filters to apply"),
    pastMinutesStart: z
      .number()
      .optional()
      .describe("Minutes ago start"),
    pastMinutesEnd: z
      .number()
      .optional()
      .describe("Minutes ago end"),
    steps: z
      .array(
        z.object({
          value: z.string().describe("Page path or event name"),
          type: z.enum(["page", "event"]).describe("Step type"),
          name: z
            .string()
            .optional()
            .describe("Display name for the step"),
        })
      )
      .min(2)
      .describe("The funnel steps definition (same as used in rybbit_analyze_funnel)"),
    ...paginationSchema,
  },

• src/tools/funnels.ts:6-10 (helper)

  FunnelStep interface used in the handler to type the steps parameter.

  interface FunnelStep {
    value: string;
    type: "page" | "event";
    name?: string;
  }

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

  Registration of the registerFunnelsTools function (which registers rybbit_get_funnel_step_sessions along with other funnel tools) in the main entry point.

  registerFunnelsTools(server, client);
  registerGoalsTools(server, client);
  registerJourneysTools(server, client);