Go to website

Create

Create new conversations and choose who speaks first (agent, user, or an external event).

Quick Start: Choosing Your Message Type

Use the table below to determine which initial_message_type to use:

Your Use Case
Parameter Value
Example Scenario

User submits a query or prompt

"user-message"

Web form submission, generated conversation starters, voice input, chat message

Agent greets the user first

(omit both parameters)

Default greeting behavior, proactive agent engagement

System or external trigger

"external-event"

Payment failed, alert triggered, status change, webhook event

Prerequisites

  • Valid JWT for the acting user (see Authentication)

  • service_id for the target service

  • Organization ID

Create a conversation

post
/v1/{organization}/conversation/

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.CreateConversation for the new conversation.

This endpoint may be impacted by the following permissions:

  • CurrentAgentActionEvents are only emitted if the authenticated user has the Conversation:GetInteractionInsights permission.
Authorizations
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
response_formatstring · enumRequired

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

Possible values:
current_agent_action_typestringOptional

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 ^$.

Default: ^.*$
audio_formatany ofOptional

The format of the audio response, if response_format is set to voice.

string · enumOptionalPossible values:
or
nullOptional
response_audio_formatany ofOptional

The format of the audio response, if response_format is set to voice.

one ofOptional
or
or
nullOptional
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.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
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
initial_messageany ofOptional

The initial user or agent inner thought message to send to the service. If not provided, the conversation will start with an agent message.

string · min: 1Optional
or
nullOptional
initial_message_typeany ofOptional

The type of the initial_message. Can only be specified if initial_message is provided.

string · enumOptionalPossible values:
or
nullOptional
Responses
post
/v1/{organization}/conversation/
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"
}

Authentication & Token Management

All requests must include Authorization: Bearer <AUTH-TOKEN-OF-USER>.

First time using the API? The Bearer token is a JWT obtained by calling the Sign In with API Key endpoint. See the complete Authentication Guide for step-by-step instructions.

Agent-First Conversations

When no initial_message is provided, the agent sends the first message.

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

User-First Conversations

Start with a user message using initial_message and initial_message_type: "user-message".

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>",
       "initial_message": "Hello, I need help with my account settings",
       "initial_message_type": "user-message"
     }'

External Event Messages

Start with an external system event using initial_message_type: "external-event".

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>",
       "initial_message": "URGENT: System failure detected in payment processing",
       "initial_message_type": "external-event"
     }'

Example Response Stream

The response is an NDJSON stream with events. See the full list in Conversations → Events.

{"type":"conversation-created","conversation_id":"67d871c23eb91293ecfae8b0"}
{"type":"new-message","message":"Hi","message_metadata":[],"stop":false,"sequence_number":1,"message_id":"67d871c23eb91293ecfae8b2"}
{"type":"new-message","message":" there! How can I help you today?","message_metadata":[],"stop":false,"sequence_number":2,"message_id":"67d871c23eb91293ecfae8b2"}
{"type":"interaction-complete"}

Tips

Conversation Management

  • Store the conversation_id from the conversation-created event for subsequent calls

  • Always process events until interaction-complete

  • Handle error events by retrying the interaction

PreviousConversationsNextInteract

Last updated

Was this helpful?