Class: Telnyx::Resources::AI

Inherits:
Object
  • Object
show all
Defined in:
lib/telnyx/resources/ai.rb,
lib/telnyx/resources/ai/chat.rb,
lib/telnyx/resources/ai/audio.rb,
lib/telnyx/resources/ai/tools.rb,
lib/telnyx/resources/ai/openai.rb,
lib/telnyx/resources/ai/clusters.rb,
lib/telnyx/resources/ai/missions.rb,
lib/telnyx/resources/ai/assistants.rb,
lib/telnyx/resources/ai/embeddings.rb,
lib/telnyx/resources/ai/fine_tuning.rb,
lib/telnyx/resources/ai/mcp_servers.rb,
lib/telnyx/resources/ai/openai/chat.rb,
lib/telnyx/resources/ai/integrations.rb,
lib/telnyx/resources/ai/conversations.rb,
lib/telnyx/resources/ai/missions/runs.rb,
lib/telnyx/resources/ai/missions/tools.rb,
lib/telnyx/resources/ai/assistants/tags.rb,
lib/telnyx/resources/ai/assistants/tests.rb,
lib/telnyx/resources/ai/assistants/tools.rb,
lib/telnyx/resources/ai/fine_tuning/jobs.rb,
lib/telnyx/resources/ai/openai/embeddings.rb,
lib/telnyx/resources/ai/embeddings/buckets.rb,
lib/telnyx/resources/ai/missions/runs/plan.rb,
lib/telnyx/resources/ai/assistants/versions.rb,
lib/telnyx/resources/ai/missions/mcp_servers.rb,
lib/telnyx/resources/ai/missions/runs/events.rb,
lib/telnyx/resources/ai/assistants/tests/runs.rb,
lib/telnyx/resources/ai/conversations/insights.rb,
lib/telnyx/resources/ai/conversations/messages.rb,
lib/telnyx/resources/ai/assistants/instructions.rb,
lib/telnyx/resources/ai/integrations/connections.rb,
lib/telnyx/resources/ai/missions/knowledge_bases.rb,
lib/telnyx/resources/ai/assistants/canary_deploys.rb,
lib/telnyx/resources/ai/assistants/scheduled_events.rb,
lib/telnyx/resources/ai/missions/runs/telnyx_agents.rb,
lib/telnyx/resources/ai/assistants/tests/test_suites.rb,
lib/telnyx/resources/ai/conversations/insight_groups.rb,
lib/telnyx/resources/ai/assistants/tests/test_suites/runs.rb,
lib/telnyx/resources/ai/conversations/insight_groups/insights.rb,
sig/telnyx/resources/ai.rbs,
sig/telnyx/resources/ai/chat.rbs,
sig/telnyx/resources/ai/audio.rbs,
sig/telnyx/resources/ai/tools.rbs,
sig/telnyx/resources/ai/openai.rbs,
sig/telnyx/resources/ai/clusters.rbs,
sig/telnyx/resources/ai/missions.rbs,
sig/telnyx/resources/ai/assistants.rbs,
sig/telnyx/resources/ai/embeddings.rbs,
sig/telnyx/resources/ai/fine_tuning.rbs,
sig/telnyx/resources/ai/mcp_servers.rbs,
sig/telnyx/resources/ai/openai/chat.rbs,
sig/telnyx/resources/ai/integrations.rbs,
sig/telnyx/resources/ai/conversations.rbs,
sig/telnyx/resources/ai/missions/runs.rbs,
sig/telnyx/resources/ai/missions/tools.rbs,
sig/telnyx/resources/ai/assistants/tags.rbs,
sig/telnyx/resources/ai/assistants/tests.rbs,
sig/telnyx/resources/ai/assistants/tools.rbs,
sig/telnyx/resources/ai/fine_tuning/jobs.rbs,
sig/telnyx/resources/ai/openai/embeddings.rbs,
sig/telnyx/resources/ai/embeddings/buckets.rbs,
sig/telnyx/resources/ai/missions/runs/plan.rbs,
sig/telnyx/resources/ai/assistants/versions.rbs,
sig/telnyx/resources/ai/missions/mcp_servers.rbs,
sig/telnyx/resources/ai/missions/runs/events.rbs,
sig/telnyx/resources/ai/assistants/tests/runs.rbs,
sig/telnyx/resources/ai/conversations/insights.rbs,
sig/telnyx/resources/ai/conversations/messages.rbs,
sig/telnyx/resources/ai/assistants/instructions.rbs,
sig/telnyx/resources/ai/integrations/connections.rbs,
sig/telnyx/resources/ai/missions/knowledge_bases.rbs,
sig/telnyx/resources/ai/assistants/canary_deploys.rbs,
sig/telnyx/resources/ai/assistants/scheduled_events.rbs,
sig/telnyx/resources/ai/missions/runs/telnyx_agents.rbs,
sig/telnyx/resources/ai/assistants/tests/test_suites.rbs,
sig/telnyx/resources/ai/conversations/insight_groups.rbs,
sig/telnyx/resources/ai/assistants/tests/test_suites/runs.rbs,
sig/telnyx/resources/ai/conversations/insight_groups/insights.rbs

Defined Under Namespace

Classes: Assistants, Audio, Chat, Clusters, Conversations, Embeddings, FineTuning, Integrations, McpServers, Missions, OpenAI, Tools

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ AI

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

Parameters:



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/telnyx/resources/ai.rb', line 197

def initialize(client:)
  @client = client
  @assistants = Telnyx::Resources::AI::Assistants.new(client: client)
  @audio = Telnyx::Resources::AI::Audio.new(client: client)
  @chat = Telnyx::Resources::AI::Chat.new(client: client)
  @clusters = Telnyx::Resources::AI::Clusters.new(client: client)
  @conversations = Telnyx::Resources::AI::Conversations.new(client: client)
  @embeddings = Telnyx::Resources::AI::Embeddings.new(client: client)
  @fine_tuning = Telnyx::Resources::AI::FineTuning.new(client: client)
  @integrations = Telnyx::Resources::AI::Integrations.new(client: client)
  @mcp_servers = Telnyx::Resources::AI::McpServers.new(client: client)
  @missions = Telnyx::Resources::AI::Missions.new(client: client)
  @openai = Telnyx::Resources::AI::OpenAI.new(client: client)
  @tools = Telnyx::Resources::AI::Tools.new(client: client)
end

Instance Attribute Details

#assistants ⇒ Telnyx::Resources::AI::Assistants (readonly)

Configure AI assistant specifications

Returns:



8
9
10
 
# File 'lib/telnyx/resources/ai.rb', line 8

def assistants
  @assistants
end

#audio ⇒ Telnyx::Resources::AI::Audio (readonly)

Returns:



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

def audio
  @audio
end

#chat ⇒ Telnyx::Resources::AI::Chat (readonly)

Returns:



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

def chat
  @chat
end

#clusters ⇒ Telnyx::Resources::AI::Clusters (readonly)

Identify common themes and patterns in your embedded documents

Returns:



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

def clusters
  @clusters
end

#conversations ⇒ Telnyx::Resources::AI::Conversations (readonly)

Manage historical AI assistant conversations

Returns:



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

def conversations
  @conversations
end

#embeddings ⇒ Telnyx::Resources::AI::Embeddings (readonly)

Embed documents and perform text searches

Returns:



26
27
28
 
# File 'lib/telnyx/resources/ai.rb', line 26

def embeddings
  @embeddings
end

#fine_tuning ⇒ Telnyx::Resources::AI::FineTuning (readonly)

Returns:



29
30
31
 
# File 'lib/telnyx/resources/ai.rb', line 29

def fine_tuning
  @fine_tuning
end

#integrations ⇒ Telnyx::Resources::AI::Integrations (readonly)

Returns:



32
33
34
 
# File 'lib/telnyx/resources/ai.rb', line 32

def integrations
  @integrations
end

#mcp_servers ⇒ Telnyx::Resources::AI::McpServers (readonly)

Returns:



35
36
37
 
# File 'lib/telnyx/resources/ai.rb', line 35

def mcp_servers
  @mcp_servers
end

#missions ⇒ Telnyx::Resources::AI::Missions (readonly)

Returns:



38
39
40
 
# File 'lib/telnyx/resources/ai.rb', line 38

def missions
  @missions
end

#openai ⇒ Telnyx::Resources::AI::OpenAI (readonly)

Returns:



41
42
43
 
# File 'lib/telnyx/resources/ai.rb', line 41

def openai
  @openai
end

#tools ⇒ Telnyx::Resources::AI::Tools (readonly)

Configure AI assistant specifications

Returns:



45
46
47
 
# File 'lib/telnyx/resources/ai.rb', line 45

def tools
  @tools
end

Instance Method Details

#retrieve_conversation_histories(q:, filter_ingested_at_gte: nil, filter_ingested_at_lte: nil, filter_record_created_at_gte: nil, filter_record_created_at_lte: nil, filter_record_id: nil, filter_region_in: nil, filter_retention: nil, filter_user_id: nil, min_score: nil, page_number: nil, page_size: nil, region: nil, request_options: {}) ⇒ Telnyx::Models::AIRetrieveConversationHistoriesResponse

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

Performs semantic vector search across conversation history records.

How it works:

  1. The query text is embedded into a 1024-dimensional vector using the multilingual-e5-large model.
  2. The vector is compared against indexed record chunks using semantic similarity search.
  3. When no region is specified, all regions are queried in parallel (fan-out) and results are merged by score.
  4. Results are ranked by similarity score (descending) and paginated via page[number] / page[size].

Authentication: Requires a Telnyx API key via Authorization: Bearer <key>. Results are automatically scoped to the caller's organization — organization_id is injected from the auth token and cannot be overridden.

Chunking: Records are split into chunks of up to 480 tokens with 64-token overlap at ingestion time. Each search result represents a single chunk, with chunk_index and chunk_total indicating its position within the original record.

Filtering: Use filter[field][operator]=value query parameters to narrow results before vector search.

Top-level filterable fields: user_id, region, record_id, record_created_at, ingested_at, retention

Note: retention is filter-only — it can be used to narrow results but is not returned in the response body.

Metadata fields: any field not in the list above is resolved to data.metadata.<field> (e.g., filter[language]=en → data.metadata.language).

Supported filter operators:

  • eq — exact match (default when no operator specified)
  • in — match any of comma-separated values
  • gte, gt, lte, lt — range comparisons (useful for date filtering)
  • contains — wildcard substring match

Examples:

GET /v2/ai/conversation_histories?q=billing+issue&page[size]=10
GET /v2/ai/conversation_histories?q=setup+guide&region=USA&min_score=0.5
GET /v2/ai/conversation_histories?q=refund&filter[record_created_at][gte]=2026-01-01T00:00:00Z
GET /v2/ai/conversation_histories?q=outage&filter[region][in]=USA,DEU
GET /v2/ai/conversation_histories?q=hold+time&filter[language]=en

Parameters:

  • q (String) —

    Natural language search query. The text is embedded into a 1024-dimensional vect

  • filter_ingested_at_gte (Time) —

    Only include records ingested (chunked, embedded, and indexed) on or after this

  • filter_ingested_at_lte (Time) —

    Only include records ingested (chunked, embedded, and indexed) on or before this

  • filter_record_created_at_gte (Time) —

    Only include records whose original creation time is on or after this ISO 8601 t

  • filter_record_created_at_lte (Time) —

    Only include records whose original creation time is on or before this ISO 8601

  • filter_record_id (String) —

    Filter to chunks belonging to a specific parent record (exact match).

  • filter_region_in (String) —

    Filter by the region stored on the record. Comma-separated to match multiple reg

  • filter_retention (String) —

    Filter by retention policy (exact match). Filter-only: not returned in the respo

  • filter_user_id (String) —

    Filter to records owned by a specific user (exact match).

  • min_score (Float) —

    Minimum cosine similarity score threshold (0.0 to 1.0). Results below this thres

  • page_number (Integer) —

    Page number to return (1-based). Defaults to 1.

  • page_size (Integer) —

    Number of results per page. Defaults to 20, maximum 100.

  • region (Symbol, Telnyx::Models::AIRetrieveConversationHistoriesParams::Region) —

    Restrict search to a specific region. When omitted, all regions are queried in p

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

Returns:

See Also:



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

def retrieve_conversation_histories(params)
  parsed, options = Telnyx::AIRetrieveConversationHistoriesParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "ai/conversation_histories",
    query: query.transform_keys(
      filter_ingested_at_gte: "filter[ingested_at][gte]",
      filter_ingested_at_lte: "filter[ingested_at][lte]",
      filter_record_created_at_gte: "filter[record_created_at][gte]",
      filter_record_created_at_lte: "filter[record_created_at][lte]",
      filter_record_id: "filter[record_id]",
      filter_region_in: "filter[region][in]",
      filter_retention: "filter[retention]",
      filter_user_id: "filter[user_id]",
      page_number: "page[number]",
      page_size: "page[size]"
    ),
    model: Telnyx::Models::AIRetrieveConversationHistoriesResponse,
    options: options
  )
end

#summarize(bucket:, filename:, system_prompt: nil, request_options: {}) ⇒ Telnyx::Models::AISummarizeResponse

Generate a summary of a file's contents.

Supports the following text formats:

  • PDF, HTML, txt, json, csv

Supports the following media formats (billed for both the transcription and summary):

  • flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm
  • Up to 100 MB

Parameters:

  • bucket (String) —

    The name of the bucket that contains the file to be summarized.

  • filename (String) —

    The name of the file to be summarized.

  • system_prompt (String) —

    A system prompt to guide the summary generation.

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

Returns:

See Also:



183
184
185
186
187
188
189
190
191
192
 
# File 'lib/telnyx/resources/ai.rb', line 183

def summarize(params)
  parsed, options = Telnyx::AISummarizeParams.dump_request(params)
  @client.request(
    method: :post,
    path: "ai/summarize",
    body: parsed,
    model: Telnyx::Models::AISummarizeResponse,
    options: options
  )
end