Consultar os registros de WhatsApp de um processo

GET/whatsapp/recordschave públicapuk_

Este serviço retorna o histórico completo de conversas do WhatsApp de um processo da Auco: as mensagens que o bot da Auco enviou ao participante, as respostas do participante e os status de entrega informados pelo WhatsApp.

A resposta é um array plano em ordem cronológica crescente, sem paginação e sem filtros. Se o processo não teve atividade no WhatsApp, o array volta vazio ([]).

O que esta página cobre

Esta página documenta como consultar o histórico de mensagens, e não como configurar o WhatsApp como canal de assinatura ou notificação. Para habilitar o fluxo de assinatura por WhatsApp (options.whatsapp, options.both), consulte Validações de identidade.

Autenticação

Inclua sua chave pública no cabeçalho Authorization.

Authorization: puk_xxx...

Parâmetros de consulta

Nome	Tipo	Descrição
`code`	String obrigatório	Código do processo. Mínimo de 9 caracteres. Seu comprimento determina o tipo de processo consultado.
`userId`	String condicional	Identificador do participante dentro do processo. Obrigatório para processos de assinatura e não permitido para AucoFace.

Os registros são por participante

Não é possível obter um processo completo com vários signatários em uma única chamada: você deve consultar participante por participante e combinar os resultados na sua integração.

🧩 Tipos de processo suportados

O comprimento de code determina qual tipo de processo a Auco consulta e se userId é obrigatório.

Comprimento	Tipo de processo	`userId`	Onde obter os identificadores
9	Contrato	obrigatório	`code` e `signProfile[].id` de `GET /document`
10	Documento	obrigatório	`code` e `signProfile[].id` de `GET /document`
16	Validação de identidade (AucoFace)	não permitido	`code` de `GET /veriface`
24	Pacote de documentos	obrigatório	o id do pacote e `signers[].userId`

Os processos AucoFace têm um único participante, por isso não recebem userId.

🧪 Exemplos de uso

dica

Você pode copiar qualquer um dos exemplos conforme a sua linguagem preferida.

🔹 Processo de assinatura (`code` e `userId`)

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/ext/whatsapp/records?code=CODEDOCUM&userId=01' \
  --header 'Authorization: puk_yourPublicKey'

import requests

response = requests.get(
  "https://api.auco.ai/v1.5/ext/whatsapp/records",
  headers={"Authorization": "puk_yourPublicKey"},
  params={"code": "CODEDOCUM", "userId": "01"}
)
print(response.json())

const axios = require('axios');

axios
  .get('https://api.auco.ai/v1.5/ext/whatsapp/records', {
    headers: { Authorization: 'puk_yourPublicKey' },
    params: { code: 'CODEDOCUM', userId: '01' },
  })
  .then((response) => console.log(response.data));

🔸 Processo AucoFace (somente `code`)

curl
Python
Node.js

curl --location 'https://api.auco.ai/v1.5/ext/whatsapp/records?code=VERIFACECODE1234' \
  --header 'Authorization: puk_yourPublicKey'

import requests

response = requests.get(
  "https://api.auco.ai/v1.5/ext/whatsapp/records",
  headers={"Authorization": "puk_yourPublicKey"},
  params={"code": "VERIFACECODE1234"}
)
print(response.json())

const axios = require('axios');

axios
  .get('https://api.auco.ai/v1.5/ext/whatsapp/records', {
    headers: { Authorization: 'puk_yourPublicKey' },
    params: { code: 'VERIFACECODE1234' },
  })
  .then((response) => console.log(response.data));

📥 Exemplos de resposta

🔹 Conversa com mensagens enviadas e recebidas

[
  {
    "entity": "auco",
    "phone": "+573001234567",
    "message": "👋🏼 Hola Juan, has sido invitado a firmar un documento creado por ACME...",
    "date": 1746028800000,
    "actions": [
      { "action": "sent", "timestamp": 1746028800000 },
      { "action": "delivered", "timestamp": 1746028805000 },
      { "action": "read", "timestamp": 1746028860000 }
    ]
  },
  {
    "entity": "signer",
    "phone": "+573001234567",
    "message": "comenzar",
    "date": 1746028900000
  },
  {
    "entity": "auco",
    "phone": "+573001234567",
    "message": "Este es el documento, recuerda que debes leerlo en su *totalidad*.",
    "date": 1746028950000,
    "actions": [
      { "action": "sent", "timestamp": 1746028950000 },
      { "action": "delivered", "timestamp": 1746028952000 }
    ]
  },
  {
    "entity": "signer",
    "phone": "+573001234567",
    "message": "Completo el formulario",
    "date": 1746029050000
  }
]

As mensagens recebidas neste exemplo mostram os dois casos que você pode encontrar. O segundo registro, comenzar, é o texto de um botão que o participante tocou. O último, Completo el formulario, não é algo que o participante digitou: é a referência sob a qual uma de suas ações dentro do fluxo foi registrada. Esse texto é descritivo e varia conforme o processo, portanto não dependa dele para detectar ações na sua integração.

Por que os exemplos estão em espanhol

Os valores de message nestes exemplos são literais do canal WhatsApp, que opera no idioma do próprio participante. A API não os localiza.

🔸 Mensagem que não pôde ser entregue

[
  {
    "entity": "auco",
    "phone": "+573001234567",
    "message": "👋🏼 Hola Juan, has sido invitado a firmar un documento creado por ACME...",
    "date": 1746028800000,
    "actions": [
      { "action": "sent", "timestamp": 1746028800000 },
      {
        "action": "failed",
        "timestamp": 1746028802000,
        "errors": ["WHATSAPP_NUMBER_NOT_REGISTERED"]
      }
    ]
  }
]

🔸 Processo sem atividade no WhatsApp

[]

📋 Campos da resposta

Campo	Tipo	Descrição
`entity`	String	Sempre presente. `auco` = mensagem enviada pelo bot da Auco. `signer` = mensagem recebida, enviada pelo participante.
`phone`	String	Sempre presente. Número de telefone do participante em formato internacional, com código do país e o sinal `+`.
`message`	String	Sempre presente. Texto simples, já renderizado: os modelos do WhatsApp chegam com suas variáveis substituídas.
`date`	Number	Sempre presente. Timestamp epoch em milissegundos.
`actions`	Array<Object>	Opcional. Somente em mensagens com status de entrega informados pelo WhatsApp. As mensagens do participante (`entity: "signer"`) não o incluem.
`actions[].action`	String	Status de entrega: `sent`, `delivered`, `read` ou `failed`.
`actions[].timestamp`	Number	Timestamp epoch em milissegundos do momento em que o WhatsApp informou o status.
`actions[].errors`	Array<String>	Opcional. Somente quando `action` é `failed`. Contém os motivos da falha.

Datas em milissegundos

Tanto date quanto actions[].timestamp estão em milissegundos, não em segundos. Por exemplo, 1746028800000 corresponde a 2025-04-30T16:00:00.000Z. Se a linguagem da sua integração espera segundos, divida o valor por 1000.

Não compare message com um texto fixo

A resposta não inclui URLs de mídia nem arquivos. Quando o participante envia um anexo ou realiza uma ação dentro do fluxo, o registro armazena uma referência textual a essa ação (por exemplo, algo como Completo el formulario) em vez do conteúdo em si.

Esse texto é descritivo, não um identificador: depende do fluxo do processo, pode ser personalizado e pode mudar. Além disso, vem do canal WhatsApp no idioma do participante e não é localizado pela API. Se a sua integração precisa reagir a ações específicas, não a construa comparando o conteúdo de message.

Para baixar os arquivos enviados pelo participante, use Consultar processo e anexos.

🔄 Status de entrega (`actions[].action`)

Status	Descrição
`sent`	A Auco entregou a mensagem ao WhatsApp e o WhatsApp a aceitou para envio.
`delivered`	O WhatsApp confirmou que a mensagem chegou ao dispositivo do participante.
`read`	O participante abriu a mensagem.
`failed`	O WhatsApp não conseguiu entregar a mensagem; o motivo está em `actions[].errors`.

Os status são cumulativos e chegam na ordem em que o WhatsApp os informa. Uma mensagem pode permanecer em sent se o participante tiver desativado a confirmação de leitura.

🚫 Motivos de falha (`actions[].errors`)

Estes códigos não são códigos HTTP: a requisição pode retornar 200 e ainda assim conter mensagens com status failed.

Código	Descrição
`WHATSAPP_RATE_LIMIT`	O limite de mensagens permitido pelo WhatsApp na janela de tempo atual foi excedido.
`WHATSAPP_NUMBER_NOT_REGISTERED`	O número do participante não está registrado no WhatsApp.
`WHATSAPP_NO_ACTIVE_CONVERSATION`	Não há conversa ativa; o WhatsApp não permite mensagens fora de modelo.
`WHATSAPP_UNSUPPORTED_MESSAGE_TYPE`	O WhatsApp rejeitou o tipo de mensagem.
`WHATSAPP_TEMPLATE_NOT_FOUND`	O modelo utilizado não existe.
`WHATSAPP_TEMPLATE_PAUSED`	O modelo está pausado pelo WhatsApp.
`WHATSAPP_TEMPLATE_DISABLED`	O modelo foi desativado pelo WhatsApp.
`WHATSAPP_SERVICE_UNAVAILABLE`	O serviço do WhatsApp estava indisponível.
`WHATSAPP_NUMBER_NOT_ACTIVE`	O número de envio da Auco não estava ativo.
`WHATSAPP_SEND_ERROR`	Erro de envio não classificado.

⚠️ Respostas de erro

Código	Descrição
400	Erro de validação ou processo não encontrado: `CODE_REQUIRED` (`code` ausente), `CODE_NOT_VALID` (`code` com menos de 9 caracteres), `USER_ID_REQUIRED` (`userId` ausente em um processo de assinatura), `USER_ID_NOT_ALLOWED` (`userId` enviado em um processo AucoFace) e `PROCESS_NOT_FOUND`
401	Autenticação inválida ou ausente

PROCESS_NOT_FOUND é retornado quando o processo não existe, não pertence à sua organização, o participante não faz parte do processo ou o processo AucoFace não usou o WhatsApp como canal.

Processos AucoFace concluídos pela web

Um processo AucoFace concluído pela web, sem o canal WhatsApp, retorna PROCESS_NOT_FOUND em vez de um array vazio.

Autenticação​

Parâmetros de consulta​

🧩 Tipos de processo suportados​

🧪 Exemplos de uso​

🔹 Processo de assinatura (code e userId)​

🔸 Processo AucoFace (somente code)​

📥 Exemplos de resposta​

🔹 Conversa com mensagens enviadas e recebidas​

🔸 Mensagem que não pôde ser entregue​

🔸 Processo sem atividade no WhatsApp​

📋 Campos da resposta​

🔄 Status de entrega (actions[].action)​

🚫 Motivos de falha (actions[].errors)​

⚠️ Respostas de erro​