# Threads API

> You're reading the Mindset v3 documentation. v3 is no longer sold; this is reference for existing customers. Mindset 4 docs are at /docs.

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.

---

## 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 →](https://docs4.mindset.ai/v3/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