Create

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

Prerequisites

• Valid JWT for the acting user (see Authentication)

• service_id for the target service

• Organization ID

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:

• 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

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

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

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

application/json

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

201

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.

application/x-ndjson

Responseone of

or

or

or

or

400

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.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization, service, or version set is not found.

409

A related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 5 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

HTTPcURLJavaScriptPython

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>. See the Authentication guide for patterns and token refresh recommendations.

Agent-First Conversations

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

cURL

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

Python SDK

from amigo_sdk import AmigoClient
from amigo_sdk.models import (
    ConversationCreateConversationRequest,
    CreateConversationParametersQuery,
)

with AmigoClient() as client:
    events = client.conversation.create_conversation(
        ConversationCreateConversationRequest(
            service_id="<SERVICE-ID>",
            service_version_set_name="release"
        ),
        CreateConversationParametersQuery(response_format="text")
    )

    for event in events:
        data = event.model_dump(mode="json")
        if data.get("type") == "conversation-created":
            conversation_id = data.get("conversation_id")
            break

TypeScript SDK

import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ /* config */ });
const events = await client.conversations.createConversation(
  {
    service_id: "<SERVICE-ID>",
    service_version_set_name: "release",
  },
  { response_format: "text" }
);

for await (const event of events) {
  if (event.type === "conversation-created") {
    const conversationId = event.conversation_id;
    break;
  }
}

User-First Conversations

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

cURL

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

Python SDK

with AmigoClient() as client:
    events = client.conversation.create_conversation(
        ConversationCreateConversationRequest(
            service_id="<SERVICE-ID>",
            service_version_set_name="release",
            initial_message="Hello, I need help with my account settings",
            initial_message_type="user-message"
        ),
        CreateConversationParametersQuery(response_format="text")
    )

TypeScript SDK

const events = await client.conversations.createConversation(
  {
    service_id: "<SERVICE-ID>",
    service_version_set_name: "release",
    initial_message: "Hello, I need help with my account settings",
    initial_message_type: "user-message",
  },
  { response_format: "text" }
);

External Event Messages

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

cURL

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

Python SDK

with AmigoClient() as client:
    events = client.conversation.create_conversation(
        ConversationCreateConversationRequest(
            service_id="<SERVICE-ID>",
            service_version_set_name="release",
            initial_message="URGENT: System failure detected in payment processing",
            initial_message_type="external-event"
        ),
        CreateConversationParametersQuery(response_format="text")
    )

TypeScript SDK

const events = await client.conversations.createConversation(
  {
    service_id: "<SERVICE-ID>",
    service_version_set_name: "release",
    initial_message: "URGENT: System failure detected in payment processing",
    initial_message_type: "external-event",
  },
  { response_format: "text" }
);

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