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/insight_groups/insights.rb

Overview

Manage historical AI assistant conversations

Defined Under Namespace

Classes: 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:



234
235
236
237
238
239
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 234

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)
end

Instance Attribute Details

#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, request_options: {}) ⇒ nil

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) —

    The ID of the conversation

  • role (String)
  • content (String)
  • metadata (Hash{Symbol=>String, Integer, Boolean, Array<String, Integer, Boolean>})
  • name (String)
  • sent_at (Time)
  • tool_call_id (String)
  • tool_calls (Array<Hash{Symbol=>Object}>)
  • tool_choice (String, Hash{Symbol=>Object})
  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



201
202
203
204
205
206
207
208
209
210
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 201

def add_message(conversation_id, params)
  parsed, options = Telnyx::AI::ConversationAddMessageParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["ai/conversations/%1$s/message", conversation_id],
    body: parsed,
    model: NilClass,
    options: options
  )
end

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

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

Create a new AI Conversation.

Parameters:

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

    Metadata associated with the conversation. Set ‘ai_disabled` to `true` to create

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

Returns:

See Also:



36
37
38
39
40
41
42
43
44
45
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 36

def create(params = {})
  parsed, options = Telnyx::AI::ConversationCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "ai/conversations",
    body: parsed,
    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:



164
165
166
167
168
169
170
171
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 164

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

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:



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 134

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:



58
59
60
61
62
63
64
65
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 58

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:

Returns:

See Also:



222
223
224
225
226
227
228
229
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 222

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:



83
84
85
86
87
88
89
90
91
92
 
# File 'lib/telnyx/resources/ai/conversations.rb', line 83

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