API de Análise e Relatórios

Estes endpoints de leitura apenas permitem-lhe extrair a atividade da sua conta para os seus próprios dashboards e relatórios: contagens de eventos de mensagens, consumo de créditos, gastos com IA e os mesmos gráficos e informações que o dashboard na aplicação apresenta. Este guia abrange:

Resumo — contadores de volume de mensagens (enviadas, entregues, lidas, respondidas, agendadas, contactos criados, créditos).
Créditos — um registo detalhado e paginado da utilização de créditos com totais e detalhamentos.
Custo de IA — um resumo diário dos gastos com IA.
Séries de métricas — uma série temporal pronta a usar em gráficos para uma ou mais métricas, agrupadas por campanha, canal, Agente de IA ou número.
Resultados das conversas — como as conversas terminaram, por etiqueta de resultado atribuída pela IA.
Informações do Dashboard e Informações de IA do Dashboard — todos os dados por detrás do dashboard na aplicação, incluindo resumos escritos pela IA.
Atividade da entidade — a cronologia de um único contacto, negócio ou tarefa.
Contagens de eventos agregados — uma forma legada, em camelCase, do Resumo, mantida para integrações existentes.

Cada endpoint nesta página necessita de um âmbito exato, não de ambos: passe no máximo um de campaign_id (legado) ou agent_id onde o endpoint o aceite. Enviar ambos devolve 400, e um id que não pertença à sua conta devolve 404 em vez de 403, para que os ids de outras contas permaneçam impossíveis de adivinhar.

Todos os caminhos abaixo são relativos ao URL base da API:

https://api.youraiconnector.com/v1

Todos os pedidos devem ser autenticados. Consulte Autenticação para os quatro métodos aceites. Os exemplos aqui utilizam o cabeçalho X-API-Key (e uma forma de parâmetro de consulta para cURL).

Intervalo de datas

Todos os três endpoints aceitam os mesmos filtros de data opcionais:

Parâmetro	Descrição
`from`	Início do intervalo, `YYYY-MM-DD`, inclusivo. O padrão é há 30 dias.
`to`	Fim do intervalo, `YYYY-MM-DD`, inclusivo. O padrão é hoje.

As datas são interpretadas em UTC. O intervalo tem como padrão os últimos 30 dias e está limitado a 366 dias — um intervalo mais amplo devolve 400. from não deve ser posterior a to.

O sinalizador `truncated`

Os endpoints de Resumo e Créditos limitam quantos registos um único pedido analisa. Se o seu intervalo for suficientemente movimentado para atingir esse limite, a resposta inclui "truncated": true. Quando o vir, os números baseiam-se numa análise parcial — reduza o seu intervalo de datas (ou navegue pelas páginas com uma janela mais pequena) para obter números completos.

Nota: Os valores de custo e de tokens apenas são incluídos para chamadas de IA faturadas através das suas próprias chaves de API de fornecedor. Quando os valores de custo estão ocultos para a sua conta, a resposta define "costs_redacted": true e os campos de custo são devolvidos como zero.

Resumo do volume de mensagens

Devolve contadores agregados de eventos de mensagens para a sua conta, tanto como totais do intervalo como como uma série diária. Todos os dias no intervalo aparecem em by_date — os dias sem atividade são preenchidos com zero. Opcionalmente, filtre para uma única campanha com campaign_id.

GET /analytics/summary

Parâmetro	Obrigatório	Descrição
`from`	Não	Início do intervalo, `YYYY-MM-DD`.
`to`	Não	Fim do intervalo, `YYYY-MM-DD`.
`campaign_id`	Não	Contar apenas eventos pertencentes a esta campanha.

cURL

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/summary?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/summary",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

Resposta

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total": 1240,
    "sent": 800,
    "delivered": 760,
    "read": 540,
    "replied": 210,
    "booked": 35,
    "contact_created": 120,
    "credits_spent": 412.5,
    "credits_recharged": 500
  },
  "by_date": [
    {
      "date": "2026-05-01",
      "total": 40,
      "sent": 25,
      "delivered": 24,
      "read": 18,
      "replied": 7,
      "booked": 1,
      "contact_created": 4,
      "credits_spent": 13.5,
      "credits_recharged": 0
    }
  ],
  "truncated": false
}

Cada entrada em by_date tem os mesmos campos de contador que totals, mais um date.

Se passar um campaign_id que não pertence à sua conta, a resposta será 404 com { "success": false, "error": "Campaign not found" }.

Utilização de créditos

Devolve a utilização de créditos durante o intervalo: uma lista paginada de registos individuais, além de totais do intervalo e detalhamentos por motivo e por campanha.

GET /analytics/credits

Parâmetro	Obrigatório	Descrição
`from`	Não	Início do intervalo, `YYYY-MM-DD`.
`to`	Não	Fim do intervalo, `YYYY-MM-DD`.
`campaign_id`	Não	Incluir apenas a utilização atribuída a esta campanha.
`limit`	Não	Tamanho da página para `records`, 1–100. O padrão é 50.
`cursor`	Não	Passe o `next_cursor` da página anterior para obter a página seguinte.

Ajustes vs. consumo: Alterações de saldo, tais como bónus, renovações de planos e correções, são excluídas de totals e dos detalhamentos — não constituem consumo real. Ainda aparecem na lista records, assinaladas com "is_adjustment": true.

Os totais e detalhamentos aparecem apenas na primeira página (quando não é fornecido nenhum cursor). Nas páginas seguintes, totals, by_reason, by_reason_cost e by_campaign são devolvidos como null — apenas a matriz records continua. Isto evita voltar a analisar todo o intervalo para cada página.

cURL

curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  limit: "50",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/credits?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

// To page: pass data.next_cursor as ?cursor on the next request, until it is null.

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/credits",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31", "limit": 50},
)
data = res.json()

# To page: pass data["next_cursor"] as cursor on the next request, until it is None.

Resposta (primeira página)

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "credits_used": 412.5,
    "cost_usd": 1.284512,
    "records": 318
  },
  "by_reason": {
    "AI Message": 380.0,
    "Campaign Message": 32.5
  },
  "by_reason_cost": {
    "AI Message": 1.284512,
    "Campaign Message": 0
  },
  "by_campaign": {
    "Spring Promo": 250.0,
    "Reactivation": 162.5
  },
  "records": [
    {
      "id": "rec_abc123",
      "amount": 1,
      "timestamp": "2026-05-31T14:02:11.000Z",
      "reason": "AI Message",
      "is_adjustment": false,
      "campaign_id": "campaign123",
      "campaign_name": "Spring Promo",
      "contact_id": "contact456",
      "contact_name": "Jane Smith",
      "credit_type": "ai",
      "custom_keys_used": false,
      "description": null,
      "cost_usd": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "ai_model": null,
      "request_id": null,
      "is_test": false
    }
  ],
  "next_cursor": "rec_abc123",
  "costs_redacted": false,
  "truncated": false
}

Notas de campo:

amount — créditos cobrados pelo registo. Zero para registos faturados na sua própria chave de API de fornecedor.
is_adjustment — true para alterações de saldo (excluídas dos totais/detalhamentos).
cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — preenchidos apenas em registos faturados na sua própria chave de API de fornecedor; zero ou null caso contrário.
is_test — true para execuções de teste/playground, que nunca são faturadas.
next_cursor — o cursor para a página seguinte, ou null quando não existem mais registos.

Resumo de custos de IA

Devolve o resumo diário de gastos com IA da sua conta. Isto lê totais diários pré-agregados, pelo que é rápido mesmo em intervalos longos. Todos os dias no intervalo aparecem em days — os dias sem atividade são preenchidos com zero.

GET /analytics/ai-cost

Parâmetro	Obrigatório	Descrição
`from`	Não	Início do intervalo, `YYYY-MM-DD`.
`to`	Não	Fim do intervalo, `YYYY-MM-DD`.

cURL

curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/ai-cost?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/ai-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

Resposta

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total_usd": 12.4821,
    "byok_usd": 12.4821,
    "platform_usd": 0,
    "calls": 4210
  },
  "days": [
    {
      "date": "2026-05-01",
      "total_usd": 0.4012,
      "byok_usd": 0.4012,
      "platform_usd": 0,
      "input_usd": 0.18,
      "output_usd": 0.19,
      "cache_creation_usd": 0.02,
      "cache_read_usd": 0.0112,
      "calls": 140,
      "by_provider": { "anthropic": 0.4012 }
    }
  ],
  "costs_redacted": false
}

Notas de campo:

byok_usd — despesas cobradas através das suas próprias chaves de API de fornecedor.
platform_usd — a parte das despesas que foi executada na plataforma em vez de na sua própria chave.
input_usd, output_usd, cache_creation_usd, cache_read_usd — as componentes de custo que constituem total_usd.
by_provider — despesas em USD organizadas pelo nome do fornecedor de IA.
Os valores em USD só são devolvidos a contas que utilizam a sua própria chave de fornecedor. Para contas que pagam com crédito, todos os campos em USD são zero e costs_redacted é true (as contagens de chamadas permanecem visíveis).

Séries de métricas

Devolve uma ou mais séries temporais de métricas numa única chamada, opcionalmente agrupadas por até duas dimensões — o endpoint para vincular a um gráfico. Um único pedido pode responder a “enviadas e respondidas por dia, por canal, para esta campanha” sem ser necessária uma chamada por campanha.

GET /analytics/series

Cada resposta contém uma matriz labels (o eixo temporal, preenchido com zeros em todo o intervalo) e uma entrada em series por grupo, cada uma contendo uma matriz por métrica solicitada alinhada com labels. As séries após limit não são descartadas — colapsam em other_bucket, calculado como o total do intervalo menos as séries devolvidas, para que um gráfico renderizado some sempre os seus números reais; truncated é true sempre que isso acontece.

De onde vêm os números: sent, delivered, read e replied provêm de registos de mensagens, que contêm o canal e o número de envio. booked, contact_created e credits_spent provêm do fluxo de eventos, que não contém número de envio, pelo que essas métricas caem no balde de número null quando agrupa por number.

Parâmetro	Obrigatório	Descrição
`from`	Não	Início do intervalo, `YYYY-MM-DD`. O padrão é há 30 dias.
`to`	Não	Fim do intervalo, `YYYY-MM-DD`. O padrão é hoje.
`metrics`	Não	Lista separada por vírgulas de `sent`, `ai_sent`, `human_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent`. O padrão é `sent,replied`. Uma métrica desconhecida devolve `400`.
`group_by`	Não	Lista separada por vírgulas de até duas dimensões de `date`, `campaign`, `channel`, `agent`, `number`. `date` é aceite, mas não tem efeito — cada resposta já contém o eixo temporal. Omitir para uma única série de toda a conta.
`granularity`	Não	`day` (padrão), `week` ou `month`. Os baldes semanais começam à segunda-feira, os baldes mensais no dia 1.
`limit`	Não	Quantas séries devolver antes que o resto colapse em `other_bucket`, 1–50. O padrão é 12.
`campaign_id`	Não	Contar apenas a atividade pertencente a esta campanha. Legado; prefira `agent_id`.
`agent_id`	Não	Contar apenas a atividade pertencente a este Agente de IA.
`channel`	Não	Contar apenas a atividade neste canal, por exemplo `whatsapp`.

O intervalo de datas deste endpoint está limitado a 92 dias (mais restrito do que o limite de 366 dias usado noutros locais desta página).

cURL

curl "https://api.youraiconnector.com/v1/analytics/series?from=2026-05-01&to=2026-05-31&metrics=sent,replied,booked&group_by=campaign,channel&limit=10&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  metrics: "sent,replied,booked",
  group_by: "campaign,channel",
  limit: "10",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/series?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/series",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "from": "2026-05-01",
        "to": "2026-05-31",
        "metrics": "sent,replied,booked",
        "group_by": "campaign,channel",
        "limit": 10,
    },
)
data = res.json()

Resposta

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "granularity": "day",
  "labels": ["2026-05-01", "2026-05-02"],
  "group_by": ["campaign", "channel"],
  "metrics": ["sent", "replied", "booked"],
  "series": [
    {
      "key": {
        "campaign_id": "campaign123",
        "campaign_name": "Spring Promo",
        "channel": "whatsapp"
      },
      "total": 812,
      "metrics": {
        "sent": [40, 35],
        "replied": [12, 9],
        "booked": [2, 1]
      }
    }
  ],
  "other_bucket": {
    "series_count": 6,
    "total": 340,
    "metrics": {
      "sent": [18, 20],
      "replied": [5, 6],
      "booked": [0, 1]
    }
  },
  "truncated": true
}

Notas de campo:

key — a identidade de uma série. Apenas as chaves para as dimensões group_by solicitadas estão presentes; uma dimensão cujo valor é desconhecido para uma linha (uma mensagem sem campanha, um evento sem canal) volta como null em vez de ser descartada, para que as séries continuem a somar os totais.
other_bucket — null quando nada foi colapsado.
Este endpoint devolve 503 com "error_code": "analytics_unavailable" quando a base de dados de relatórios não consegue responder pela sua conta, em vez de um 200 cheio de zeros — um gráfico a zeros seria lido como um facto.

Resultados das conversas

Devolve como as conversas terminaram durante um intervalo de datas: uma contagem diária para cada etiqueta de resultado que a IA atribuiu, mais totais de intervalo para respostas, agendamentos, transferências para um humano e conversas que a IA nunca classificou.

GET /analytics/outcomes

Passe group_by=tag para colapsar o eixo temporal e obter apenas totais de intervalo por etiqueta — nesse modo, labels está vazio e a matriz counts de cada etiqueta está vazia, enquanto total continua preenchido.

Parâmetro	Obrigatório	Descrição
`from`	Não	Início do intervalo, `YYYY-MM-DD`. Predefinição: há 30 dias.
`to`	Não	Fim do intervalo, `YYYY-MM-DD`. Predefinição: hoje.
`campaign_id`	Não	Contar apenas conversas com contactos atualmente nesta campanha. Legado; prefira `agent_id`.
`agent_id`	Não	Contar apenas resultados pertencentes a este Agente de IA.
`group_by`	Não	`date` (predefinição) mantém as contagens diárias; `tag` agrupa em totais de intervalo.

O intervalo de datas deste endpoint está limitado a 92 dias.

cURL

curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/outcomes?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/outcomes",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

Resposta

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "group_by": "date",
  "labels": ["2026-05-01", "2026-05-02"],
  "by_tag": [
    { "tag": "interested", "total": 84, "counts": [3, 5] },
    { "tag": "not_interested", "total": 40, "counts": [1, 2] },
    { "tag": null, "total": 12, "counts": [0, 1] }
  ],
  "totals": {
    "sessions": 260,
    "replied": 210,
    "booked": 35,
    "human_alerted": 18,
    "unresolved": 12
  }
}

Notas de campo:

by_tag[].tag — null para conversas às quais a IA nunca atribuiu uma etiqueta de resultado.
totals.human_alerted — conversas transferidas para um humano; isto é registado em cada transferência e não era anteriormente apresentado por nenhum endpoint.
Mesma postura 503/analytics_unavailable que a série de Métricas quando a base de dados de relatórios não consegue responder.

Informações do dashboard

Devolve o payload completo do dashboard para um intervalo de datas numa única chamada: um mapa de calor da taxa de resposta por dia da semana e hora, a tabela de classificação de campanhas, volume por canal, totais exatos por ligação, detalhe de métricas por dia (a nível de conta, por canal e por número), origem dos contactos, tempo de resposta da caixa de entrada e um feed de atividade recente. Este é o payload de relatórios mais rico da API — alimenta diretamente o dashboard na aplicação.

GET /analytics/dashboard-insights

Parâmetro	Obrigatório	Descrição
`startDate`	Sim	Início do intervalo, `YYYY-MM-DD`.
`endDate`	Sim	Fim do intervalo, `YYYY-MM-DD`.
`campaignId`	Não	Incluir apenas atividade pertencente a esta campanha (`campaign_id` também aceite). Legado; prefira `agent_id`.
`agent_id`	Não	Incluir apenas atividade pertencente a este Agente de IA (`agentId` também aceite). Sob o âmbito de um agente, a tabela de classificação de campanhas é construída apenas a partir da atividade desse agente.

Este endpoint utiliza startDate/endDate (não from/to) porque partilha a sua implementação com o dashboard na aplicação. O intervalo está limitado a 92 dias e é ajustado, não rejeitado, quando é superior.

Nulo significa indisponível, não zero. Vários blocos (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) são calculados a partir da base de dados de relatórios e devolvem null quando esta não consegue responder pela sua conta. Não apresente um bloco null como um gráfico vazio.

cURL

curl "https://api.youraiconnector.com/v1/analytics/dashboard-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()

Resposta (abreviada — este payload é grande; consulte a Referência da API para o esquema completo)

{
  "success": true,
  "data": {
    "heatmap": {
      "buckets": [
        { "weekday": 1, "hour": 9, "sent": 12, "replied": 5, "replyRate": 0.42 }
      ]
    },
    "topCampaigns": [
      { "campaignId": "campaign123", "name": "Spring Promo", "sent": 420, "replied": 180, "booked": 22, "replyRate": 0.43, "creditsSpent": 210.5 }
    ],
    "channelVolume": [
      { "channel": "whatsapp", "sent": 800, "received": 540, "lastMessageAt": "2026-05-31T14:02:11.000Z" }
    ],
    "inboxSla": { "medianFirstResponseMs": 92000, "sampleSize": 140 },
    "activityFeed": [
      { "id": "evt_1", "kind": "booked", "at": "2026-05-31T14:02:11.000Z", "contactId": "contact456", "contactName": "Jane Smith", "campaignId": "campaign123", "campaignName": "Spring Promo", "label": "Jane Smith booked an appointment" }
    ],
    "numberStats": null,
    "channelDailySeries": null,
    "metricDailyBreakdown": null,
    "contactsByCountry": null,
    "ai_human_split": null
  }
}

Notas de campo:

heatmap.buckets[].weekday — 0 é domingo até 6 é sábado.
numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — cada um independentemente null quando a base de dados de relatórios está indisponível para a sua conta; todos os outros blocos continuam a devolver resultados.

Informações de IA do dashboard

Devolve três breves informações escritas por IA sobre as mensagens da conta durante um intervalo de datas: uma vitória, um ponto de atenção e uma dica — frases que pode colar diretamente num relatório em vez de números que ainda teria de interpretar. Gerado apenas a partir das métricas de mensagens da própria conta.

GET /analytics/dashboard-ai-insights

Parâmetro	Obrigatório	Descrição
`startDate`	Sim	Início do intervalo, `YYYY-MM-DD`.
`endDate`	Sim	Fim do intervalo, `YYYY-MM-DD`.

Este endpoint é aplicável a toda a conta — não requer âmbito de campanha ou de agente.

cURL

curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()

Resposta

{
  "success": true,
  "data": {
    "insights": [
      { "tone": "win", "title": "Reply rate is up", "detail": "Your reply rate climbed to 43% this period, up from 36% the period before." },
      { "tone": "watch", "title": "Bookings slowed midweek", "detail": "Wednesday bookings dropped to a third of Monday's, worth a look at your Wednesday follow-up timing." },
      { "tone": "tip", "title": "Re-send to non-repliers", "detail": "212 contacts received a message but never replied — a short follow-up template often recovers 10-15% of them." }
    ]
  }
}

A falta de startDate ou endDate devolve 400.

Cronologia de atividade da entidade

Devolve a atividade de um único contacto, negócio ou tarefa como uma cronologia única, da mais recente para a mais antiga: o que aconteceu e quando, através de mensagens, marcações, notas e alterações de estado. Utilize-o para responder a “o que aconteceu com esta pessoa” sem ter de combinar vários endpoints de lista.

GET /analytics/entity-activity

Parâmetro	Obrigatório	Descrição
`entityType`	Sim	`contact`, `deal` ou `task`.
`entityId`	Sim	ID do registo cuja cronologia pretende obter.

cURL

curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ entityType: "contact", entityId: "contact456" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/entity-activity?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/entity-activity",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"entityType": "contact", "entityId": "contact456"},
)
data = res.json()

Resposta

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "evt_9",
        "kind": "appointment_booked",
        "at": "2026-05-31T14:02:11.000Z",
        "label": "Booked an appointment for June 3",
        "detail": "Consultation call, 30 minutes"
      },
      {
        "id": "evt_8",
        "kind": "message_replied",
        "at": "2026-05-31T13:58:02.000Z",
        "label": "Replied: \"Yes, that time works\""
      }
    ]
  }
}

Um entityType/entityId em falta ou inválido devolve 400. Uma entidade que não existe na sua conta devolve 404, para que os IDs de outras contas permaneçam impossíveis de adivinhar.

Contagens de eventos agregadas (legado)

Devolve as mesmas contagens de eventos agregadas que o Resumo do volume de mensagens, mas no formato camelCase (contactCreated em vez de contact_created, byDate em vez de by_date) para o qual algumas integrações mais antigas foram criadas. Prefira /analytics/summary para novas integrações — este endpoint existe apenas para que o dashboard da aplicação e a API partilhem a mesma implementação.

GET /analytics/aggregate

Parâmetro	Obrigatório	Descrição
`startDate`	Não	Início do intervalo, data ou data-hora ISO. Predefinição para a mesma janela que `/analytics/summary` utiliza.
`endDate`	Não	Fim do intervalo, data ou data-hora ISO.
`campaignId`	Não	Contar apenas eventos pertencentes a esta campanha (`campaign_id` também aceite). Legado; prefira `agent_id`.
`agent_id`	Não	Contar apenas eventos pertencentes a este Agente de IA (`agentId` também aceite).

cURL

curl "https://api.youraiconnector.com/v1/analytics/aggregate?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "data": {
    "from": "2026-05-01",
    "to": "2026-05-31",
    "total": 1240,
    "byAnalyticType": {
      "total": 1240,
      "sent": 800,
      "delivered": 760,
      "read": 540,
      "replied": 210,
      "booked": 35,
      "contactCreated": 120,
      "creditsSpent": 412.5,
      "creditsRecharged": 500
    },
    "byDate": [
      { "date": "2026-05-01", "byAnalyticType": { "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contactCreated": 4, "creditsSpent": 13.5, "creditsRecharged": 0 } }
    ]
  }
}

Agrupamento de subcontas de agência

Erros da API de Analytics

Os endpoints de Analytics devolvem o envelope de erro padrão:

{
  "success": false,
  "error": "Date range too large. Maximum is 366 days."
}

Num endpoint de análise, um formato de data inválido ou uma janela fora do intervalo devolve 400, e um campaign_id ou agent_id desconhecido devolve 404. Enviar tanto campaign_id como agent_id num endpoint que aceite qualquer um deles é também um 400 — envie no máximo um. Os endpoints de relatórios exclusivos de PG (Série de métricas, Resultados de conversação, Agrupamento de agência) devolvem 503 com "error_code": "analytics_unavailable" em vez de um 200 cheio de zeros quando a base de dados de relatórios não consegue responder pela sua conta — tente novamente em breve. Os códigos partilhados que qualquer endpoint pode devolver — 401, 403 (o seu plano não inclui acesso à API ou, no agrupamento de agência, a sua conta não é Agência/Dev), 429 (limite de taxa) e 500 — estão listados com orientações de repetição em Erros e Paginação.

Próximos passos

Autenticação — as quatro formas de autenticar um pedido.
Erros e Limites de Taxa — códigos de estado e o limite de 300 pedidos/min.
API de Campanhas — as campanhas pelas quais estes números podem ser filtrados.

API de Análise e Relatórios #

Intervalo de datas #

O sinalizador truncated #

Resumo do volume de mensagens #

Utilização de créditos #

Resumo de custos de IA #

Séries de métricas #

Resultados das conversas #

Informações do dashboard #

Informações de IA do dashboard #

Cronologia de atividade da entidade #

Contagens de eventos agregadas (legado) #

Agrupamento de subcontas de agência #

Erros da API de Analytics #

Próximos passos #

API de Análise e Relatórios

Intervalo de datas

O sinalizador `truncated`

Resumo do volume de mensagens

Utilização de créditos

Resumo de custos de IA

Séries de métricas

Resultados das conversas

Informações do dashboard

Informações de IA do dashboard

Cronologia de atividade da entidade

Contagens de eventos agregadas (legado)

Agrupamento de subcontas de agência

Erros da API de Analytics

Próximos passos