V1/conversation
Was this helpful?
Was this helpful?
Retrieve feedbacks for a conversation. Both conversation-level feedbacks and interaction-level feedbacks are supported.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo for the authenticated user.
This endpoint may be impacted by the following permissions:
If type is conversation, only feedbacks for which the authenticated user has the Conversation:GetConversationFeedback permission will be returned.
If type is interaction, only feedbacks for which the authenticated user has the Conversation:GetInteractionFeedback permission will be returned.
The type of feedback to retrieve.
The IDs of conversations to retrieve feedbacks for.
If type is interaction, the IDs of interactions to retrieve feedbacks for.
The maximum number of feedbacks to retrieve.
10The continuation token from the previous request used to retrieve the next page of feedbacks.
0The fields to sort the feedbacks by. Supported fields are created_at, user_id, user_org_id, conversation_id, and feedback_content.interaction_id if type is interaction.
[]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.
Return the metrics generated for a conversation. If a conversation's metrics is not generated yet, this endpoint will return an empty array, so check thecompleted_post_processings field on the conversation first.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo on the authenticated user.
Conversation:GetConversationMetrics on the conversation.
The identifier of the conversation.
^[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.
Retrieve a conversation by its ID.
Permissions
This endpoint requires the following permissions:
User.GetUserInfo for the authenticated user.
Conversation.GetConversation for the conversation.
This endpoint is impacted by the following permissions:
The user_id field in the response is only non-empty if the authenticated user has the User.GetUserInfo permission on the user who started the conversation.
The agent_name and agent_pfp fields in the response are only non-empty if the authenticated user has the Organization.GetAgent permission on the agent that this conversation uses.
The identifier of the conversation.
^[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.
Retrieve messages in a conversation, sorted in the specified order, up to the specified limit.
Permissions
This endpoint requires the following permissions:
User.GetUserInfo for the authenticated user.
This endpoint is impacted by the following permissions:
Only messages that the authenticated user has Conversation.GetMessage permission 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 100 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.
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 andInteract 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:GetUserInfo on the authenticated user.
User:UpdateUserInfo on the user who started the conversation.
Conversation:InteractWithConversation on the conversation.
Organization:GetAgent on the agent that the conversation uses.
Organization:GetServiceHierarchicalStateMachine on the state machine that this conversation uses.
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.
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:
User:GetUserInfo on the authenticated user.
Conversation:GetRecommendedResponses on this conversation.
Organization:GetServiceHierarchicalStateMachine on the service HSM version that the session is currently on as well as all its dependencies.
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.
Retrieve insights about the agent's message for a given interaction.
Permissions:
This endpoint requires the following permissions:
User:GetUserInfo on the authenticated user.
Conversation:GetInteractionInsights on the conversation.
Organization:GetServiceHierarchicalStateMachineDetails 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.
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.
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:GetUserInfo on the authenticated user.
User:UpdateUserInfo on the user who started the conversation.
Conversation:InteractWithConversation on the conversation.
Organization:GetAgent on the agent that the conversation uses.
Organization:GetServiceHierarchicalStateMachine on the service hierarchical state machine that the conversation uses.
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`
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.
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:
User:GetUserInfo on the authenticated user.
Conversation:GetMessage on 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.
No content
Delete an interaction feedback.
Permissions
This endpoint requires the following permissions:
User.GetUserInfo on the authenticated user.
Conversation.UpsertInteractionFeedback on the feedback to be deleted.
The ID of the conversation.
^[a-f0-9]{24}$The ID of the interaction.
^[a-f0-9]{24}$The ID of the feedback.
^[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.
No content
Delete a conversation feedback.
Permissions
This endpoint requires the following permissions:
User.GetUserInfo on the authenticated user.
Conversation.UpsertConversationFeedback on the feedback to be deleted.
The ID of the conversation.
^[a-f0-9]{24}$The ID of the feedback.
^[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.
No content
Retrieve conversations in an organization based on supplied filters.
Permissions
This endpoint requires the following permissions:
User.GetUserInfo for the authenticated user.
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.
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.
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:
User.GetUserInfo on the authenticated user.
Conversation.CreateConversation for the new conversation.
Service.GetService on the specified service.
Service.GetVersionSet on the specified service version set.
Organization.GetAgent on the agent used by the specified service.
Organization.GetServiceHierarchicalStateMachine on the service hierarchical state machine used by the specified service as well as all its dependencies.
The format of the response that will be sent to the user.
Whether to emit CurrentAgentActionEvents.
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.
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.
releaseUpdate an existing feedback in the interaction.
For feedbacks of type interaction_comment, if it is resolved, the comment cannot be changed.
Permissions
This endpoint requires the following permissions:
User.GetUserInfo on the authenticated user.
Conversation.UpsertConversationFeedback on the feedback to be updated.
The ID of the conversation.
^[a-f0-9]{24}$The ID of the interaction.
^[a-f0-9]{24}$The ID of the feedback.
^[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.
No content
Update the feedback for a conversation.
Permissions
This endpoint requires the following permissions:
User.GetUserInfo on the authenticated user.
Conversation.UpsertConversationFeedback on the feedback to be upserted.
The ID of the conversation to update feedback for.
^[a-f0-9]{24}$The ID of the feedback.
^[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 feedback message.
No content
Create a new feedback for an interaction.
Permissions
This endpoint requires the following permissions:
User.GetUserInfo on the authenticated user.
Conversation.UpsertInteractionFeedback on the feedback to be created.
The ID of the conversation.
^[a-f0-9]{24}$The ID 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.
Create a new feedback for the conversation.
Permissions
This endpoint requires the following permissions:
User.GetUserInfo on the authenticated user.
Conversation.UpsertConversationFeedback on the feedback to be created.
The ID of the conversation.
^[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 comment for the conversation.
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:
User:GetUserInfo on the authenticated user.
Organization:GetAgent on the agent.
Organization:GetServiceHierarchicalStateMachine on the state machines used by the conversation as well as its dependencies.
Conversation:InteractWithConversation on 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.