Class: Telnyx::Resources::AI::Conversations

Inherits:
Object
  • Object
show all
Defined in:
lib/telnyx/resources/ai/conversations.rb,
lib/telnyx/resources/ai/conversations/insights.rb,
lib/telnyx/resources/ai/conversations/messages.rb,
lib/telnyx/resources/ai/conversations/insight_groups.rb,
lib/telnyx/resources/ai/conversations/conversation_insights.rb,
lib/telnyx/resources/ai/conversations/insight_groups/insights.rb,
sig/telnyx/resources/ai/conversations.rbs,
sig/telnyx/resources/ai/conversations/insights.rbs,
sig/telnyx/resources/ai/conversations/messages.rbs,
sig/telnyx/resources/ai/conversations/insight_groups.rbs,
sig/telnyx/resources/ai/conversations/conversation_insights.rbs,
sig/telnyx/resources/ai/conversations/insight_groups/insights.rbs

Overview

Manage historical AI assistant conversations

Defined Under Namespace

Classes: ConversationInsights, InsightGroups, Insights, Messages

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Conversations

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Conversations.

Parameters:



251
252
253
254
255
256
257
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 251

def initialize(client:)
  @client = client
  @insight_groups = Telnyx::Resources::AI::Conversations::InsightGroups.new(client: client)
  @insights = Telnyx::Resources::AI::Conversations::Insights.new(client: client)
  @messages = Telnyx::Resources::AI::Conversations::Messages.new(client: client)
  @conversation_insights = Telnyx::Resources::AI::Conversations::ConversationInsights.new(client: client)
end

Instance Attribute Details

#conversation_insights ⇒ Telnyx::Resources::AI::Conversations::ConversationInsights (readonly)

Manage historical AI assistant conversations

Returns:



22
23
24
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 22

def conversation_insights
  @conversation_insights
end

#insight_groups ⇒ Telnyx::Resources::AI::Conversations::InsightGroups (readonly)

Manage historical AI assistant conversations

Returns:



10
11
12
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 10

def insight_groups
  @insight_groups
end

#insights ⇒ Telnyx::Resources::AI::Conversations::Insights (readonly)

Manage historical AI assistant conversations

Returns:



14
15
16
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 14

def insights
  @insights
end

#messages ⇒ Telnyx::Resources::AI::Conversations::Messages (readonly)

Manage historical AI assistant conversations

Returns:



18
19
20
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 18

def messages
  @messages
end

Instance Method Details

#add_message(conversation_id, role:, content: nil, metadata: nil, name: nil, sent_at: nil, tool_call_id: nil, tool_calls: nil, tool_choice: nil, idempotency_key: nil, request_options: {}) ⇒ nil

Some parameter documentations has been truncated, see Models::AI::ConversationAddMessageParams for more details.

Add a new message to the conversation. Used to insert a new messages to a conversation manually ( without using chat endpoint )

Parameters:

  • conversation_id (String) —

    Path param: The ID of the conversation

  • role (String) —

    Body param

  • content (String) —

    Body param

  • metadata (Hash{Symbol=>String, Integer, Boolean, Array<String, Integer, Boolean>}) —

    Body param

  • name (String) —

    Body param

  • sent_at (Time) —

    Body param

  • tool_call_id (String) —

    Body param

  • tool_calls (Array<Hash{Symbol=>Object}>) —

    Body param

  • tool_choice (String, Hash{Symbol=>Object}) —

    Body param

  • idempotency_key (String) —

    Header param: Optional opaque, unquoted key for safely retrying the same logical

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 215

def add_message(conversation_id, params)
  parsed, options = Telnyx::AI::ConversationAddMessageParams.dump_request(params)
  header_params = {idempotency_key: "idempotency-key"}
  @client.request(
    method: :post,
    path: ["ai/conversations/%1$s/message", conversation_id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: NilClass,
    options: options
  )
end

#create(metadata: nil, name: nil, idempotency_key: nil, request_options: {}) ⇒ Telnyx::Models::AI::Conversation

Some parameter documentations has been truncated, see Models::AI::ConversationCreateParams for more details.

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

Parameters:

  • metadata (Hash{Symbol=>String}) —

    Body param: Metadata associated with the conversation. Set ai_disabled to `tru

  • name (String) —

    Body param

  • idempotency_key (String) —

    Header param: Optional opaque, unquoted key for safely retrying the same logical

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 43

def create(params = {})
  parsed, options = Telnyx::AI::ConversationCreateParams.dump_request(params)
  header_params = {idempotency_key: "idempotency-key"}
  @client.request(
    method: :post,
    path: "ai/conversations",
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Telnyx::AI::Conversation,
    options: options
  )
end

#delete(conversation_id, request_options: {}) ⇒ nil

Delete a specific conversation by its ID.

Parameters:

  • conversation_id (String) —

    The ID of the conversation to delete

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



173
174
175
176
177
178
179
180
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 173

def delete(conversation_id, params = {})
  @client.request(
    method: :delete,
    path: ["ai/conversations/%1$s", conversation_id],
    model: NilClass,
    options: params[:request_options]
  )
end

#list(id: nil, created_at: nil, last_message_at: nil, limit: nil, metadata_assistant_id: nil, metadata_call_control_id: nil, metadata_telnyx_agent_target: nil, metadata_telnyx_conversation_channel: nil, metadata_telnyx_end_user_target: nil, name: nil, or_: nil, order: nil, request_options: {}) ⇒ Telnyx::Models::AI::ConversationListResponse

Some parameter documentations has been truncated, see Models::AI::ConversationListParams for more details.

Retrieve a list of all AI conversations configured by the user. Supports PostgREST-style query parameters 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.

Parameters:

  • id (String) —

    Filter by conversation ID (e.g. id=eq.123)

  • created_at (String) —

    Filter by creation datetime (e.g., created_at=gte.2025-01-01)

  • last_message_at (String) —

    Filter by last message datetime (e.g., last_message_at=lte.2025-06-01)

  • limit (Integer) —

    Limit the number of returned conversations (e.g., limit=10)

  • metadata_assistant_id (String) —

    Filter by assistant ID (e.g., metadata->assistant_id=eq.assistant-123)

  • metadata_call_control_id (String) —

    Filter by call control ID (e.g., metadata->call_control_id=eq.v3:123)

  • metadata_telnyx_agent_target (String) —

    Filter by the phone number, SIP URI, or other identifier for the agent (e.g., `m

  • metadata_telnyx_conversation_channel (String) —

    Filter by conversation channel (e.g., `metadata->telnyx_conversation_channel=eq.

  • metadata_telnyx_end_user_target (String) —

    Filter by the phone number, SIP URI, or other identifier for the end user (e.g.,

  • name (String) —

    Filter by conversation Name (e.g. name=like.Voice%)

  • or_ (String) —

    Apply OR conditions using PostgREST syntax (e.g., `or=(created_at.gte.2025-04-01

  • order (String) —

    Order the results by specific fields (e.g., order=created_at.desc or `order=la

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 143

def list(params = {})
  parsed, options = Telnyx::AI::ConversationListParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "ai/conversations",
    query: query.transform_keys(
      metadata_assistant_id: "metadata->assistant_id",
      metadata_call_control_id: "metadata->call_control_id",
      metadata_telnyx_agent_target: "metadata->telnyx_agent_target",
      metadata_telnyx_conversation_channel: "metadata->telnyx_conversation_channel",
      metadata_telnyx_end_user_target: "metadata->telnyx_end_user_target",
      or_: "or"
    ),
    model: Telnyx::Models::AI::ConversationListResponse,
    options: options
  )
end

#retrieve(conversation_id, request_options: {}) ⇒ Telnyx::Models::AI::ConversationRetrieveResponse

Retrieve a specific AI conversation by its ID.

Parameters:

  • conversation_id (String) —

    The ID of the conversation to retrieve

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



67
68
69
70
71
72
73
74
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 67

def retrieve(conversation_id, params = {})
  @client.request(
    method: :get,
    path: ["ai/conversations/%1$s", conversation_id],
    model: Telnyx::Models::AI::ConversationRetrieveResponse,
    options: params[:request_options]
  )
end

#retrieve_conversations_insights(conversation_id, request_options: {}) ⇒ Telnyx::Models::AI::ConversationRetrieveConversationsInsightsResponse

Retrieve insights for a specific conversation

Parameters:

  • conversation_id (String) —

    Unique identifier of the conversation.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



239
240
241
242
243
244
245
246
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 239

def retrieve_conversations_insights(conversation_id, params = {})
  @client.request(
    method: :get,
    path: ["ai/conversations/%1$s/conversations-insights", conversation_id],
    model: Telnyx::Models::AI::ConversationRetrieveConversationsInsightsResponse,
    options: params[:request_options]
  )
end

#update(conversation_id, metadata: nil, request_options: {}) ⇒ Telnyx::Models::AI::ConversationUpdateResponse

Some parameter documentations has been truncated, see Models::AI::ConversationUpdateParams for more details.

Update metadata for a specific conversation.

Parameters:

  • conversation_id (String) —

    The ID of the conversation to update

  • metadata (Hash{Symbol=>String}) —

    Metadata associated with the conversation. Set ai_disabled to true to stop A

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



92
93
94
95
96
97
98
99
100
101
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 92

def update(conversation_id, params = {})
  parsed, options = Telnyx::AI::ConversationUpdateParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["ai/conversations/%1$s", conversation_id],
    body: parsed,
    model: Telnyx::Models::AI::ConversationUpdateResponse,
    options: options
  )
end