VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: histórico e ligações

Ligações

Lista as ligações de voz atendidas no WhatsApp da loja, abre uma com a transcrição e entrega a gravação.

Quando a ligação por WhatsApp está ligada, o telefone da loja é atendido por um atendente virtual de voz que conversa com o cliente e pode montar um pedido. Cada chamada vira um registro com duração, resultado, nota que o cliente deu ao final (de 1 a 5), transcrição e gravação. Estas três rotas só leem. Para saber por que o telefone toca e ninguém atende, veja o diagnóstico em conexão e configuração.

O outcome resume o que a chamada produziu:

outcomeSignificado
pedidoA ligação gerou um pedido (order_number preenchido).
conversouHouve conversa e uso de ferramentas, mas nenhum pedido.
sem_interacaoA chamada terminou sem o atendente usar nenhuma ferramenta.
(vazio)A chamada ainda não terminou ou não foi encerrada normalmente.
Dados sensíveis

Uma ligação pode conter nome, endereço e até CPF. A gravação não fica em URL pública: só sai pela rota autenticada abaixo. Trate a transcrição e o áudio como dado pessoal (LGPD) e não os copie para sistemas sem controle de acesso.

Listar ligações

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

Lista as ligações atendidas, as mais recentes primeiro

Cabeçalhos

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

Parâmetros de consulta

limitintegerpadrão: 50
Quantidade de ligações, de 1 a 200. Fora disso, ou não numérico, vale 50.
phonestring
Telefone do cliente. Só os dígitos contam e a busca é pelo final do número: 987654321 acha 5511987654321. Vazio não filtra.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/whatsapp-confluence/calls?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ligações
json
{
  "calls": [
    {
      "call_id": "wacid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjA",
      "phone": "5511987654321",
      "started_at": "2026-10-10T14:32:10Z",
      "duration_seconds": 184,
      "tools_used": 5,
      "order_number": "SD-004218",
      "outcome": "pedido",
      "rating": 5,
      "has_audio": true,
      "has_transcript": true
    }
  ]
}

Campos da resposta

callsarray

Da mais recente para a mais antiga. Lista vazia se não há ligações. A lista não traz o texto da transcrição, só has_transcript; abra a ligação para ler.

call_idstring
Id da ligação, texto opaco que vem da Meta.
phonestring
Telefone do cliente, só dígitos, com DDI.
started_atstring
Início da chamada, em UTC (2026-10-10T14:32:10Z).
duration_secondsinteger
Duração em segundos. 0 enquanto a chamada não terminou.
tools_usedinteger
Quantas vezes o atendente usou ferramentas (buscar produto, montar pedido, calcular frete).
order_numberstring
Número do pedido gerado. Omitido se a ligação não gerou pedido.
outcomestring
pedidoconversousem_interacao
Resultado: pedido, conversou, sem_interacao, ou vazio enquanto a chamada não foi encerrada.
ratinginteger
Nota de 1 a 5 dada pelo cliente na pesquisa pós-ligação. Omitido se o cliente não respondeu.
has_audioboolean
true se há gravação do lado do cliente.
has_transcriptboolean
true se há transcrição.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um administrador.{"error":"insufficient permissions"}
500Banco indisponível para a loja.{"error":"db_unavailable"}
Erro de leitura vira lista vazia

Se a consulta falhar depois de aberta a conexão, a rota responde 200 com {"calls":[]} em vez de erro. Uma lista vazia, portanto, não prova que não houve ligações.

Consultar ligação

GET/api/v1/admin/whatsapp-confluence/calls/{callID}Admin

Retorna uma ligação com a transcrição

Cabeçalhos

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

Parâmetros de caminho

callIDstringobrigatório
Id da ligação (call_id de Listar ligações). Texto, não UUID.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/whatsapp-confluence/calls/wacid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjA" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ligação
json
{
  "call_id": "wacid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjA",
  "phone": "5511987654321",
  "started_at": "2026-10-10T14:32:10Z",
  "duration_seconds": 184,
  "tools_used": 5,
  "order_number": "SD-004218",
  "outcome": "pedido",
  "rating": 5,
  "has_audio": true,
  "has_transcript": true,
  "transcript": "Atendente: Olá, em que posso ajudar?\nCliente: Quero fazer um pedido de 3 caixas..."
}

Campos da resposta

call_idstring
Id da ligação, texto opaco que vem da Meta.
phonestring
Telefone do cliente, só dígitos, com DDI.
started_atstring
Início da chamada, em UTC (2026-10-10T14:32:10Z).
duration_secondsinteger
Duração em segundos. 0 enquanto a chamada não terminou.
tools_usedinteger
Quantas vezes o atendente usou ferramentas (buscar produto, montar pedido, calcular frete).
order_numberstring
Número do pedido gerado. Omitido se a ligação não gerou pedido.
outcomestring
pedidoconversousem_interacao
Resultado: pedido, conversou, sem_interacao, ou vazio enquanto a chamada não foi encerrada.
ratinginteger
Nota de 1 a 5 dada pelo cliente na pesquisa pós-ligação. Omitido se o cliente não respondeu.
has_audioboolean
true se há gravação do lado do cliente.
has_transcriptboolean
true se há transcrição.
transcriptstring
Transcrição da conversa. Omitido se não há.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um administrador.{"error":"insufficient permissions"}
404Ligação inexistente.{"error":"call_not_found"}
500Falha ao ler o registro.{"error":"read_failed"}

Gravação da ligação

Entrega o arquivo de áudio de um dos lados da conversa. O caminho do arquivo vem sempre do registro da loja e é conferido contra a pasta da própria loja antes da leitura; nada que você envie escolhe o arquivo. A resposta aceita pedidos parciais (Range), então um player consegue avançar na gravação.

GET/api/v1/admin/whatsapp-confluence/calls/{callID}/audioAdmin

Entrega a gravação de uma ligação

Cabeçalhos

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

Parâmetros de caminho

callIDstringobrigatório
Id da ligação (call_id de Listar ligações). Texto, não UUID.

Parâmetros de consulta

sidestring
cliente
Qual lado ouvir. cliente é a voz do cliente. Qualquer outro valor, ou omitido, é a voz do atendente virtual.

Exemplo de requisição

bash
curl -o ligacao-cliente.ogg "$BASE_URL/api/v1/admin/whatsapp-confluence/calls/wacid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjA/audio?side=cliente" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Áudio da gravação
http
HTTP/1.1 200 OK
Content-Type: audio/ogg
Cache-Control: private, max-age=300

<bytes do áudio>

Campos da resposta

corpobinary
Áudio audio/ogg. Pode ser cacheado de forma privada por 5 minutos.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um administrador.{"error":"insufficient permissions"}
404A ligação não existe, não tem gravação desse lado, ou o arquivo não está mais disponível. O corpo é texto simples em português, não JSON.sem gravação
403O caminho gravado fica fora da pasta da loja (texto simples).caminho inválido
500Banco indisponível para a loja (texto simples).db unavailable
Erros em texto simples

Esta rota é a única da seção cujos erros 404 e 403 não são JSON: o corpo é uma frase em português (sem gravação, arquivo indisponível, caminho inválido), e fica assim em qualquer idioma. Verifique o status antes de tentar res.json().

Veja também

  • Conversas
  • Conexão e diagnóstico
  • Visão geral da seção
Anterior
Mídia da mensagem
Próxima
WhatsApp: campanhas
Nesta página
  • Listar ligações
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar ligação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravação da ligação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também