Récupérer les enregistrements WhatsApp d'un processus

GET/whatsapp/recordsclé publiquepuk_

Ce service renvoie l'historique complet des conversations WhatsApp d'un processus Auco : les messages que le bot Auco a envoyés au participant, les réponses du participant et les statuts de livraison signalés par WhatsApp.

La réponse est un tableau plat, en ordre chronologique croissant, sans pagination ni filtres. Si le processus n'a eu aucune activité WhatsApp, le tableau est renvoyé vide ([]).

Ce que couvre cette page

Cette page documente la manière d'interroger l'historique des messages, et non la configuration de WhatsApp comme canal de signature ou de notification. Pour activer le flux de signature par WhatsApp (options.whatsapp, options.both), consultez Validations d'identité.

---

Authentification

Incluez votre clé publique dans l'en-tête Authorization.

Authorization: puk_xxx...

---

Paramètres de requête

Nom	Type	Description
code	String obligatoire	Code du processus. Minimum 9 caractères. Sa longueur détermine le type de processus interrogé.
userId	String conditionnel	Identifiant du participant au sein du processus. Obligatoire pour les processus de signature et non autorisé pour AucoFace.

Les enregistrements sont par participant

Il n'existe aucun moyen de récupérer un processus complet à plusieurs signataires en un seul appel : vous devez interroger participant par participant et fusionner les résultats dans votre intégration.

---

🧩 Types de processus pris en charge

La longueur de code détermine le type de processus interrogé par Auco et si userId est requis.

Longueur	Type de processus	userId	Où obtenir les identifiants
9	Contrat	requis	code et signProfile[].id de GET /document
10	Document	requis	code et signProfile[].id de GET /document
16	Validation d'identité (AucoFace)	non autorisé	code de GET /veriface
24	Lot de documents	requis	l'identifiant du lot et signers[].userId

Les processus AucoFace n'ont qu'un seul participant, c'est pourquoi ils ne prennent pas de userId.

---

🧪 Exemples d'utilisation

astuce

Vous pouvez copier n'importe lequel des exemples selon votre langage préféré.

🔹 Processus de signature (code et userId)

curl

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

Python

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

Node.js

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

---

🔸 Processus AucoFace (code uniquement)

curl

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

Python

import requests

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

Node.js

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

---

📥 Exemples de réponse

🔹 Conversation avec messages sortants et entrants

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

Les messages entrants de cet exemple illustrent les deux cas que vous pouvez rencontrer. Le deuxième enregistrement, comenzar, est le texte d'un bouton sur lequel le participant a appuyé. Le dernier, Completo el formulario, n'est pas un texte saisi par le participant : c'est la référence sous laquelle l'une de ses actions au sein du flux a été enregistrée. Ce texte est descriptif et varie selon le processus ; ne vous y fiez donc pas pour détecter des actions dans votre intégration.

Pourquoi les exemples sont en espagnol

Les valeurs de message de ces exemples sont des textes littéraux du canal WhatsApp, qui fonctionne dans la langue du participant. L'API ne les localise pas.

🔸 Message qui n'a pas pu être livré

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

🔸 Processus sans activité WhatsApp

[]

---

📋 Champs de la réponse

Champ	Type	Description
entity	String	Toujours présent. auco = message sortant envoyé par le bot Auco. signer = message entrant envoyé par le participant.
phone	String	Toujours présent. Numéro de téléphone du participant au format international, avec l'indicatif du pays et le signe +.
message	String	Toujours présent. Texte brut, déjà rendu : les modèles WhatsApp arrivent avec leurs variables substituées.
date	Number	Toujours présent. Horodatage epoch en millisecondes.
actions	Array<Object>	Facultatif. Uniquement sur les messages dont WhatsApp a signalé des statuts de livraison. Les messages du participant (entity: "signer") ne l'incluent pas.
actions[].action	String	Statut de livraison : sent, delivered, read ou failed.
actions[].timestamp	Number	Horodatage epoch en millisecondes du moment où WhatsApp a signalé le statut.
actions[].errors	Array<String>	Facultatif. Uniquement lorsque action vaut failed. Contient les motifs de l'échec.

Dates en millisecondes

date et actions[].timestamp sont tous deux exprimés en millisecondes, et non en secondes. Par exemple, 1746028800000 correspond à 2025-04-30T16:00:00.000Z. Si le langage de votre intégration attend des secondes, divisez la valeur par 1000.

Ne comparez pas message à un texte fixe

La réponse n'inclut ni URL de médias ni fichiers. Lorsque le participant envoie une pièce jointe ou effectue une action au sein du flux, l'enregistrement conserve une référence textuelle à cette action (par exemple, quelque chose comme Completo el formulario) au lieu du contenu lui-même.

Ce texte est descriptif et non un identifiant : il dépend du flux du processus, peut être personnalisé et peut changer. Il provient en outre du canal WhatsApp dans la langue du participant et n'est pas localisé par l'API. Si votre intégration doit réagir à des actions précises, ne la construisez pas en comparant le contenu de message.

Pour télécharger les fichiers téléversés par le participant, utilisez Récupérer le processus et les pièces jointes.

---

🔄 Statuts de livraison (actions[].action)

Statut	Description
sent	Auco a transmis le message à WhatsApp et WhatsApp l'a accepté pour livraison.
delivered	WhatsApp a confirmé que le message est arrivé sur l'appareil du participant.
read	Le participant a ouvert le message.
failed	WhatsApp n'a pas pu livrer le message ; le motif figure dans actions[].errors.

Les statuts sont cumulatifs et arrivent dans l'ordre où WhatsApp les signale. Un message peut rester au statut sent si le participant a désactivé les accusés de lecture.

---

🚫 Motifs d'échec (actions[].errors)

Ces codes ne sont pas des codes HTTP : la requête peut renvoyer 200 et contenir malgré tout des messages au statut failed.

Code	Description
WHATSAPP_RATE_LIMIT	La limite de messages autorisée par WhatsApp dans la fenêtre de temps actuelle a été dépassée.
WHATSAPP_NUMBER_NOT_REGISTERED	Le numéro du participant n'est pas enregistré sur WhatsApp.
WHATSAPP_NO_ACTIVE_CONVERSATION	Il n'y a pas de conversation active ; WhatsApp n'autorise pas les messages hors modèle.
WHATSAPP_UNSUPPORTED_MESSAGE_TYPE	WhatsApp a rejeté le type de message.
WHATSAPP_TEMPLATE_NOT_FOUND	Le modèle utilisé n'existe pas.
WHATSAPP_TEMPLATE_PAUSED	Le modèle est mis en pause par WhatsApp.
WHATSAPP_TEMPLATE_DISABLED	Le modèle a été désactivé par WhatsApp.
WHATSAPP_SERVICE_UNAVAILABLE	Le service WhatsApp était indisponible.
WHATSAPP_NUMBER_NOT_ACTIVE	Le numéro d'envoi d'Auco n'était pas actif.
WHATSAPP_SEND_ERROR	Erreur d'envoi non classifiée.

---

⚠️ Réponses d'erreur

Code	Description
400	Erreur de validation ou processus introuvable : CODE_REQUIRED (code manquant), CODE_NOT_VALID (code de moins de 9 caractères), USER_ID_REQUIRED (userId manquant sur un processus de signature), USER_ID_NOT_ALLOWED (userId envoyé sur un processus AucoFace) et PROCESS_NOT_FOUND
401	Authentification invalide ou absente

PROCESS_NOT_FOUND est renvoyé lorsque le processus n'existe pas, n'appartient pas à votre organisation, que le participant ne fait pas partie du processus, ou que le processus AucoFace n'a pas utilisé WhatsApp comme canal.

Processus AucoFace terminés sur le web

Un processus AucoFace terminé via le web, sans le canal WhatsApp, renvoie PROCESS_NOT_FOUND au lieu d'un tableau vide.