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

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:



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

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(body:, request_options: {}) ⇒ Hash{Symbol=>Object}

Deprecated.

Deprecated: Use ‘POST /v2/ai/openai/responses` instead. This endpoint is compatible with the [OpenAI Responses API](developers.openai.com/api/reference/responses/overview) 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[:body],
    model: Telnyx::Internal::Type::HashOf[Telnyx::Internal::Type::Unknown],
    options: options
  )
end

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

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:



95
96
97
98
99
100
101
102
 
# File 'lib/telnyx/resources/ai.rb', line 95

def retrieve_models(params = {})
  @client.request(
    method: :get,
    path: "ai/models",
    model: Telnyx::Models::AIRetrieveModelsResponse,
    options: params[:request_options]
  )
end

#search_conversation_histories(q:, record_type:, filter_document_id: nil, 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, region: nil, top_k: nil, request_options: {}) ⇒ Telnyx::Models::AISearchConversationHistoriesResponse

Some parameter documentations has been truncated, see Models::AISearchConversationHistoriesParams 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 sent to regional OpenSearch clusters for kNN search using HNSW cosine similarity.

  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 cosine similarity score (descending) and truncated to ‘top_k`.

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[operator]=value` query parameters to narrow results before vector search.

Top-level filterable fields: ‘user_id`, `record_type`, `region`, `document_id`, `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>` in OpenSearch (e.g., `filter=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&record_type=voice&top_k=10 GET /v2/ai/conversation_histories?q=setup+guide&record_type=knowledge_base&region=USA&min_score=0.5 GET /v2/ai/conversation_histories?q=refund&record_type=voice&filter[gte]=2026-01-01T00:00:00Z GET /v2/ai/conversation_histories?q=outage&record_type=voice&filter[in]=USA,DEU GET /v2/ai/conversation_histories?q=hold+time&record_type=voice&filter=en “`

Parameters:

  • q (String) —

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

  • record_type (Symbol, Telnyx::Models::AISearchConversationHistoriesParams::RecordType) —

    The type of records to search. Each record type is stored in a separate vector i

  • filter_document_id (String) —

    Filter by document identifier (exact match). Populated for knowledge_base record

  • 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

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

    Restrict search to a specific region’s OpenSearch cluster. When omitted, all reg

  • top_k (Integer) —

    Maximum number of results to return. Defaults to 20, maximum 100.

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

Returns:

See Also:



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

def search_conversation_histories(params)
  parsed, options = Telnyx::AISearchConversationHistoriesParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "ai/conversation_histories",
    query: query.transform_keys(
      filter_document_id: "filter[document_id]",
      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]"
    ),
    model: Telnyx::Models::AISearchConversationHistoriesResponse,
    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:



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

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