---
title: "Create a conversation"
method: POST
path: "/ai/conversations"
tags: ["Conversations"]
---

# Create a conversation

`POST /ai/conversations`

Creates a new AI conversation, the container for messages exchanged with an assistant, and returns the created conversation.

## Headers

- `Idempotency-Key` string

## Request body

- CreateConversationRequest
  - `name` string
  - `metadata` object — Metadata associated with the conversation. Set `ai_disabled` to `true` to create the conversation with AI message responses disabled.

## Response `200`

Successful Response

- Conversation
  - `id` string, uuid, required
  - `name` string
  - `created_at` string, date-time, required — The datetime the conversation was created.
  - `metadata` object, required — Metadata associated with the conversation. Telnyx provides several pieces of metadata, but customers can also add their own. The reserved field `ai_disabled` (boolean) can be set to `true` to prevent AI-generated responses on this conversation. When `ai_disabled` is `true`, calls to the chat endpoint will return a 400 error. Set to `false` or remove the field to re-enable AI responses. This is useful when a human agent needs to take over the conversation mid-stream (e.g., a technician stepping in while AI was messaging a resident).
  - `last_message_at` string, date-time, required — The datetime of the latest message in the conversation.

## Other responses

- `400` — Bad Request / Validation Failed (10015). Invalid, duplicate, empty, malformed, or overlong Idempotency-Key headers are rejected by Edge with HTTP 400 and error code 10015.
- `409` — A request with the same Idempotency-Key is still being processed (10036). Retry later with the same key and request.
- `413` — Payload Too Large. A request sent with an Idempotency-Key whose body exceeds the endpoint's Edge replay-protection limit (256 KB) is rejected before it reaches the service. Requests sent without the header are not subject to this limit.
- `422` — Validation Error. Reusing an Idempotency-Key with a different request body also returns 422 with error code 10027.
- `503` — Service unavailable (10016), including unavailable Edge idempotency protection for a keyed request.

## Changes

> 73 revisions in range; 1 not diffed.

- **2026-09-16** `a6a61a29ecdd` — 1 breaking, 1 warning, 6 info
  - the response's body type changed from `object` to no type for status `422`
  - removed the optional property `detail` from the response with the `422` status
  - added the new optional `header` request parameter `Idempotency-Key`
  - added `#/components/schemas/HTTPValidationError, #/components/schemas/inference-embedding_ErrorResponse` to the response body `anyOf` list for the response status `422`
  - …4 more

[Change history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/conversations/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/673109139443?raw)