API atual/Referência completa/WhatsApp Commerce: número do seller

Ligações

Confere se a loja atende ligações no WhatsApp e consulta o histórico de ligações com transcrição e gravação.

Além de mensagens, o WhatsApp Business recebe ligações de voz feitas pelo cliente dentro do aplicativo. Quando a loja ativa o atendimento por voz, um assistente virtual atende a ligação, conversa com o cliente e, se for o caso, registra um pedido. Estas quatro rotas mostram se isso está funcionando (diagnostico) e guardam o histórico (calls).

Diagnosticar o atendimento

GET/api/v1/vendor/whatsapp/diagnosticoSeller

Confere por que o telefone da loja atende (ou não) ligações

Responde à pergunta "por que o telefone toca e ninguém atende?". Faz duas conferências: se o assistente de voz está configurado no servidor e se a loja tem um número conectado com credencial que abre. Não chama a Meta.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/diagnostico" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resultado do diagnóstico

json

{
  "can_answer": false,
  "summary": "A ligação nativa do WhatsApp ainda não atende. Veja o que falta abaixo.",
  "checks": [
    {
      "id": "vi",
      "label": "Atendente virtual",
      "status": "erro",
      "detail": "A VI de voz não está ligada neste servidor.",
      "fix": "Peça à plataforma para configurar a chave da voz. Sem isso o WhatsApp toca e ninguém atende."
    },
    {
      "id": "conta",
      "label": "Número do WhatsApp",
      "status": "ok",
      "detail": "Número conectado e com credencial válida."
    }
  ],
  "phone_number_id": "104857392011234"
}

Campos da resposta

can_answerboolean

true quando as duas conferências passaram.

summarystring

Frase pronta para mostrar ao usuário, em português.

checksarray

Uma entrada por conferência.

checks[].idstring

viconta

vi: assistente de voz configurado no servidor. conta: número conectado e credencial válida.

checks[].labelstring

Nome da conferência.

checks[].statusstring

okerroaviso

Resultado. Hoje a rota devolve ok ou erro.

checks[].detailstring

O que foi encontrado.

checks[].fixstring

Como corrigir. Ausente quando status é ok.

phone_number_idstring

Código do número encontrado. Vazio se não há número conectado.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller	`{"error":"insufficient permissions"}`
403	Módulo desligado	`{"error":"module_disabled","module":"whatsapp-commerce"}`

Uma falha na conferência não vira erro HTTP: ela aparece em checks com status: "erro".

Listar as ligações

GET/api/v1/vendor/whatsapp/callsSeller

Lista as ligações recebidas, da mais recente para a mais antiga

Devolve o resumo de cada ligação. A transcrição não vem na lista: ela só existe em has_transcript. Para ler o texto, abra a ligação.

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade de ligações, de 1 a 200. Valor fora desse intervalo ou inválido volta para 50.

phonestring

Filtra pelo final do telefone do cliente. Só os dígitos contam (9999-0000 vira 99990000).

Exemplo de requisição

bash

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

Resposta

200Ligações devolvidas

json

{
  "calls": [
    {
      "call_id": "wacall.ABGGFjFVU2AfAgo6V",
      "phone": "5511999990000",
      "started_at": "2026-10-11T12:30:05Z",
      "duration_seconds": 142,
      "tools_used": 3,
      "order_number": "PEDIDO-20261011-0012",
      "outcome": "pedido",
      "rating": 5,
      "has_audio": true,
      "has_transcript": true
    }
  ]
}

Campos da resposta

callsarray

Ligações, da mais recente para a mais antiga. Lista vazia quando não há nenhuma.

calls[].call_idstring

Identificador da ligação, dado pela Meta. Use nas outras rotas.

calls[].phonestring

Telefone do cliente, só dígitos.

calls[].started_atstring

RFC 3339 em UTC.

calls[].duration_secondsinteger

Duração em segundos. 0 enquanto a ligação não terminou ou quando não foi medida.

calls[].tools_usedinteger

Quantas ações o assistente executou na ligação (buscar produto, montar carrinho, registrar pedido).

calls[].order_numberstring

Número do pedido gerado pela ligação. Ausente se nenhum.

calls[].outcomestring

pedidoconversousem_interacao

Resultado: pedido gerou um pedido, conversou houve conversa sem pedido, sem_interacao o cliente não interagiu. Vazio enquanto a ligação não foi encerrada.

calls[].ratinginteger

Nota de 1 a 5 dada pelo cliente na pesquisa após a ligação. Ausente se não respondeu.

calls[].has_audioboolean

true quando há gravação do cliente.

calls[].has_transcriptboolean

true quando há transcrição.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou tipo de token	veja a tabela do diagnóstico
500	Banco de dados indisponível	`{"error":"db_unavailable"}`

Abrir uma ligação

GET/api/v1/vendor/whatsapp/calls/{callID}Seller

Lê uma ligação com a transcrição

Parâmetros de caminho

callIDstringobrigatório

Identificador da ligação (calls[].call_id).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/calls/$CALL_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ligação

json

{
  "call_id": "wacall.ABGGFjFVU2AfAgo6V",
  "phone": "5511999990000",
  "started_at": "2026-10-11T12:30:05Z",
  "duration_seconds": 142,
  "tools_used": 3,
  "order_number": "PEDIDO-20261011-0012",
  "outcome": "pedido",
  "rating": 5,
  "has_audio": true,
  "has_transcript": true,
  "transcript": "Cliente: Oi, queria um tênis preto tamanho 42.\nAtendente: Claro! Tenho o Tênis Urbano Preto por R$ 189,00..."
}

Os campos são os de um item da lista, mais transcript: o texto da conversa, com falas separadas por quebra de linha. Fica ausente quando não há transcrição.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou tipo de token	veja a tabela do diagnóstico
404	Ligação inexistente	`{"error":"call_not_found"}`
500	Falha ao ler	`{"error":"read_failed"}` ou `{"error":"db_unavailable"}`

Baixar a gravação

GET/api/v1/vendor/whatsapp/calls/{callID}/audioSeller

Baixa o áudio gravado da ligação

Devolve o arquivo de áudio em audio/ogg. A gravação não fica em endereço público: só sai por esta rota autenticada.

Parâmetros de caminho

callIDstringobrigatório

Identificador da ligação.

Parâmetros de consulta

sidestringpadrão: vi

clientevi

Qual lado baixar. cliente é a voz do cliente; qualquer outro valor (ou nenhum) baixa a voz do assistente.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/calls/$CALL_ID/audio?side=cliente" \
  -H "Authorization: Bearer $TOKEN" -o ligacao-cliente.ogg

Resposta

200Áudio

http

HTTP/1.1 200 OK
Content-Type: audio/ogg
Cache-Control: private, max-age=300

(bytes do arquivo)

O arquivo aceita requisições com Range, então um player pode pular para o meio da gravação.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou tipo de token	veja a tabela do diagnóstico
403	O caminho da gravação não pertence a esta loja	texto simples `caminho inválido`
404	Sem gravação desse lado	texto simples `sem gravação`
404	O arquivo não está mais disponível	texto simples `arquivo indisponível`
500	Banco indisponível	texto simples `db unavailable`

Veja também

API atual/Referência completa/WhatsApp Commerce: número do seller

Ligações

Confere se a loja atende ligações no WhatsApp e consulta o histórico de ligações com transcrição e gravação.

Diagnosticar o atendimento

GET/api/v1/vendor/whatsapp/diagnosticoSeller

Confere por que o telefone da loja atende (ou não) ligações

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/diagnostico" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resultado do diagnóstico

json

{
  "can_answer": false,
  "summary": "A ligação nativa do WhatsApp ainda não atende. Veja o que falta abaixo.",
  "checks": [
    {
      "id": "vi",
      "label": "Atendente virtual",
      "status": "erro",
      "detail": "A VI de voz não está ligada neste servidor.",
      "fix": "Peça à plataforma para configurar a chave da voz. Sem isso o WhatsApp toca e ninguém atende."
    },
    {
      "id": "conta",
      "label": "Número do WhatsApp",
      "status": "ok",
      "detail": "Número conectado e com credencial válida."
    }
  ],
  "phone_number_id": "104857392011234"
}

Campos da resposta

can_answerboolean

true quando as duas conferências passaram.

summarystring

Frase pronta para mostrar ao usuário, em português.

checksarray

Uma entrada por conferência.

checks[].idstring

viconta

vi: assistente de voz configurado no servidor. conta: número conectado e credencial válida.

checks[].labelstring

Nome da conferência.

checks[].statusstring

okerroaviso

Resultado. Hoje a rota devolve ok ou erro.

checks[].detailstring

O que foi encontrado.

checks[].fixstring

Como corrigir. Ausente quando status é ok.

phone_number_idstring

Código do número encontrado. Vazio se não há número conectado.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller	`{"error":"insufficient permissions"}`
403	Módulo desligado	`{"error":"module_disabled","module":"whatsapp-commerce"}`

Uma falha na conferência não vira erro HTTP: ela aparece em checks com status: "erro".

Listar as ligações

GET/api/v1/vendor/whatsapp/callsSeller

Lista as ligações recebidas, da mais recente para a mais antiga

Devolve o resumo de cada ligação. A transcrição não vem na lista: ela só existe em has_transcript. Para ler o texto, abra a ligação.

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade de ligações, de 1 a 200. Valor fora desse intervalo ou inválido volta para 50.

phonestring

Filtra pelo final do telefone do cliente. Só os dígitos contam (9999-0000 vira 99990000).

Exemplo de requisição

bash

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

Resposta

200Ligações devolvidas

json

{
  "calls": [
    {
      "call_id": "wacall.ABGGFjFVU2AfAgo6V",
      "phone": "5511999990000",
      "started_at": "2026-10-11T12:30:05Z",
      "duration_seconds": 142,
      "tools_used": 3,
      "order_number": "PEDIDO-20261011-0012",
      "outcome": "pedido",
      "rating": 5,
      "has_audio": true,
      "has_transcript": true
    }
  ]
}

Campos da resposta

callsarray

Ligações, da mais recente para a mais antiga. Lista vazia quando não há nenhuma.

calls[].call_idstring

Identificador da ligação, dado pela Meta. Use nas outras rotas.

calls[].phonestring

Telefone do cliente, só dígitos.

calls[].started_atstring

RFC 3339 em UTC.

calls[].duration_secondsinteger

Duração em segundos. 0 enquanto a ligação não terminou ou quando não foi medida.

calls[].tools_usedinteger

Quantas ações o assistente executou na ligação (buscar produto, montar carrinho, registrar pedido).

calls[].order_numberstring

Número do pedido gerado pela ligação. Ausente se nenhum.

calls[].outcomestring

pedidoconversousem_interacao

Resultado: pedido gerou um pedido, conversou houve conversa sem pedido, sem_interacao o cliente não interagiu. Vazio enquanto a ligação não foi encerrada.

calls[].ratinginteger

Nota de 1 a 5 dada pelo cliente na pesquisa após a ligação. Ausente se não respondeu.

calls[].has_audioboolean

true quando há gravação do cliente.

calls[].has_transcriptboolean

true quando há transcrição.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou tipo de token	veja a tabela do diagnóstico
500	Banco de dados indisponível	`{"error":"db_unavailable"}`

Abrir uma ligação

GET/api/v1/vendor/whatsapp/calls/{callID}Seller

Lê uma ligação com a transcrição

Parâmetros de caminho

callIDstringobrigatório

Identificador da ligação (calls[].call_id).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/calls/$CALL_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ligação

json

{
  "call_id": "wacall.ABGGFjFVU2AfAgo6V",
  "phone": "5511999990000",
  "started_at": "2026-10-11T12:30:05Z",
  "duration_seconds": 142,
  "tools_used": 3,
  "order_number": "PEDIDO-20261011-0012",
  "outcome": "pedido",
  "rating": 5,
  "has_audio": true,
  "has_transcript": true,
  "transcript": "Cliente: Oi, queria um tênis preto tamanho 42.\nAtendente: Claro! Tenho o Tênis Urbano Preto por R$ 189,00..."
}

Os campos são os de um item da lista, mais transcript: o texto da conversa, com falas separadas por quebra de linha. Fica ausente quando não há transcrição.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou tipo de token	veja a tabela do diagnóstico
404	Ligação inexistente	`{"error":"call_not_found"}`
500	Falha ao ler	`{"error":"read_failed"}` ou `{"error":"db_unavailable"}`

Baixar a gravação

GET/api/v1/vendor/whatsapp/calls/{callID}/audioSeller

Baixa o áudio gravado da ligação

Devolve o arquivo de áudio em audio/ogg. A gravação não fica em endereço público: só sai por esta rota autenticada.

Parâmetros de caminho

callIDstringobrigatório

Identificador da ligação.

Parâmetros de consulta

sidestringpadrão: vi

clientevi

Qual lado baixar. cliente é a voz do cliente; qualquer outro valor (ou nenhum) baixa a voz do assistente.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/calls/$CALL_ID/audio?side=cliente" \
  -H "Authorization: Bearer $TOKEN" -o ligacao-cliente.ogg

Resposta

200Áudio

http

HTTP/1.1 200 OK
Content-Type: audio/ogg
Cache-Control: private, max-age=300

(bytes do arquivo)

O arquivo aceita requisições com Range, então um player pode pular para o meio da gravação.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou tipo de token	veja a tabela do diagnóstico
403	O caminho da gravação não pertence a esta loja	texto simples `caminho inválido`
404	Sem gravação desse lado	texto simples `sem gravação`
404	O arquivo não está mais disponível	texto simples `arquivo indisponível`
500	Banco indisponível	texto simples `db unavailable`