> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/classic-api/core-api/conversations.md).

# Conversations

Core conversation API for creating, interacting with, and managing AI-powered conversations.

The Conversations API is the core interface for managing AI-powered interactions on the Concurrence platform.

## Overview

Conversations are the primary way users interact with Concurrence agents. Each conversation maintains context, manages state, and handles the flow of messages between users and the AI.

## API Endpoints

### Conversation Management

* [**Create**](/developer-guide/classic-api/core-api/conversations/conversations-create.md): initialize new conversations with agents; the endpoint contract is embedded on the reference page
* [**Starters**](/developer-guide/classic-api/core-api/conversations/conversations-starters.md): generate contextual conversation starters
* [**Interact**](/developer-guide/classic-api/core-api/conversations/conversations-interact.md): send messages and receive AI responses through the embedded endpoint contract
* [**Events**](/developer-guide/classic-api/core-api/conversations/conversations-events.md): events are delivered as the NDJSON stream returned by the Create and Interact endpoints
* [**Lifecycle & Finish**](/developer-guide/classic-api/core-api/conversations/conversations-lifecycle.md): manage conversation states and completion
* [**Voice**](/developer-guide/classic-api/core-api/conversations/conversations-voice.md): text-channel voice uses the Interact endpoint with `request_format=voice` rather than a separate `/voice` path
* [**Real-time Voice (WebSocket)**](/developer-guide/classic-api/core-api/conversations/conversations-realtime.md): bidirectional voice transport documented separately because WebSocket routes are not represented in the HTTP OpenAPI schema
* [**External Events & Multi-Stream (WebSocket)**](/developer-guide/classic-api/core-api/conversations/conversations-realtime-external-events.md): interleave external events with user text and audio on a single WebSocket connection
* [**Conversation History**](/developer-guide/classic-api/core-api/conversations/conversation-history.md): retrieve conversations, messages, tags, and interaction insights

## Key Features

* **Contextual Memory**: conversations keep context across multiple interactions.
* **Multi-modal Support**: text, voice, and structured data inputs.
* **Real-time Streaming**: NDJSON event streams for live updates.
* **WebSocket Support**: low-latency bidirectional communication for real-time voice.
* **Voice Activity Detection**: automatic speech detection in real-time mode.
* **State Management**: track and control conversation flow.
* **Voice Integration**: voice-to-text and text-to-voice.
* **Automatic Audio Fillers**: handles perceived latency during voice interactions.

## Common Use Cases

1. **Customer Support**: automated support conversations with context awareness.
2. **Virtual Assistants**: personal AI assistants with memory and learning.
3. **Interactive Workflows**: guide users through complex processes.
4. **Voice Interfaces**: natural language voice interactions.

## Quick Start

```javascript
// Create a new conversation (the acting user is identified via the JWT)
const events = await amigo.conversations.createConversation(
  { service_id: "<SERVICE-ID>", service_version_set_name: "release" },
  { response_format: "text" }
);

// Events are delivered as the NDJSON stream returned by create/interact.
// Iterate the stream rather than subscribing to a separate events endpoint.
let conversationId;
for await (const event of events) {
  if (event.type === "conversation-created") {
    conversationId = event.conversation_id;
  }
  if (event.type === "new-message") {
    console.log("New message:", event.message);
  }
}

// Send a message and iterate the returned event stream until interaction-complete
const interactEvents = await amigo.conversations.interactWithConversation(
  conversationId,
  "Hello, I need help with my order",
  { request_format: "text", response_format: "text" }
);

for await (const event of interactEvents) {
  if (event.type === "new-message") {
    console.log("New message:", event.message);
  }
}
```

## Related Documentation

* [Authentication](/developer-guide/getting-started/authentication.md)
* [SDK Reference](/developer-guide/classic-api/sdks.md)
* [Conversation History](/developer-guide/classic-api/core-api/conversations/conversation-history.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/classic-api/core-api/conversations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.