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:



254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/telnyx/resources/ai.rb', line 254

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)

Generate text with LLMs

Returns:



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

def chat
  @chat
end

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

Identify common themes and patterns in your embedded documents

Returns:



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

def clusters
  @clusters
end

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

Manage historical AI assistant conversations

Returns:



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

def conversations
  @conversations
end

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

Embed documents and perform text searches

Returns:



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

def embeddings
  @embeddings
end

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

Returns:



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

def fine_tuning
  @fine_tuning
end

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

Returns:



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

def integrations
  @integrations
end

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

Returns:



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

def mcp_servers
  @mcp_servers
end

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

Returns:



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

def missions
  @missions
end

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

Returns:



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

def openai
  @openai
end

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

Configure AI assistant specifications

Returns:



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

def tools
  @tools
end

Instance Method Details

#create_response_deprecated(response_request:, request_options: {}) ⇒ Hash{Symbol=>Object}

Deprecated.

Deprecated: Use POST /v2/ai/openai/responses instead. This endpoint is compatible with the OpenAI Responses API and may be used with the OpenAI JS or Python SDK. Response id parameter is not supported at the moment. Use the conversation parameter with a Telnyx Conversation ID to leverage persistent conversations.

Parameters:

Returns:

  • (Hash{Symbol=>Object})

See Also:



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

def create_response_deprecated(params)
  parsed, options = Telnyx::AICreateResponseDeprecatedParams.dump_request(params)
  @client.request(
    method: :post,
    path: "ai/responses",
    body: parsed[:response_request],
    model: Telnyx::Internal::Type::HashOf[Telnyx::Internal::Type::Unknown],
    options: options
  )
end

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



164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/telnyx/resources/ai.rb', line 164

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

#retrieve_models(request_options: {}) ⇒ Telnyx::Models::ModelsResponse

Deprecated.

Deprecated: Use GET /v2/ai/openai/models instead.

Returns the same ModelsResponse payload as the OpenAI-compatible endpoint — open-source LLMs hosted on Telnyx (e.g. moonshotai/Kimi-K2.6, zai-org/GLM-5.1-FP8, MiniMaxAI/MiniMax-M2.7), embedding models, and fine-tuned models — kept around for backwards compatibility. New integrations should use /v2/ai/openai/models.

Model ids follow the {organization}/{model_name} convention from Hugging Face.

Parameters:

Returns:

See Also:



206
207
208
209
210
211
212
213
 
# File 'lib/telnyx/resources/ai.rb', line 206

def retrieve_models(params = {})
  @client.request(
    method: :get,
    path: "ai/models",
    model: Telnyx::ModelsResponse,
    options: params[:request_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:



240
241
242
243
244
245
246
247
248
249
 
# File 'lib/telnyx/resources/ai.rb', line 240

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