Vos outils.
Vos conversations.

PREMIÈRE REQUÊTE · LECTURE SEULE

Consulter les capacités.

Définissez BECLEVER_API_KEY depuis votre coffre de secrets côté serveur, puis appelez :

curl --fail-with-body https://beclever.fr/api/v1/capabilities \
  --header "Authorization: Bearer $BECLEVER_API_KEY" \
  --header "Accept: application/json"

Cet exemple ne transmet aucun message. Consultez le contrat OpenAPI pour les champs, les erreurs et les règles de reprise de chaque route. Ne répétez pas automatiquement une écriture dont le résultat est inconnu.

Les limites annoncées sont de 60 requêtes par minute par clé et 300 par organisation. Le serveur peut refuser une demande lorsque la limite est atteinte ; respectez les indications de reprise retournées.

CONVERSATIONS · LECTURE SEULE

Retrouver un échange conservé.

Avec la permission conversations:read, consultez les conversations déjà conservées par BECLEVER. Aucun appel au moteur ni import du passé WhatsApp n’est déclenché ; le compte peut être déconnecté. Cette permission reste distincte de messages:read et de l’envoi.

GET /api/v1/conversations sans paramètre conserve sa réponse {conversations} : 100 résultats maximum, classés par dernière mise à jour décroissante. Pour parcourir la liste, ajoutez limit, channelId ou cursor. Le mode paginé renvoie {conversations, hasMore, nextCursor}, avec 50 résultats par défaut et de 1 à 100 par page. Les paramètres inconnus, répétés ou vides sont refusés.

curl --fail-with-body --get 'https://beclever.fr/api/v1/conversations' \
  --header "Authorization: Bearer ${BECLEVER_API_KEY}" \
  --data-urlencode 'channelId=clever_00000000000000000000000000000000' \
  --data-urlencode 'limit=50'

Les pages suivent un ordre d’indexation interne immuable, du plus récent au plus ancien. Ce n’est ni l’ordre de updatedAt, ni une date de création historique WhatsApp. La première page fixe une borne haute : les conversations ajoutées ensuite restent hors du relevé. Le statut et updatedAt sont ceux conservés au moment de chaque lecture.

Reprenez avec le nextCursor reçu et le même filtre channelId ; limit peut changer. Le curseur opaque est lié à votre organisation et au filtre, et expire 15 minutes après la première page, sans prolongation. Il ne remplace pas la clé ni ses droits. À la dernière page, hasMore vaut false et nextCursor vaut null. Pour changer de filtre ou voir les nouveaux échanges, recommencez sans curseur et dédupliquez par conversations[].id.

curl --fail-with-body --get 'https://beclever.fr/api/v1/conversations' \
  --header "Authorization: Bearer ${BECLEVER_API_KEY}" \
  --data-urlencode 'channelId=clever_00000000000000000000000000000000' \
  --data-urlencode 'limit=100' \
  --data-urlencode "cursor=${BECLEVER_CONVERSATIONS_CURSOR}"

Pour un échange précis, utilisez son identifiant interne. Exemple fictif :

curl --fail-with-body \
  'https://beclever.fr/api/v1/conversations/22222222-2222-4222-8222-222222222222' \
  --header "Authorization: Bearer ${BECLEVER_API_KEY}"

La réponse {conversation} fournit les identifiants de l’échange et du compte, chatId, l’état courant, le motif et updatedAt, ainsi que les références de publication et de bloc éventuelles. Elle ne contient ni messages ni variables internes. Un échange inconnu ou inaccessible renvoie 404 sans révéler une autre organisation. La route /conversations/{id}/messages reste inchangée ; la pagination décrite ici porte sur la liste des conversations.

Paramètre invalide : 400 runtime-conversations-invalid-query ; curseur invalide ou expiré : 400 runtime-conversations-cursor-invalid ; conversation ou filtre inaccessible : 404 runtime-conversation-not-found. Aucun paramètre de requête n’est accepté sur le détail. La chaîne de requête est limitée à 4 096 caractères et le curseur à 2 048.

Filtrer votre boîte commune.

La liste paginée des conversations accepte les filtres combinables channelId, provider=whatsapp|telegram, tag et q. Les filtres sont appliqués à tout le journal avant pagination. q recherche un titre de conversation, un identifiant ou un numéro (100 caractères maximum), jamais le contenu des messages. tag sélectionne une étiquette exacte, normalisée en minuscules et limitée à 40 caractères.

Le DTO peut fournir title, le titre conservé d’une conversation Telegram (200 caractères maximum), ainsi que chatType, canSend et manualOnly pour un compte personnel. Une conversation synchronisée peut ne contenir aucun message : ces lectures n’ouvrent pas l’historique Telegram et ne le marquent pas comme lu. Dans le Studio, le propriétaire ou un administrateur autorisé peut charger cet historique depuis le détail de la conversation : la confirmation signale le marquage comme lu dans Telegram. La pagination des messages déjà conservés reste une lecture locale sans cet effet. Ce parcours utilise la session du Studio ; il n’ajoute pas de droit à une clé API. Le DTO fournit conversationTags, contactTags, leur union tags et tagRevisions. Une étiquette contact suit le même identifiant exact sur les comptes d’un même fournisseur et d’une même organisation. Aucun rapprochement automatique PN/LID ni WhatsApp/Telegram. Les marquages se modifient dans le Studio ; aucune écriture de marquage n’est exposée par l’API publique.

Conservez tous les filtres avec le curseur. Les étiquettes restent courantes : si elles changent pendant la pagination, actualisez sans curseur pour une vue complète à jour. Les conversations déconnectées restent consultables. Ces lectures n’importent pas l’historique antérieur à BECLEVER.

GET /api/v1/conversations?provider=whatsapp&tag=vip&q=336&limit=50

HISTORIQUE · LECTURE SEULE

Relire les messages conservés.

GET /api/v1/messages consulte uniquement le journal reçu et conservé par BECLEVER dans votre organisation. Il ne synchronise pas tout le passé WhatsApp, ne contacte pas le moteur et ne télécharge aucune pièce jointe. Un compte déconnecté peut conserver un historique consultable.

Créez une clé avec la permission distincte messages:read. Les clés existantes ne reçoivent pas automatiquement ce droit ; messages:send et conversations:read ne le remplacent pas. Les droits du créateur restent vérifiés à chaque page.

Filtrez facultativement par channelId et/ou conversationId. Si les deux sont présents, ils doivent correspondre au même compte. limit vaut 50 par défaut, de 1 à 100. Les paramètres inconnus ou répétés sont refusés. Exemple fictif, sans effet WhatsApp :

curl --fail-with-body --get 'https://beclever.fr/api/v1/messages' \
  --header "Authorization: Bearer ${BECLEVER_API_KEY}" \
  --data-urlencode 'channelId=clever_00000000000000000000000000000000' \
  --data-urlencode 'limit=50'

La réponse contient messages, nextCursor et hasMore. Chaque message fournit ses identifiants de conversation et de compte, chatId, createdAt ISO et le contenu conservé. Les médias restent des métadonnées privées. Dédupliquez avec messages[].id.

L’ordre va du plus récent au plus ancien, puis suit une séquence stable pour les dates identiques. Le premier appel fixe une borne haute : les messages insérés ensuite restent hors de ce relevé, même avec une date ancienne. Les statuts de livraison peuvent évoluer entre deux lectures.

Reprenez avec cursor égal au nextCursor reçu, sans le modifier et en conservant les mêmes filtres ; limit peut changer. Le curseur opaque chiffré expire 15 minutes après la première page, sans prolongation, et reste lié à l’organisation, aux filtres et au relevé. Exemple de page suivante :

curl --fail-with-body --get 'https://beclever.fr/api/v1/messages' \
  --header "Authorization: Bearer ${BECLEVER_API_KEY}" \
  --data-urlencode 'channelId=clever_00000000000000000000000000000000' \
  --data-urlencode 'limit=100' \
  --data-urlencode "cursor=${BECLEVER_NEXT_CURSOR}"

À la fin, hasMore vaut false et nextCursor vaut null. Pour voir les nouveaux messages, changer de filtre ou reprendre après expiration, recommencez sans curseur et dédupliquez les résultats.

Un paramètre invalide renvoie 400 runtime-history-invalid-query ; un curseur altéré, expiré ou réutilisé hors de son contexte renvoie 400 runtime-history-cursor-invalid. Un filtre inaccessible ou incohérent renvoie 404 runtime-history-filter-not-found. L’historique par conversation garde sa route et sa permission conversations:read.

ROUTES PRINCIPALES

Lire, puis agir explicitement.

• GET /api/v1/channels : vos comptes WhatsApp.
• GET /api/v1/conversations : liste simple ou paginée ; GET /api/v1/conversations/{id} : détail ; GET /api/v1/conversations/{id}/messages : messages conservés.
• GET /api/v1/channels/{id}/operations : catalogue et disponibilité du compte ciblé.
• POST /api/v1/conversations/{id}/reply : réponse texte ou média privé.
• GET /api/v1/messages : historique BECLEVER paginé, permission messages:read.
• POST /api/v1/messages : message avec channelId, to et contenu.
• GET /api/v1/operations/{jobId} : état d’une opération mise en file.

Les envois demandent une référence requestId stable, composée de lettres, chiffres, tirets ou traits de soulignement (80 caractères maximum). Conservez la même référence lors de la reprise d’une demande incertaine. Une nouvelle intention d’envoi reçoit une nouvelle référence.

L’exemple suivant transmet une réponse au contact de la conversation choisie. Remplacez CONVERSATION_ID et la référence uniquement après avoir vérifié le destinataire et votre autorisation d’envoi :

curl --fail-with-body --request POST \
  https://beclever.fr/api/v1/conversations/CONVERSATION_ID/reply \
  --header "Authorization: Bearer $BECLEVER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"text":"Votre réponse","requestId":"REFERENCE_UNIQUE_DEMANDE"}'

Une réponse HTTP 202 signifie que l’opération est prise en charge, pas que le contact a reçu ou lu le message. Une pièce jointe utilise mediaId avec une caption facultative ; elle ne doit pas être combinée avec text. Un sticker utilise un WebP statique de 512 × 512 pixels exactement, limité à 100 Kio ; il est envoyé sans légende. Les vocaux privés utilisent Ogg/Opus (8 Mio, 20 minutes, mono ou stéréo) et sont transmis sans légende ; MP3 et M4A ne sont pas acceptés. Les schémas complets et les permissions de chaque route restent définis par OpenAPI.

Rapprocher des contacts PN / LID

POST /api/v1/channels/{channelId}/contacts/resolve utilise le droit whatsapp:read. Envoyez explicitement 1 à 25 identifiants canoniques @c.us ou @lid. Le résultat conserve l’ordre et les doublons : chaque élément contient input, status (resolved ou unknown), phoneChatId et lidChatId, éventuellement nuls.

curl -X POST 'https://beclever.fr/api/v1/channels/channel_exemple/contacts/resolve' \
  -H "Authorization: Bearer $BECLEVER_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"contacts":["33600000000@c.us","123456789@lid"]}'

Cette lecture consulte réellement le moteur pour ces contacts. Elle ne synchronise pas le carnet, ne modifie pas les alias enregistrés et ne lève aucun STOP. Les deux opérations phoneByLid et lidByPhone doivent être approuvées ; le compte doit être connecté. Limites : 15 secondes pour le lot, deux lots simultanés sur le service et un par organisation. Une incohérence fournisseur fait échouer le lot.

Entrée invalide : HTTP 400 ; compte inaccessible : 404 ; approbation ou session indisponible : 409 ; limite simultanée : 429 ; échec de résolution : 502. Un contact inconnu peut simplement produire status: unknown. Cette route ne donne pas l’autorisation d’envoyer un message.

ENVOI DÉDIÉ · VIDÉO PRIVÉE

Envoyer une note vidéo ronde.

Après téléversement d’un MP4 privé par POST /api/v1/media (media:write), utilisez POST /api/v1/messages ou POST /api/v1/conversations/{id}/reply avec messages:send. Le fichier conserve kind: video. Ajoutez explicitement mediaType: videoNote : aucun texte, aperçu de lien ni légende non vide ne peut accompagner cette demande.

curl --fail-with-body -X POST 'https://beclever.fr/api/v1/conversations/conversation_exemple/reply' \
  -H "Authorization: Bearer $BECLEVER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"mediaId":"media_prive_exemple","mediaType":"videoNote","requestId":"note-video-exemple-001"}'

Conditions : MP4 H.264 carré, une piste vidéo, 8 Mio et 60 secondes maximum, audio AAC-LC facultatif (mp4a.40.2, mono/stéréo, 8–48 kHz) et aucune autre piste. Le serveur renvoie les métadonnées width, height et videoNoteCompatible ; elles ne sont jamais acceptées comme preuve fournie par le client. Réimportez un ancien fichier non mesuré. Aucune conversion automatique ni URL de fichier externe.

Vérifiez sendVideoNote.available dans les capacités du compte. Ce transport dédié exige sa propre autorisation ; la disponibilité de sendVideo ne suffit pas et aucune route générique ne remplace cet envoi. Sans mediaType, l’envoi du MP4 reste une vidéo classique. Le message sortant conserve kind: sendVideoNote et mediaType: videoNote, tandis que son média reste kind: video.

Après une erreur réseau, conservez exactement le même contenu et requestId. HTTP 202 signifie pris en charge, pas livré. Erreurs : media-video-note-incompatible, runtime-video-note-caption-unsupported et runtime-operation-unavailable. Aucun repli automatique vers un envoi classique.