API atual/Referência completa/WhatsApp: caixa de entrada

Busca de mensagens e métricas

Procura mensagens em todas as conversas e consulta os números do atendimento por período.

Duas consultas de leitura: a busca localiza mensagens pelo texto em qualquer conversa, e as métricas resumem o volume de atendimento num período, com a série diária para gráficos.

Buscar mensagens

Exige ao menos um filtro entre q, type, direction, vendor_id, from e to. A busca de texto ignora maiúsculas e minúsculas e procura no trecho do corpo.

GET/api/v1/admin/whatsapp/messages/searchAdmin

Procura mensagens por texto, tipo, direção, seller e data

Parâmetros de consulta

qstring

Trecho do texto.

typestring

textimagevideoaudiodocumentbuttoninteractivelocation

Tipo da mensagem.

directionstring

inboundoutbound

Direção.

vendor_idstring

UUID do seller.

fromstring

Data inicial YYYY-MM-DD (inclusiva).

tostring

Data final YYYY-MM-DD (inclusiva).

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página (máximo 200).

Exemplo de requisição (Buscar mensagens)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/messages/search?q=camisa&direction=inbound" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Buscar mensagens)

200Resultados

json

{
  "hits": [
    {
      "id": 2027,
      "thread_id": "014ff6d8-8ff0-40da-82ce-e5a349b57be6",
      "customer_phone": "+5511999990428",
      "direction": "inbound",
      "message_type": "text",
      "body": "Oi, tem a camisa M?",
      "match_snippet": "Oi, tem a camisa M?",
      "created_at": "2026-10-11T14:52:49Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50,
  "total_pages": 1,
  "q": "camisa"
}

Campos da resposta

hitsarray

Mensagens encontradas.

idinteger

Id da mensagem.

thread_idstring

UUID da conversa, para abrir o resultado.

customer_phonestring

Telefone do cliente.

directionstring

inbound ou outbound.

message_typestring

Tipo.

bodystring

Texto completo.

match_snippetstring

Trecho em torno do que casou.

template_namestring

Template, se houver.

created_atstring

Data, RFC 3339.

totalinteger

Total de resultados.

pageinteger

Página.

per_pageinteger

Itens por página.

total_pagesinteger

Páginas.

qstring

Texto buscado.

Erros (Buscar mensagens)

Status	Quando	Corpo
400	Nenhum filtro informado, ou data inválida.	`{"error":"at least one of q, type, direction, vendor_id, from, to is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_orders"}` ou `{"error":"admin access required"}`

Métricas de atendimento

Sem parâmetros, cobre os últimos 30 dias. O intervalo máximo é 366 dias. As datas são dias inteiros em UTC e to entra por inteiro.

GET/api/v1/admin/whatsapp/metricsAdmin

Resume o volume de conversas e mensagens num período

Parâmetros de consulta

fromstring

Início YYYY-MM-DD.

tostring

Fim YYYY-MM-DD (inclusivo).

Exemplo de requisição (Métricas de atendimento)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/metrics?from=2026-09-12&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Métricas de atendimento)

200Métricas

json

{
  "from": "2026-09-12",
  "to": "2026-10-12",
  "conversations_total": 41,
  "conversations_new": 18,
  "messages_inbound": 320,
  "messages_outbound": 210,
  "bot_escalated": 6,
  "active_sessions": 3,
  "escalation_rate": 0.1463,
  "daily_series": [
    {
      "date": "2026-09-12",
      "conversations": 2,
      "inbound": 12,
      "outbound": 8
    }
  ]
}

Campos da resposta

fromstring

Início aplicado.

tostring

Fim (exclusivo): o dia seguinte ao pedido.

conversations_totalinteger

Conversas com atividade no período.

conversations_newinteger

Conversas criadas no período.

messages_inboundinteger

Mensagens recebidas de clientes.

messages_outboundinteger

Mensagens enviadas.

bot_escalatedinteger

Conversas em que o assistente passou para um humano.

active_sessionsinteger

Fluxos de conversa ativos agora.

escalation_ratenumber

bot_escalated dividido pelo total, de 0 a 1.

daily_seriesarray

Um ponto por dia: date, conversations, inbound, outbound.

Erros (Métricas de atendimento)

Status	Quando	Corpo
400	Data fora do formato, `from` depois de `to`, ou intervalo acima de 366 dias.	`{"error":"invalid 'from' date; expected YYYY-MM-DD"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_orders"}` ou `{"error":"admin access required"}`

Veja também

API atual/Referência completa/WhatsApp: caixa de entrada

Busca de mensagens e métricas

Procura mensagens em todas as conversas e consulta os números do atendimento por período.

Duas consultas de leitura: a busca localiza mensagens pelo texto em qualquer conversa, e as métricas resumem o volume de atendimento num período, com a série diária para gráficos.

Buscar mensagens

Exige ao menos um filtro entre q, type, direction, vendor_id, from e to. A busca de texto ignora maiúsculas e minúsculas e procura no trecho do corpo.

GET/api/v1/admin/whatsapp/messages/searchAdmin

Procura mensagens por texto, tipo, direção, seller e data

Parâmetros de consulta

qstring

Trecho do texto.

typestring

textimagevideoaudiodocumentbuttoninteractivelocation

Tipo da mensagem.

directionstring

inboundoutbound

Direção.

vendor_idstring

UUID do seller.

fromstring

Data inicial YYYY-MM-DD (inclusiva).

tostring

Data final YYYY-MM-DD (inclusiva).

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página (máximo 200).

Exemplo de requisição (Buscar mensagens)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/messages/search?q=camisa&direction=inbound" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Buscar mensagens)

200Resultados

json

{
  "hits": [
    {
      "id": 2027,
      "thread_id": "014ff6d8-8ff0-40da-82ce-e5a349b57be6",
      "customer_phone": "+5511999990428",
      "direction": "inbound",
      "message_type": "text",
      "body": "Oi, tem a camisa M?",
      "match_snippet": "Oi, tem a camisa M?",
      "created_at": "2026-10-11T14:52:49Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50,
  "total_pages": 1,
  "q": "camisa"
}

Campos da resposta

hitsarray

Mensagens encontradas.

idinteger

Id da mensagem.

thread_idstring

UUID da conversa, para abrir o resultado.

customer_phonestring

Telefone do cliente.

directionstring

inbound ou outbound.

message_typestring

Tipo.

bodystring

Texto completo.

match_snippetstring

Trecho em torno do que casou.

template_namestring

Template, se houver.

created_atstring

Data, RFC 3339.

totalinteger

Total de resultados.

pageinteger

Página.

per_pageinteger

Itens por página.

total_pagesinteger

Páginas.

qstring

Texto buscado.

Erros (Buscar mensagens)

Status	Quando	Corpo
400	Nenhum filtro informado, ou data inválida.	`{"error":"at least one of q, type, direction, vendor_id, from, to is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_orders"}` ou `{"error":"admin access required"}`

Métricas de atendimento

Sem parâmetros, cobre os últimos 30 dias. O intervalo máximo é 366 dias. As datas são dias inteiros em UTC e to entra por inteiro.

GET/api/v1/admin/whatsapp/metricsAdmin

Resume o volume de conversas e mensagens num período

Parâmetros de consulta

fromstring

Início YYYY-MM-DD.

tostring

Fim YYYY-MM-DD (inclusivo).

Exemplo de requisição (Métricas de atendimento)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/metrics?from=2026-09-12&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Métricas de atendimento)

200Métricas

json

{
  "from": "2026-09-12",
  "to": "2026-10-12",
  "conversations_total": 41,
  "conversations_new": 18,
  "messages_inbound": 320,
  "messages_outbound": 210,
  "bot_escalated": 6,
  "active_sessions": 3,
  "escalation_rate": 0.1463,
  "daily_series": [
    {
      "date": "2026-09-12",
      "conversations": 2,
      "inbound": 12,
      "outbound": 8
    }
  ]
}

Campos da resposta

fromstring

Início aplicado.

tostring

Fim (exclusivo): o dia seguinte ao pedido.

conversations_totalinteger

Conversas com atividade no período.

conversations_newinteger

Conversas criadas no período.

messages_inboundinteger

Mensagens recebidas de clientes.

messages_outboundinteger

Mensagens enviadas.

bot_escalatedinteger

Conversas em que o assistente passou para um humano.

active_sessionsinteger

Fluxos de conversa ativos agora.

escalation_ratenumber

bot_escalated dividido pelo total, de 0 a 1.

daily_seriesarray

Um ponto por dia: date, conversations, inbound, outbound.

Erros (Métricas de atendimento)

Status	Quando	Corpo
400	Data fora do formato, `from` depois de `to`, ou intervalo acima de 366 dias.	`{"error":"invalid 'from' date; expected YYYY-MM-DD"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_orders"}` ou `{"error":"admin access required"}`