Retrieve the WhatsApp Records of a Process

GET /whatsapp/records

This service returns the full WhatsApp conversation history of an Auco process: the messages the Auco bot sent to the participant, the participant's replies, and the delivery statuses reported by WhatsApp.

The response is a flat array in ascending chronological order, with no pagination and no filters. If the process had no WhatsApp activity, the array comes back empty ([]).

What this page covers

This page documents how to query the message history, not how to configure WhatsApp as a signing or notification channel. To enable the WhatsApp signing flow (options.whatsapp, options.both, options.flow), see Identity Validations.

Authentication

Include your public key in the Authorization header.

Authorization: puk_xxx...

Query Parameters

Name	Type	Required	Description
`code`	String	Required	Process code. Minimum 9 characters. Its length determines the type of process being queried.
`userId`	String	Conditional	Identifier of the participant within the process. Required for signing processes and not allowed for AucoFace.

Records are per participant

There is no way to retrieve a complete multi-signer process in a single call: you must query participant by participant and merge the results in your integration.

🧩 Supported process types

The length of code determines which type of process Auco queries and whether userId is required.

Length	Process type	`userId`	Where to get the identifiers
9	Contract	required	`code` and `signProfile[].id` from `GET /document`
10	Document	required	`code` and `signProfile[].id` from `GET /document`
16	Identity validation (AucoFace)	not allowed	`code` from `GET /veriface`
24	Document package	required	the package id and `signers[].userId`

AucoFace processes have a single participant, which is why they do not take a userId.

🧪 Usage Examples

tip

You can copy any of the examples depending on your preferred language.

🔹 Signing process (`code` and `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));

🔸 AucoFace process (`code` only)

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));

📥 Response Examples

🔹 Conversation with outgoing and incoming messages

[
  {
    "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
  }
]

The incoming messages in this example show the two cases you may come across. The second record, comenzar, is the text of a button the participant tapped. The last one, Completo el formulario, is not something the participant typed: it is the reference under which one of their actions within the flow was recorded. That text is descriptive and varies by process, so do not rely on it to detect actions in your integration.

Why the examples are in Spanish

The message values in these examples are literals of the WhatsApp channel, which runs in the participant's own language. The API does not localize them.

🔸 Message that could not be delivered

[
  {
    "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"]
      }
    ]
  }
]

🔸 Process with no WhatsApp activity

[]

📋 Response Fields

Field	Type	Description
`entity`	String	Always present. `auco` = outgoing message sent by the Auco bot. `signer` = incoming message sent by the participant.
`phone`	String	Always present. Participant's phone number in international format, with country code and the `+` sign.
`message`	String	Always present. Plain text, already rendered: WhatsApp templates arrive with their variables substituted.
`date`	Number	Always present. Epoch timestamp in milliseconds.
`actions`	Array<Object>	Optional. Only on messages with delivery statuses reported by WhatsApp. Participant messages (`entity: "signer"`) do not include it.
`actions[].action`	String	Delivery status: `sent`, `delivered`, `read` or `failed`.
`actions[].timestamp`	Number	Epoch timestamp in milliseconds of the moment WhatsApp reported the status.
`actions[].errors`	Array<String>	Optional. Only when `action` is `failed`. Contains the failure reasons.

Dates in milliseconds

Both date and actions[].timestamp are in milliseconds, not seconds. For example, 1746028800000 corresponds to 2025-04-30T16:00:00.000Z. If your integration's language expects seconds, divide the value by 1000.

Do not compare message against fixed text

The response does not include media URLs or files. When the participant sends an attachment or performs an action within the flow, the record stores a text reference to that action (for example, something like Completo el formulario) instead of the content itself.

That text is descriptive, not an identifier: it depends on the process flow, it may be customized and it may change. It also comes from the WhatsApp channel in the participant's language and is not localized by the API. If your integration needs to react to specific actions, do not build it by comparing the contents of message.

To download the files the participant uploaded, use Retrieve Process and Attachments.

🔄 Delivery statuses (`actions[].action`)

Status	Description
`sent`	Auco handed the message over to WhatsApp and WhatsApp accepted it for delivery.
`delivered`	WhatsApp confirmed the message reached the participant's device.
`read`	The participant opened the message.
`failed`	WhatsApp could not deliver the message; the reason is in `actions[].errors`.

Statuses are cumulative and arrive in the order WhatsApp reports them. A message may stay at sent if the participant has read receipts turned off.

🚫 Failure reasons (`actions[].errors`)

These codes are not HTTP codes: the request can return 200 and still contain messages with a failed status.

Code	Description
`WHATSAPP_RATE_LIMIT`	The message limit WhatsApp allows in the current time window was exceeded.
`WHATSAPP_NUMBER_NOT_REGISTERED`	The participant's number is not registered on WhatsApp.
`WHATSAPP_NO_ACTIVE_CONVERSATION`	There is no active conversation; WhatsApp does not allow non-template messages.
`WHATSAPP_UNSUPPORTED_MESSAGE_TYPE`	WhatsApp rejected the message type.
`WHATSAPP_TEMPLATE_NOT_FOUND`	The template used does not exist.
`WHATSAPP_TEMPLATE_PAUSED`	The template is paused by WhatsApp.
`WHATSAPP_TEMPLATE_DISABLED`	The template was disabled by WhatsApp.
`WHATSAPP_SERVICE_UNAVAILABLE`	The WhatsApp service was unavailable.
`WHATSAPP_NUMBER_NOT_ACTIVE`	Auco's sending number was not active.
`WHATSAPP_SEND_ERROR`	Unclassified sending error.

⚠️ Error Responses

Code	Description
400	Validation error or process not found: `CODE_REQUIRED` (missing `code`), `CODE_NOT_VALID` (`code` shorter than 9 characters), `USER_ID_REQUIRED` (missing `userId` on a signing process), `USER_ID_NOT_ALLOWED` (`userId` sent on an AucoFace process) and `PROCESS_NOT_FOUND`
401	Invalid or missing authentication

PROCESS_NOT_FOUND is returned when the process does not exist, does not belong to your company, the participant is not part of the process, or the AucoFace process did not use WhatsApp as its channel.

AucoFace processes completed on the web

An AucoFace process completed through the web, without the WhatsApp channel, returns PROCESS_NOT_FOUND instead of an empty array.

Authentication​

Query Parameters​

🧩 Supported process types​

🧪 Usage Examples​

🔹 Signing process (code and userId)​

🔸 AucoFace process (code only)​

📥 Response Examples​

🔹 Conversation with outgoing and incoming messages​

🔸 Message that could not be delivered​

🔸 Process with no WhatsApp activity​

📋 Response Fields​

🔄 Delivery statuses (actions[].action)​

🚫 Failure reasons (actions[].errors)​

⚠️ Error Responses​