---
title: "Create a conversation"
method: POST
path: "/v1/{organization}/conversation/"
tags: ["Conversation"]
---

# 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:
* `CurrentAgentActionEvent`s are only emitted if the authenticated user has the `Conversation:GetInteractionInsights` permission.

## Path parameters

- `organization` string, required

## Query parameters

- `response_format` 'text' | 'voice', required — The format of the response that will be sent to the user.
- `current_agent_action_type` string — 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 `^$`.

## Headers

- `x-mongo-cluster-name` string, nullable — 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.
- `Sec-WebSocket-Protocol` string[]

## Request body

- SrcAppEndpointsConversationCreateConversationRequest
  - `service_id` string, required — The identifier of the service to create a conversation in.
  - `service_version_set_name` string — The version set of the service to use. If not provided, the `release` version set is used.
  - `initial_message` string
  - `initial_message_type` 'user-message' | 'external-event', nullable — The type of the `initial_message`. Can only be specified if `initial_message` is provided.
  - `tags` object — A list of tags for the conversation. The key can only contain alphanumeric characters, underscores, or spaces. The value can only contain up to 100 characters.

## Response `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.

## Other responses

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

---

[API](https://skmtc.net/amigo/apis/amigo-api.md) · [All operations](https://skmtc.net/amigo/apis/amigo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/amigo/amigo-api/revisions/f0f28319e448/schema)