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

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

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

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

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

nullOptional

initial_message_typeany ofOptional

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

string · enumOptionalPossible values:

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

400

This may occur for the following reasons:

Attempting to start a conversation when other unfinished conversations exist.
The preferred language does not support voice response.
The response_audio_format field is not set when voice output is requested.
The agent does not have voice config specified.

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

/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: 163

{
  "service_id": "text",
  "service_version_set_name": "release",
  "initial_message": "text",
  "initial_message_type": "user-message",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

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

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

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

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")
    )

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

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")
    )

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

PreviousConversations NextStarters

Last updated 3 months ago

Was this helpful?

Good afternoon

hashtagQuick Start: Choosing Your Message Type

hashtagPrerequisites

hashtagCreate a conversation

Permissions

hashtagAuthentication & Token Management

hashtagAgent-First Conversations

hashtagUser-First Conversations

hashtagExternal Event Messages

hashtagExample Response Stream

hashtagTips

Quick Start: Choosing Your Message Type

Prerequisites

Create a conversation

Authentication & Token Management

Agent-First Conversations

User-First Conversations

External Event Messages

Example Response Stream

Tips