Ir para o conteúdo

Consultar métricas e conversas

Você pode obter métricas sobre mensagens e conversas associadas à sua conta do WhatsApp Business (WABA, pelas iniciais em inglês). Por exemplo, é possível obter o número de mensagens enviadas e entregues, dados de conversa, assim como o número de envios de cada modelo.

Somente métricas de números de telefone e modelos comerciais associados à sua WABA no momento da solicitação serão incluídas na resposta.

Análise de Métricas

Fornece o número e o tipo de mensagens enviadas e entregues por números de telefone associados a uma WABA específica.

URI

URI: https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/metricas
Método: GET

Você pode anexar os parâmetros a seguir.

Parâmetros de análise

Nome Descrição
início

Tipo: registro de data e hora UNIX ou no formato "dd-MM-yyyy"

Obrigatório.

É a data de início do intervalo para o qual você está recuperando análises.
fim

Tipo: registro de data e hora UNIX ou no formato "dd-MM-yyyy"

Obrigatório.

É a data de término do intervalo para o qual você está recuperando análises.
granularidade

Tipo: string

 Obrigatório.

É o detalhamento desejado para a análise.

Valores possíveis:

- MEIA_HORA

- DIA

- MES
numerosTelefone

Tipo: matriz

 Opcional.

É a matriz de números de telefone referentes à análise que você quer recuperar. Caso não seja fornecida, todos os números de telefone adicionados à sua WABA serão incluídos.
tiposProdutos

Tipo: matriz

 Opcional.

São os tipos de mensagens referentes à análise que você quer recuperar (mensagens de notificação e/ou de suporte ao cliente). Forneça uma matriz e inclua 0 para mensagens de notificação e 2 para mensagens de suporte ao cliente. Caso a matriz não seja fornecida, retornaremos análises para todas as mensagens.

Valores possíveis:

- NOTIFICACAO

- SUPORTE_CLIENTE
codigosPaises

Tipo: matriz

 Opcional.

São os países referentes à análise que você quer recuperar. Forneça uma matriz com códigos de duas letras para os países a serem incluídos. Caso a matriz não seja fornecida, retornaremos análises para todos os países com os quais você se comunicou.

Exemplo

Cenário: você precisa obter o número de mensagens enviadas e entregues por todos os números de telefone associados à sua WABA.

Solução sugerida: monte a URL que você quer chamar e inclua estes parâmetros de filtragem: inicio, fim e granularidade. Depois disso, faça uma solicitação GET à URL: 

curl -i -X GET \ 
"https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/metricas?inicio=1680503760&fim=1695754714962&granularidade=DIA
Uma resposta bem-sucedida retornará um objeto analytics com os dados solicitados:

{
  "analytics": {
    "numerosTelefone": [
      "16505550111",
      "16505550112",
      "16505550113"
    ],
    "codigosPaises": [
      "US",
      "BR"
    ],
    "granularidade": "DIA",
    "dados": [
      {
        "inicio": 1543543200,
        "fim": 1543629600,
        "quantidadeEnviadas": 196093,
        "quantidadeEntregues": 179715
      },
      {
        "inicio": 1543629600,
        "fim": 1543716000,
        "quantidadeEnviadas": 147649,
        "quantidadeEntregues": 139032
      },
      {
        "inicio": 1543716000,
        "fim": 1543802400,
        "quantidadeEnviadas": 61988,
        "quantidadeEntregues": 58830
      },
      {
        "inicio": 1543802400,
        "fim": 1543888800,
        "quantidadeEnviadas": 132465,
        "quantidadeEntregues": 124392
      }
      # more data points
    ]
  },
  "id": "102290129340398"
}

Análise de conversas

Fornece informações de conversas para uma WABA específica.

URI

URI: https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/metricas/conversas
Método: GET

Você pode anexar os parâmetros a seguir.

Nome Descrição
início

Tipo: registro de data e hora UNIX ou no formato "dd-MM-yyyy"

Obrigatório.

É a data de início do intervalo para o qual você está recuperando análises.
fim

Tipo: registro de data e hora UNIX ou no formato "dd-MM-yyyy"

Obrigatório.

É a data de término do intervalo para o qual você está recuperando análises.
granularidade

Tipo: string

 Obrigatório.

É o detalhamento desejado para a análise.

Valores possíveis:

- MEIA_HORA

- DIA

- MES
tiposConversa Opcional.

É uma lista de tipos de conversa. Se você enviar uma lista vazia, retornaremos resultados para todos os tipos de conversa.

Valores possíveis:

- ENTRADA_GRATUITA

- NIVEL_GRATUITO

- REGULAR
direcoesConversa Opcional.

É uma lista de direções de conversa. Se você enviar uma lista vazia, retornaremos resultados para todas as direções de conversa.

Valores possíveis:

- INICIADA_PELA_EMPRESA

- INICIADA_PELO_USUARIO
dimensoesConversas Opcional.

É a lista de detalhamentos que você quer aplicar às suas métricas. Se você enviar uma lista vazia, retornaremos os resultados sem detalhamento.

Valores possíveis:

- CATEGORIA_CONVERSA

- DIRECAO_CONVERSA

- TIPO_CONVERSA

- PAIS

- TELEFONE

Importante!

Os dados de análise são aproximados e podem ser diferentes do que aparece nas faturas devido a pequenas variações no processamento.

Exemplo

Ao definir um período, você pode obter informações de conversas associadas à sua WABA. É possível filtrar e detalhar os resultados. Consulte os exemplos de código abaixo.

Como obter dados mensais usando todos os detalhamentos

Cenário: em um determinado mês, você quer recuperar informações de conversa de todos os números de telefone associados a uma WABA.

Solução sugerida: monte a URL que você quer chamar e inclua estes parâmetros de filtragem:

  • inicio: indica o início do período. Nesse caso, é o início do mês referente às métricas que você quer ver.
  • fim: indica o término do período. Nesse caso, é o término do mês para o qual você que ver as métricas.
  • granularidade: representa o detalhamento desejado para os pontos de dados. No exemplo abaixo, usamos MES para que cada ponto represente o valor de um mês de dados.
  • dimensoesConversas: defina todos os detalhamentos disponíveis: "CATEGORIA_CONVERSA", "TIPO_CONVERSA", "PAIS" e "TELEFONE".

Nesse caso, não é preciso especificar country_codes, metric_types, conversation_types nem conversation_categories. Se você não enviar um valor para esses campos, retornaremos todas as opções disponíveis. Depois de configurar a URL, faça uma solicitação GET: 

curl -i -X GET
"https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/metricas/conversas?inicio=12-05-2022&fim=12-10-2022&granularidade=MES&dimensoesConversas=CATEGORIA_CONVERSA&dimensoesConversas=TIPO_CONVERSA&dimensoesConversas=PAIS&dimensoesConversas=TELEFONE

Uma resposta bem-sucedida retornará um objeto conversation_analytics com os dados solicitados. No exemplo a seguir, a WABA contém apenas um número de telefone. 

{
    "id": "110115228401530",
    "analytics": {
        "dados": [
            {
                "pontosDeDados": [
                    {
                        "inicio": 12-05-2022,
                        "fim": 12-06-2022,
                        "conversas": 1,
                        "pais": "BR",
                        "tipoConversa": "NIVEL_GRATUITO",
                        "direcaoConversa": "INICIADA_PELO_USUARIO",
                        "categoriaConversa": "DESCONHECIDO"
                    },
                    {
                        "inicio": 12-06-2022,
                        "fim": 12-08-2022,
                        "conversas": 1,
                        "pais": "BR",
                        "tipoConversa": "NIVEL_GRATUITO",
                        "direcaoConversa": "INICIADA_PELO_USUARIO",
                        "categoriaConversa": "DESCONHECIDO"
                    },
                    {
                        "inicio": 12-08-2022,
                        "fim": 12-10-2022,
                        "conversas": 8,
                        "pais": "BR",
                        "tipoConversa": "NIVEL_GRATUITO",
                        "direcaoConversa": "INICIADA_PELO_USUARIO",
                        "categoriaConversa": "DESCONHECIDO"
                    }
                  ]
            }
        ]
    }
}