Skip to main content
Version: v2

AI Session Summary API

Quick Start Guide: Leveraging Fullstory Session Summary APIs

This guide will walk you through generating tailored AI-powered summaries of user sessions in Fullstory using the Session Summary APIs, a part of the Anywhere: Activation offering. These summaries can provide valuable insights for various teams, such as context for support agents, key information for sales teams, or relevant history for AI agents & chatbots.

The process involves two main steps, with an optional third step for workflows where you don't have a session ID upfront:

  1. Step 1: Creating and Managing Prompt Profiles: This defines the kind of information you want the AI to extract, how the input session data should be structured for the AI, and how the summary should be formatted.
  2. Step 2: Generating a Session Summary: This uses your configured prompt profile to summarize a specific user session.
  3. Optional Step 3: Listing Sessions for a User: This explains how to retrieve a list of session IDs when you only have a user's Email or User ID, which is common when working from a CRM or contact center platform.

The following is also included for your reference:

Step 1: Creating and Managing Summary Profiles​

A Summary Profile instructs the Fullstory AI on how to process session data and generate a summary. This includes providing instructional text (pre/post prompts), configuring the session data sent to the AI, specifying the AI temperature, and defining the desired output format.

API documentation referenced in this section:

API DocAPI Endpoint
Create ProfilePOST /v2/visit_profile

Effective Profile Configuration​

The request to create a profile is built from several optional, top-level JSON objects. Understanding these objects is key to shaping the AI's input and output.

  • llm object: This object contains the configuration for the Large Language Model.

    • pre_prompt & post_prompt: These string fields allow you to provide instructional text to the AI.
      • pre_prompt: Text included before the session data. Use this for primary instructions, setting the persona, or outlining the main goal of the summary.
      • post_prompt: Text included after the session data. Use this for final instructions or specific questions about the preceding session data.
    • output_schema (JSON Schema, stringified): For consistent, structured output (e.g., JSON), define a JSON schema. This is highly recommended for programmatic use of the summary data.
    • temperature: Adjust the temperature (randomness). Lower temperatures are better for factual, consistent summaries.

  • slice object: This object allows you to trim the session data sent to the AI by removing the earliest or latest events.

    • mode: Can be set to FIRST (default), LAST, or TIMESTAMP to define which part of the session to keep.
    • event_limit: An integer to limit the number of events.
    • duration_limit_ms: An integer to limit the session duration in milliseconds.
    • start_timestamp: If specified, the event limit and duration limit will be applied to the time beginning at this timestamp.

  • context object: This object controls which high-level session context elements are included, such as user, organization, location, or device information.

    • You can use include or exclude string arrays to specify which context elements to use (e.g., ['user',’org’,’location’,'device']).
    • Alternatively, you can use boolean flags like exclude_user_context or exclude_org_context.

  • events object: This object gives you fine-grained control over the session events sent to the AI. This is crucial for improving the relevance and conciseness of the generated summaries.

Including/Excluding Event Types​

Within the events object, the include_types and exclude_types arrays allow you to filter the events sent to the AI. By specifying which events to focus on or ignore, you can significantly improve summary quality.

  • include_types: Use this array to specify only the event types that should be processed. If this field is present, all other event types not listed will be ignored.

  • exclude_types: Use this array to specify event types that should be ignored. All other event types will be processed.

Note: It's generally recommended to use either include_types or exclude_types, but not both simultaneously, to avoid conflicting logic.

Here's a list of common standard event type strings you can use in these arrays:

API String ValueDescription
"navigate"User navigation between pages
"click"User clicks on elements
"dead-click"User clicks on elements without a response from the UI
"error-click"User clicks on elements causing an error
"rage-click"User rapidly clicks on elements with no response from the UI
"input-change"Changes to input fields (typing, selections)
"network-error"Captured network requests, often for errors
"console-error"Console error messages recorded during session
"mouse-thrash"Rapid, erratic mouse movements (frustration)
"highlight"User text selection/highlighting
"copy"User copying text
"paste"User pasting text
"element-seen"An element became visible in the viewport

Custom Events​

To include or exclude your organization's custom events (defined via FS.event or through Fullstory integrations), you would use the custom event name directly as a string in these arrays.

Example: If you have a custom event named "Added to Cart" and another named "Video Watched", your configuration might look like:

  "configuration": {
    "include_types": [
      "click",
      "input-change",
      "Added to Cart",
      "Video Watched"
    ],
    // ... other configuration options
  }

Or to exclude noisy standard events but keep your custom ones:

  "configuration": {
    "exclude_types": [
      "mouse-thrash",
      "element-seen"
    ],
  }

By thoughtfully using these event type filters, you can tailor the session narrative provided to the AI, leading to more accurate and actionable summaries.

Prompt Engineering Best Practices​

The following guidance can help you to fine tune your pre_prompt and post_prompt values:

  • Be Specific and Clear: Clearly define the purpose, the information needed, and avoid vague language.
  • Define Persona/Role (in pre_prompt): e.g., "You are a meticulous QA tester. Identify all anomalies in this session."
  • Iterate and Refine: This is crucial. Test your profile with diverse sessions, analyze the summaries, and tweak your pre_prompt, post_prompt, and configuration settings. Keep a log of changes. Practical Workflow:
    1. Formulate an initial profile configuration.
    2. Test with a few varied session replays (success, failure, errors).
    3. Analyze: Did it capture key info? Too verbose/brief? Correct format?
    4. Refine profile settings and re-test.
  • What NOT to do:
    • Avoid overly generic prompts (e.g., only "Summarize").
    • Don't ask for what Fullstory can't know (e.g., "User's thoughts"). Rephrase to focus on observable actions (e.g., "What actions suggest user confusion?").
    • Avoid overly complex pre_prompt/post_prompt with many unrelated instructions. Consider multiple, focused profiles.

Prompt Examples​

For a Support Agent:

  • pre_prompt: "You are a support agent assistant. Analyze the following session data to understand the user's issue."
  • post_prompt: "Based on the session, identify the primary user goal, any errors encountered, and the steps leading to the final critical issue. List any help documentation pages visited."

For a Sales Team:

  • pre_prompt: "Identify signals of buying intent or strong product interest in this user session."
  • post_prompt: "Summarize which specific product features or pricing pages the user engaged with, and note any expressions of need or comparison with alternatives if evident from their navigation or typed inputs. Output as a brief paragraph."

API Call Example​

Request Body Example:

This example creates a profile designed for a support assistant. It focuses on the last 200 events of a session, excludes noisy console and network errors, and instructs the GEMINI_2_FLASH_LITE model to provide a factual summary.

{
  "events": {
     "exclude_types": [ // Example: reduce noise
        "console-error",
         "network-error"],
   },
   "slice": {
      "mode": "LAST", // Focus on the end of the session
      "event_limit": 200 // Limit to the last 200
                         // relevant events (after filtering)
   },
  "llm": {
    "pre_prompt": "You are a support assistant. The following is a log of user session events. Please analyze carefully.",
    "post_prompt": "Summarize the user's primary goal, any issues encountered (errors, rage clicks), the user's final action, and suggest a possible reason for any friction encountered. If the user visited help pages, list them.",
    "temperature": 0.2
   },
}

Response:

The API will respond by confirming the profile, returning the profile id.

{  "id": "23o34-43234-234534–3452342-34233454"}

Save this id as you'll need it to generate summaries.

Note: If you are using our Salesforce App, only step 1 is required. The prompt id generated will be added to the Salesforce App settings.

Step 2: Generating a Session Summary​

Once you have a prompt profile id, you can use it to generate summaries for specific user sessions.

API documentation referenced in this section:

API DocAPI Endpoint
Generate SummaryGET /v2/sessions/{session_id}/summary

Generate Summary API Guidance​

Path Parameters:

  • session_id (string, required): The ID of the Fullstory session you want to summarize.
    • Session IDs must be URL encoded (e.g., a colon : becomes %3A)
    • To retrieve Session IDs, use the appropriate Get Session Details API for Web, iOS, or Android; or call the List Sessions API (see below) for a user.

Query Parameters:

  • config_profile (string, required): The client-defined id of the prompt profile you created in Step 1.

Example Generate Summary API Call​

Construct a GET request to the endpoint, ensuring the session_id is URL encoded in the path and the config_profile (the id from the end of Step 1 above) is in the query string.

Example Request URL:

GET https://api.fullstory.com/v2/sessions/12345%3AsessionId/summary?config_profile=23o34-43234-234534–3452342-34233454

Response:

The API will respond with a simple JSON object containing the summary as a text string. If you define an output_schema in the llm object in your profile that requests JSON, the summary string itself will be a JSON formatted string.

{  "summary": "This is the LLM summary output value. If an output_schema for JSON was used, this string will be the JSON output."}

For instance, if output_schema in the llm object of your profile was for JSON:

{  "summary": "{\"primary_goal\":\"User attempted to update payment method.\",\"issues_encountered\":[\"Received 'invalid card number' error twice.\",\"Clicked 'Submit' button multiple times with apparent frustration (based on event patterns).\"],\"final_action\":\"Navigated away from payment page to dashboard.\",\"reason_for_termination_suggestion\":\"Could not update payment method successfully.\",\"help_pages_visited\":[\"/help/payment-errors\"]}"}

Optional Step 3: Finding Session IDs for a User​

This step is necessary when your workflow starts with a user identifier (like an email or uid) instead of a session_id. This is common when triggering a summary from a CRM or a customer support platform. You can first find relevant sessions and then pass the IDs to the summary API.

API documentation referenced in this section:

API DocAPI Endpoint
List SessionsGET /sessions/v2

NOTE: This API requires an API key passed in the Authorization header.

List Sessions API Guidance​

Construct a GET request to the endpoint, using query parameters to specify the user.

Key Query Parameters:

  • uid: The User ID created in Fullstory, e.g. via FS('setIdentity')
  • email: The user's email address. The email should be URL encoded in the request
  • limit: Number of sessions to return (defaults to 20)

NOTE: You must provide a uid or an email value.

Example​

To find all sessions for the user jane@doe.com, your request would look like this:

GET https://api.fullstory.com/sessions/v2?email=jane%40doe.com&limit=10

Handling the Response:

The API returns a JSON array where each object represents a single session. You can parse this response to extract the userId and sessionId from each session object.

Example Response Snippet:

{
  "sessions": [
    {
      "userId": "6973903723107198876",
      "sessionId": "5156932900183134039",
      "createdTime": "1750978914",
      "fsUrl": "https://app.fullstory.com/ui/XYZ/session/6973903723107198876:5156932900183134039"
    },
    {
      "userId": "6973903723107198876",
      "sessionId": "7595300836794220845",
      "createdTime": "1750971633",
      "fsUrl": "https://app.fullstory.com/ui/XYZ/session/6973903723107198876:7595300836794220845"
    }  ]}

The format for the session_id value required for Step 2 above is a combination of the userId and sessionId, but URL encoded:

  1. Format: userId:SessionId
  2. Example: 6973903723107198876:7595300836794220845
  3. Example URL encoded: 6973903723107198876%3A7595300836794220845

The last value, 6973903723107198876%3A7595300836794220845, is what you would provide as the session_id when generating a session summary.

Workflow Summary & Best Practices​

  1. Strategize: Define the purpose of your summaries and who will use them.
  2. Configure Prompt Profiles: Use the POST /v2/visit_profile endpoint. Carefully structure the llm, slice, context, and events objects to tailor the AI's input.
  3. Generate Summaries: Use the GET /v2/sessions/{session_id}/summary endpoint with the session ID (URL encoded) and your chosen config_profile ID.
  4. Review and Iterate: Analyze the generated summaries. If they aren't optimal, refine your prompt profile objects (llm, events, etc.). Small changes can have big impacts.
  5. Consider Session Data Quality: The richness of your Fullstory data (custom events, user variables, named elements and properties) will significantly impact the quality of AI summaries.

By following these steps and iteratively refining your prompt profiles, you can effectively harness Fullstory's AI session summary APIs to extract powerful, tailored insights from user session data. Always refer to the official Fullstory API documentation for the most detailed parameter descriptions and advanced options.

Example Prompt​

Summarize this session for a [Ticket Service] concierge service employee.

Format for slack mrkdwn (single * for bold, • for list). The primary goal is to provide concise, actionable context for a follow-up to help close a sale with a high-value customer who added high-value tickets to their cart but may have abandoned the checkout process due to a likely technical issue or because they are not ready to buy, or it was a lot of money to spend and need more trust or white glove service or were not incentivized enough. Also ok to just say they abandoned cart and didn’t buy. If you see an Order Completed event, that means they did successfully purchase and you should flag accordingly.

Structure the summary with the following sections: 'Customer Profile', 'Session Overview', 'Key Behaviors & Insights for Follow-Up', and 'Recommended Concierge Actions'. Include only the following essential information:

  • Customer Profile
    • User ID
    • Location
    • Device type
  • Session Overview
    • A brief statement confirming active shopping for a specific event, and if the user converted or abandoned during checkout.
  • Key Behaviors & Insights for Follow-Up
    • Focus strictly on the user's demonstrated purchase intent:
      • The specific event targeted (Name, Venue, Date)
      • Mention they viewed the event page
      • The specific tickets added to the cart (key details: quantity, type, price per ticket, overall cart price) and that they initiated checkout.
  • Recommended Concierge Actions
    • Provide concrete steps for the concierge, covering:
      • Immediate actions (contact method, acknowledging the issue, verifying availability/pricing, offering assistance to complete the purchase, suggesting a goodwill gesture. Do not offer to waive fees, as that is not possible).
      • Follow-up strategy points (personalization, emphasizing value/urgency, addressing concerns, offering VIP service).
    • Crucially, EXCLUDE the following details:
      • Specific technical error codes, messages, or detailed network error explanations.
      • Detailed user navigation paths (e.g., sequences of pages visited, search terms used).
      • Counts of how many times specific pages or elements (like low inventory banners) were viewed.
      • Information about general account activity (like viewing order history) unless directly tied to the failed purchase attempt.
      • A separate "Key Takeaways" or general interpretation section. Insights should be implicit in the recommended actions. Keep the language focused and directly useful for enabling the concierge's outreach.