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

# Conversation History

Retrieve and analyze historical conversation data for users and services.

{% hint style="info" %}
**Data Access**\
Access conversation history for analytics, quality assurance, and user-experience improvements.
{% endhint %}

## List Conversations

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/?user_id=<USER-ID>&limit=10&continuation_token=0' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'accept: application/json'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient
from amigo_sdk.models import GetConversationsParametersQuery

with AmigoClient() as client:
    conversations = client.conversation.get_conversations(
        GetConversationsParametersQuery(
            user_id=user_id,
            limit=10,
            continuation_token=0,
        )
    )

    for c in conversations.conversations or []:
        print(f"Conversation ID: {c.id}")
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ /* config */ });
const conversations = await client.conversations.getConversations({
  user_id: userId,
  limit: 10,
  continuation_token: 0,
});

conversations.conversations?.forEach((c) => {
  console.log(`Conversation ID: ${c.id}`);
});
```

{% endtab %}
{% endtabs %}

### Query Parameters

| Parameter            | Type    | Description                                       |
| -------------------- | ------- | ------------------------------------------------- |
| `user_id`            | string  | Filter by specific user                           |
| `service_id`         | string  | Filter by specific service                        |
| `is_finished`        | boolean | Filter by conversation state                      |
| `limit`              | integer | Results per page (max 150, default 150)           |
| `continuation_token` | integer | Pagination token (a zero-based offset, default 0) |

## Get Conversation Messages

Retrieve all messages from a specific conversation.

{% hint style="info" %}
**Message Order**\
Messages are returned in chronological order, preserving the conversation flow.
{% endhint %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/{conversation\_id}/messages/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/<CONVERSATION-ID>/messages/' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'accept: application/json'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient

with AmigoClient() as client:
    msgs = client.conversation.get_conversation_messages(conversation_id=conversation_id)
    for m in msgs.messages or []:
        print(f"Message from {m.sender}: {m.message_text}")
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
const messages = await client.conversations.getConversationMessages(conversationId);
messages.messages?.forEach((m) => {
  console.log(`Message from ${m.sender}: ${m.message_text}`);
});
```

{% endtab %}
{% endtabs %}

## Retrieve Message Source

For non-text messages (for example, audio from voice channels), retrieve the original source data. The response is a signed URL to the raw message content.

{% hint style="warning" %}
**Non-text messages only.** This endpoint returns an error for messages that originated as text. It is intended for voice recordings and other media sources.
{% endhint %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/{conversation\_id}/messages/{message\_id}/source" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/<CONVERSATION-ID>/messages/<MESSAGE-ID>/source' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'accept: application/json'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient

with AmigoClient() as client:
    source = client.conversation.get_message_source(
        conversation_id=conversation_id,
        message_id=message_id,
    )
    print(f"Source URL: {source.url}")
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
const source = await client.conversations.getMessageSource(
  conversationId,
  messageId
);
console.log(`Source URL: ${source.url}`);
```

{% endtab %}

{% tab title="Agent Forge CLI" %}

```bash
# Get message source (short-lived signed URL)
forge conversation message-source CONVERSATION_ID MESSAGE_ID -e myorg

# Long-lived URL (12 hours) for sharing or debugging
forge conversation message-source CONVERSATION_ID MESSAGE_ID -e myorg --long-lived

# JSON output
forge conversation message-source CONVERSATION_ID MESSAGE_ID -e myorg --json
```

{% endtab %}
{% endtabs %}

### Query Parameters

| Parameter    | Type    | Default | Description                                                                                  |
| ------------ | ------- | ------- | -------------------------------------------------------------------------------------------- |
| `long_lived` | boolean | `false` | Generate a long-lived URL valid for 12 hours. Short-lived URLs are recommended for security. |

## Modify Conversation Tags

Add, update, or remove tags on a conversation. Tags are key-value pairs for categorization, filtering, and routing.

**Permission required:** `Conversation:ModifyConversation`

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/{conversation\_id}/tags/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

The request body supports two operations:

| Field     | Type   | Description                                                                           |
| --------- | ------ | ------------------------------------------------------------------------------------- |
| `updates` | object | A mapping of tags to add or update. Existing tags not included here remain unchanged. |
| `deletes` | array  | A list of tag keys to remove from the conversation.                                   |

{% hint style="info" %}
**Channel Tagging** For guidance on using tags to implement channel-based routing and filtering, see [Channel Tagging System](/developer-guide/operations/devops/channel-tagging.md).
{% endhint %}

## Recommend Responses

Generate recommended responses for the user based on the conversation history. Call this when the most recent interaction has concluded but the user has not yet responded.

**Permission required:** `Conversation:GetRecommendedResponses`

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/{conversation\_id}/interaction/{interaction\_id}/recommend\_responses" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

The optional `context` field in the request body provides additional context for generating the recommendations.

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/<CONVERSATION-ID>/interaction/<INTERACTION-ID>/recommend_responses' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{"context": "User is asking about billing"}'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient

with AmigoClient() as client:
    recommendations = client.conversation.recommend_responses_for_interaction(
        conversation_id=conversation_id,
        interaction_id=interaction_id,
        body={"context": "User is asking about billing"},
    )
    for rec in recommendations.get("recommended_responses", []):
        print(f"Suggested: {rec}")
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
const recommendations =
  await client.conversations.recommendResponsesForInteraction(
    conversationId,
    interactionId,
    { context: "User is asking about billing" }
  );

recommendations.recommended_responses?.forEach((r) => console.log(`Suggested: ${r}`));
```

{% endtab %}
{% endtabs %}

## Get Interaction Insights

Retrieve insights into the agent's reasoning and behavior for a given interaction. The response covers the current state, state transitions, working memory, reflections, and tool call logs.

**Permissions required:**

* `Conversation:GetInteractionInsights` on the conversation
* `Organization:GetServiceHierarchicalStateMachine` on the context graph used by the interaction

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/{conversation\_id}/interaction/{interaction\_id}/insights" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

The response includes:

| Field                                         | Description                                          |
| --------------------------------------------- | ---------------------------------------------------- |
| `current_state_name`                          | The state the agent is currently in                  |
| `current_state_action`                        | The action taken in the current state                |
| `current_state_objective`                     | The objective of the current state                   |
| `state_transition_logs`                       | Log of state transitions during the interaction      |
| `working_memory`                              | Active memories used to generate the message         |
| `reflections`                                 | Reflections the agent made during message generation |
| `triggered_dynamic_behavior_set_version_info` | Dynamic behavior that was activated, if any          |
| `select_next_action_tool_call_logs`           | Tool calls during the `SelectNextAction` step        |
| `engage_user_tool_call_logs`                  | Tool calls during the `EngageUser` step              |

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/<CONVERSATION-ID>/interaction/<INTERACTION-ID>/insights' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'accept: application/json'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient

with AmigoClient() as client:
    insights = client.conversation.get_interaction_insights(
        conversation_id=conversation_id,
        interaction_id=interaction_id,
    )
    print(f"Current state: {insights.current_state_name}")
    print(f"Action: {insights.current_state_action}")
    for transition in insights.state_transition_logs or []:
        print(f"  Transition: {transition}")
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
const insights = await client.conversations.getInteractionInsights(
  conversationId,
  interactionId
);

console.log(`Current state: ${insights.current_state_name}`);
console.log(`Action: ${insights.current_state_action}`);
insights.state_transition_logs?.forEach((t) =>
  console.log(`  Transition: ${JSON.stringify(t)}`)
);
```

{% endtab %}
{% endtabs %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversation-history.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.