README

Official PHP SDK for the FalaAI API - call transcription, conversation intelligence and compliance auditing (COPC CX, ISO 18295-1).

What is FalaAI API?

FalaAI API turns conversations into auditable business intelligence, in three steps:

Transcribe - audio (calls, voice notes, meetings) to text, with speaker separation.
Diagnose - summary, reason, recommended action, topic and sentiment per conversation.
Audit compliance - risk score and violations against COPC CX and ISO 18295-1.

It works with phone calls and call recordings (PABX IP, Asterisk, FreePBX, contact center), messaging (WhatsApp, Telegram, web chat, SMS) and email - anything that can be turned into text. Three core endpoints (plus health, usage, webhooks and email alerts), one API key, no setup.

Who it's for

Role	What they get
Contact Center / Quality	Audit 100% of conversations instead of a sample
Compliance / Legal	Forensic, auditable evidence for audits and disputes
CX / Operations	Risk score, sentiment and reason for every conversation
Developers	One typed SDK, three core endpoints, one API key
Data / BI	Clean, typed JSON ready for your database or BI tool

Install

composer require actiontecbr/falaai-api

Quick start

<?php

require "vendor/autoload.php";

use FalaAI\Api\SpeechApi;
use FalaAI\Configuration;

$config = (new Configuration())
    ->setHost("https://api01-falaai.action.tec.br")
    ->setAccessToken("fai_xxxxxx");

$speech = new SpeechApi(null, $config);

[$response, $status] = $speech->createTranscriptionV1AudioTranscriptionsPostWithHttpInfo(
    new \SplFileObject("call.mp3"),
    "falaai-transcribe-1",
    "pt"
);

echo $response->getText();

Request and response examples

Real requests and responses, captured against the live API.

Health

Request

curl https://api01-falaai.action.tec.br/v1/health \
  -H "Authorization: Bearer fai_xxxxxx"

Response

{
  "status": "ok",
  "version": "api_v1.21.47",
  "uptime_seconds": 92855,
  "database": true,
  "phase": "production",
  "launch_date": "2026-08-01"
}

Transcribe

Response (the request is in Quick start)

{
  "id": "tr-a38a97d0-452e-4519-b6bb-3c63694bf7ae",
  "object": "transcription",
  "model": "falaai-transcribe-1",
  "filename": "analise_25s.mp3",
  "processed_at": "2026-09-23T17:42:54.242449+00:00",
  "usage": {
    "audio_seconds": 25.0,
    "credits_consumed": 25,
    "processing_ms": 951
  },
  "language": "por",
  "duration_seconds": 25.0,
  "text": "Novatechno tudo, bom dia. Bom dia, Mateus. Tudo bem? Bem e você? Tudo bem. Não tem nada no sistema. Eu queria ver se de  ...",
  "dialog": "Speaker 1: [00:00:01.639 - 00:00:02.560] Novatechno tudo, bom dia.\nSpeaker 2: [00:00:02.980 - 00:00:03.980] Bom dia, Mateus. Tudo bem?\nSpeaker 1: [00:00:04.700 - 00:00:05.179] Bem e você?\nSpeaker 2: [ ...",
  "audio_events": [
    {
      "event": "[tosse]",
      "start_s": 22.06,
      "end_s": 22.44,
      "duration_s": 0.38,
      "formatted_timestamp": "00:00:22.059"
    }
  ],
  "event_types": [
    "[tosse]"
  ],
  "word_count": 129,
  "input": {
    "duration_s": 25.2,
    "original_format": "mp3",
    "codec": "mp3",
    "sample_rate": 8000,
    "channels": 1
  },
  "language_confidence": 1.0,
  "client_reference_id": "readme-example"
}

Diagnose

Request

curl https://api01-falaai.action.tec.br/v1/analyze/diagnostic \
  -H "Authorization: Bearer fai_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"dialog": "<transcription dialog>", "language": "pt-BR", "duration_seconds": 25.0}'

Response

{
  "id": "di-15c79d7c-7245-4af4-9a4e-ead237c1a6ed",
  "response_language": "pt-BR",
  "object": "analysis",
  "analysis": {
    "dialogue_summary": {
      "explanation": "O cliente (Speaker 2) contatou a Novatechno (Speaker 1) para obter informações sobre um produto (código 4675005) que saiu de linha. O cliente já realizou uma pe ..."
    },
    "contact_reason": {
      "explanation": "O cliente busca informação sobre qual produto substituiu o código 4675005, que saiu de linha."
    },
    "identified_action": {
      "list_choice": "Sem Ação",
      "justification": "O cliente buscou informações sobre um produto que saiu de linha, mas a conversa terminou sem uma ação definida ou resolução.",
      "evidence_phrases": [
        "Novatechno tudo, bom dia.",
        "Bom dia, Mateus. Tudo bem?",
        "Tudo bem. Não tem nada no sistema. Eu queria ver se de repente você tem alguma informação.",
        "Quatro meia sete cinco zero zero cinco saiu de linha. Ééé, eu procurei no Google ver se o que entrou no lugar. Aí ele fala"
      ]
    },
    "identified_label": {
      "list_choice": "Pedido de Informação",
      "justification": "O cliente busca informações sobre um produto que saiu de linha, perguntando o que o substituiu, indicando uma necessidade de dados.",
      "evidence_phrases": [
        "Não tem nada no sistema. Eu queria ver se de repente você tem alguma informação.",
        "É, o produto, posso te falar o código?",
  ... (truncated)

Audit compliance

Request

curl https://api01-falaai.action.tec.br/v1/analyze/auditoriaRisco \
  -H "Authorization: Bearer fai_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"dialog": "<transcription dialog>", "language": "pt-BR", "duration_seconds": 25.0, "response_format": "v2"}'

Response

{
  "response": {
    "meta": {
      "id": "ar-3439fd5f-1932-4ebe-bfb5-944ec1046e60",
      "usage": {
        "characters": 378,
        "credits_consumed": 90,
        "processing_ms": 6534
      },
      "object": "auditoria_risco",
      "call_duration_s": 25.0,
      "analyzed_at": "2026-09-23T17:43:02.092299",
      "client_reference_id": "readme-example"
    },
    "participants": {
      "identified": [
        {
          "confidence": "high",
          "source": "input",
          "evidence": "fornecido pelo input",
          "interlocutor": "Speaker 1",
          "name": "Mateus",
          "role": "agent"
        },
        {
          "confidence": "high",
          "source": "input",
          "evidence": "fornecido pelo input",
          "interlocutor": "Speaker 2",
          "name": "Cliente",
          "role": "client"
        }
      ],
      "call_direction": "inbound",
      "role_inference_reliable": true,
      "identification_status": "input",
      "unidentified_items_count": 0
    },
    "verdict": {
      "label": "Limpa",
      "level_code": "LIMPA",
      "color": "#4fff4d",
      "icon": "mdi:check-circle",
      "risk_matrix": {
        "severity": "NOTE",
        "likelihood_avg": 0.0,
        "impact_avg": 0.0,
        "likelihood_level": "LOW",
        "impact_level": "LOW"
      },
      "applied_actions": [
        {
          "action_type": "nenhuma_acao",
          "label": "Nenhuma Acao",
          "description": "Nenhuma acao necessaria. A chamada nao apresentou deteccoes que exijam intervencao. Continuar monitoramento de rotina.",
          "priority": "BAIXO",
          "color": "#6B7280",
          "icon": "mdi:check-circle-outline",
          "condition": "sempre",
          "reason": "condição=sempre"
        }
      ],
  ... (truncated)

The forensic HTML report

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.

import base64, gzip, json, httpx

res = httpx.post(
    "https://api01-falaai.action.tec.br/v1/analyze/auditoriaRisco",
    headers={"Authorization": "Bearer fai_xxxxxx"},
    json={"dialog": dialog, "language": "pt-BR", "duration_seconds": 25.0, "response_format": "v2"},
    timeout=900,
).json()

html = gzip.decompress(base64.b64decode(res["response"]["html_report"])).decode("utf-8")
open("report.html", "w", encoding="utf-8").write(html)

Use cases

Call and voice-note transcription with speaker separation
Contact center quality assurance (QA) automation
Compliance auditing against COPC CX and ISO 18295-1
Risk detection - churn risk, legal threats, escalation
WhatsApp, Telegram and chat conversation analysis
CRM and help desk enrichment
Call analytics and speech-to-text at scale - every call transcribed and scored
Conversation intelligence - summary, reason, action, topic and sentiment analysis per conversation
Speaker diarization (speaker separation) on stereo or mono audio
Quality monitoring and agent performance - audit 100% instead of a sample
Built from a single OpenAPI contract, so all SDKs stay in sync
LGPD-aware handling of customer conversations

Where it fits

Plugs into omnichannel service platforms, help desks, chatbots and unified messaging - anywhere a conversation becomes text.

Common PHP stacks in contact center, CRM and help desk - if you build on any of these, the SDK drops in:

WordPress / WooCommerce - SuiteCRM - Vtiger - Bitrix24 (self-hosted) - Perfex - FreePBX / Asterisk - RD Station - Meetime

Product names are trademarks of their respective owners, listed as common stacks in this ecosystem. No partnership is implied.

Endpoints

Method	Path	Description
`POST`	`/v1/audio/transcriptions`	Audio to text, with speaker separation
`POST`	`/v1/analyze/diagnostic`	Conversation analysis - summary, reason, action, topic, sentiment
`POST`	`/v1/analyze/auditoriaRisco`	Compliance audit - risk score and violations
`GET`	`/v1/health`	Service health check (public)

All endpoints require Authorization: Bearer fai_xxxxxx. Full reference: https://api01-falaai.action.tec.br/docs Other operations: usage logs, webhooks and email alerts - see the full reference.

Other official SDKs

Language	Install	Package
Python	`pip install falaai-api`	PyPI
Node.js / TypeScript	`npm install falaai-api`	npm
PHP	`composer require actiontecbr/falaai-api`	Packagist
Go	`go get github.com/actiontecbr/falaai-api`	pkg.go.dev
Ruby	`gem install falaai-api`	RubyGems
Java	`io.github.actiontecbr:falaai-api`	Maven Central
.NET / C#	`dotnet add package FalaAI.Api`	NuGet

Requirements, support and more

Requirements: an API key (fai_...) and a runtime able to upload audio files.
Documentation: https://api01-falaai.action.tec.br/docs
Support: open an issue in this repository.
Security: responsible disclosure policy in SECURITY.md.
Contributing: see CONTRIBUTING.md · Code of Conduct.
Changelog: see CHANGELOG.md.

actiontecbr / falaai-api

Package info

Security

Statistics

README

What is FalaAI API?

Who it's for

Install

Quick start

Request and response examples

Health

Transcribe

Diagnose

Audit compliance

The forensic HTML report

Use cases

Where it fits

Endpoints

Links

Other official SDKs

Requirements, support and more

License