# 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 100)   |
| `continuation_token` | string  | Pagination token             |

## 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](https://docs.amigo.ai/developer-guide/operations/devops/channel-tagging).
{% 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(
        conversation_id=conversation_id,
        interaction_id=interaction_id,
        body={"context": "User is asking about billing"},
    )
    for rec in recommendations.get("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.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 %}