falaai-api 1.21.48 → 1.21.49
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +239 -339
- data/docs/AnalysisApi.md +33 -37
- data/docs/AudioEvent.md +5 -5
- data/docs/AudioInputMeta.md +5 -5
- data/docs/CreateEmailAlertRequest.md +3 -3
- data/docs/CreateWebhookRequest.md +4 -4
- data/docs/DiagnosticAudioEvent.md +5 -5
- data/docs/DiagnosticCategoricalAnalysis.md +3 -3
- data/docs/DiagnosticParticipant.md +22 -0
- data/docs/DiagnosticRequest.md +10 -4
- data/docs/DiagnosticResponse.md +4 -4
- data/docs/DiagnosticTextAnalysis.md +1 -1
- data/docs/DiagnosticUsage.md +3 -3
- data/docs/EmailAlertsApi.md +18 -18
- data/docs/HealthApi.md +3 -13
- data/docs/HealthResponse.md +6 -6
- data/docs/Participant.md +2 -2
- data/docs/ParticipantDiagnostic.md +5 -5
- data/docs/{AuditoriaRiscoAnalysisV2.md → RiskAuditAnalysisV2.md} +2 -2
- data/docs/{AuditoriaRiscoAppliedActionV2.md → RiskAuditAppliedActionV2.md} +2 -2
- data/docs/{AuditoriaRiscoAudioEventModelV2.md → RiskAuditAudioEventModelV2.md} +2 -2
- data/docs/{AuditoriaRiscoAuditDecisionsV2.md → RiskAuditAuditDecisionsV2.md} +2 -2
- data/docs/{AuditoriaRiscoConversationScoresV2.md → RiskAuditConversationScoresV2.md} +2 -2
- data/docs/{AuditoriaRiscoDetectionItemV2.md → RiskAuditDetectionItemV2.md} +2 -2
- data/docs/RiskAuditDetectionsV2.md +26 -0
- data/docs/{AuditoriaRiscoIndexerV2.md → RiskAuditIndexerV2.md} +2 -2
- data/docs/{AuditoriaRiscoMetaV2.md → RiskAuditMetaV2.md} +4 -4
- data/docs/{AuditoriaRiscoParticipantV2.md → RiskAuditParticipantV2.md} +2 -2
- data/docs/{AuditoriaRiscoParticipantsV2.md → RiskAuditParticipantsV2.md} +3 -3
- data/docs/{AuditoriaRiscoRequest.md → RiskAuditRequest.md} +12 -12
- data/docs/{AuditoriaRiscoScoresV2.md → RiskAuditScoresV2.md} +3 -3
- data/docs/{AuditoriaRiscoScoringExplanationV2.md → RiskAuditScoringExplanationV2.md} +2 -2
- data/docs/{AuditoriaRiscoSummaryV2.md → RiskAuditSummaryV2.md} +2 -2
- data/docs/{AuditoriaRiscoTimelineV2.md → RiskAuditTimelineV2.md} +2 -2
- data/docs/{AuditoriaRiscoUsageV2.md → RiskAuditUsageV2.md} +2 -2
- data/docs/RiskAuditV2.md +46 -0
- data/docs/RiskAuditV2Response.md +18 -0
- data/docs/{AuditoriaRiscoVerdictV2.md → RiskAuditVerdictV2.md} +3 -3
- data/docs/SpeechApi.md +1 -3
- data/docs/TranscriptionResponse.md +13 -14
- data/docs/TranscriptionUsage.md +3 -3
- data/docs/UpdateWebhookRequest.md +5 -5
- data/docs/UsageApi.md +1 -1
- data/docs/VersionApi.md +2 -7
- data/docs/VersionResponse.md +3 -3
- data/docs/WebhooksApi.md +22 -22
- data/docs/index.html +758 -0
- data/lib/falaai-api/api/analysis_api.rb +38 -42
- data/lib/falaai-api/api/email_alerts_api.rb +10 -10
- data/lib/falaai-api/api/health_api.rb +4 -4
- data/lib/falaai-api/api/speech_api.rb +2 -4
- data/lib/falaai-api/api/usage_api.rb +2 -2
- data/lib/falaai-api/api/version_api.rb +3 -3
- data/lib/falaai-api/api/webhooks_api.rb +18 -18
- data/lib/falaai-api/api_client.rb +2 -2
- data/lib/falaai-api/api_error.rb +2 -2
- data/lib/falaai-api/api_model_base.rb +2 -2
- data/lib/falaai-api/configuration.rb +6 -6
- data/lib/falaai-api/models/audio_event.rb +2 -2
- data/lib/falaai-api/models/audio_input_meta.rb +2 -2
- data/lib/falaai-api/models/create_email_alert_request.rb +2 -2
- data/lib/falaai-api/models/create_webhook_request.rb +2 -2
- data/lib/falaai-api/models/diagnostic_analysis_map.rb +2 -2
- data/lib/falaai-api/models/diagnostic_audio_event.rb +2 -2
- data/lib/falaai-api/models/diagnostic_categorical_analysis.rb +2 -2
- data/lib/falaai-api/models/diagnostic_participant.rb +226 -0
- data/lib/falaai-api/models/diagnostic_request.rb +91 -6
- data/lib/falaai-api/models/diagnostic_response.rb +2 -2
- data/lib/falaai-api/models/diagnostic_text_analysis.rb +2 -2
- data/lib/falaai-api/models/diagnostic_usage.rb +2 -2
- data/lib/falaai-api/models/email_alert_item.rb +2 -2
- data/lib/falaai-api/models/email_alert_list_response.rb +2 -2
- data/lib/falaai-api/models/email_alert_message_response.rb +2 -2
- data/lib/falaai-api/models/email_event.rb +2 -2
- data/lib/falaai-api/models/health_response.rb +2 -2
- data/lib/falaai-api/models/http_validation_error.rb +2 -2
- data/lib/falaai-api/models/location_inner.rb +2 -2
- data/lib/falaai-api/models/message_response.rb +2 -2
- data/lib/falaai-api/models/participant.rb +2 -2
- data/lib/falaai-api/models/participant_diagnostic.rb +2 -2
- data/lib/falaai-api/models/{auditoria_risco_analysis_v2.rb → risk_audit_analysis_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_applied_action_v2.rb → risk_audit_applied_action_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_audio_event_model_v2.rb → risk_audit_audio_event_model_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_audit_decisions_v2.rb → risk_audit_audit_decisions_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_conversation_scores_v2.rb → risk_audit_conversation_scores_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_detection_item_v2.rb → risk_audit_detection_item_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_detections_v2.rb → risk_audit_detections_v2.rb} +8 -8
- data/lib/falaai-api/models/{auditoria_risco_indexer_v2.rb → risk_audit_indexer_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_meta_v2.rb → risk_audit_meta_v2.rb} +7 -7
- data/lib/falaai-api/models/{auditoria_risco_participant_v2.rb → risk_audit_participant_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_participants_v2.rb → risk_audit_participants_v2.rb} +6 -6
- data/lib/falaai-api/models/{auditoria_risco_request.rb → risk_audit_request.rb} +8 -8
- data/lib/falaai-api/models/{auditoria_risco_scores_v2.rb → risk_audit_scores_v2.rb} +6 -6
- data/lib/falaai-api/models/{auditoria_risco_scoring_explanation_v2.rb → risk_audit_scoring_explanation_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_summary_v2.rb → risk_audit_summary_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_timeline_v2.rb → risk_audit_timeline_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_usage_v2.rb → risk_audit_usage_v2.rb} +5 -5
- data/lib/falaai-api/models/{auditoria_risco_v2.rb → risk_audit_v2.rb} +35 -35
- data/lib/falaai-api/models/{auditoria_risco_v2_response.rb → risk_audit_v2_response.rb} +7 -7
- data/lib/falaai-api/models/{auditoria_risco_verdict_v2.rb → risk_audit_verdict_v2.rb} +6 -6
- data/lib/falaai-api/models/transcription_response.rb +2 -2
- data/lib/falaai-api/models/transcription_usage.rb +2 -2
- data/lib/falaai-api/models/update_email_alert_request.rb +2 -2
- data/lib/falaai-api/models/update_webhook_request.rb +2 -2
- data/lib/falaai-api/models/usage_by_key_item.rb +2 -2
- data/lib/falaai-api/models/usage_log_item.rb +2 -2
- data/lib/falaai-api/models/usage_log_response.rb +2 -2
- data/lib/falaai-api/models/validation_error.rb +2 -2
- data/lib/falaai-api/models/version_response.rb +2 -2
- data/lib/falaai-api/models/webhook_event.rb +2 -2
- data/lib/falaai-api/models/webhook_item.rb +2 -2
- data/lib/falaai-api/models/webhook_list_response.rb +2 -2
- data/lib/falaai-api/version.rb +3 -3
- data/lib/falaai-api.rb +23 -22
- metadata +45 -42
- data/docs/AuditoriaRiscoDetectionsV2.md +0 -26
- data/docs/AuditoriaRiscoV2.md +0 -46
- data/docs/AuditoriaRiscoV2Response.md +0 -18
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: cd424a4222684b15b8858c2545873748ae0186905e13df8b87edb5b9cc7a0176
|
|
4
|
+
data.tar.gz: 36d4614309d8ddeaa0b647fb7a9f141a4ed102fbb7761faafa8b3fb106e3cb54
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 4eab457d32570575ae15027dd0e4499330d3aeb7fc6447bc67674c5ace493a6aca993c590155b596efae744bfdb65079f2f631f745bd14e1898e86b61c673926
|
|
7
|
+
data.tar.gz: da26196663d8efa3e9f4fa79d124739c698ca455187fd84e510fc6a0c08a41581d7b691cc07595f711a2f95c24cfc71932da0bd9af1a3a3b077a0b4d97757b30
|
data/README.md
CHANGED
|
@@ -1,339 +1,239 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
[](https://rubygems.org/gems/falaai-api)
|
|
4
|
-
[![
|
|
5
|
-
[![
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
##
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
```json
|
|
89
|
-
{
|
|
90
|
-
"id": "tr
|
|
91
|
-
"object": "transcription",
|
|
92
|
-
"model": "falaai-transcribe-1",
|
|
93
|
-
"
|
|
94
|
-
"
|
|
95
|
-
"
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
**
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
"label": "Nenhuma Acao",
|
|
241
|
-
"description": "Nenhuma acao necessaria. A chamada nao apresentou deteccoes que exijam intervencao. Continuar monitoramento de rotina.",
|
|
242
|
-
"priority": "BAIXO",
|
|
243
|
-
"color": "#6B7280",
|
|
244
|
-
"icon": "mdi:check-circle-outline",
|
|
245
|
-
"condition": "sempre",
|
|
246
|
-
"reason": "condição=sempre"
|
|
247
|
-
}
|
|
248
|
-
],
|
|
249
|
-
... (truncated)
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
### The forensic HTML report
|
|
253
|
-
|
|
254
|
-
The audit response carries **`response.html_report`** - the complete **forensic report as HTML**, encoded as a **base64 gzip** string (~19 KB). Decode it and open in a browser (or convert to PDF) to get the auditable evidence: timeline, audio events (MAC/MVAD/MOD), violations against **COPC CX** and **ISO 18295-1**, and the executive verdict.
|
|
255
|
-
|
|
256
|
-
```python
|
|
257
|
-
import base64, gzip, json, httpx
|
|
258
|
-
|
|
259
|
-
res = httpx.post(
|
|
260
|
-
"https://api01-falaai.action.tec.br/v1/analyze/auditoriaRisco",
|
|
261
|
-
headers={"Authorization": "Bearer fai_xxxxxx"},
|
|
262
|
-
json={"dialog": dialog, "language": "pt-BR", "duration_seconds": 25.0, "response_format": "v2"},
|
|
263
|
-
timeout=900,
|
|
264
|
-
).json()
|
|
265
|
-
|
|
266
|
-
html = gzip.decompress(base64.b64decode(res["response"]["html_report"])).decode("utf-8")
|
|
267
|
-
open("report.html", "w", encoding="utf-8").write(html)
|
|
268
|
-
```
|
|
269
|
-
|
|
270
|
-
## Use cases
|
|
271
|
-
|
|
272
|
-
- Call and voice-note **transcription** with speaker separation
|
|
273
|
-
- **Contact center quality assurance (QA)** automation
|
|
274
|
-
- **Compliance auditing** against **COPC CX** and **ISO 18295-1**
|
|
275
|
-
- **Risk detection** - churn risk, legal threats, escalation
|
|
276
|
-
- **WhatsApp, Telegram and chat** conversation analysis
|
|
277
|
-
- **CRM and help desk** enrichment
|
|
278
|
-
- **Call analytics** and **speech-to-text** at scale - every call transcribed and scored
|
|
279
|
-
- **Conversation intelligence** - summary, reason, action, topic and **sentiment analysis** per conversation
|
|
280
|
-
- **Speaker diarization** (speaker separation) on stereo or mono audio
|
|
281
|
-
- **Quality monitoring** and **agent performance** - audit 100% instead of a sample
|
|
282
|
-
- Built from a single **OpenAPI** contract, so all SDKs stay in sync
|
|
283
|
-
- **LGPD**-aware handling of customer conversations
|
|
284
|
-
|
|
285
|
-
## Where it fits
|
|
286
|
-
|
|
287
|
-
Plugs into **omnichannel service platforms**, **help desks**, **chatbots** and **unified messaging** - anywhere a conversation becomes text.
|
|
288
|
-
|
|
289
|
-
Common Ruby stacks in contact center, CRM and help desk - if you build on any of these, the SDK drops in:
|
|
290
|
-
|
|
291
|
-
Chatwoot - Zendesk Support - Discourse - Fat Free CRM
|
|
292
|
-
|
|
293
|
-
> Product names are trademarks of their respective owners, listed as common stacks in this ecosystem. No partnership is implied.
|
|
294
|
-
|
|
295
|
-
## Endpoints
|
|
296
|
-
|
|
297
|
-
| Method | Path | Description |
|
|
298
|
-
| --- | --- | --- |
|
|
299
|
-
| `POST` | `/v1/audio/transcriptions` | Audio to text, with speaker separation |
|
|
300
|
-
| `POST` | `/v1/analyze/diagnostic` | Conversation analysis - summary, reason, action, topic, sentiment |
|
|
301
|
-
| `POST` | `/v1/analyze/auditoriaRisco` | Compliance audit - risk score and violations |
|
|
302
|
-
| `GET` | `/v1/health` | Service health check (public) |
|
|
303
|
-
|
|
304
|
-
All endpoints require `Authorization: Bearer fai_xxxxxx`.
|
|
305
|
-
Full reference: <https://api01-falaai.action.tec.br/docs>
|
|
306
|
-
Other operations: usage logs, webhooks and email alerts - see the full reference.
|
|
307
|
-
|
|
308
|
-
## Links
|
|
309
|
-
|
|
310
|
-
- **Product:** <https://falaai.action.tec.br/api>
|
|
311
|
-
- **API reference:** <https://api01-falaai.action.tec.br/docs>
|
|
312
|
-
- **Get an API key:** <https://falaai.action.tec.br/api/auth>
|
|
313
|
-
- **Package (RubyGems):** <https://rubygems.org/gems/falaai-api>
|
|
314
|
-
- **Source:** <https://github.com/ActionTecBr/falaai-api-ruby>
|
|
315
|
-
|
|
316
|
-
## Other official SDKs
|
|
317
|
-
|
|
318
|
-
| Language | Install | Package |
|
|
319
|
-
| --- | --- | --- |
|
|
320
|
-
| **Python** | `pip install falaai-api` | [PyPI](https://pypi.org/project/falaai-api/) |
|
|
321
|
-
| **Node.js / TypeScript** | `npm install falaai-api` | [npm](https://www.npmjs.com/package/falaai-api) |
|
|
322
|
-
| **PHP** | `composer require actiontecbr/falaai-api` | [Packagist](https://packagist.org/packages/actiontecbr/falaai-api) |
|
|
323
|
-
| **Go** | `go get github.com/actiontecbr/falaai-api` | [pkg.go.dev](https://pkg.go.dev/github.com/actiontecbr/falaai-api) |
|
|
324
|
-
| **Ruby** | `gem install falaai-api` | [RubyGems](https://rubygems.org/gems/falaai-api) |
|
|
325
|
-
| **Java** | `io.github.actiontecbr:falaai-api` | [Maven Central](https://central.sonatype.com/artifact/io.github.actiontecbr/falaai-api) |
|
|
326
|
-
| **.NET / C#** | `dotnet add package FalaAI.Api` | [NuGet](https://www.nuget.org/packages/FalaAI.Api) |
|
|
327
|
-
|
|
328
|
-
## Requirements, support and more
|
|
329
|
-
|
|
330
|
-
- **Requirements:** an API key (`fai_...`) and a runtime able to upload audio files.
|
|
331
|
-
- **Documentation:** <https://api01-falaai.action.tec.br/docs>
|
|
332
|
-
- **Support:** open an issue in this repository.
|
|
333
|
-
- **Security:** responsible disclosure policy in [SECURITY.md](SECURITY.md).
|
|
334
|
-
- **Contributing:** see [CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
335
|
-
- **Changelog:** see [CHANGELOG.md](CHANGELOG.md).
|
|
336
|
-
|
|
337
|
-
## License
|
|
338
|
-
|
|
339
|
-
MIT (c) 2026 Action Tec Br - see [LICENSE](LICENSE).
|
|
1
|
+
# falaai-api — Ruby SDK for Conversation Intelligence, Speech Analytics & Compliance
|
|
2
|
+
|
|
3
|
+
[](https://rubygems.org/gems/falaai-api)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://github.com/ActionTecBr/falaai-api-ruby/actions/workflows/ci.yml)
|
|
6
|
+
[](https://actiontecbr.github.io/falaai-api-ruby/)
|
|
7
|
+
|
|
8
|
+
Official **Ruby SDK** for the **FalaAI API** — transcribe audio, analyze conversations and audit compliance (COPC CX, ISO 18295-1). **Use each API independently or combine them into your own pipeline.**
|
|
9
|
+
|
|
10
|
+
> Analyze calls, contact-center recordings, voice notes, chat and email. Get speaker-separated transcripts, summaries, reasons, actions, sentiment and a **compliance risk score**.
|
|
11
|
+
|
|
12
|
+
## Use any FalaAI API independently
|
|
13
|
+
|
|
14
|
+
FalaAI is a set of **independent REST APIs**. You **do not** need FalaAI Transcription to use FalaAI analysis or compliance auditing. If your application already has a transcript, send that text straight to the analysis APIs.
|
|
15
|
+
|
|
16
|
+
| If you have... | Use |
|
|
17
|
+
|---|---|
|
|
18
|
+
| Audio but no transcript | `FalaAI::SpeechApi` — Transcription |
|
|
19
|
+
| An existing transcript | `FalaAI::AnalysisApi` — Diagnostic |
|
|
20
|
+
| A transcript needing compliance analysis | `FalaAI::AnalysisApi` — Risk Audit |
|
|
21
|
+
| An existing transcript needing both | Diagnostic + Risk Audit |
|
|
22
|
+
| Your own STT provider (Whisper, Deepgram...) | Skip FalaAI Transcription |
|
|
23
|
+
|
|
24
|
+
```text
|
|
25
|
+
Your STT -> FalaAI Diagnostic -> FalaAI Risk Audit
|
|
26
|
+
Telegram voice -> your STT -> FalaAI Risk Audit
|
|
27
|
+
3CX / Asterisk / Genesys transcript -> FalaAI Diagnostic -> FalaAI Risk Audit
|
|
28
|
+
CRM conversation -> FalaAI Risk Audit
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Use the APIs the way you want
|
|
32
|
+
|
|
33
|
+
Every FalaAI API is **independent and optional** — chain any subset, in any combination.
|
|
34
|
+
|
|
35
|
+
```mermaid
|
|
36
|
+
flowchart LR
|
|
37
|
+
A["Audio"] -.->|optional| T["Transcribe"]
|
|
38
|
+
T --> X["Text / dialog"]
|
|
39
|
+
S["Your own STT / CRM / chat / existing transcript"] --> X
|
|
40
|
+
X -.->|optional| D["Diagnostic"]
|
|
41
|
+
X -.->|optional| R["Risk Audit"]
|
|
42
|
+
D --> O["Structured intelligence + auditable report"]
|
|
43
|
+
R --> O
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
> Skip **Transcribe** if you already have text. Call only **Diagnostic**, only **Risk Audit**, or both.
|
|
47
|
+
|
|
48
|
+
## Install
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
gem install falaai-api
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Requires **Ruby 2.7+**.
|
|
55
|
+
|
|
56
|
+
## Quickstart
|
|
57
|
+
|
|
58
|
+
### 1. Get an API key
|
|
59
|
+
Create a free account and copy your `fai_` key: <https://falaai.action.tec.br/api/auth> (or the [Dashboard](https://falaai.action.tec.br/api/dashboard)).
|
|
60
|
+
|
|
61
|
+
### 2. Set environment variables
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
FALAAI_BASE_URL=https://api01-falaai.action.tec.br
|
|
65
|
+
FALAAI_API_KEY=fai_xxxxxxxx
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### 3. Transcribe a call (audio -> text)
|
|
69
|
+
|
|
70
|
+
```ruby
|
|
71
|
+
require 'falaai-api'
|
|
72
|
+
|
|
73
|
+
config = FalaAI::Configuration.new
|
|
74
|
+
config.host = ENV.fetch('FALAAI_BASE_URL', 'https://api01-falaai.action.tec.br')
|
|
75
|
+
config.access_token = ENV['FALAAI_API_KEY']
|
|
76
|
+
client = FalaAI::ApiClient.new(config)
|
|
77
|
+
|
|
78
|
+
transcription, _status = FalaAI::SpeechApi.new(client).create_transcription_v1_audio_transcriptions_post_with_http_info(
|
|
79
|
+
File.open('call.mp3'),
|
|
80
|
+
{ model: 'falaai-transcribe-1', language: 'pt', client_reference_id: 'call_202609271408' }
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
puts JSON.pretty_generate(transcription)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Expected response (abridged):
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"id": "tr-...",
|
|
91
|
+
"object": "transcription",
|
|
92
|
+
"model": "falaai-transcribe-1",
|
|
93
|
+
"language": "por",
|
|
94
|
+
"duration_seconds": 25.0,
|
|
95
|
+
"text": "...",
|
|
96
|
+
"dialog": "Speaker 1: [...] ...",
|
|
97
|
+
"usage": { "audio_seconds": 25.0, "credits_consumed": 25, "processing_ms": 951 }
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
> Only need analysis? **Skip step 3** and call `FalaAI::AnalysisApi` with your own transcript (use the `text` field for a plain transcript).
|
|
102
|
+
|
|
103
|
+
### 4. Analyze or audit an existing transcript (no transcription needed)
|
|
104
|
+
|
|
105
|
+
```ruby
|
|
106
|
+
require 'falaai-api'
|
|
107
|
+
|
|
108
|
+
config = FalaAI::Configuration.new
|
|
109
|
+
config.host = ENV['FALAAI_BASE_URL']
|
|
110
|
+
config.access_token = ENV['FALAAI_API_KEY']
|
|
111
|
+
client = FalaAI::ApiClient.new(config)
|
|
112
|
+
analysis = FalaAI::AnalysisApi.new(client)
|
|
113
|
+
|
|
114
|
+
transcript = 'Good morning, how can I help? I need to cancel my subscription.'
|
|
115
|
+
|
|
116
|
+
# 5 analyses in one call: summary, reason, action, topic, sentiment
|
|
117
|
+
diagnostic, _status = analysis.create_diagnostic_v1_analyze_diagnostic_post_with_http_info(
|
|
118
|
+
FalaAI::DiagnosticRequest.new(text: transcript, language: 'pt-BR', duration_seconds: 81.46)
|
|
119
|
+
)
|
|
120
|
+
|
|
121
|
+
# Compliance risk score + violations + auditable report
|
|
122
|
+
audit, _status = analysis.create_risk_audit_v1_analyze_risk_audit_post_with_http_info(
|
|
123
|
+
FalaAI::RiskAuditRequest.new(text: transcript, language: 'pt-BR', response_language: 'pt-BR', duration_seconds: 81.46)
|
|
124
|
+
)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## What is FalaAI API?
|
|
128
|
+
|
|
129
|
+
FalaAI API is an **AI conversation-intelligence API** for analyzing customer-service, contact-center, sales, messaging and other business conversations. It combines speech-to-text (with speaker diarization and audio-event detection), conversation analysis (summary, contact reason, action taken, topic classification, sentiment) and a **compliance/risk audit** against **COPC CX** and **ISO 18295-1**. Conversation content is processed and discarded (zero-storage).
|
|
130
|
+
|
|
131
|
+
## What can you do with FalaAI?
|
|
132
|
+
|
|
133
|
+
- **Transcribe** audio to text with speaker separation and audio events.
|
|
134
|
+
- **Diagnose** a conversation: summary, reason, action taken, topic and sentiment.
|
|
135
|
+
- **Audit** conversations: compliance risk score, detections/violations and an auditable HTML report.
|
|
136
|
+
- **Track usage**, **manage webhooks** and **email alerts**, and **health/version** checks.
|
|
137
|
+
|
|
138
|
+
## Use cases
|
|
139
|
+
|
|
140
|
+
- **Contact center / Quality** — audit 100% of conversations instead of a sample.
|
|
141
|
+
- **Compliance / Legal** — auditable evidence for audits and disputes.
|
|
142
|
+
- **CX / Operations** — risk score, sentiment and reason per conversation.
|
|
143
|
+
- **BI / Data** — typed JSON ready for your database or analytics stack.
|
|
144
|
+
|
|
145
|
+
## SDK surface (Ruby)
|
|
146
|
+
|
|
147
|
+
| Class | Namespace | Purpose |
|
|
148
|
+
|---|---|---|
|
|
149
|
+
| `Configuration` | `FalaAI` | `host`, `access_token` |
|
|
150
|
+
| `ApiClient` | `FalaAI` | `FalaAI::ApiClient.new(config)` |
|
|
151
|
+
| `HealthApi` | `FalaAI` | `health_check` |
|
|
152
|
+
| `SpeechApi` | `FalaAI` | `create_transcription_v1_audio_transcriptions_post_with_http_info(...)` |
|
|
153
|
+
| `AnalysisApi` | `FalaAI` | `create_diagnostic_v1_analyze_diagnostic_post_with_http_info(...)`, `create_risk_audit_v1_analyze_risk_audit_post_with_http_info(...)` |
|
|
154
|
+
| `UsageApi` / `WebhooksApi` / `EmailAlertsApi` / `VersionApi` | `FalaAI` | management |
|
|
155
|
+
| Models | `FalaAI` | `DiagnosticRequest`, `RiskAuditRequest`, `Participant`, `DiagnosticAudioEvent` |
|
|
156
|
+
| `ApiError` | `FalaAI` | HTTP errors |
|
|
157
|
+
|
|
158
|
+
> Model IDs: `falaai-transcribe-1`, `falaai-diagnostic-1`, `falaai-risk-audit-1`.
|
|
159
|
+
|
|
160
|
+
## Examples
|
|
161
|
+
|
|
162
|
+
Runnable examples in [`examples/`](./examples): `health.rb`, `transcribe.rb`, `diagnose.rb`, `audit.rb`.
|
|
163
|
+
|
|
164
|
+
## Authentication
|
|
165
|
+
|
|
166
|
+
Every request requires `Authorization: Bearer fai_<your_key>` — except the public endpoints (`GET/HEAD /v1/health`, `GET /api/version`). Set the key with `Configuration#access_token=` (or `FALAAI_API_KEY`).
|
|
167
|
+
|
|
168
|
+
## Error handling
|
|
169
|
+
|
|
170
|
+
Non-2xx responses raise `FalaAI::ApiError`.
|
|
171
|
+
|
|
172
|
+
```ruby
|
|
173
|
+
require 'falaai-api'
|
|
174
|
+
|
|
175
|
+
begin
|
|
176
|
+
health = FalaAI::HealthApi.new(client).health_check
|
|
177
|
+
puts health.status
|
|
178
|
+
rescue FalaAI::ApiError => e
|
|
179
|
+
warn "FalaAI API error: #{e.message}"
|
|
180
|
+
end
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Where to integrate (this SDK)
|
|
184
|
+
|
|
185
|
+
FalaAI is language-independent; this package targets **Ruby** backends.
|
|
186
|
+
|
|
187
|
+
| Platform / environment (this SDK's language: **Ruby**) | Integration |
|
|
188
|
+
|---|---|
|
|
189
|
+
| **Ruby on Rails** apps | `falaai-api` (Ruby) |
|
|
190
|
+
| Ruby workers / Sidekiq jobs | `falaai-api` (Ruby) |
|
|
191
|
+
| Ruby data pipelines | `falaai-api` (Ruby) |
|
|
192
|
+
| Other stacks (3CX, Salesforce, Genesys...) | REST / cURL — [API reference](https://api01-falaai.action.tec.br/docs) (or the SDK for that backend's language) |
|
|
193
|
+
|
|
194
|
+
> These are **integration examples**, not certified native integrations. Any platform can integrate through **REST / cURL** — see the [API reference](https://api01-falaai.action.tec.br/docs). Authenticated calls use `Authorization: Bearer fai_<key>`.
|
|
195
|
+
|
|
196
|
+
## Production usage
|
|
197
|
+
|
|
198
|
+
- Store API keys in environment variables or a secret manager — never hard-code.
|
|
199
|
+
- Reuse the `ApiClient` across requests.
|
|
200
|
+
- Handle `FalaAI::ApiError` explicitly.
|
|
201
|
+
|
|
202
|
+
## Compatibility
|
|
203
|
+
|
|
204
|
+
| Requirement | Version |
|
|
205
|
+
|---|---|
|
|
206
|
+
| Ruby | 2.7+ |
|
|
207
|
+
| API | v1.21.49 |
|
|
208
|
+
|
|
209
|
+
## Documentation
|
|
210
|
+
|
|
211
|
+
- **SDK docs (this language):** <https://actiontecbr.github.io/falaai-api-ruby/>
|
|
212
|
+
- **API reference (Swagger UI):** <https://api01-falaai.action.tec.br/docs>
|
|
213
|
+
- **OpenAPI contract:** <https://api01-falaai.action.tec.br/openapi.json>
|
|
214
|
+
- **Sandbox:** <https://falaai.action.tec.br/api#playground>
|
|
215
|
+
- **Quickstart:** <https://falaai.action.tec.br/api/quickstart>
|
|
216
|
+
- **Product page:** <https://falaai.action.tec.br/api>
|
|
217
|
+
|
|
218
|
+
## Versioning
|
|
219
|
+
|
|
220
|
+
Semantic versioning; the SDK version tracks the API version (`1.21.49`). See [CHANGELOG.md](CHANGELOG.md) and [Releases](https://github.com/ActionTecBr/falaai-api-ruby/releases).
|
|
221
|
+
|
|
222
|
+
## Security
|
|
223
|
+
|
|
224
|
+
See [SECURITY.md](SECURITY.md). Never commit real keys — use environment variables.
|
|
225
|
+
|
|
226
|
+
## Contributing
|
|
227
|
+
|
|
228
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
229
|
+
|
|
230
|
+
## License
|
|
231
|
+
|
|
232
|
+
[MIT](LICENSE).
|
|
233
|
+
|
|
234
|
+
## Links
|
|
235
|
+
|
|
236
|
+
- Website: <https://falaai.action.tec.br>
|
|
237
|
+
- API base URL: <https://api01-falaai.action.tec.br>
|
|
238
|
+
- GitHub organization: <https://github.com/ActionTecBr>
|
|
239
|
+
- Other SDKs: Python, Node.js, PHP, Go, Java, .NET.
|