Conversation
Retrieve conversations in an organization based on supplied filters.
Permissions
This endpoint may be impacted by the following permissions:
The
final_messagefield in the response is only non-empty if the authenticated user has theConversation.GetMessagepermission on the final message.The
version_set_infofield in the response is only non-empty if the authenticated user has theService.GetVersionSetpermission on the version set.Only conversations for which the user has the
Conversation.GetConversationpermission are returned.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the user whose conversations to retrieve.
[]The identifier of the service whose conversation to retrieve.
[]Whether the conversation is finished.
The ID of the conversation to retrieve.
[]The maximum number of conversations to retrieve.
150The continuation token returned from the previous response to retrieve the next set of conversations.
0The 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.
[]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.
[]Succeeded.
Invalid authorization credentials.
Missing required permissions.
Invalid request path parameter or query parameter failed validation.
The user has exceeded the rate limit of 15 requests per minute for this endpoint.
The service is going through temporary maintenance.
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": "2025-11-13T18:45:43.691Z",
"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",
"top_p": 1,
"temperature": 1,
"top_k": 1
}
}
},
"num_messages": 1
}
],
"has_more": true,
"continuation_token": 1
}Create a new conversation and start it. The user must not have any unfinished conversations that belong to the same service.
Permissions
This endpoint requires the following permissions:
Conversation.CreateConversationfor the new conversation.
This endpoint may be impacted by the following permissions:
CurrentAgentActionEvents are only emitted if the authenticated user has theConversation:GetInteractionInsightspermission.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The format of the response that will be sent to the user.
A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance ^$.
^.*$The format of the audio response, if response_format is set to voice.
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.
[]The identifier of the service to create a conversation in.
^[a-f0-9]{24}$The version set of the service to use. If not provided, the release version set is used.
releaseThe initial user or agent inner thought message to send to the service. If not provided, the conversation will start with an agent message.
The type of the initial_message. Can only be specified if initial_message is provided.
Succeeded. The response will be a stream of events in JSON format separated by newlines. The server will transmit an event as soon as one is available, so the client should respond to the events as soon as one arrives, and keep listening until the server closes the connection.
Attempting to start a conversation when other unfinished conversations exist, or the preferred language does not support voice response, or the audio_format field is not set when voice output is requested.
Invalid authorization credentials.
Missing required permissions.
Specified organization, service, or version set is not found.
A related operation is in progress.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 5 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/conversation/?response_format=text 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: 121
{
"service_id": "text",
"service_version_set_name": "release",
"initial_message": "text",
"initial_message_type": "user-message"
}{
"type": "conversation-created",
"conversation_id": "text"
}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.GetMessagepermission on will be returned.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the conversation.
^[a-f0-9]{24}$The IDs of the messages to retrieve.
[]The IDs of the interactions to retrieve messages for.
[]The maximum number of messages to return. At most 500 messages can be returned in one request.
500The continuation token to use to retrieve the next set of messages.
0The 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.
[]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.
[]Succeeded.
Invalid authorization credentials.
Missing required permissions.
Specified organization or conversation is not found.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
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": "2025-11-13T18:45:43.691Z",
"sender": "text",
"message": "text",
"format": "text",
"message_type": "user-message"
}
],
"has_more": true,
"continuation_token": 1
}Conclude a conversation and asynchronously initiate post-conversation analysis.
This endpoint should only be called on a started, non-finished conversation. It can only be called when the previous Start a conversation and Interact with a conversation calls have finished.
If the conversation has no messages, the conversation is deleted.
It's possible for some conversations to automatically finish during an Interact with a conversation call (for instance, if the user explicitly sends a message indicating that they're done with the conversation). In that case, this endpoint shouldn't be called, as the Interact with a conversation endpoint automatically wraps up the conversation.
Permissions
This endpoint requires the following permissions:
User:UpdateUserInfoon the user who started the conversation.Conversation:InteractWithConversationon the conversation.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the conversation to finish.
^[a-f0-9]{24}$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.
[]Succeeded.
The conversation has no interactions.
Invalid authorization credentials.
Missing required permissions.
Specified organization or conversation is not found.
The specified conversation is already finished, or a related operation is in process.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 5 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/conversation/{conversation_id}/finish/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
No content
Recommend responses for interaction (Deprecated)
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:GetRecommendedResponseson this conversation.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the conversation.
^[a-f0-9]{24}$The identifier of the most recent interaction.
^[a-f0-9]{24}$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.
[]The context under which the recommended responses should be generated.
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.
Succeeded.
The conversation is finished, or the supplied interaction ID doesn't correspond to the latest, completed interaction.
Invalid authorization credentials.
Missing required permissions.
Specified organization or conversation is not found.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
GET /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"
]
}Recommend responses for interaction
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:GetRecommendedResponseson this conversation.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the conversation.
^[a-f0-9]{24}$The identifier of the most recent interaction.
^[a-f0-9]{24}$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.
[]The context under which the recommended responses should be generated.
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.
Succeeded.
The conversation is finished, or the supplied interaction ID doesn't correspond to the latest, completed interaction.
Invalid authorization credentials.
Missing required permissions.
Specified organization or conversation is not found.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
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"
]
}Get interaction insights
Retrieve insights about the agent's message for a given interaction.
Permissions:
This endpoint requires the following permissions:
Conversation:GetInteractionInsightson the conversation.Organization:GetServiceHierarchicalStateMachineon 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:GetMessagepermission are included in the response.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the conversation.
^[a-f0-9]{24}$The identifier of the interaction.
^[a-f0-9]{24}$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.
[]Succeeded.
Invalid authorization credentials.
Missing required permissions.
Specified organization, conversation, or interaction is not found.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
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,
"hidden": false
}
]
]
}
],
"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,
"hidden": false
}
]
],
"engage_user_tool_call_logs": [
[
{
"tool_name": "text",
"tool_id": "text",
"tool_version": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"output": "text",
"duration": 1,
"hidden": false
}
]
]
}Send a new user message to the conversation. The endpoint will perform analysis and generate an agent message in response.
If request_format is text, the request body must follow multipart/form-data with precise one form field called recorded_message that corresponds to UTF-8 encoded bytes of the text message. If request_format is voice, the entire request body must be the bytes of the voice recording in audio/wav or audio/mpeg (MP3) format. The body can be sent as a stream, and the endpoint will start processing chunks as they're received, which will reduce latency.
A UserMessageAvailableEvent will be the first event in the response, which includes the user message if it's sent as text, or the transcribed message if it's sent as voice. A series of CurrentAgentActionEvents will follow, which indicates steps in the agent's thinking process. Then the agent message is generated sequentially in pieces, with each piece being sent as a NewMessageEvent in the response. After all the pieces are sent, an InteractionCompleteEvent is sent. The response might end here, or, if the conversation automatically ends (for instance, because the user message indicates the user wants to end the session), an EndSessionEvent would be emitted, while the conversation is marked as finished and the post-conversation analysis asynchronously initiated. The connection will then terminate.
Any further action on the conversation is only allowed after the connection is terminated.
A 200 status code doesn't indicate the successful completion of this endpoint, because the status code is transmitted before the stream starts. At any point during the stream, an ErrorEvent might be sent, which indicates that an error has occurred. The connection will be immediately closed after.
This endpoint can only be called on a conversation that has started but not finished.
Permissions
This endpoint requires the following permissions:
User:UpdateUserInfoon the user who started the conversation.Conversation:InteractWithConversationon the conversation.
This endpoint may be impacted by the following permissions:
CurrentAgentActionEvents are only emitted if the authenticated user has theConversation:GetInteractionInsightspermission.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the conversation to send a message to.
^[a-f0-9]{24}$The format in which the user message is delivered to the server.
The format of the response that will be sent to the user.
A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance ^$.
^.*$Configuration for the user message audio. This is only required if request_format is set to voice.
The format of the audio response, if response_format is set to voice.
The content type of the request body, which must be multipart/form-data followed by a boundary.
^multipart\/form-data; boundary=.+$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.
[]Succeeded. The response will be a stream of events in JSON format separated by newlines. The server will transmit an event as soon as one is available, so the client should respond to the events as soon as one arrives, and keep listening until the server closes the connection.
The user message is empty, or the preferred language does not support voice transcription or response, or the audio_format field is not set when voice output is requested, or the timestamps for external event messages are not in the past, or the timestamps for external event messages are inconsistent with the conversation.
Invalid authorization credentials.
Missing required permissions.
Specified organization or conversation is not found.
The specified conversation is already finished, or a related operation is in process.
The format of the supplied audio file is not supported.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 15 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/conversation/{conversation_id}/interact?request_format=text&response_format=text HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
content-type: text
Accept: */*
{
"type": "interaction-complete",
"message_id": "text",
"interaction_id": "text",
"full_message": "text",
"conversation_completed": true
}Retrieve message 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:GetMessageon the the message.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the conversation.
^[a-f0-9]{24}$The identifier of the message.
^[a-f0-9]{24}$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.
falseThe 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.
[]Succeeded.
The message is a text message.
Invalid authorization credentials.
Missing required permissions.
Specified organization or message is not found.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 30 request per minute for this endpoint.
The service is going through temporary maintenance.
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
Generate conversation starters for a service
Generate conversation starters for a service.
Permissions
This endpoint requires the following permissions:
Conversation:CreateConversationfor a hypothetical new conversation created using the same setting.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
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.
[]The identifier of the service to create a conversation starter for.
^[a-f0-9]{24}$The version set of the service to use. If not provided, the release version set is used.
releaseThe facets that the generated conversation starter should be about. Each generated starter is related to some of these facets.
The minimum (inclusive) number of conversation starters to generate.
The maximum (inclusive) number of conversation starters to generate.
The instruction for the conversation starter generation.
Succeeded.
Invalid authorization credentials.
Missing required permissions.
Service not found.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/conversation/conversation_starter 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: 137
{
"service_id": "text",
"service_version_set_name": "release",
"facets": [
"text"
],
"min_count": 1,
"max_count": 1,
"generation_instructions": "text"
}{
"prompts": [
{
"prompt": "text",
"facets": [
"text"
]
}
]
}Last updated
Was this helpful?