falaai-api 1.21.54 → 1.21.67

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2124fbb4e1ed6511a5749326aa954da95d70c298e244a5b80dc09c214b66f8d3
-  data.tar.gz: ea43b97e08f90260511970b2616066aef0433d0948a512a12e34c36bfa7ba0e2
+  metadata.gz: 277ba7b89298c6e8064b94c458f36a6db3a2d679a33ba160e989ce3fec496635
+  data.tar.gz: ba21f1c150fb4dc71d6a699e2c29b8ee01abf8cf6fc99e1449bb659b46c1ef47
 SHA512:
-  metadata.gz: 9c41a3551e9c471ff24cdfbd1849ff772af1ed55844834dfb22299d0a6f5f44e5bd7b16f2ac3595db8df0a02d7c62771c53fd0b02982351f883cec089dfe5808
-  data.tar.gz: c90657bb08a24f46ca3854bea50be4f6e1a05e60885c3afab871f51925fc238b2b98565456a43d11aa5e3d945081f217f704a9dc1d2696e8eed8b0494d303627
+  metadata.gz: 881ee96022301c48bbdb94a05489ceb87b4aaeefa1d0f3b897e155e1b65aa6fb67916bc67e42b2cf099c752ca00a775f35b5929d4abeee74661581a73cdc0a5a
+  data.tar.gz: 2825a69f51a3782da91f57e605f76c49f519ce3f7fa1c965cb3a3297dcc58de4e568ccceda9efc92c9da51d1c9fca4ffe19ccb9c0bbe2eba43dd009a191b272e

data/README.md

@@ -50,6 +50,8 @@ FALAAI_API_KEY=fai_xxxxxxxx
 
 ### 3. Transcribe a call (audio -> text)
 
+> No audio file? See **[audio help](https://falaai.action.tec.br/api/audio-help)** for accepted formats and limits.
+
 ```ruby
 require 'falaai-api'
 
@@ -95,15 +97,16 @@ client = FalaAI::ApiClient.new(config)
 analysis = FalaAI::AnalysisApi.new(client)
 
 transcript = 'Good morning, how can I help? I need to cancel my subscription.'
+dialog = "Speaker 1: [00:00:00.100 - 00:00:03.100] Good morning, how can I help?\nSpeaker 2: [00:00:03.100 - 00:00:06.200] I need to cancel my subscription."
 
 # 5 analyses in one call: summary, reason, action, topic, sentiment
 diagnostic, _status = analysis.create_diagnostic_v1_analyze_diagnostic_post_with_http_info(
   FalaAI::DiagnosticRequest.new(text: transcript, language: 'pt-BR', duration_seconds: 81.46)
 )
 
-# Compliance risk score + violations + auditable report
+# Compliance risk score + violations + auditable report (Risk Audit requires a diarized 'dialog', not 'text')
 audit, _status = analysis.create_risk_audit_v1_analyze_risk_audit_post_with_http_info(
-  FalaAI::RiskAuditRequest.new(text: transcript, language: 'pt-BR', response_language: 'pt-BR', duration_seconds: 81.46)
+  FalaAI::RiskAuditRequest.new(dialog: dialog, language: 'pt-BR', response_language: 'pt-BR', duration_seconds: 81.46)
 )
 ```
 
@@ -149,6 +152,8 @@ FalaAI is **language-independent** - integrate at **any point** of your pipeline
 
 > These are **integration examples**, not certified native integrations. Any platform can integrate through **REST / cURL** - the standard, language-independent path. Native ingestion connectors are on the roadmap.
 
+**This SDK's language (Ruby):** FalaAI is language-independent; this package targets **Ruby** backends (your target platform does not need to be built in Ruby).
+
 ## BYOT - Bring Your Own Transcription
 
 Already have speech-to-text (Whisper, Deepgram, AssemblyAI, your own)? **Skip Transcription** and send the text straight to **Diagnostic** and/or **Risk Audit**. You only pay for what you use.
@@ -171,7 +176,7 @@ Already have speech-to-text (Whisper, Deepgram, AssemblyAI, your own)? **Skip Tr
 
 ## Examples
 
-Runnable examples in [`examples/`](./examples): `health.rb`, `transcribe.rb`, `diagnose.rb`, `audit.rb`, `whatsapp.rb`.
+Runnable examples in [`examples/`](https://github.com/ActionTecBr/falaai-api-ruby/tree/main/examples): `health.rb`, `transcribe.rb`, `diagnose.rb`, `audit.rb`, `whatsapp.rb`.
 
 ## Authentication
 
@@ -203,7 +208,7 @@ end
 | Requirement | Version |
 |---|---|
 | Ruby | 2.7+ |
-| API | v1.21.54 |
+| API | v1.21.67 |
 
 ## Documentation
 
@@ -216,7 +221,7 @@ end
 
 ## Versioning
 
-Semantic versioning; the SDK version tracks the API version (`1.21.54`). See [CHANGELOG.md](CHANGELOG.md) and [Releases](https://github.com/ActionTecBr/falaai-api-ruby/releases).
+Semantic versioning; the SDK version tracks the API version (`1.21.67`). See [CHANGELOG.md](CHANGELOG.md) and [Releases](https://github.com/ActionTecBr/falaai-api-ruby/releases).
 
 ## Security
 
@@ -235,4 +240,5 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 - Website: <https://falaai.action.tec.br>
 - API base URL: <https://api01-falaai.action.tec.br>
 - GitHub organization: <https://github.com/ActionTecBr>
+- Run in Postman: [![Run in Postman](https://run.pstmn.io/button.svg)](https://www.postman.com/liviopanizza-7615625/falaai-api/collection/tzxf8gc/falaai-api)
 - Other SDKs: Python, Node.js, PHP, Go, Java, .NET.

data/docs/AnalysisApi.md

@@ -14,6 +14,8 @@ All URIs are relative to *https://api01-falaai.action.tec.br*
 
 Analyze a call transcript — 5 parallel analyses
 
+Analyzes a call transcript and returns six structured blocks: dialogue summary, contact reason, identified action, theme label, predominant sentiment and identified participants with roles, names, confidence and evidence; use it for a fast, generic diagnosis of what happened in a call, and use /v1/analyze/riskAudit instead when the goal is compliance violation auditing. Provide at least one of dialog (primary source: diarized transcript in the format 'Speaker 1: [00:00:00.540 - 00:00:01.139] text', speaker labels accepted in any case as Speaker, Interlocutor, Hablante, Locutor or Orador plus number) or text (plain transcript fallback), each up to 300,000 characters; when dialog is used duration_seconds is required by the schema and, when provided, must be >= the last turn end time. Required: language; optional: model (always 'falaai-diagnostic-1'), audio_events, response_language (language of the results, defaulting to language), participants (up to 10 with interlocutor and optional name and role agent/client/bot, ground truth when the role is informed and otherwise inferred), call_direction (inferred when omitted), client_reference_id (echoed verbatim, charset [A-Za-z0-9 _/:.-], max 60). Returns id, object 'analysis', response_language, analysis with the six blocks, usage (characters, credits_consumed, processing_ms) and html_report (base64 gzip) only when dialog is provided; with text-only input the participant roles are forced to confidence 'low'. Credits are charged per character of the transcript (0.03/char, counted without speaker labels, timestamps and inline expression tokens, minimum 500 characters, plus 50 characters per audio event) and the amount charged is returned in usage.credits_consumed. Stateless: neither the transcript nor the analysis is persisted (only billing and usage metadata is logged), protecting personal data under LGPD.
+
 ### Examples
 
 ```ruby
@@ -81,6 +83,8 @@ end
 
 Compliance Risk Audit — conversation compliance analysis
 
+Runs a compliance risk audit on a diarized call transcript, detecting violations and positives, applying the ISO 31000 risk matrix, classifying the conversation into a level and returning the verdict with the applied actions and the NIST/OWASP risk framework enquadramento; use it for compliance and quality audits of company-agent-to-client calls, not for generic conversation summarization. Required fields: dialog (diarized transcript in the format 'Speaker 1: [00:00:00.540 - 00:00:01.139] text', speaker labels accepted in any case as Speaker, Interlocutor, Hablante, Locutor or Orador plus number; plain text is not accepted; max 300,000 characters), duration_seconds (total audio duration in seconds, must be >= the last turn end time) and language plus response_language (only pt-BR, en-US or es-ES). Optional: model (always 'falaai-risk-audit-1'), audio_events (up to 500, each requiring event and start_s), participants (up to 10 with interlocutor and role agent/client/bot, ground truth when provided, else inferred), call_direction (inbound/outbound, inferred when omitted), response_format (only 'v2'), client_reference_id (echoed verbatim, charset [A-Za-z0-9 _/:.-], max 60). Returns response (V2) with meta+usage, participants, verdict with level and applied actions, scores, detections (violations, positives, client alerts), analysis frameworks, timeline, categories_summary, executive summary, scoring explanation and an HTML report (gzip+base64). Credits are charged per character of the spoken transcript (0.09/char, counted without speaker labels and inline expression tokens, minimum 1,000 characters, plus 50 characters per audio event) and a minimum-cost guard may raise the final amount, so response.meta.usage.credits_consumed is the amount actually charged. Stateless: neither the transcript nor the analysis is persisted (only billing and usage metadata is logged), protecting personal data under LGPD.
+
 ### Examples
 
 ```ruby

data/docs/DiagnosticUsage.md

@@ -5,7 +5,7 @@
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
 | **characters** | **Integer** | Total characters analyzed |  |
-| **credits_consumed** | **Integer** | Credits consumed: max(ceil(chars/500)*3, 3) * 5 |  |
+| **credits_consumed** | **Float** | Credits consumed: per character, round(max(characters, 500) * 0.03, 2) |  |
 | **processing_ms** | **Integer** | Total processing time in milliseconds |  |
 
 ## Example

data/docs/ResponseExtractConversationsV1WhatsappExtractconversationsPost.md

@@ -0,0 +1,42 @@
+# FalaAI::ResponseExtractConversationsV1WhatsappExtractconversationsPost
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **id** | **String** | Unique identifier. Prefix 'wc-' + UUID |  |
+| **object** | **String** | Object type. Always 'whatsapp_preview' |  |
+| **usage** | [**WhatsappUsage**](WhatsappUsage.md) | Usage and processing information |  |
+| **conversations** | [**Array<WhatsappConversation>**](WhatsappConversation.md) | Segmented conversations |  |
+| **client_reference_id** | **String** | Client-supplied ID echoed verbatim (if provided) | [optional] |
+| **meta** | [**WhatsappMeta**](WhatsappMeta.md) | Segmentation parameters and counts |  |
+| **dry_run** | **Boolean** | Always true (preview: no AI call, no charge) |  |
+| **credits_charged** | **Integer** | Always 0 in preview |  |
+| **credits_total** | **Float** | TOTAL credits = exact SUM of the selected conversations (2 decimals, NO rounding up) |  |
+| **params** | [**WhatsappPreviewParams**](WhatsappPreviewParams.md) | Filter parameters actually used (reuse them in the extraction) |  |
+| **windows** | [**Array<WhatsappPreviewWindow>**](WhatsappPreviewWindow.md) | Explicit windows used (empty when a single start/end range was used) |  |
+| **items** | [**Array<WhatsappPreviewItem>**](WhatsappPreviewItem.md) | Per-conversation detail (send back as `windows` to extract only what you want) |  |
+| **warnings** | **Array<String>** | Human-readable notices about what would be ignored |  |
+
+## Example
+
+```ruby
+require 'falaai-api'
+
+instance = FalaAI::ResponseExtractConversationsV1WhatsappExtractconversationsPost.new(
+  id: null,
+  object: null,
+  usage: null,
+  conversations: null,
+  client_reference_id: null,
+  meta: null,
+  dry_run: null,
+  credits_charged: null,
+  credits_total: null,
+  params: null,
+  windows: null,
+  items: null,
+  warnings: null
+)
+```
+

data/docs/RiskAuditAppliedActionV2.md

@@ -8,8 +8,6 @@
 | **label** | **String** | Action label |  |
 | **description** | **String** | Action description |  |
 | **priority** | **String** | CRITICO/ALTO/MEDIO/BAIXO |  |
-| **color** | **String** | Color | [optional][default to ''] |
-| **icon** | **String** | Icon | [optional][default to ''] |
 | **condition** | **String** | Condition | [optional] |
 | **reason** | **String** | Reason | [optional][default to ''] |
 
@@ -23,8 +21,6 @@ instance = FalaAI::RiskAuditAppliedActionV2.new(
   label: null,
   description: null,
   priority: null,
-  color: null,
-  icon: null,
   condition: null,
   reason: null
 )

data/docs/RiskAuditAuditDecisionsV2.md

@@ -6,7 +6,6 @@
 | ---- | ---- | ----------- | ----- |
 | **risk_origin** | **String** | Risk origin | [optional] |
 | **has_zero_tolerance_violation** | **Boolean** | Has zero-tolerance violation | [optional] |
-| **deterministic_validator_changes** | **Array<Object>** | Deterministic validator changes | [optional] |
 
 ## Example
 
@@ -15,8 +14,7 @@ require 'falaai-api'
 
 instance = FalaAI::RiskAuditAuditDecisionsV2.new(
   risk_origin: null,
-  has_zero_tolerance_violation: null,
-  deterministic_validator_changes: null
+  has_zero_tolerance_violation: null
 )
 ```
 

data/docs/RiskAuditConversationScoresV2.md

@@ -12,7 +12,6 @@
 | **positive_negative_ratio** | **Object** | Positive:negative ratio | [optional] |
 | **global_risk_severity** | **String** | Global risk severity code | [optional] |
 | **global_risk_severity_label** | **String** | Global risk severity label | [optional] |
-| **global_risk_severity_color** | **String** | Global risk severity color | [optional] |
 | **risk_likelihood_avg** | **Float** | Risk likelihood avg | [optional] |
 | **risk_impact_avg** | **Float** | Risk impact avg | [optional] |
 
@@ -30,7 +29,6 @@ instance = FalaAI::RiskAuditConversationScoresV2.new(
   positive_negative_ratio: null,
   global_risk_severity: null,
   global_risk_severity_label: null,
-  global_risk_severity_color: null,
   risk_likelihood_avg: null,
   risk_impact_avg: null
 )

data/docs/RiskAuditDetectionItemV2.md

@@ -7,50 +7,15 @@
 | **turn** | **Integer** | Turn number | [optional] |
 | **interlocutor** | **String** | Speaker | [optional] |
 | **role** | **String** | Role | [optional] |
-| **timestamp_start_s** | **Float** | Start (s) | [optional] |
-| **timestamp_end_s** | **Float** | End (s) | [optional] |
 | **timestamp_formatted** | **String** | Formatted timestamp | [optional] |
 | **term_text** | **String** | Detected term | [optional] |
-| **suggested_term_for_bank** | **Object** | Suggested term for bank | [optional] |
-| **category** | **String** | Category code | [optional] |
 | **category_label** | **String** | Category label (i18n) |  |
-| **category_color** | **String** | Category color | [optional] |
-| **category_icon** | **String** | Category icon | [optional] |
+| **subcategory_label** | **String** | Subcategory label (i18n) | [optional] |
 | **criticality** | **String** | Criticality | [optional] |
-| **category_threshold** | **Float** | Category threshold | [optional] |
-| **category_type** | **String** | Category type | [optional] |
-| **category_group** | **String** | Category group label (i18n) |  |
-| **nature** | **String** | Nature | [optional] |
-| **llm_confidence** | **Float** | LLM confidence | [optional] |
+| **status** | **String** | Status | [optional] |
 | **reason** | **String** | Reason | [optional] |
-| **is_valid_context** | **Boolean** | Valid context | [optional] |
-| **risk_probability** | **Float** | Risk probability | [optional] |
-| **risk_impact** | **Float** | Risk impact | [optional] |
-| **category_weight** | **Float** | Category weight | [optional] |
-| **turn_sentiment** | **String** | Turn sentiment | [optional] |
-| **intensity** | **Object** | Intensity | [optional] |
-| **mod_applied** | **Float** | Total modifier applied | [optional] |
-| **mac_applied** | **Float** | Audio modifier applied | [optional] |
-| **mvad_applied** | **Float** | Intensity modifier applied | [optional] |
-| **mod_formula** | **String** | Modifier formula | [optional] |
-| **mac_details** | **Array<Hash<String, Object>>** | MAC details | [optional] |
-| **calibration_reason** | **String** | Calibration reason | [optional] |
 | **final_score** | **Float** | Final score | [optional] |
-| **final_score_formula** | **String** | Final score formula | [optional] |
-| **conversation_limit** | **Object** | Conversation limit | [optional] |
-| **apply_saturation** | **Boolean** | Apply saturation | [optional] |
-| **block_repetition** | **Boolean** | Block repetition | [optional] |
-| **status** | **String** | Status | [optional] |
-| **effective_impact** | **Float** | Effective impact | [optional] |
-| **saturation_factor** | **Float** | Saturation factor | [optional] |
-| **saturation_formula** | **String** | Saturation formula | [optional] |
-| **threshold_formula** | **String** | Threshold formula | [optional] |
-| **blocked_formula** | **String** | Blocked formula | [optional] |
-| **reconciliation_note** | **String** | Reconciliation note | [optional] |
 | **violated_frameworks** | **Array<Object>** | Violated frameworks | [optional] |
-| **citation_fidelity** | **Boolean** | Citation fidelity | [optional][default to true] |
-| **subcategory** | **String** | Subcategory code | [optional] |
-| **subcategory_label** | **String** | Subcategory label (i18n) | [optional] |
 
 ## Example
 
@@ -61,50 +26,15 @@ instance = FalaAI::RiskAuditDetectionItemV2.new(
   turn: null,
   interlocutor: null,
   role: null,
-  timestamp_start_s: null,
-  timestamp_end_s: null,
   timestamp_formatted: null,
   term_text: null,
-  suggested_term_for_bank: null,
-  category: null,
   category_label: null,
-  category_color: null,
-  category_icon: null,
+  subcategory_label: null,
   criticality: null,
-  category_threshold: null,
-  category_type: null,
-  category_group: null,
-  nature: null,
-  llm_confidence: null,
+  status: null,
   reason: null,
-  is_valid_context: null,
-  risk_probability: null,
-  risk_impact: null,
-  category_weight: null,
-  turn_sentiment: null,
-  intensity: null,
-  mod_applied: null,
-  mac_applied: null,
-  mvad_applied: null,
-  mod_formula: null,
-  mac_details: null,
-  calibration_reason: null,
   final_score: null,
-  final_score_formula: null,
-  conversation_limit: null,
-  apply_saturation: null,
-  block_repetition: null,
-  status: null,
-  effective_impact: null,
-  saturation_factor: null,
-  saturation_formula: null,
-  threshold_formula: null,
-  blocked_formula: null,
-  reconciliation_note: null,
-  violated_frameworks: null,
-  citation_fidelity: null,
-  subcategory: null,
-  subcategory_label: null
+  violated_frameworks: null
 )
 ```
 

data/docs/RiskAuditSummaryV2.md

@@ -11,8 +11,6 @@
 | **blocked** | **Integer** | Blocked detections | [optional] |
 | **audio_events_used** | **Integer** | Audio events used | [optional] |
 | **audio_events_aggravated** | **Integer** | Audio events aggravated | [optional] |
-| **mac_audio_applied** | **Object** | MAC audio applied | [optional] |
-| **mvad_applied** | **Object** | MVAD applied | [optional] |
 | **total_participants** | **Integer** | Total participants | [optional] |
 | **total_agents** | **Integer** | Total agents | [optional] |
 | **total_clients** | **Integer** | Total clients | [optional] |
@@ -34,8 +32,6 @@ instance = FalaAI::RiskAuditSummaryV2.new(
   blocked: null,
   audio_events_used: null,
   audio_events_aggravated: null,
-  mac_audio_applied: null,
-  mvad_applied: null,
   total_participants: null,
   total_agents: null,
   total_clients: null,

data/docs/RiskAuditUsageV2.md

@@ -5,7 +5,7 @@
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
 | **characters** | **Integer** | Characters analyzed |  |
-| **credits_consumed** | **Integer** | Credits consumed |  |
+| **credits_consumed** | **Float** | Credits consumed |  |
 | **processing_ms** | **Integer** | Processing time (ms) |  |
 
 ## Example

data/docs/RiskAuditVerdictV2.md

@@ -6,11 +6,8 @@
 | ---- | ---- | ----------- | ----- |
 | **label** | **String** | Human-readable verdict | [optional] |
 | **level_code** | **String** | Classification level code | [optional] |
-| **color** | **String** | Level color | [optional] |
-| **icon** | **String** | Level icon | [optional] |
 | **risk_matrix** | **Hash<String, Object>** | Risk matrix | [optional] |
 | **applied_actions** | [**Array<RiskAuditAppliedActionV2>**](RiskAuditAppliedActionV2.md) | Applied actions | [optional] |
-| **decision_details** | **Object** | Decision details | [optional] |
 
 ## Example
 
@@ -20,11 +17,8 @@ require 'falaai-api'
 instance = FalaAI::RiskAuditVerdictV2.new(
   label: null,
   level_code: null,
-  color: null,
-  icon: null,
   risk_matrix: null,
-  applied_actions: null,
-  decision_details: null
+  applied_actions: null
 )
 ```
 

data/docs/SpeechApi.md

@@ -13,6 +13,8 @@ All URIs are relative to *https://api01-falaai.action.tec.br*
 
 Transcribe audio to text
 
+Transcribes one uploaded audio file into text with speaker diarization and timestamped audio events (laughs, sighs, pauses), returning the full transcript, a turn-by-turn dialog with speaker labels and start/end timestamps, the detected events and the word count. Use it when a recording must become text for analysis, review or storage of the transcript. The required file field takes a single audio upload limited to 1GB and 3 hours, with accepted MIME types audio/mpeg, audio/mp3, audio/mp4, audio/m4a, audio/wav, audio/wave, audio/x-wav, audio/flac, audio/x-flac, audio/ogg, audio/opus, video/ogg, audio/webm, video/webm, audio/aac and audio/x-aac. model is optional and defaults to falaai-transcribe-1, the only supported value; language is an optional two-letter code (pt, en, es, fr, de, it, ja, ko, nl, pl, ru, tr, zh, vi, id, th, ar, hi, cs, da, el, fi, he, hu, ms, no, ro, sk, sv, ta, uk) that forces the audio language and is auto-detected when omitted; client_reference_id is optional, charset A-Za-z0-9 space _/:.- up to 60 chars, echoed verbatim (not idempotency). Billing is 1 credit per second of processed audio with a minimum of 10 credits per request, rounded to 2 decimals; usage reports credits_consumed and processing_ms. Stateless: the audio is processed in memory and never persisted (LGPD). Returns id (tr-), language, language_confidence, duration_seconds, text, dialog, audio_events, event_types, word_count and input metadata (duration, format, codec, sample rate, channels).
+
 ### Examples
 
 ```ruby

data/docs/TranscriptionUsage.md

@@ -5,7 +5,7 @@
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
 | **audio_seconds** | **Float** | Actual audio duration processed in seconds |  |
-| **credits_consumed** | **Integer** | Number of credits consumed in this request |  |
+| **credits_consumed** | **Float** | Number of credits consumed in this request |  |
 | **processing_ms** | **Integer** | Total processing time in milliseconds |  |
 
 ## Example

data/docs/WhatsappApi.md

@@ -9,10 +9,12 @@ All URIs are relative to *https://api01-falaai.action.tec.br*
 
 ## extract_conversations_v1_whatsapp_extract_conversations_post
 
-> <WhatsappConversationsResponse> extract_conversations_v1_whatsapp_extract_conversations_post(file, start, _end, timezone, date_format, opts)
+> <ResponseExtractConversationsV1WhatsappExtractconversationsPost> extract_conversations_v1_whatsapp_extract_conversations_post(file, timezone, date_format, opts)
 
 Extract and segment WhatsApp conversations from an export
 
+Extracts and segments the conversations of a WhatsApp export (.zip or .txt containing chat.txt in UTF-8 with at least one turn) and, unless it is a preview, resolves each selected conversation with AI by transcribing voice/audio/video notes and describing visual expressions, returning the segmented conversations with speakers, dialogs, counts and usage. Use dry_run=true for a PREVIEW: it validates the file, segments the conversations, counts media and ESTIMATES the credits WITHOUT calling the AI and WITHOUT charging (credits_charged=0), returning object whatsapp_preview with credits_total, the params actually used, the windows, per-conversation items and warnings. The window is given either as a single start/end pair or as windows, a JSON string holding a non-empty list of sub-objects each with start and end; windows must not be combined with start/end, and a windows selection is the deduplicated chronological union of the overlaps, which bypasses the noise filter and keeps conversations that are monologues or below min_messages, while for a single window sending only one of start/end is rejected and empty/all-zeros values select the real period of the export, both being allowed to be omitted in dry_run while outside dry_run both absent is rejected. timezone and date_format are required, where date_format must be day_first, month_first or year_first. gap_minutes is optional (default 720) and splits conversations on idle gaps, min_messages is optional (default 2) and is the minimum messages kept per conversation outside the explicit windows selection, voice_note is optional (default true) and turns voice/audio/video media into text, expression is optional (default true) and describes visual expressions (figurinha, GIF, emoji), and client_reference_id is optional, echoed verbatim, charset A-Za-z0-9 space _/:.- up to 60 chars. Billing outside the preview is 0.15 credit per conversation plus 0.15 per figurinha, 0.18 per GIF and 0.1 per emoji (only with expression=true) plus 0.19 per second of voice/audio/video (only with voice_note=true), rounded to 2 decimals with no rounding up, and the preview credits_total is the same exact sum with 2 decimals; files are limited to 1GB and the endpoint is stateless (export and media processed in memory, temporary files removed, nothing persisted), returning object conversations with id (wc-), usage and the conversations (conversation_id, first_at, last_at, duration_seconds, speakers, dialog, message_count, characters) plus meta.
+
 ### Examples
 
 ```ruby
@@ -26,21 +28,23 @@ end
 
 api_instance = FalaAI::WhatsappApi.new
 file = File.new('/path/to/some/file') # File | 
-start = 'start_example' # String | 
-_end = '_end_example' # String | 
 timezone = 'timezone_example' # String | 
 date_format = 'date_format_example' # String | 
 opts = {
+  start: 'start_example', # String | Inicio da janela. Obrigatorio fora do dry_run; no dry_run ausente = primeiro turno do export.
+  _end: '_end_example', # String | Fim da janela. Obrigatorio fora do dry_run; no dry_run ausente = ultimo turno do export.
+  windows: 'windows_example', # String | Selecao explicita por varias janelas: JSON [{\\\"start\\\":\\\"...\\\",\\\"end\\\":\\\"...\\\"}]. Nao combinar com 'start'/'end'.
   gap_minutes: 8.14, # Float | 
   min_messages: 56, # Integer | 
   voice_note: true, # Boolean | Transcrever mensagens de voz/video gravadas na hora?
   expression: true, # Boolean | Descrever expressoes visuais (figurinha/GIF/imagem)?
+  dry_run: true, # Boolean | So analisa o arquivo: valida, segmenta e ESTIMA os creditos SEM chamar a IA e SEM debitar (credits_charged=0).
   client_reference_id: 'client_reference_id_example' # String | 
 }
 
 begin
   # Extract and segment WhatsApp conversations from an export
-  result = api_instance.extract_conversations_v1_whatsapp_extract_conversations_post(file, start, _end, timezone, date_format, opts)
+  result = api_instance.extract_conversations_v1_whatsapp_extract_conversations_post(file, timezone, date_format, opts)
   p result
 rescue FalaAI::ApiError => e
   puts "Error when calling WhatsappApi->extract_conversations_v1_whatsapp_extract_conversations_post: #{e}"
@@ -51,15 +55,15 @@ end
 
 This returns an Array which contains the response data, status code and headers.
 
-> <Array(<WhatsappConversationsResponse>, Integer, Hash)> extract_conversations_v1_whatsapp_extract_conversations_post_with_http_info(file, start, _end, timezone, date_format, opts)
+> <Array(<ResponseExtractConversationsV1WhatsappExtractconversationsPost>, Integer, Hash)> extract_conversations_v1_whatsapp_extract_conversations_post_with_http_info(file, timezone, date_format, opts)
 
 ```ruby
 begin
   # Extract and segment WhatsApp conversations from an export
-  data, status_code, headers = api_instance.extract_conversations_v1_whatsapp_extract_conversations_post_with_http_info(file, start, _end, timezone, date_format, opts)
+  data, status_code, headers = api_instance.extract_conversations_v1_whatsapp_extract_conversations_post_with_http_info(file, timezone, date_format, opts)
   p status_code # => 2xx
   p headers # => { ... }
-  p data # => <WhatsappConversationsResponse>
+  p data # => <ResponseExtractConversationsV1WhatsappExtractconversationsPost>
 rescue FalaAI::ApiError => e
   puts "Error when calling WhatsappApi->extract_conversations_v1_whatsapp_extract_conversations_post_with_http_info: #{e}"
 end
@@ -70,19 +74,21 @@ end
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
 | **file** | **File** |  |  |
-| **start** | **String** |  |  |
-| **_end** | **String** |  |  |
 | **timezone** | **String** |  |  |
 | **date_format** | **String** |  |  |
+| **start** | **String** | Inicio da janela. Obrigatorio fora do dry_run; no dry_run ausente &#x3D; primeiro turno do export. | [optional] |
+| **_end** | **String** | Fim da janela. Obrigatorio fora do dry_run; no dry_run ausente &#x3D; ultimo turno do export. | [optional] |
+| **windows** | **String** | Selecao explicita por varias janelas: JSON [{\\\&quot;start\\\&quot;:\\\&quot;...\\\&quot;,\\\&quot;end\\\&quot;:\\\&quot;...\\\&quot;}]. Nao combinar com &#39;start&#39;/&#39;end&#39;. | [optional] |
 | **gap_minutes** | **Float** |  | [optional][default to 720] |
 | **min_messages** | **Integer** |  | [optional][default to 2] |
 | **voice_note** | **Boolean** | Transcrever mensagens de voz/video gravadas na hora? | [optional][default to true] |
 | **expression** | **Boolean** | Descrever expressoes visuais (figurinha/GIF/imagem)? | [optional][default to true] |
+| **dry_run** | **Boolean** | So analisa o arquivo: valida, segmenta e ESTIMA os creditos SEM chamar a IA e SEM debitar (credits_charged&#x3D;0). | [optional][default to false] |
 | **client_reference_id** | **String** |  | [optional] |
 
 ### Return type
 
-[**WhatsappConversationsResponse**](WhatsappConversationsResponse.md)
+[**ResponseExtractConversationsV1WhatsappExtractconversationsPost**](ResponseExtractConversationsV1WhatsappExtractconversationsPost.md)
 
 ### Authorization
 

data/docs/WhatsappConversation.md

@@ -4,7 +4,7 @@
 
 | Name | Type | Description | Notes |
 | ---- | ---- | ----------- | ----- |
-| **conversation_id** | **String** | Conversation identifier in the batch |  |
+| **conversation_id** | **String** | Stable conversation id: yyyymmddhhmm-<first speaker>[-xN for >2 speakers] |  |
 | **first_at** | **String** | Real start (wall-clock, ISO) |  |
 | **last_at** | **String** | Real end (wall-clock, ISO) |  |
 | **duration_seconds** | **Float** | (last - first) + last turn duration |  |

data/docs/WhatsappMeta.md

@@ -21,6 +21,7 @@
 | **conversations_selected** | **Integer** | Final conversations returned |  |
 | **voice_note** | **Boolean** | Voice/video medias were transcribed |  |
 | **expression** | **Boolean** | Visual expressions were described |  |
+| **windows** | **Integer** | Explicit windows used (0 = simple start/end range) |  |
 
 ## Example
 
@@ -44,7 +45,8 @@ instance = FalaAI::WhatsappMeta.new(
   monologues_dropped: null,
   conversations_selected: null,
   voice_note: null,
-  expression: null
+  expression: null,
+  windows: null
 )
 ```
 

data/docs/WhatsappPreviewItem.md

@@ -0,0 +1,32 @@
+# FalaAI::WhatsappPreviewItem
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **conversation_id** | **String** | Stable id: yyyymmddhhmm-<first speaker>[-xN for >2 speakers] |  |
+| **first_at** | **String** | Conversation start (ISO) |  |
+| **last_at** | **String** | Conversation end (ISO) |  |
+| **duration_minutes** | **Float** | Conversation duration in minutes |  |
+| **messages** | **Integer** | Messages in this conversation |  |
+| **characters** | **Integer** | Characters of this conversation (estimate: media text is only replaced by tokens on extraction) |  |
+| **media** | [**WhatsappPreviewItemMedia**](WhatsappPreviewItemMedia.md) | Media of this conversation |  |
+| **credits** | [**WhatsappPreviewItemCredits**](WhatsappPreviewItemCredits.md) | Credits of this conversation |  |
+
+## Example
+
+```ruby
+require 'falaai-api'
+
+instance = FalaAI::WhatsappPreviewItem.new(
+  conversation_id: null,
+  first_at: null,
+  last_at: null,
+  duration_minutes: null,
+  messages: null,
+  characters: null,
+  media: null,
+  credits: null
+)
+```
+

data/docs/WhatsappPreviewItemBreakdown.md

@@ -0,0 +1,26 @@
+# FalaAI::WhatsappPreviewItemBreakdown
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **conversation** | **Float** | Conversation credit (0,15) |  |
+| **figurinha** | **Float** | Figurinha credits of this conversation |  |
+| **gif** | **Float** | GIF credits of this conversation |  |
+| **emoji** | **Float** | Emoji credits of this conversation |  |
+| **audio** | **Float** | Audio credits of this conversation |  |
+
+## Example
+
+```ruby
+require 'falaai-api'
+
+instance = FalaAI::WhatsappPreviewItemBreakdown.new(
+  conversation: null,
+  figurinha: null,
+  gif: null,
+  emoji: null,
+  audio: null
+)
+```
+

data/docs/WhatsappPreviewItemCredits.md

@@ -0,0 +1,20 @@
+# FalaAI::WhatsappPreviewItemCredits
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **total** | **Float** | Credits of THIS conversation (2 decimals, exact fraction — the charge is ONE ceil on the batch total) |  |
+| **breakdown** | [**WhatsappPreviewItemBreakdown**](WhatsappPreviewItemBreakdown.md) | Credits by component for THIS conversation |  |
+
+## Example
+
+```ruby
+require 'falaai-api'
+
+instance = FalaAI::WhatsappPreviewItemCredits.new(
+  total: null,
+  breakdown: null
+)
+```
+

data/docs/WhatsappPreviewItemMedia.md

@@ -0,0 +1,30 @@
+# FalaAI::WhatsappPreviewItemMedia
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **figurinha** | **Integer** | Figurinha occurrences in this conversation (0 quando expression=false) |  |
+| **gif** | **Integer** | GIF occurrences in this conversation (0 quando expression=false) |  |
+| **emoji** | **Integer** | Emoji occurrences in this conversation (0 quando expression=false) |  |
+| **ptt** | **Integer** | Voice/audio/video turns in this conversation (cobra 0,19/segundo SO quando voice_note=true) |  |
+| **ptt_seconds** | **Float** | Voice/video SECONDS counted in this conversation (0 quando voice_note=false) |  |
+| **anexos** | **Integer** | Image/document turns in this conversation (ANEXO: nunca cobrado) |  |
+| **by_type** | **Hash<String, Integer>** | Media turns by type in THIS conversation (voz/audio/video/imagem/figurinha/gif/arquivo/oculta/chamada) |  |
+
+## Example
+
+```ruby
+require 'falaai-api'
+
+instance = FalaAI::WhatsappPreviewItemMedia.new(
+  figurinha: null,
+  gif: null,
+  emoji: null,
+  ptt: null,
+  ptt_seconds: null,
+  anexos: null,
+  by_type: null
+)
+```
+