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

# Create

Initialize conversations with agent-first, user-first, or external-event message types.

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","transcript_alignment":null,"stop":false,"sequence_number":1,"message_id":"67d871c23eb91293ecfae8b2"}
{"type":"new-message","message":" there! How can I help you today?","transcript_alignment":null,"stop":true,"sequence_number":2,"message_id":"67d871c23eb91293ecfae8b2"}
{"type":"interaction-complete","message_id":"67d871c23eb91293ecfae8b2","interaction_id":"67d871c23eb91293ecfae8b1","full_message":"Hi there! How can I help you today?","conversation_completed":false}
```

## 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: if one arrives before `interaction-complete`, treat the interaction as void and retry; if it arrives after, the interaction is saved and you should call the Finish endpoint to retry the post-processing.
  {% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.