Métricas & Insights

9. Métricas & Insights#

O canal oficial expõe as métricas da WhatsApp Business Management API da Meta: qualidade do número, volume de envios, taxa de entrega e custo das conversas cobradas por categoria. Ideal para dashboards de operação e custo.

Insights consolidados#

text 
GET /v1/instances/{instanceId}/official/insights?days=30

days aceita 1 a 90 (padrão 30). Cada seção é best-effort — se uma métrica não puder ser carregada, ela vira um aviso em warnings e o resto continua (nunca falha o dashboard inteiro).

json 
{
  "period": { "start": 1781748265, "end": 1784340265, "days": 30 },
  "quality": {
    "quality_rating": "GREEN",
    "messaging_limit_tier": "TIER_1K",
    "name_status": "AVAILABLE_WITHOUT_REVIEW",
    "display_phone_number": "+55 41 6349-0888",
    "verified_name": "Catcher"
  },
  "messaging": {
    "sent": 1240,
    "delivered": 1198,
    "points": [{ "start": 1784257200, "end": 1784343600, "sent": 42, "delivered": 41 }]
  },
  "cost": {
    "total_cost": 18.60,
    "total_conversations": 74,
    "by_category": [
      { "category": "MARKETING", "conversations": 40, "cost": 14.20 },
      { "category": "UTILITY", "conversations": 34, "cost": 4.40 }
    ],
    "points": [ ]
  },
  "warnings": [ ]
}
Campo Significado
quality.quality_rating GREEN (alta) / YELLOW (média) / RED (baixa). Reflete a satisfação dos destinatários.
quality.messaging_limit_tier Limite de contatos únicos por dia: TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED.
messaging.sent / delivered Volume no período. A taxa de entrega é delivered / sent.
cost.by_category Conversas cobradas e custo por categoria (MARKETING, UTILITY, AUTHENTICATION, SERVICE). Conversas de atendimento na janela de serviço não geram custo.

Analytics por template#

text 
GET /v1/instances/{instanceId}/official/template-analytics?days=30&template_ids=T1,T2

Funil por template (enviados → entregues → lidos) e cliques por botão. Requer que a WABA tenha o analytics de template habilitado na Meta (opt-in único); sem isso, retorna um 400 limpo.

json 
{
  "period": { "start": 1781748265, "end": 1784340265, "days": 30 },
  "data_points": [
    {
      "template_id": "T1",
      "sent": 400, "delivered": 388, "read": 300,
      "clicked": [{ "type": "quick_reply_button", "button_content": "Sim", "count": 120 }]
    }
  ]
}

Uso da conexão#

text 
GET /v1/instances/{instanceId}/official/usage

Rollup de medição da conexão na janela recente (mensagens enviadas/recebidas, templates enviados, conversas).

json 
{
  "instance_id": "<uuid>",
  "channel": "whatsapp_official",
  "period_days": 30,
  "messages_sent": 1240,
  "messages_received": 980,
  "templates_sent": 74,
  "conversations": 74
}