Telnyx Conversations API
Manage historical AI assistant conversations
OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Access Tokens Conversations API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Manage historical AI assistant conversations
name: Conversations
paths:
/ai/conversations:
get:
description: Retrieve a list of all AI conversations configured by the user. Supports [PostgREST-style query parameters](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for filtering. Examples are included for the standard metadata fields, but you can filter on any field in the metadata JSON object. For example, to filter by a custom field `metadata->custom_field`, use `metadata->custom_field=eq.value`.
operationId: get_conversations_public_conversations_get
parameters:
- description: Filter by conversation ID (e.g. id=eq.123)
in: query
name: id
required: false
schema:
type: string
- description: Filter by conversation Name (e.g. `name=like.Voice%`)
in: query
name: name
required: false
schema:
type: string
- description: Filter by creation datetime (e.g., `created_at=gte.2025-01-01`)
in: query
name: created_at
required: false
schema:
type: string
- description: Filter by last message datetime (e.g., `last_message_at=lte.2025-06-01`)
in: query
name: last_message_at
required: false
schema:
type: string
- description: Filter by assistant ID (e.g., `metadata->assistant_id=eq.assistant-123`)
in: query
name: metadata->assistant_id
required: false
schema:
type: string
- description: Filter by call control ID (e.g., `metadata->call_control_id=eq.v3:123`)
in: query
name: metadata->call_control_id
required: false
schema:
type: string
- description: Filter by the phone number, SIP URI, or other identifier for the agent (e.g., `metadata->telnyx_agent_target=eq.+13128675309`)
in: query
name: metadata->telnyx_agent_target
required: false
schema:
type: string
- description: Filter by the phone number, SIP URI, or other identifier for the end user (e.g., `metadata->telnyx_end_user_target=eq.+13128675309`)
in: query
name: metadata->telnyx_end_user_target
required: false
schema:
type: string
- description: Filter by conversation channel (e.g., `metadata->telnyx_conversation_channel=eq.phone_call`)
in: query
name: metadata->telnyx_conversation_channel
required: false
schema:
type: string
- description: Limit the number of returned conversations (e.g., `limit=10`)
in: query
name: limit
required: false
schema:
minimum: 1
type: integer
- description: Order the results by specific fields (e.g., `order=created_at.desc` or `order=last_message_at.asc`)
in: query
name: order
required: false
schema:
type: string
- description: Apply OR conditions using PostgREST syntax (e.g., `or=(created_at.gte.2025-04-01,last_message_at.gte.2025-04-01)`)
in: query
name: or
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsListData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: List conversations
tags:
- Conversations
x-latency-category: responsive
post:
description: Create a new AI Conversation.
operationId: create_new_conversation_public_conversations_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConversationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Create a conversation
tags:
- Conversations
x-latency-category: responsive
/ai/conversations/insight-groups:
get:
description: Get all insight groups
operationId: get_all_insight_groups
parameters:
- description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
description: Page number (0-based)
minimum: 1
title: Page[Number]
type: integer
size:
default: 20
description: Number of items per page
exclusiveMaximum: 100
minimum: 0
title: Page[Size]
type: integer
type: object
style: deepObject
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetInsightTemplateGroupsRespData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get Insight Template Groups
tags:
- Conversations
x-latency-category: responsive
post:
description: Create a new insight group
operationId: create_insight_group
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InsightTemplateGroupCreateReq'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InsightTemplateGroupDetailRespData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Create Insight Template Group
tags:
- Conversations
x-latency-category: responsive
/ai/conversations/insight-groups/{group_id}:
delete:
description: Delete insight group by ID
operationId: delete_insight_group_by_id
parameters:
- description: The ID of the insight group
in: path
name: group_id
required: true
schema:
description: The ID of the insight group
format: uuid
title: Group Id
type: string
responses:
'200':
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Delete Insight Template Group
tags:
- Conversations
x-latency-category: responsive
get:
description: Get insight group by ID
operationId: get_insight_group_by_id
parameters:
- description: The ID of the insight group
in: path
name: group_id
required: true
schema:
description: The ID of the insight group
format: uuid
title: Group Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InsightTemplateGroupDetailRespData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get Insight Template Group
tags:
- Conversations
x-latency-category: responsive
put:
description: Update an insight template group
operationId: update_insight_group_by_id
parameters:
- description: The ID of the insight group
in: path
name: group_id
required: true
schema:
description: The ID of the insight group
format: uuid
title: Group Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InsightTemplateGroupUpdateReq'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InsightTemplateGroupDetailRespData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Update Insight Template Group
tags:
- Conversations
x-latency-category: responsive
/ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign:
post:
description: Assign an insight to a group
operationId: assign_insight_to_group
parameters:
- description: The ID of the insight group
in: path
name: group_id
required: true
schema:
description: The ID of the insight group
format: uuid
title: Group Id
type: string
- description: The ID of the insight
in: path
name: insight_id
required: true
schema:
description: The ID of the insight
format: uuid
title: Insight Id
type: string
responses:
'200':
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Assign Insight Template To Group
tags:
- Conversations
x-latency-category: responsive
/ai/conversations/insight-groups/{group_id}/insights/{insight_id}/unassign:
delete:
description: Remove an insight from a group
operationId: unassign_insight_from_group
parameters:
- description: The ID of the insight group
in: path
name: group_id
required: true
schema:
description: The ID of the insight group
format: uuid
title: Group Id
type: string
- description: The ID of the insight
in: path
name: insight_id
required: true
schema:
description: The ID of the insight
format: uuid
title: Insight Id
type: string
responses:
'200':
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Unassign Insight Template From Group
tags:
- Conversations
x-latency-category: responsive
/ai/conversations/insights:
get:
description: Get all insights
operationId: get_all_insights
parameters:
- description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
description: Page number (0-based)
minimum: 1
title: Page[Number]
type: integer
size:
default: 20
description: Number of items per page
exclusiveMaximum: 100
minimum: 0
title: Page[Size]
type: integer
type: object
style: deepObject
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetInsightTemplatesRespData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get Insight Templates
tags:
- Conversations
x-latency-category: responsive
post:
description: Create a new insight
operationId: create_insight
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InsightTemplateCreateReq'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InsightTemplateDetailRespData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Create Insight Template
tags:
- Conversations
x-latency-category: responsive
/ai/conversations/insights/{insight_id}:
delete:
description: Delete insight by ID
operationId: delete_insight_by_id
parameters:
- description: The ID of the insight
in: path
name: insight_id
required: true
schema:
description: The ID of the insight
format: uuid
title: Insight Id
type: string
responses:
'200':
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Delete Insight Template
tags:
- Conversations
x-latency-category: responsive
get:
description: Get insight by ID
operationId: get_insight_by_id
parameters:
- description: The ID of the insight
in: path
name: insight_id
required: true
schema:
description: The ID of the insight
format: uuid
title: Insight Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InsightTemplateDetailRespData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get Insight Template
tags:
- Conversations
x-latency-category: responsive
put:
description: Update an insight template
operationId: update_insight_by_id
parameters:
- description: The ID of the insight
in: path
name: insight_id
required: true
schema:
description: The ID of the insight
format: uuid
title: Insight Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InsightTemplateUpdateReq'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InsightTemplateDetailRespData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Update Insight Template
tags:
- Conversations
x-latency-category: responsive
/ai/conversations/{conversation_id}:
delete:
description: Delete a specific conversation by its ID.
operationId: delete_conversation_by_id_public_conversations_delete
parameters:
- description: The ID of the conversation to delete
in: path
name: conversation_id
required: true
schema:
type: string
responses:
'200':
description: Successful Response
'404':
description: Conversation Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Delete a conversation
tags:
- Conversations
x-latency-category: responsive
get:
description: Retrieve a specific AI conversation by its ID.
operationId: get_conversation_by_id_public_conversations_get
parameters:
- description: The ID of the conversation to retrieve
in: path
name: conversation_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/Conversation'
description: Successful Response
'404':
description: Conversation Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get a conversation
tags:
- Conversations
x-latency-category: responsive
put:
description: Update metadata for a specific conversation.
operationId: update_conversation_by_id_public_conversations_put
parameters:
- description: The ID of the conversation to update
in: path
name: conversation_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateConversationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/Conversation'
description: Successful Update
'404':
description: Conversation Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Update conversation metadata
tags:
- Conversations
x-latency-category: responsive
/ai/conversations/{conversation_id}/conversations-insights:
get:
description: Retrieve insights for a specific conversation
operationId: get_conversations_public__conversation_id__insights_get
parameters:
- in: path
name: conversation_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationInsightListData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get insights for a conversation
tags:
- Conversations
x-latency-category: responsive
/ai/conversations/{conversation_id}/message:
post:
description: Add a new message to the conversation. Used to insert a new messages to a conversation manually ( without using chat endpoint )
operationId: add_new_message
parameters:
- description: The ID of the conversation
in: path
name: conversation_id
required: true
schema:
description: The ID of the conversation
format: uuid
title: Conversation Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMsgReq'
required: true
responses:
'200':
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Create Message
tags:
- Conversations
x-latency-category: responsive
/ai/conversations/{conversation_id}/messages:
get:
description: Retrieve messages for a specific conversation, including tool calls made by the assistant.
operationId: get_conversations_public__conversation_id__messages_get
parameters:
- in: path
name: conversation_id
required: true
schema:
type: string
- description: The number of messages to return per page.
in: query
name: page[size]
required: false
schema:
default: 20
maximum: 100
minimum: 1
type: integer
- description: The page number to retrieve.
in: query
name: page[number]
required: false
schema:
default: 1
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationMessageListData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get conversation messages
tags:
- Conversations
x-latency-category: responsive
components:
schemas:
CreateConversationRequest:
properties:
metadata:
additionalProperties:
type: string
description: Metadata associated with the conversation. Set `ai_disabled` to `true` to create the conversation with AI message responses disabled.
type: object
name:
type: string
title: CreateConversationRequest
type: object
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
title: Location
type: array
msg:
title: Message
type: string
type:
title: Error Type
type: string
required:
- loc
- msg
- type
title: ValidationError
type: object
InsightTemplateGroupUpdateReq:
properties:
description:
title: Description
type: string
name:
title: Name
type: string
webhook:
title: Webhook
type: string
title: InsightTemplateGroupUpdateReq
type: object
InsightTemplateUpdateReq:
properties:
instructions:
title: Instructions
type: string
json_schema:
anyOf:
- type: string
- title: JsonSchemaObject
type: object
title: Json Schema
name:
title: Name
type: string
webhook:
title: Webhook
type: string
title: InsightTemplateUpdateReq
type: object
Meta:
properties:
page_number:
type: integer
page_size:
type: integer
total_pages:
type: integer
total_results:
type: integer
required:
- total_pages
- total_results
- page_number
- page_size
title: Meta
type: object
ConversationsListData:
properties:
data:
items:
$ref: '#/components/schemas/Conversation'
title: Data
type: array
required:
- data
title: ConversationsListData
type: object
GetInsightTemplateGroupsRespData:
properties:
data:
items:
$ref: '#/components/schemas/InsightTemplateGroupResp'
title: Data
type: array
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
title: GetInsightTemplateGroupsRespData
type: object
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
ConversationInsightListData:
properties:
data:
items:
$ref: '#/components/schemas/ConversationInsight'
title: Data
type: array
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
title: ConversationInsightListData
type: object
InsightTemplateGroupDetailRespData:
properties:
data:
$ref: '#/components/schemas/InsightTemplateGroupResp'
required:
- data
title: InsightTemplateGroupDetailRespData
type: object
TemplateType:
enum:
- custom
- default
title: TemplateType
type: string
ConversationMessage:
properties:
created_at:
description: The datetime the message was created on the conversation. This does not necesarily correspond to the time the message was sent. The best field to use to determine the time the end user experienced the message is `sent_at`.
example: '2025-04-15T13:07:28.764Z'
format: date-time
type: string
role:
description: The role of the message sender.
enum:
- user
- assistant
- tool
type: string
sent_at:
description: The datetime the message was sent to the end user.
example: '2025-04-15T13:07:28.764Z'
format: date-time
type: string
text:
description: The message content. Can be null for tool calls.
type: string
tool_calls:
description: Optional tool calls made by the assistant.
items:
properties:
function:
properties:
arguments:
description: JSON-formatted arguments to pass to the function.
type: string
name:
description: Name of the function to call.
type: string
required:
- name
- arguments
type: object
id:
description: Unique identifier for the tool call.
type: string
type:
description: Type of the tool call.
enum:
- function
type: string
required:
- id
- type
- function
type: object
type: array
required:
- role
- text
type: object
CreateMsgReq:
properties:
content:
default: ''
title: Content
type: string
metadata:
additionalProperties:
anyOf:
- type: string
- type: integer
- type: boolean
- items:
anyOf:
- type: string
- type: integer
- type: boolean
type: array
title: Metadata
type: object
name:
title: Name
type: string
role:
title: Role
type: string
sent_at:
format: date-time
title: Sent At
type: string
tool_call_id:
title: Tool Call Id
type: string
tool_calls:
items:
additionalProperties: true
type: object
title: Tool Calls
type: array
tool_choice:
anyOf:
- type: string
- title: ToolChoiceObject
type: object
title: Tool Choice
required:
- role
title: CreateMsgReq
type: object
InsightTemplateCreateReq:
properties:
instructions:
title: Instructions
type: string
json_schema:
anyOf:
- type: string
- title: JsonSchemaObject
type: object
description: If specified, the output will follow the JSON schema.
title: Json Schema
name:
title: Name
type: string
webhook:
default: ''
title: Webhook
type: string
required:
- instructions
- name
title: InsightTemplateCreateReq
type: object
InsightTemplateGroupResp:
properties:
created_at:
format: date-time
title: Created At
type: string
description:
title: Description
type: string
id:
format: uuid
title: Id
type: string
insights:
items:
$ref: '#/components/schemas/InsightTemplateResp'
title: Insights
type: array
name:
title: Name
type: string
webhook:
default: ''
title: Webhook
type: string
required:
- id
- name
- created_at
title: InsightTemplateGroupResp
type: object
InsightTemplateGroupCreateReq:
properties:
description:
title: Description
type: string
name:
title: Name
type: string
webhook:
default: ''
title: Webhook
type: string
required:
- name
title: InsightTemplateGroupCreateReq
type: object
ConversationMessageListData:
properties:
data:
items:
$ref: '#/components/schemas/ConversationMessage'
title: Data
type: array
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
title: ConversationMessageListData
type: object
Conversation:
properties:
created_at:
description: The datetime the conversation was created.
example: '2025-04-15T13:07:28.764Z'
format: date-time
type: string
id:
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
format: uuid
type: string
last_message_at:
description: The datetime of the latest message in the conversation.
example: '2025-04-15T13:07:28.764Z'
format: date-time
type: string
metadata:
additionalProperties:
type: string
description: 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 w
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-conversations-api-openapi.yml