API atual/Referência completa/WhatsApp: histórico e ligações

Conversas

Lista as conversas do WhatsApp da loja, as mais recentes primeiro, e abre uma conversa pelo id.

Uma conversa (thread) liga um telefone de cliente a um número da loja e guarda todas as mensagens trocadas entre os dois, venham do cliente, do assistente automático, de um atendente ou do aplicativo WhatsApp Business. Estas duas rotas só leem. Na API de administração a lista traz as conversas de todas as contas da loja.

Listar conversas

GET/api/v1/admin/whatsapp-confluence/threadsAdmin

Lista as conversas, as mais recentes primeiro

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador da loja. Veja Tokens.

Parâmetros de consulta

filterstring

unreadhumanminevia_appunanswered

Atalho de filtro. unread com mensagens não lidas; human com atendimento humano ou assistente pausado; mine atribuídas ao usuário do token; via_app cuja última mensagem veio do aplicativo WhatsApp Business; unanswered cuja última mensagem é do cliente. Outro valor é ignorado, sem erro.

unreadboolean

true equivale a filter=unread.

originstring

CABEH

Só conversas cuja última mensagem tem esta origem. via_app e unanswered sobrescrevem este parâmetro.

assigneeuuid

Só conversas atribuídas a este usuário. Um valor que não é UUID responde 500.

qstring

Trecho do nome do contato ou do telefone, sem diferenciar maiúsculas. O telefone é guardado só com dígitos: pesquise 5511987, não +55 (11) 987.

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.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/whatsapp-confluence/threads?filter=unread&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conversas

json

{
  "page": 1,
  "threads": [
    {
      "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "account_id": "3b9d8c52-1f0a-4e7b-8a21-6d5c4b3a2f10",
      "customer_phone": "5511987654321",
      "contact_name": "Maria Souza",
      "assignee_user_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "assignee_name": "Ana Lima",
      "unread_count": 2,
      "last_message_at": "2026-10-10T14:32:10Z",
      "last_message_preview": "Quero 3 caixas, pode entregar amanhã?",
      "last_message_origin": "C",
      "csw_expires_at": "2026-10-11T14:32:10Z",
      "status": "A",
      "bot_mode": "H",
      "bot_mode_updated_at": "2026-10-10T14:20:00Z",
      "created_at": "2026-09-28T21:56:44Z",
      "updated_at": "2026-10-10T14:32:10Z"
    }
  ]
}

Campos da resposta

pageinteger

Página devolvida.

threadsarray

Conversas da página, da atividade mais recente para a mais antiga. Não há total: continue pedindo páginas até vir uma lista vazia. Cada item tem os campos abaixo.

iduuid

Id da conversa.

account_iduuid

Conta (número de WhatsApp da loja) pela qual a conversa acontece.

customer_phonestring

Telefone do cliente, só dígitos, com DDI (5511987654321).

contact_namestring

Nome do contato no WhatsApp. Vazio se desconhecido.

customer_user_iduuid

Cliente da loja ligado a este telefone. Omitido quando não há.

assignee_user_iduuid

Usuário da equipe responsável. Omitido quando ninguém foi atribuído.

assignee_namestring

Nome do responsável. Omitido quando não há.

unread_countinteger

Mensagens do cliente ainda não marcadas como lidas.

last_message_atstring

Data da última mensagem (RFC 3339). Omitido se a conversa não tem mensagens.

last_message_previewstring

Prévia da última mensagem (texto cortado).

last_message_originstring

CABEH

Quem escreveu a última: C cliente, A API ou atendente pela caixa, B assistente, E aplicativo WhatsApp Business (eco), H histórico importado.

csw_expires_atstring

Fim da janela de atendimento de 24 horas, contada da última mensagem do cliente. Até lá é possível enviar texto livre. Omitido se nunca houve mensagem do cliente.

fep_expires_atstring

Fim do ponto de entrada gratuito de 72 horas aberto por um anúncio que leva ao WhatsApp. Omitido quando não existe.

referralobject

Dados do anúncio de origem, como a Meta enviou. Omitido quando não veio de anúncio.

statusstring

Estado do registro da conversa, uma letra. O padrão é A; nenhuma rota desta seção o altera. Não confunda com bot_mode.

bot_modestring

APH

Quem atende agora: A assistente, P assistente pausado, H pessoa.

bot_mode_updated_atstring

Quando bot_mode mudou. Omitido se nunca mudou.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
500	Falha interna ao ler ou gravar.	`{"error":"..."}`

Consultar conversa

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

Retorna uma conversa

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador da loja. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da conversa (id de Listar conversas). Um UUID válido que não existe também responde, veja os erros de cada rota.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/whatsapp-confluence/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conversa

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "account_id": "3b9d8c52-1f0a-4e7b-8a21-6d5c4b3a2f10",
  "customer_phone": "5511987654321",
  "contact_name": "Maria Souza",
  "assignee_user_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "assignee_name": "Ana Lima",
  "unread_count": 2,
  "last_message_at": "2026-10-10T14:32:10Z",
  "last_message_preview": "Quero 3 caixas, pode entregar amanhã?",
  "last_message_origin": "C",
  "csw_expires_at": "2026-10-11T14:32:10Z",
  "status": "A",
  "bot_mode": "H",
  "bot_mode_updated_at": "2026-10-10T14:20:00Z",
  "created_at": "2026-09-28T21:56:44Z",
  "updated_at": "2026-10-10T14:32:10Z"
}

O corpo é o objeto da conversa, com os mesmos campos de cada item de threads em Listar conversas.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
400	Um segmento do caminho é `0` ou um inteiro negativo.	`{"error":"invalid id parameter"}`
404	Conversa inexistente, ou `id` que não é um UUID.	`{"error":"thread not found"}`

Veja também

Conversas

Lista as conversas do WhatsApp da loja, as mais recentes primeiro, e abre uma conversa pelo id.

Listar conversas

GET/api/v1/admin/whatsapp-confluence/threadsAdmin

Lista as conversas, as mais recentes primeiro

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador da loja. Veja Tokens.

Parâmetros de consulta

filterstring

unreadhumanminevia_appunanswered

unreadboolean

true equivale a filter=unread.

originstring

CABEH

Só conversas cuja última mensagem tem esta origem. via_app e unanswered sobrescrevem este parâmetro.

assigneeuuid

Só conversas atribuídas a este usuário. Um valor que não é UUID responde 500.

qstring

Trecho do nome do contato ou do telefone, sem diferenciar maiúsculas. O telefone é guardado só com dígitos: pesquise 5511987, não +55 (11) 987.

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.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/whatsapp-confluence/threads?filter=unread&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conversas

json

{
  "page": 1,
  "threads": [
    {
      "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "account_id": "3b9d8c52-1f0a-4e7b-8a21-6d5c4b3a2f10",
      "customer_phone": "5511987654321",
      "contact_name": "Maria Souza",
      "assignee_user_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "assignee_name": "Ana Lima",
      "unread_count": 2,
      "last_message_at": "2026-10-10T14:32:10Z",
      "last_message_preview": "Quero 3 caixas, pode entregar amanhã?",
      "last_message_origin": "C",
      "csw_expires_at": "2026-10-11T14:32:10Z",
      "status": "A",
      "bot_mode": "H",
      "bot_mode_updated_at": "2026-10-10T14:20:00Z",
      "created_at": "2026-09-28T21:56:44Z",
      "updated_at": "2026-10-10T14:32:10Z"
    }
  ]
}

Campos da resposta

pageinteger

Página devolvida.

threadsarray

Conversas da página, da atividade mais recente para a mais antiga. Não há total: continue pedindo páginas até vir uma lista vazia. Cada item tem os campos abaixo.

iduuid

Id da conversa.

account_iduuid

Conta (número de WhatsApp da loja) pela qual a conversa acontece.

customer_phonestring

Telefone do cliente, só dígitos, com DDI (5511987654321).

contact_namestring

Nome do contato no WhatsApp. Vazio se desconhecido.

customer_user_iduuid

Cliente da loja ligado a este telefone. Omitido quando não há.

assignee_user_iduuid

Usuário da equipe responsável. Omitido quando ninguém foi atribuído.

assignee_namestring

Nome do responsável. Omitido quando não há.

unread_countinteger

Mensagens do cliente ainda não marcadas como lidas.

last_message_atstring

Data da última mensagem (RFC 3339). Omitido se a conversa não tem mensagens.

last_message_previewstring

Prévia da última mensagem (texto cortado).

last_message_originstring

CABEH

Quem escreveu a última: C cliente, A API ou atendente pela caixa, B assistente, E aplicativo WhatsApp Business (eco), H histórico importado.

csw_expires_atstring

Fim da janela de atendimento de 24 horas, contada da última mensagem do cliente. Até lá é possível enviar texto livre. Omitido se nunca houve mensagem do cliente.

fep_expires_atstring

Fim do ponto de entrada gratuito de 72 horas aberto por um anúncio que leva ao WhatsApp. Omitido quando não existe.

referralobject

Dados do anúncio de origem, como a Meta enviou. Omitido quando não veio de anúncio.

statusstring

Estado do registro da conversa, uma letra. O padrão é A; nenhuma rota desta seção o altera. Não confunda com bot_mode.

bot_modestring

APH

Quem atende agora: A assistente, P assistente pausado, H pessoa.

bot_mode_updated_atstring

Quando bot_mode mudou. Omitido se nunca mudou.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
500	Falha interna ao ler ou gravar.	`{"error":"..."}`

Consultar conversa

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

Retorna uma conversa

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador da loja. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da conversa (id de Listar conversas). Um UUID válido que não existe também responde, veja os erros de cada rota.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/whatsapp-confluence/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conversa

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "account_id": "3b9d8c52-1f0a-4e7b-8a21-6d5c4b3a2f10",
  "customer_phone": "5511987654321",
  "contact_name": "Maria Souza",
  "assignee_user_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "assignee_name": "Ana Lima",
  "unread_count": 2,
  "last_message_at": "2026-10-10T14:32:10Z",
  "last_message_preview": "Quero 3 caixas, pode entregar amanhã?",
  "last_message_origin": "C",
  "csw_expires_at": "2026-10-11T14:32:10Z",
  "status": "A",
  "bot_mode": "H",
  "bot_mode_updated_at": "2026-10-10T14:20:00Z",
  "created_at": "2026-09-28T21:56:44Z",
  "updated_at": "2026-10-10T14:32:10Z"
}

O corpo é o objeto da conversa, com os mesmos campos de cada item de threads em Listar conversas.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
400	Um segmento do caminho é `0` ou um inteiro negativo.	`{"error":"invalid id parameter"}`
404	Conversa inexistente, ou `id` que não é um UUID.	`{"error":"thread not found"}`