VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: caixa de entrada

Conversas

Lista e abre as conversas de WhatsApp, marca como lida, liga e desliga o assistente e age em lote.

Uma conversa (thread) junta todas as mensagens trocadas entre um número da loja e um telefone de cliente. É a unidade da caixa de entrada: cada conversa tem um estado (assistente ligado ou atendente humano), um contador de não lidas, etiquetas e, opcionalmente, um atendente responsável. As rotas abaixo listam, abrem e organizam conversas.

Listar conversas

Devolve uma página de conversas. Os filtros se combinam. Se o usuário do token estiver vinculado a um seller, a lista é restrita a esse seller mesmo que você peça outro vendor_id.

GET/api/v1/admin/whatsapp/threadsAdmin

Lista as conversas, as mais recentes primeiro, com filtros

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 200. Fora disso vale 50.
statusstring
openpendingresolved
Atalho de estado. open: assistente ligado. pending: tem mensagens não lidas. resolved: nenhuma não lida. Quando enviado, substitui bot e unread.
botboolean
true só com assistente ligado; false só com humano.
unreadboolean
true só conversas com não lidas; false só sem.
vendor_idstring
UUID do seller.
qstring
Trecho do telefone do cliente.
fromstring
Início, YYYY-MM-DD, sobre a data da última mensagem do cliente (inclusivo).
tostring
Fim, YYYY-MM-DD (inclusivo).
assigned_tostring
me (você), unassigned (sem responsável) ou um UUID de usuário.
tagsstring
Etiquetas separadas por vírgula; a conversa precisa ter todas.

Exemplo de requisição (Listar conversas)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/threads?status=open&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar conversas)

200Página de conversas
json
{
  "threads": [
    {
      "id": "014ff6d8-8ff0-40da-82ce-e5a349b57be6",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Exemplo",
      "customer_phone": "+5511999990428",
      "customer_user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "bot_enabled": true,
      "last_inbound_at": "2026-10-11T14:52:49.987899Z",
      "last_outbound_at": "2026-10-11T14:50:10.100000Z",
      "unread_count": 1,
      "created_at": "2026-10-01T02:52:49.971994Z",
      "updated_at": "2026-10-11T14:52:49.987899Z",
      "urgency_state": "normal",
      "tags": [
        "vip"
      ]
    }
  ],
  "total": 17,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

threadsarray

Conversas da página.

idstring
UUID da conversa.
vendor_idstring
UUID do seller dono do número em que a conversa acontece. Ausente quando é o número da loja.
vendor_namestring
Nome do seller, quando há.
customer_phonestring
Telefone do cliente, com + e código do país.
customer_user_idstring
UUID do cliente cadastrado cujo telefone bate com o da conversa. Ausente se o cliente nunca se cadastrou.
bot_enabledboolean
true quando o assistente automático responde nesta conversa; false quando um atendente assumiu.
human_requested_atstring
Quando o cliente (ou o assistente) pediu um humano. Ausente se não houve pedido.
pending_actionstring
Ação interna aguardando resposta do cliente, quando existe.
last_inbound_atstring
Última mensagem do cliente, RFC 3339. Define a janela de 24 horas.
last_outbound_atstring
Última mensagem enviada pela loja.
unread_countinteger
Mensagens do cliente ainda não marcadas como lidas.
created_atstring
Criação da conversa, RFC 3339.
updated_atstring
Última alteração.
urgency_statestring
normalhuman_requestedwaiting_clientmanual_mode
Estado de urgência, calculado na hora: normal, human_requested (humano pedido, contagem regressiva), waiting_client (a loja respondeu por último, aguardando o cliente) ou manual_mode (bot desligado à mão).
urgency_seconds_remaininginteger
Segundos que faltam na contagem de human_requested ou waiting_client. Ausente nos demais estados.
assigned_to_user_idstring
UUID do atendente responsável. Ausente quando ninguém assumiu.
tagsarray
Etiquetas livres da conversa (vip, lead...). Sempre um array, vazio quando não há.
totalinteger
Total de conversas que atendem ao filtro.
pageinteger
Página devolvida.
per_pageinteger
Itens por página aplicados.
total_pagesinteger
Número de páginas.

Erros (Listar conversas)

StatusQuandoCorpo
400from ou to fora do formato YYYY-MM-DD.{"error":"invalid from date ..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O 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"}
`status=pending` não é o que parece

pending filtra por não lidas, não por "humano pedido". Para achar quem pediu atendimento humano, olhe urgency_state = human_requested no resultado.

Abrir uma conversa

Devolve a conversa com as 50 mensagens mais recentes. Atenção: abrir a conversa envia confirmação de leitura à Meta das até 10 últimas mensagens do cliente (o cliente vê o "visto" azul). Não zera o contador de não lidas: use a rota de marcar como lida para isso.

GET/api/v1/admin/whatsapp/threads/{id}Admin

Devolve a conversa e as últimas 50 mensagens

Parâmetros de caminho

idstringobrigatório
UUID da conversa.

Exemplo de requisição (Abrir uma conversa)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Abrir uma conversa)

200Conversa com mensagens
json
{
  "thread": {
    "id": "014ff6d8-8ff0-40da-82ce-e5a349b57be6",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "vendor_name": "Loja Exemplo",
    "customer_phone": "+5511999990428",
    "customer_user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
    "bot_enabled": true,
    "last_inbound_at": "2026-10-11T14:52:49.987899Z",
    "last_outbound_at": "2026-10-11T14:50:10.100000Z",
    "unread_count": 1,
    "created_at": "2026-10-01T02:52:49.971994Z",
    "updated_at": "2026-10-11T14:52:49.987899Z",
    "urgency_state": "normal",
    "tags": [
      "vip"
    ]
  },
  "messages": [
    {
      "id": 2027,
      "thread_id": "014ff6d8-8ff0-40da-82ce-e5a349b57be6",
      "wa_message_id": "wamid.HBgNNTUxMTk5OTk5MDQyOBUCABIYFA",
      "direction": "inbound",
      "message_type": "text",
      "body": "Oi, tem a camisa M?",
      "status": "V",
      "sent_manually": false,
      "is_rep": false,
      "created_at": "2026-10-11T14:52:49.982318Z"
    }
  ]
}

Campos da resposta

threadobject

A conversa.

(...)object
Mesmos campos de cada item da listagem.
messagesarray

Até 50 mensagens.

idinteger
Id numérico da mensagem. É o que media/{message_id} espera.
thread_idstring
UUID da conversa.
wa_message_idstring
Id da mensagem na Meta (wamid...).
directionstring
inboundoutbound
inbound (do cliente) ou outbound (da loja).
message_typestring
Tipo: text, image, video, audio, document, button, interactive, location, template...
bodystring
Texto da mensagem.
media_urlstring
Origem da mídia, quando é uma mensagem de mídia. Para baixar, use a rota de mídia.
media_mime_typestring
Tipo MIME da mídia.
media_filenamestring
Nome do arquivo de mídia.
template_namestring
Nome do template, quando a mensagem foi um template.
statusstring
PSVRF
Situação da mensagem como letra: P pendente, S enviada, V entregue (também usada para mensagem recebida), R lida, F falhou.
sent_manuallyboolean
true quando um atendente enviou, false quando foi o assistente ou um automatismo.
is_repboolean
true quando o remetente é um representante de vendas cadastrado (veja Representantes).
sent_atstring
Envio, RFC 3339.
delivered_atstring
Entrega, RFC 3339.
read_atstring
Leitura, RFC 3339.
created_atstring
Registro da mensagem, RFC 3339.

Erros (Abrir uma conversa)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O 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"}
404A conversa não existe.{"error":"thread not found"}

Marcar como lida

Põe unread_count em 0. Não envia confirmação de leitura ao cliente. Sem corpo.

POST/api/v1/admin/whatsapp/threads/{id}/mark-readAdmin

Zera o contador de não lidas da conversa

Parâmetros de caminho

idstringobrigatório
UUID da conversa.

Exemplo de requisição (Marcar como lida)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/mark-read" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Marcar como lida)

200Marcada
json
{
  "success": "ok"
}

Campos da resposta

successstring
Sempre a string ok.

Erros (Marcar como lida)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O 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"}

Ligar ou desligar o assistente

Define se o assistente (bot) responde sozinho às mensagens do cliente. Com enabled: false, só atendentes respondem; com true, o assistente volta a atuar.

POST/api/v1/admin/whatsapp/threads/{id}/toggle-botAdmin

Liga ou desliga o assistente automático nesta conversa

Parâmetros de caminho

idstringobrigatório
UUID da conversa.

Corpo da requisição

enabledbooleanobrigatório
true liga o assistente, false desliga.

Exemplo de requisição (Ligar ou desligar o assistente)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/toggle-bot" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Resposta (Ligar ou desligar o assistente)

200Atualizada
json
{
  "success": true,
  "thread": {
    "id": "014ff6d8-8ff0-40da-82ce-e5a349b57be6",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "vendor_name": "Loja Exemplo",
    "customer_phone": "+5511999990428",
    "customer_user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
    "bot_enabled": false,
    "last_inbound_at": "2026-10-11T14:52:49.987899Z",
    "last_outbound_at": "2026-10-11T14:50:10.100000Z",
    "unread_count": 1,
    "created_at": "2026-10-01T02:52:49.971994Z",
    "updated_at": "2026-10-11T14:52:49.987899Z",
    "urgency_state": "manual_mode",
    "tags": [
      "vip"
    ]
  }
}

Campos da resposta

successboolean
true.
threadobject
A conversa já atualizada.

Erros (Ligar ou desligar o assistente)

StatusQuandoCorpo
400Corpo que não é JSON.{"error":"invalid request body"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O 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"}
404A conversa não existe.{"error":"thread not found"}
Responder também desliga o assistente

Enviar uma resposta manual (rota de resposta) já desliga o assistente da conversa. Use esta rota para devolvê-lo ao bot.

Ação em lote

Aplica a mesma action às conversas listadas em thread_ids (até 200). Devolve quantas linhas mudaram. Com usuário vinculado a um seller, só as conversas desse seller são afetadas. A rota também aceita o modo "por critério" da API de lotes da plataforma (selecionar por filtro em vez de ids), com pré-visualização antes de aplicar.

POST/api/v1/admin/whatsapp/threads/bulkAdmin

Aplica uma ação a várias conversas de uma vez

Parâmetros de consulta

vendor_idstring
Restringe a ação às conversas deste seller.

Corpo da requisição

thread_idsarrayobrigatório
UUIDs das conversas, de 1 a 200.
actionstringobrigatório
closereopenassign_to_usertransfertoggle_botadd_tagremove_tag
Ação a aplicar.
paramsobject
Parâmetros da ação: user_id para assign_to_user e transfer (string vazia remove o responsável); enabled (booleano) para toggle_bot; tag (texto) para add_tag e remove_tag.

Exemplo de requisição (Ação em lote)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_ids": [
      "014ff6d8-8ff0-40da-82ce-e5a349b57be6"
    ],
    "action": "add_tag",
    "params": {
      "tag": "vip"
    }
  }'

Resposta (Ação em lote)

200Aplicada
json
{
  "affected": 1
}

Campos da resposta

affectedinteger
Conversas realmente alteradas.

Erros (Ação em lote)

StatusQuandoCorpo
400thread_ids vazio ou acima de 200, action ausente ou inválida, ou parâmetro faltando.{"error":"thread_ids required"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O 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"}
O que cada ação faz

close: desliga o assistente, limpa o pedido de humano e zera as não lidas. reopen: liga o assistente. assign_to_user e transfer fazem a mesma coisa (definem o responsável). add_tag é idempotente: repetir a mesma etiqueta não duplica.

Veja também

  • Responder ao cliente
  • Notas internas
  • Busca e métricas
Anterior
WhatsApp: caixa de entrada
Próxima
Responder ao cliente
Nesta página
  • Listar conversas
  • Exemplo de requisição (Listar conversas)
  • Resposta (Listar conversas)
  • Erros (Listar conversas)
  • Abrir uma conversa
  • Exemplo de requisição (Abrir uma conversa)
  • Resposta (Abrir uma conversa)
  • Erros (Abrir uma conversa)
  • Marcar como lida
  • Exemplo de requisição (Marcar como lida)
  • Resposta (Marcar como lida)
  • Erros (Marcar como lida)
  • Ligar ou desligar o assistente
  • Exemplo de requisição (Ligar ou desligar o assistente)
  • Resposta (Ligar ou desligar o assistente)
  • Erros (Ligar ou desligar o assistente)
  • Ação em lote
  • Exemplo de requisição (Ação em lote)
  • Resposta (Ação em lote)
  • Erros (Ação em lote)
  • Veja também