# Argos Voip — Documentação Completa da API & Inteligência Artificial (para IAs e Desenvolvedores)

> **Versão:** 2.1.0 (REST API & AI Suite)  
> **Base URL:** https://api.argosvoip.com.br/api/v1 (ou http://localhost:8080/api/v1 em desenvolvimento local)  
> **Protocolo:** WhatsApp VoIP Nativo (Opus 16kHz & H.264 HD)  
> **Padrão de Autenticação:** Bearer Token (`Authorization: Bearer ag_live_...`)

---

## 1. Visão Geral da Plataforma

O **Argos Voip** é a primeira plataforma de telefonia VoIP nativa para WhatsApp do Brasil. Ele permite que softwares, CRMs, ferramentas No-Code (n8n, Typebot) e **Agentes de Inteligência Artificial (LLMs)** disparem, recebam, gravem e analisem chamadas de voz e vídeo diretamente no WhatsApp do cliente com até 78% de taxa de atendimento.

### Principais Casos de Uso com Inteligência Artificial:
1. **Agentes SDR / Vendas Autônomos:** Um agente LLM detecta um lead quente no CRM e dispara imediatamente uma ligação de voz pelo WhatsApp para iniciar a qualificação.
2. **Auditoria & Quality Assurance (QA) Automatizado:** 100% das chamadas gravadas são automaticamente transcritas com Whisper v3 Turbo e analisadas por IA (sentimento, objeções, itens de ação e nota de satisfação).
3. **Recuperação de Vendas e Cobrança:** Disparo de ligações de aviso amigável com conexão instantânea a um operador humano ou bot interativo.

---

## 2. Autenticação, Tokens & Segurança

### 2.1 Formato do Token
Toda requisição à API do Argos Voip deve conter o header:
```http
Authorization: Bearer ag_live_9f8a42c6b9d04e7f9a12bc503e91a0c7
```

- **Produção (`ag_live_...`):** Roteia chamadas para chips WhatsApp reais pareados e consome minutos contratados.
- **Sandbox / Testes (`ag_test_...`):** Simula sinalização de chamadas, dispara webhooks e gera transcrições mock sem tarifação.

### 2.2 Ciclo de Vida e Segurança para Agentes de IA
- **Variáveis de Ambiente:** Em agentes de IA (OpenAI Assistants, Claude, LangChain), NUNCA insira o token no corpo do prompt de sistema. Armazene em `ARGOS_API_KEY` e injete no cabeçalho das requisições HTTP da ferramenta (tool/function call).
- **Isolamento Multi-Tenant:** Cada chave de API é estritamente vinculada a uma `organization_id` no banco de dados. Um agente nunca acessará gravações ou instâncias de outro cliente.
- **IP Whitelisting:** Suporte opcional para restringir a execução da API apenas aos IPs dos seus servidores de produção.

### 2.3 Rate Limits & Quotas
- **Limite Padrão:** 120 requisições por minuto por chave.
- **Burst Permitido:** Até 300 requisições por minuto para picos de automação.
- **Headers de Rate Limit retornados:**
  - `X-RateLimit-Limit`: 120
  - `X-RateLimit-Remaining`: 118
  - `X-RateLimit-Reset`: 1788900000

---

## 3. Endpoints da API REST

### 3.1 Disparar Chamada de Voz
- **Método:** `POST /api/v1/calls/audio`
- **Descrição:** Inicia uma chamada de áudio nativa no WhatsApp do destinatário.
- **Request Body:**
```json
{
  "to": "5511999998888",
  "contact_name": "Mariana Silva",
  "webhook_url": "https://seu-sistema.com.br/webhook"
}
```
- **Response (200 OK):**
```json
{
  "success": true,
  "call_id": "ag_call_1788900000000",
  "status": "ringing",
  "type": "audio",
  "target": "5511999998888",
  "contact_name": "Mariana Silva",
  "engine_dispatched": true,
  "created_at": "2026-09-08T20:45:00.000Z"
}
```

---

### 3.2 Disparar Chamada de Vídeo HD
- **Método:** `POST /api/v1/calls/video`
- **Descrição:** Inicia uma chamada de vídeo em alta definição diretamente no WhatsApp.
- **Request Body:**
```json
{
  "to": "5511999998888",
  "contact_name": "Cliente VIP"
}
```
- **Response (200 OK):**
```json
{
  "success": true,
  "call_id": "ag_video_1788900000000",
  "status": "ringing",
  "type": "video",
  "target": "5511999998888",
  "created_at": "2026-09-08T20:45:00.000Z"
}
```

---

### 3.3 Encerrar Chamada Ativa
- **Método:** `POST /api/v1/calls/:id/hangup`
- **Descrição:** Desliga uma ligação em andamento imediatamente.
- **Response (200 OK):**
```json
{
  "success": true,
  "call_id": "ag_call_1788900000000",
  "status": "completed",
  "action": "hangup",
  "ended_at": "2026-09-08T20:47:30.000Z"
}
```

---

### 3.4 Consultar Status da Chamada
- **Método:** `GET /api/v1/calls/:id`
- **Possíveis status:** `ringing`, `in_progress`, `completed`, `busy`, `missed`.
- **Response (200 OK):**
```json
{
  "id": "ag_call_1788900000000",
  "contact_name": "Mariana Silva",
  "whatsapp_id": "5511999998888",
  "call_type": "audio",
  "direction": "efetuada",
  "status": "completed",
  "duration_sec": 154,
  "recorded": true,
  "started_at": "2026-09-08T20:45:00.000Z",
  "ended_at": "2026-09-08T20:47:34.000Z"
}
```

---

## 4. Suíte de Inteligência Artificial

### 4.1 Análise Semântica de Sentimento, Resumo & Objeções
- **Método:** `POST /api/v1/ai/analyze`
- **Descrição:** Analisa o texto transcrito de uma chamada (ou busca automaticamente pelo `call_id` / `recording_id`) e retorna insights quantitativos e qualitativos.
- **Request Body:**
```json
{
  "call_id": "ag_call_1788900000000",
  "text": "Olá, queria entender como funciona o plano Pro do Argos Voip e se consigo integrar com meu n8n. O preço cabe no meu orçamento se tiver 1000 minutos inclusos.",
  "custom_prompt": "Identifique a principal objeção de compra e as intenções de fechamento."
}
```
- **Response (200 OK):**
```json
{
  "success": true,
  "sentiment": "positive",
  "sentiment_score": 0.85,
  "urgency": "medium",
  "customer_satisfaction_prediction": "alta (92%)",
  "summary": "Lead altamente interessado na contratação do Plano Pro e integração com n8n, buscando confirmar franquia de 1.000 minutos.",
  "key_topics": ["Plano Pro", "Integração n8n", "Franquia 1000 min", "Preço"],
  "objections": [
    "Necessidade de validar se a franquia de 1000 minutos atende ao pico mensal"
  ],
  "action_items": [
    "Enviar proposta do Plano Pro via WhatsApp",
    "Compartilhar modelo de workflow do n8n",
    "Agendar demonstração técnica em até 24h"
  ],
  "model": "Argos-LLM-Insight-v2",
  "created_at": "2026-09-08T20:48:00.000Z"
}
```

---

### 4.2 Transcrição Automática com Whisper v3 Turbo
- **Método:** `POST /api/v1/ai/transcribe`
- **Descrição:** Processa gravações de áudio com alta fidelidade (acurácia superior a 98% em português do Brasil), diarização de falantes e timestamps.
- **Request Body:**
```json
{
  "call_id": "ag_call_1788900000000",
  "audio_url": "https://api.argosvoip.com.br/recordings/audio_01.wav",
  "language": "pt-BR",
  "diarization": true
}
```
- **Response (200 OK):**
```json
{
  "success": true,
  "language": "pt-BR",
  "confidence": 0.98,
  "duration_sec": 45,
  "transcription": "Olá, tudo bem? Aqui é o cliente. Gostaria de confirmar nossa reunião e entender as integrações com a API de telefonia do Argos Voip.",
  "segments": [
    { "start": 0.0, "end": 4.2, "text": "Olá, tudo bem? Aqui é o cliente.", "speaker": "speaker_customer" },
    { "start": 4.5, "end": 12.0, "text": "Olá Mariana, com certeza! Vamos analisar sua infraestrutura de atendimento.", "speaker": "speaker_agent" }
  ],
  "model": "Argos-Whisper-v3-Turbo",
  "created_at": "2026-09-08T20:48:00.000Z"
}
```

---

### 4.3 Listagem de Gravações & Mídias
- **Método:** `GET /api/v1/recordings`
- **Descrição:** Retorna as últimas 50 gravações do workspace com status de IA.
- **Response (200 OK):**
```json
{
  "total": 1,
  "recordings": [
    {
      "id": "rec_1788900000000",
      "call_id": "ag_call_1788900000000",
      "contact_name": "Mariana Silva",
      "whatsapp_id": "5511999998888",
      "media_type": "audio",
      "duration_sec": 154,
      "file_url": "https://api.argosvoip.com.br/recordings/audio_01.wav",
      "transcription": "Olá, tudo bem? Aqui é o cliente...",
      "sentiment": "positive",
      "created_at": "2026-09-08T20:47:34.000Z"
    }
  ]
}
```

---

## 5. Webhooks em Tempo Real

O Argos Voip envia notificações HTTP POST com header `X-ArgosVoip-Signature` (HMAC SHA-256) nos seguintes eventos:

1. `call.started`: O WhatsApp do contato começou a tocar.
2. `call.answered`: O contato atendeu a ligação (início da tarifação de minutos).
3. `call.ended`: A chamada foi concluída.
4. `call.recording_ready`: O arquivo de gravação de áudio/vídeo está pronto para download.
5. `ai.transcription_completed`: A transcrição Whisper v3 Turbo foi processada.
6. `ai.analysis_ready`: O resumo executivo e sentimento por IA foram gerados.

---

## 6. Especificação de Ferramentas (Tools / Function Calling) para OpenAI & Claude

Copie e cole a definição abaixo no seu agente inteligente:

```json
[
  {
    "type": "function",
    "function": {
      "name": "argos_start_voice_call",
      "description": "Dispara uma chamada telefônica de voz via WhatsApp para um cliente ou lead pelo Argos Voip.",
      "parameters": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "description": "Número do destinatário com DDI e DDD (ex: 5511999998888)"
          },
          "contact_name": {
            "type": "string",
            "description": "Nome do contato para identificar a ligação"
          }
        },
        "required": ["to"]
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "argos_start_video_call",
      "description": "Dispara uma videochamada em alta definição no WhatsApp usando o Argos Voip.",
      "parameters": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "description": "Número com DDI e DDD (ex: 5511999998888)"
          },
          "contact_name": {
            "type": "string",
            "description": "Nome do contato"
          }
        },
        "required": ["to"]
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "argos_analyze_call",
      "description": "Executa análise de sentimento, resumo executivo e detecção de objeções em uma gravação de chamada.",
      "parameters": {
        "type": "object",
        "properties": {
          "call_id": {
            "type": "string",
            "description": "ID da chamada no sistema"
          },
          "text": {
            "type": "string",
            "description": "Texto transcrito caso queira analisar diretamente"
          }
        }
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "argos_get_call_status",
      "description": "Verifica o status em tempo real de uma ligação (ringing, in_progress, completed).",
      "parameters": {
        "type": "object",
        "properties": {
          "call_id": {
            "type": "string",
            "description": "ID da chamada retornado no disparo"
          }
        },
        "required": ["call_id"]
      }
    }
  }
]
```

---

## 7. Exemplo Completo em Python (com OpenAI Function Calling)

```python
import os
import requests
from openai import OpenAI

ARGOS_API_KEY = os.getenv("ARGOS_API_KEY", "ag_live_9f8a42c6b9d04e7f9a12bc503e91a0c7")
ARGOS_BASE_URL = "https://api.argosvoip.com.br/api/v1"

def call_argos_api(endpoint, method="POST", data=None):
    headers = {
        "Authorization": f"Bearer {ARGOS_API_KEY}",
        "Content-Type": "application/json"
    }
    url = f"{ARGOS_BASE_URL}{endpoint}"
    if method == "POST":
        res = requests.post(url, json=data or {}, headers=headers)
    else:
        res = requests.get(url, headers=headers)
    return res.json()

# Exemplo de disparo de chamada
disparo = call_argos_api("/calls/audio", method="POST", data={
    "to": "5511999998888",
    "contact_name": "Mariana Silva"
})
print("Chamada disparada:", disparo.get("call_id"))

# Exemplo de análise por IA
analise = call_argos_api("/ai/analyze", method="POST", data={
    "call_id": disparo.get("call_id"),
    "text": "O cliente confirmou a renovação e pediu envio da fatura via PIX."
})
print("Sentimento:", analise.get("sentiment"), "Score:", analise.get("sentiment_score"))
```