> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindset.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Threads API

> Start agent conversations from your backend and deliver them to your users — before they even open the app.

## Threads API

The Threads API lets your backend system start an agent conversation in response to something happening in your product — and then deliver that conversation directly to your user.

When the user arrives (via email, push notification, or in-app link), the agent's response is already waiting for them. They pick up a live conversation, not a blank chat window.

This is a fundamentally different model from a user-initiated chat. Your system is the trigger. The agent does the work in advance. The user gets a personalised, contextual experience the moment they arrive.

***

## Key Features

**Event-driven conversations**

Your backend detects an event — an order shipped, an onboarding milestone reached, a compliance deadline approaching — and calls the Threads API. The agent processes the event and generates its first response. By the time your user arrives, the conversation is ready.

**System messages**

You can pass context to the agent without the user seeing it. A system message lets you tell the agent exactly what happened, who the user is, and what they need — and the agent greets the user naturally, as if it initiated the conversation. The user only sees the agent's response, not your backend prompt.

**Deep linking**

The Threads API returns a thread ID that you include in your notification (email, push, in-app). When the user clicks the link, they land directly in that specific conversation. No searching, no setup, no blank slate.

**Works with your existing embedded SDK**

The conversation surfaces inside your product using the Mindset embedded SDK widget. The same widget your users already interact with — now pre-loaded with a specific thread.

***

## Use Cases

The Threads API is a good fit for any situation where something important happens in your system and a personalised AI response would help your user act on it.

Some examples:

* An order ships, and the agent briefs the user on their delivery details and offers to answer questions
* A new employee hits a milestone, and the agent surfaces relevant onboarding resources
* A compliance deadline is approaching, and the agent walks the user through what they need to do
* A support ticket is resolved, and the agent proactively follows up to confirm everything is working

***

## How It Works

At a high level, your system makes two API calls before notifying the user:

1. **Create an agent session** — links your agent to the specific user and any tools or context it needs
2. **Create a thread** — sends the event details to the agent, which processes them and generates its first response

Your system stores the session and thread IDs, includes them in a deep link, and sends the user a notification. When the user arrives, you authenticate them with Mindset and render the embedded SDK widget with the correct thread — and the conversation is right there waiting.

<Note>
  The Threads API requires agentVersion 3. If you're on an earlier version, you'll need to upgrade your agent configuration in the Agent Management Studio (AMS) before using this feature.
</Note>

***

## Prerequisites

* A Mindset AI app with a configured agent (agentVersion 3)
* An API key from the Developer section of AMS
* The Mindset AI SDK v3 embedded on the page where the agent will surface
* Your API host URL (available in the Developer section of AMS)

***

## Get Started

Ready to build? The integration guide walks through the complete flow step by step — from detecting an event in your backend to the user seeing the conversation in your app.

[Build Event-Driven Agent Conversations →](/build-optimize/Threads/build-event-driven-conversations)

***

## Current Limitations

* The Threads API currently requires agentVersion 3
* Deep link URL patterns for Universal Client are under active development and will be documented separately
* Mindset AI does not send the user notification — your system handles delivery via email, push, or in-app alert