V1/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.
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.
GET /v1/{organization}/conversation/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
"conversations": [
{
"id": "text",
"user_id": "text",
"created_at": "2025-07-01T00:45:17.400Z",
"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.
The format of the response that will be sent to the user.
Whether to emit CurrentAgentActionEvents.
falseA 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 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.
releasePOST /v1/{organization}/conversation/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 58
{
"service_id": "text",
"service_version_set_name": "release"
}{
"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.
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 timestamp. 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.
GET /v1/{organization}/conversation/{conversation_id}/messages/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
"messages": [
{
"id": "text",
"interaction_id": "text",
"timestamp": "2025-07-01T00:45:17.400Z",
"sender": "text",
"message": "text",
"format": "text",
"message_type": "user-message",
"message_metadata": [
"text"
]
}
],
"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.
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.
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.
POST /v1/{organization}/conversation/{conversation_id}/finish/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
No content
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.
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.
GET /v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/recommend_responses HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
"recommended_responses": [
"text"
]
}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.
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.
GET /v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/insights HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
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"
}
],
"working_memory": [
{
"content": "text",
"context": "text"
}
],
"reflections": [
"text"
],
"triggered_dynamic_behavior_set_version_info": []
}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.
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.
Whether to emit CurrentAgentActionEvents.
falseA 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 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.
POST /v1/{organization}/conversation/{conversation_id}/interact HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
"type": "interaction-complete",
"message_id": "text",
"interaction_id": "text",
"full_message": "text"
}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.
The identifier of the conversation.
^[a-f0-9]{24}$The identifier of the message.
^[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.
GET /v1/{organization}/conversation/{conversation_id}/messages/{message_id}/source HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
No content
Re-run the specified interaction with the agent and state machine optionally overriden.
This endpoint does not completely recreate the context under which the interaction was initially run. For instance, the dynamic behaviors that are currently available are retrieved, not the ones that were available when the interaction was initially run.
Side effect states are skipped.
This endpoint does not persist any data. The original interaction isn't overwritten.
Permissions
This endpoint requires the following permissions:
Conversation:InteractWithConversationon the conversation.
The ID of the conversation to simulate.
^[a-f0-9]{24}$The ID of the interaction to simulate.
^[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.
If specified, the specified agent will be used to simulate the interaction.
POST /v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/simulate HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 910
{
"agent_version_override": {
"identity": {
"name": "text",
"role": "text",
"developed_by": "text",
"default_spoken_language": "aaa",
"relationship_to_developer": {
"ownership": "text",
"type": "text",
"conversation_visibility": "text",
"thought_visibility": "text"
}
},
"background": "text",
"behaviors": [
"text"
],
"communication_patterns": [
"text"
]
},
"state_machine_version_override": {
"states": {
"ANY_ADDITIONAL_PROPERTY": {
"type": "text",
"objective": "text",
"actions": [
"text"
],
"intra_state_navigation_guidelines": [
"text"
],
"action_guidelines": [
"text"
],
"boundary_constraints": [
"text"
],
"exit_conditions": [
{
"description": "text",
"next_state": "text"
}
],
"message_metadata": [
"text"
]
}
},
"new_user_initial_state": "text",
"returning_user_initial_state": "text",
"terminal_state": "text",
"references": {
"ANY_ADDITIONAL_PROPERTY": []
},
"global_intra_state_navigation_guidelines": [
"text"
],
"global_action_guidelines": [
"text"
],
"global_boundary_constraints": [
"text"
]
}
}{
"agent_message": "text",
"conversation_ended": true
}Generate conversation starters for a service.
Permissions
This endpoint requires the following permissions:
Conversation:CreateConversationfor a hypothetical new conversation created using the same setting.
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.
POST /v1/{organization}/conversation/conversation_starter HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
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"
]
}
]
}Was this helpful?