> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-create.md).

# 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

* A valid JWT for the acting user (see [Authentication](/developer-guide/getting-started/authentication.md))
* The `service_id` for the target service
* Your organization ID

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Authentication & Token Management

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

{% hint style="info" %}
**First time using the API?** The Bearer token is a JWT obtained by calling the [Sign In with API Key](/developer-guide/getting-started/authentication.md#authentication-token-generation) endpoint. See the complete [Authentication Guide](/developer-guide/getting-started/authentication.md) for step-by-step instructions.
{% endhint %}

## Agent-First Conversations

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

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python SDK" %}

```python
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
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
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;
  }
}
```

{% endtab %}
{% endtabs %}

## User-First Conversations

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

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python SDK" %}

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

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
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" }
);
```

{% endtab %}
{% endtabs %}

## External Event Messages

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

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python SDK" %}

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

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
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" }
);
```

{% endtab %}
{% endtabs %}

## Example Response Stream

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

```json
{"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

{% hint style="success" %}
**Conversation Management**

* Store the `conversation_id` from the `conversation-created` event for later calls.
* Always process events until `interaction-complete`.
* Handle `error` events by retrying the interaction.
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-create.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.