Conversation Creation + Management

Creating a New Conversation

To initiate a new conversation with a user:

curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/?response_format=text' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/x-ndjson' \
     --header 'Content-Type: application/json' \
     --data '
{
  "service_version_set_name": "release",
  "service_id": "<SERVICE_ID>"
}'

The response takes the form of a body stream (MDN) containing New line Delimited JSON (ndjson):

// example response stream

{"type":"conversation-created","conversation_id":"67d871c23eb91293ecfae8b0"}
{"type":"new-message","message":"","message_metadata":[],"transcript_alignment":null,"stop":false,"sequence_number":0,"message_id":"67d871c23eb91293ecfae8b2"}
{"type":"new-message","message":"Hi","message_metadata":[],"transcript_alignment":null,"stop":false,"sequence_number":1,"message_id":"67d871c23eb91293ecfae8b2"}

It will include several event types as denoted by the type field:

Event Type	Type field Value	Description
ConversationCreatedEvent	conversation-created	Provides the conversation_id and confirms successful creation
ErrorEvent	error	Indicates an internal error occurred
NewMessageEvent	new-message	Contains message chunks (text or voice based on parameters)
InteractionCompleteEvent	interaction-complete	Signals successful stream completion

Important Conversation Management Rules

• A user cannot have multiple active conversations for the same service

• The conversation_id must be stored and used for all subsequent interactions

• The conversation object should be persisted for at least the duration of the active session

Create a conversation

post

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.
• User.GetUserModel on the authenticated user.
• Conversation.CreateConversation for the new conversation.
• Conversation:GetConversation on all conversations of the user who started the conversation.
• Conversation.GetMessage on all past messages of the user who started the 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.

This endpoint may be impacted by the following permissions:

• The endpoint will only use external events that the authenticated user has User.GetExternalEvent permission on during memory recall.
• The endpoint will only use tasks that the authenticated user has Task.GetTask permission on.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

organizationstringrequired

Query parameters

response_formatstring · enumrequired

The format of the response that will be sent to the user.

Available options:

overrides_returning_userbooleanoptional

Whether to pretend the current returning user is a new user.

Default: false

emit_current_agent_action_eventbooleanoptional

Whether to emit CurrentAgentActionEvents.

Default: false

Header parameters

x-mongo-cluster-nameany ofoptional

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.

Body

service_idstringrequired

The identifier of the service to create a conversation in.

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

service_version_set_namestringoptional

The version set of the service to use. If not provided, the release version set is used.

Default: release

Responses

application/x-ndjson

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.amigo.ai/v1/{organization}/conversation/?response_format=text' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "service_id": "text",
    "service_version_set_name": "text"
  }'

201

400

401

403

404

422

429

503

201

{
  "type": "text",
  "conversation_id": "text"
}

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.

Interacting with a Conversation

After creating a conversation, you can send user messages:

curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/<CONVERSATION-ID>/interact?request_format=text&response_format=text' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/x-ndjson' \
     --header 'Content-Type: multipart/form-data' \
     --form 'recorded_message=<UTF-8 ENCODED USER MESSAGE>'

Request Format

• The request body must use multipart/form-data format

• Include a single form field named recorded_message containing UTF-8 encoded text

• The body can be sent as a stream to reduce latency, as processing begins as soon as chunks are received

The response takes the form of a body stream:

// Example response stream

{"type":"user-message-available","message_id":"67d872693eb91293ecfae8b8","user_message":"I'm good"}
{"type":"new-message","message":"","message_metadata":[],"transcript_alignment":null,"stop":false,"sequence_number":0,"message_id":"67d8726b3eb91293ecfae8bd"}
{"type":"new-message","message":"Great","message_metadata":[],"transcript_alignment":null,"stop":false,"sequence_number":1,"message_id":"67d8726b3eb91293ecfae8bd"}

Response Stream Events

Event Type	Type Field Value	Description
UserMessageAvailableEvent	user-message-available	First event in response, includes the user message if sent as text
ErrorEvent	error	Indicates an internal error occurred
InteractionCompleteEvent	interaction-complete	Signals the interaction is complete
EndSessionEvent	end-session	Optional event if conversation automatically ends

Interact with a conversation

post

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 and the user who started the conversation.
• User:GetUserModel on the user who started the conversation.
• User:UpdateUserInfo on the user who started the conversation.
• Conversation:InteractWithConversation on the conversation.
• Conversation:GetConversation on all conversations of the user who started the conversation.
• Conversation.GetMessage on all past messages of the user who started the conversation.
• Organization:GetAgent on the agent that the conversation uses.
• Organization:GetServiceHierarchicalStateMachine on the service hierarchical state machine that the conversation uses.

This endpoint may be impacted by the following permissions:

• The endpoint will only use external events that the authenticated user has User.GetExternalEvent permission on during memory recall.
• The endpoint will only use tasks that the authenticated user has Task.GetTask permission on.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

conversation_idstringrequired

The identifier of the conversation to send a message to.

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

organizationstringrequired

Query parameters

request_formatstring · enumrequired

The format in which the user message is delivered to the server.

Available options:

response_formatstring · enumrequired

The format of the response that will be sent to the user.

Available options:

emit_current_agent_action_eventbooleanoptional

Whether to emit CurrentAgentActionEvents`

Default: false

Header parameters

x-mongo-cluster-nameany ofoptional

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.

Responses

application/x-ndjson

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.amigo.ai/v1/{organization}/conversation/{conversation_id}/interact?request_format=text&response_format=text' \
  --header 'Authorization: Bearer JWT'

200

400

401

403

404

409

415

422

429

503

200

{
  "type": "text",
  "message_id": "text",
  "interaction_id": "text",
  "full_message": "text"
}

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.

Conversation Lifecycle Management

Understanding Conversation States

• Started: Conversation is active and can receive interactions

• Finished: Conversation has ended and cannot receive further interactions

Automatic vs. Manual Finish

A conversation can finish in two ways:

1. Automatically: When the service determines the conversation should finish (based on user intent, service completion, etc.)

2. Manually: When explicitly ended via the finish conversation API (e.g. due to timeout or user action)

Finishing a Conversation

To manually finish a conversation:

curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/<CONVERSATION-ID>/finish/' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{}'

Important: This endpoint should only be called:

• On started, non-finished conversations

• After previous conversation API calls have completed

• When the conversation hasn't automatically finished during interaction

When a conversation finishes, post-conversation analysis is initiated asynchronously (memory generation, user model updates, etc.).

Finish a conversation

post

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:GetUserInfo on the authenticated user and the user who started the conversation.
• User:GetUserModel on the user who started the conversation.
• User:UpdateUserInfo on the user who started the conversation.
• Conversation:InteractWithConversation on the conversation.
• Conversation:GetConversation on the conversation.
• Conversation.GetMessage on all past messages in this conversation.
• Organization:GetAgent on the agent that the conversation uses.
• Organization:GetServiceHierarchicalStateMachine on the state machine that this conversation uses.

This endpoint may be impacted by the following permissions:

• The endpoint will only modify tasks that the authenticated user has the Task.GetTask permission on.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

conversation_idstringrequired

The identifier of the conversation to finish.

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

organizationstringrequired

Header parameters

x-mongo-cluster-nameany ofoptional

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.

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.amigo.ai/v1/{organization}/conversation/{conversation_id}/finish/' \
  --header 'Authorization: Bearer JWT'

204

401

403

404

409

422

429

503

204

No body

Succeeded.

Managing "Dangling" Conversations

Conversations never time out automatically. You have several options for handling inactive conversations:

1. Timeout Approach: Track user's last interaction time and call the finish endpoint after a defined period

   • Caution: This may terminate conversations users intend to continue

2. Resume Option (Recommended): When a user returns, offer options to:

   • Resume the existing conversation

   • Start a new conversation (which requires ending the current one)

3. Error Handling: If your application attempts to create a new conversation while one is active:

   • Catch the error response

   • Prompt the user to either resume or end the existing conversation

The Amigo system prevents users from having multiple ongoing conversations of the same service type, ensuring conversation integrity.