Conversation History

Retrieve conversation history, messages, audio sources, tags, response recommendations, and insights.

Retrieve and analyze historical conversation data for users and services.

Data Access Access conversation history for analytics, quality assurance, and user-experience improvements.

List Conversations

Get conversations

get

/v1/{organization}/conversation/

Retrieve conversations in an organization based on supplied filters.

Permissions

This endpoint may be impacted by the following permissions:

The final_message field in the response is only non-empty if the authenticated user has the Conversation.GetMessage permission on the final message.
The version_set_info field in the response is only non-empty if the authenticated user has the Service.GetVersionSet permission on the version set.
Only conversations for which the user has the Conversation.GetConversation permission are returned.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

Query parameters

user_idstring[]Optional

The identifier of the user whose conversations to retrieve.

Default: []

service_idstring[]Optional

The identifier of the service whose conversation to retrieve.

Default: []

is_finishedboolean · nullableOptional

Whether the conversation is finished.

idstring[]Optional

The ID of the conversation to retrieve.

Default: []

limitinteger · max: 150Optional

The maximum number of conversations to retrieve.

Default: 150

continuation_tokenintegerOptional

The continuation token returned from the previous response to retrieve the next set of conversations.

Default: 0

sort_bystring[]Optional

The field to sort the conversations by. Supported fields are created_at. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

tagstring[]Optional

The tags of the dynamic behavior sets. Must be specified using the syntax key:value, which means to match all sets with the given key and value pair among its tags. If value is *, it means the value does not matter. If value is empty, it matches against when the value is None.

Default: []

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

has_morebooleanRequired

Whether there are more conversations to retrieve.

continuation_tokeninteger · nullableRequired

A token to supply to the next request to retrieve the next page of conversations. Only populated if has_more is True.

401

Invalid authorization credentials.

403

Missing required permissions.

422

Invalid request path parameter or query parameter failed validation.

429

The user has exceeded the rate limit of 15 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get/v1/{organization}/conversation/

GET /v1/{organization}/conversation/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "conversations": [
    {
      "id": "text",
      "user_id": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "is_finished": true,
      "is_analyzed": true,
      "completed_post_processings": [
        "generate-user-models"
      ],
      "final_message": "text",
      "service_id": "text",
      "version_set_info": {
        "name": "text",
        "agent_version_info": [],
        "service_hierarchical_state_machine_version_info": [],
        "llm_model_preferences": {
          "ANY_ADDITIONAL_PROPERTY": {
            "llm_name": "text",
            "params": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          }
        }
      },
      "num_messages": 1,
      "tags": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

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'

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}")

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}`);
});

Query Parameters

Parameter

Type

Description

user_id

string (repeatable)

Filter by specific users

service_id

string (repeatable)

Filter by specific services

is_finished

boolean

Filter by conversation state

id

string (repeatable)

Filter by specific conversation IDs

tag

string (repeatable)

Filter by tags using key:value syntax (* matches any value; an empty value matches None)

sort_by

string (repeatable)

Sort field; supports created_at with a + (ascending) or - (descending) prefix

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.

Message Order Messages are returned sorted in the order given by the sort_by query parameter, up to limit messages per page (max 500, default 500).

Get conversation messages

get

/v1/{organization}/conversation/{conversation_id}/messages/

Retrieve messages in a conversation, sorted in the specified order, up to the specified limit.

Permissions

This endpoint is impacted by the following permissions:

Only messages that the authenticated user has Conversation.GetMessage permission on will be returned.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

conversation_idstringRequired

The identifier of the conversation.

Pattern: ^[a-f0-9]{24}$

Query parameters

idstring[]Optional

The IDs of the messages to retrieve.

Default: []

interaction_idstring[]Optional

The IDs of the interactions to retrieve messages for.

Default: []

limitinteger · max: 500Optional

The maximum number of messages to return. At most 500 messages can be returned in one request.

Default: 500

continuation_tokenintegerOptional

The continuation token to use to retrieve the next set of messages.

Default: 0

sort_bystring[]Optional

The field to sort the messages by. Supported fields are interaction_id and created_at. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

has_morebooleanRequired

Whether there are more, earlier messages in the conversation to retrieve.

continuation_tokeninteger · nullableRequired

The continuation token to use to retrieve the next set of messages.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or conversation is not found.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get/v1/{organization}/conversation/{conversation_id}/messages/

GET /v1/{organization}/conversation/{conversation_id}/messages/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "messages": [
    {
      "id": "text",
      "interaction_id": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "sender": "text",
      "message": "text",
      "format": "text",
      "message_type": "user-message"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

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'

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}")

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

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.

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.

Retrieve message source

get

/v1/{organization}/conversation/{conversation_id}/messages/{message_id}/source

Retrieve the raw source of the given message. It's only applicable to messages that did not originate as texts.

Permissions

This endpoint requires the following permissions:

Conversation:GetMessage on the the message.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

conversation_idstringRequired

The identifier of the conversation.

Pattern: ^[a-f0-9]{24}$

message_idstringRequired

The identifier of the message.

Pattern: ^[a-f0-9]{24}$

Query parameters

long_livedbooleanOptional

Whether to generate a long-lived URL which lasts 12 hours. For security purposes, it's recommended to set this to false as much as possible.

Default: false

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

anyOptional

400

The message is a text message.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or message is not found.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 30 request per minute for this endpoint.

503

The service is going through temporary maintenance.

get/v1/{organization}/conversation/{conversation_id}/messages/{message_id}/source

GET /v1/{organization}/conversation/{conversation_id}/messages/{message_id}/source HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

No content

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'

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}")

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

# 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

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

Modify tags of a conversation

post

/v1/{organization}/conversation/{conversation_id}/tags/

Modify the tags of a conversation.

Permissions

This endpoint requires the following permissions:

Conversation:ModifyConversation for the conversation to modify tags for.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

conversation_idstringRequiredPattern: ^[a-f0-9]{24}$

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

deletesstring[]Optional

A list of tags to remove from the conversation.

Default: []

Responses

204

Succeeded.

No content

400

The conversation cannot contain more than 20 tags.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or conversation is not found.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 50 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post/v1/{organization}/conversation/{conversation_id}/tags/

POST /v1/{organization}/conversation/{conversation_id}/tags/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "updates": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "deletes": [
    "text"
  ]
}

No content

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.

Channel Tagging For guidance on using tags to implement channel-based routing and filtering, see Channel Tagging System.

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

Recommend responses for interaction

post

/v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/recommend_responses

Generate a recommended response for the user to send based on the existing chat history. This should be called when the most recent interaction had concluded for a while but the user still hasn't responded.

Permissions:

This endpoint requires the following permissions:

Conversation:GetRecommendedResponses on this conversation.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

conversation_idstringRequired

The identifier of the conversation.

Pattern: ^[a-f0-9]{24}$

interaction_idstringRequired

The identifier of the most recent interaction.

Pattern: ^[a-f0-9]{24}$

organizationstringRequired

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

contextstring · min: 1Optional

The context under which the recommended responses should be generated.

Default:


PERSONA:
Name: User
Background: A typical person seeking this service.
---
SCENARIO:
Name: Complete Service
Objective: Successfully complete the service interaction.
Instructions: Engage naturally with the agent to achieve the service objective.

Responses

200

Succeeded.

application/json

recommended_responsesstring[]Required

The recommended responses to the user.

400

The conversation is finished, or the supplied interaction ID doesn't correspond to the latest, completed interaction.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or conversation is not found.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post/v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/recommend_responses

POST /v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/recommend_responses HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 270

{
  "context": "\nPERSONA:\nName: User\nBackground: A typical person seeking this service.\n---\nSCENARIO:\nName: Complete Service\nObjective: Successfully complete the service interaction.\nInstructions: Engage naturally with the agent to achieve the service objective.\n"
}

{
  "recommended_responses": [
    "text"
  ]
}

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

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"}'

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}")

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

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

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

Get interaction insights

get

/v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/insights

Retrieve insights about the agent's message for a given interaction.

Permissions:

This endpoint requires the following permissions:

Conversation:GetInteractionInsights on the conversation.
Organization:GetServiceHierarchicalStateMachine on the state machine that the current interaction is in.

This endpoint may be impacted by the following permissions:

Only reflection messages for which the authenticated user has the Conversation:GetMessage permission are included in the response.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

conversation_idstringRequired

The identifier of the conversation.

Pattern: ^[a-f0-9]{24}$

interaction_idstringRequired

The identifier of the interaction.

Pattern: ^[a-f0-9]{24}$

organizationstringRequired

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

current_state_namestringRequired

The state the agent is in.

current_state_actionstringRequired

The action taken in the current state.

current_state_objectivestringRequired

The objective of the current state.

reflectionsstring[]Required

A list of reflections the agent made during the generation of this message.

triggered_dynamic_behavior_set_version_infoarray · min: 2 · max: 2 · nullableRequired

The ID and version number of the dynamic behavior set that was activated during this interaction.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization, conversation, or interaction is not found.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get/v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/insights

GET /v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/insights HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "current_state_name": "text",
  "current_state_action": "text",
  "current_state_objective": "text",
  "state_transition_logs": [
    {
      "previous_state": "text",
      "previous_service_hierarchical_state_machine_version_info": [],
      "next_state": "text",
      "next_service_hierarchical_state_machine_version_info": [],
      "type": "action",
      "previous_state_exit_condition_description": "text",
      "tool_call_logs": [
        [
          {
            "tool_name": "text",
            "tool_id": "text",
            "tool_version": "text",
            "input": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "output": "text",
            "duration": 1
          }
        ]
      ]
    }
  ],
  "working_memory": [
    {
      "content": "text",
      "context": "text"
    }
  ],
  "reflections": [
    "text"
  ],
  "triggered_dynamic_behavior_set_version_info": [],
  "select_next_action_tool_call_logs": [
    [
      {
        "tool_name": "text",
        "tool_id": "text",
        "tool_version": "text",
        "input": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "output": "text",
        "duration": 1
      }
    ]
  ],
  "engage_user_tool_call_logs": [
    [
      {
        "tool_name": "text",
        "tool_id": "text",
        "tool_version": "text",
        "input": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "output": "text",
        "duration": 1
      }
    ]
  ]
}

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

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'

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}")

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)}`)
);

PreviousExternal Events & Multi-Stream (WebSocket)

NextTools

Last updated 3 months ago

Was this helpful?

List Conversations

Get conversations

Permissions

Query Parameters

Get Conversation Messages

Get conversation messages

Permissions

Retrieve Message Source

Retrieve message source

Permissions

Query Parameters

Modify Conversation Tags

Modify tags of a conversation

Permissions

Recommend Responses

Recommend responses for interaction

Permissions:

Get Interaction Insights

Get interaction insights

Permissions: