# 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](https://docs.amigo.ai/developer-guide/getting-started/authentication))
* 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](https://docs.amigo.ai/developer-guide/getting-started/authentication#authentication-token-generation) endpoint. See the complete [Authentication Guide](https://docs.amigo.ai/developer-guide/getting-started/authentication) 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 %}