Comptes

Un compte, c'est un fournisseur et un numéro expéditeur. Tout ce qui part sur WhatsApp part d'un compte : c'est lui qui porte les identifiants, les plafonds, les modèles et l'URL de webhook par laquelle reviennent les accusés et les STOP.

Concept

Un compte se crée dans WhatsApp Marketing → Comptes → Nouveau compte. Il porte :

• un fournisseur, choisi à la création et qui ne change plus : un autre fournisseur, c'est un autre numéro, d'autres modèles et d'autres secrets, donc un autre compte ;
• un nom, pour vous y retrouver ;
• les champs du fournisseur (identifiants, numéro) ;
• deux plafonds : « Destinataires uniques / jour » et « Messages / heure » (voir plus bas) ;
• les cases Compte actif et Compte par défaut, et des notes.

Les jetons et secrets sont chiffrés au repos et n'en ressortent jamais : l'écran n'affiche qu'un masque (••••••). Laisser le masque tel quel ne change rien ; coller une nouvelle valeur la remplace. Le serveur doit disposer de sa clé maître de chiffrement (SECRETS_MASTER_KEY) : sans elle, il refuse d'enregistrer un secret plutôt que de le stocker en clair.

Le premier compte créé devient automatiquement « par défaut ». Ce drapeau ne choisit aujourd'hui aucun numéro d'envoi : une liste sans compte ni groupe envoie par le compte de son modèle (voir Listes).

Les fournisseurs

Le bac à sable n'appelle aucun réseau. Il fournit trois modèles d'exemple et sert à dérouler une séquence sans payer un message. Il ne peut ni recevoir de STOP qui compterait pour un vrai numéro, ni retenir les envois d'un vrai compte (la pause de 24 heures décrite plus bas se compte compte par compte), ni servir à la confirmation COD.

La liste des comptes

Chaque ligne montre le numéro, le statut, la qualité et le palier (quand le fournisseur les donne), les deux plafonds, l'URL de webhook, et les actions : Vérifier, Modèles, Appairage (comptes WhatsApp Web seulement), Journal (le journal des envois filtré sur ce compte), Modifier, supprimer.

Au-dessus, quatre tuiles résument le module : la licence, les comptes connectés, les messages en file (dont ceux déjà dus et ceux en cours d'envoi), et le dernier passage du moteur. Un moteur qui ne passe plus ressemble à une file qui n'avance pas : c'est cette tuile qui fait la différence.

Les statuts

Un compte en error n'est pas écarté d'office : les envois qui lui sont confiés sont tentés, et échouent tant que la cause tient — c'est l'erreur du fournisseur qui le dit. Une exception : une SIM rangée dans un groupe peut voir ses messages en file repartir d'une autre SIM, quand le routage retient pour eux un groupe qui connaît leur modèle (la liste vise le groupe, une règle, ou un seul groupe possible pour ce métier). Sinon, ils sont tentés sur elle et échouent (voir Rotation).

Brancher l'API officielle

1. Nouveau compte, choisissez le fournisseur, remplissez ses champs, Enregistrer. Le compte naît en unverified.
2. Vérifier. Trackily interroge le fournisseur. Chez Meta, il relit aussi le numéro affiché, la note de qualité et le palier d'envoi. Chez Twilio, il vérifie que le compte est actif (Twilio n'expose ni note de qualité ni palier). Le compte passe en connected.
3. Donner l'URL de webhook au fournisseur (Meta et Twilio ; sur 360dialog, Trackily la pose lui-même, voir plus bas). La colonne Webhook affiche l'URL complète du compte, avec Copier. Elle a la forme https://votre-domaine/webhook/wa/<clé>, la clé étant une suite de 64 caractères propre au compte. Le début de l'URL est l'adresse par laquelle vous avez ouvert l'administration : ouvrez-la par l'adresse publique de Trackily avant de copier, sinon le fournisseur recevra une adresse qu'il ne peut pas joindre.
4. Modèles → Synchroniser depuis le fournisseur (voir Modèles).
5. Envoi d'essai vers votre propre numéro, puis contrôlez le journal (voir plus bas).

Sans webhook, vous envoyez à l'aveugle. C'est par lui que reviennent les accusés de remise et de lecture, les clics sur les boutons de la confirmation COD, et surtout les STOP de vos clients. Sans lui, vous continueriez d'écrire à des gens qui ont demandé l'arrêt.

Ce que chaque fournisseur attend, côté webhook :

• Meta — le jeton de vérification que Meta demande à l'enregistrement de l'URL est la clé du compte, c'est-à-dire les 64 caractères qui terminent l'URL. Les notifications sont authentifiées par l'App Secret. Trackily lit les notifications messages, message_template_status_update et user_preferences : abonnez l'application à ces champs (la manière exacte se règle dans la console de Meta).
• Twilio — Trackily fournit lui-même l'adresse de retour des statuts avec chaque message, à condition que l'URL publique de l'instance soit réglée (Settings (Paramètres) → General → Advanced Configuration → Public URL, ou à défaut la variable d'environnement BASE_URL). Les messages entrants (réponses, STOP) exigent que l'URL du compte soit posée chez Twilio sur le numéro ou le service de messagerie. Twilio signe l'URL complète avec l'Auth Token : l'URL publique réglée dans Trackily doit être exactement celle que Twilio appelle.
• 360dialog — rien à coller. Les notifications ne sont acceptées que si elles portent un secret d'en-tête que Trackily génère ; il ne se saisit pas et ne s'affiche pas. Trackily pose lui-même l'URL du webhook et ce secret chez 360dialog, et seulement sur un geste de votre part : à la création du compte, à chaque Vérifier, à la régénération de la clé de webhook et quand la clé D360 change. 360dialog n'accepte qu'un webhook par numéro : chacun de ces gestes remplace celui que le numéro avait, y compris celui d'un autre outil (chatbot, CRM) que vous y auriez branché — l'écran le demande avant, l'agent aussi (aperçu à confirmer). Au démarrage, Trackily ne pose rien : un compte actif dont il n'a jamais configuré le webhook reçoit une dernière erreur « Trackily n'a jamais configuré le webhook de ce numéro… », et c'est à vous de cliquer Vérifier. Quand vous changez l'URL publique, il ne repose que les webhooks qu'il avait lui-même posés à l'ancienne adresse. Il prend pour cela l'URL publique de l'instance (Settings (Paramètres) → General → Advanced Configuration → Public URL, ou à défaut BASE_URL), qui doit être en https, sans port et sans _ dans le domaine. Si la pose échoue, la raison s'écrit dans la dernière erreur du compte, sans bloquer le geste : une URL absente ou refusée se corrige dans l'URL publique, un refus de 360dialog se retente par Vérifier. Tant que ce n'est pas posé, aucune notification n'est acceptée — ni statut, ni réponse, ni STOP.

Régénérer la clé de webhook

Régénérer tire une nouvelle clé : l'ancienne URL cesse immédiatement de recevoir. Il faut recoller la nouvelle chez le fournisseur (et chez Meta, le nouveau jeton de vérification). Sur 360dialog, il n'y a rien à recoller : le secret d'en-tête change aussi, et Trackily pose lui-même la nouvelle URL et le nouveau secret — le compte rendu dit si 360dialog a refusé. Sur un compte WhatsApp Web, il n'y a rien à recoller non plus : Trackily annonce lui-même la nouvelle adresse à la passerelle, et vous prévient si elle n'a pas répondu.

Brancher une carte SIM (WhatsApp Web)

Cette voie passe par la passerelle, un service à héberger à côté de Trackily. Montez-la d'abord.

Contraire aux conditions d'utilisation de WhatsApp. Le numéro peut être banni sans préavis, parfois en quelques heures s'il écrit à des gens qui ne l'ont jamais contacté. Il n'y a ni recours ni support : la SIM est perdue avec ses conversations. N'utilisez jamais un numéro dont vous avez besoin (service client, numéro personnel, numéro imprimé sur les colis), et n'écrivez qu'aux destinataires qui ont donné leur accord.

Avant de créer le compte

Réglez l'URL publique de Trackily (Settings (Paramètres) → General → Advanced Configuration → Public URL ; à défaut, Trackily prend la variable d'environnement BASE_URL). C'est l'adresse où la passerelle postera les STOP, les réponses et les accusés. Sans l'une ni l'autre, le compte se crée quand même, mais la session n'est pas déclarée à la passerelle et le compte reste en unverified avec un message qui le dit.

Créer le compte

Nouveau compte → WhatsApp Web — SIM ou numéro personnel (voie non officielle). L'avertissement rouge s'affiche au-dessus des champs.

Les plafonds d'un compte WhatsApp Web démarrent plus bas que ceux de l'API officielle : 40 messages par heure et 100 destinataires uniques sur 24 h. La passerelle a ses propres limites (voir Passerelle) : les deux s'appliquent, la plus stricte gagne.

Une SIM peut être rangée dans un groupe de SIM depuis ce même formulaire (champ « Groupe de SIM », visible pour ce fournisseur seulement). Le rangement est refusé quand il mélangerait les métiers — commandes et marketing — ou laisserait des messages sans SIM capable de les envoyer ; le refus nomme les listes ou les réglages à corriger. Voir Rotation.

Appairer la SIM

Sur la ligne du compte, Appairage ouvre la boîte d'appairage.

1. Avant le premier appairage, l'avertissement « À lire avant d'appairer ce numéro » s'affiche : cochez J'ai compris. Les boutons restent grisés tant que ce n'est pas fait.
2. Appairer par QR : sur le téléphone qui porte la SIM, WhatsApp → Appareils connectés → Connecter un appareil, et scannez. Sur une session neuve, le premier QR peut mettre jusqu'à une trentaine de secondes à venir : Trackily l'attend jusqu'à 45 secondes. Le QR vit 60 secondes ; passé ce délai, redemandez-en un — ce n'est pas une erreur.
3. Ou Appairer par code, quand la caméra n'est pas disponible : tapez le numéro de la SIM au format international, puis saisissez le code affiché dans WhatsApp → Appareils connectés → Connecter avec un numéro de téléphone.

Si la SIM est déjà appairée, ou qu'un appairage est déjà en cours (le téléphone finit de se connecter), la demande est refusée avec un message qui le dit, et la boîte relit l'état de la session : ce n'est pas une panne. 4. L'écran relit l'état toutes les 3 secondes. Quand la session passe à « Connectée », le compte passe en connected et affiche le numéro.

Le bouton d'appairage déclare aussi la session à la passerelle si elle ne la connaissait pas encore : c'est lui qu'on relance quand la passerelle a été montée après la création du compte. Relire l'état relit sans rien déclencher.

Après l'appairage, laissez le téléphone allumé et connecté : la session vit sur lui, pas sur le serveur.

Les états d'une session

Une coupure réseau ordinaire ne change pas l'état : la passerelle se reconnecte seule, en espaçant ses tentatives. Pendant ce temps, les envois sont retentés plus tard, comme après toute erreur passagère.

Déconnecter ferme la session chez WhatsApp et efface son état sur la passerelle : c'est une déconnexion, pas une pause. Le compte repasse en unverified. Réappairer ensuite remet l'échauffement du numéro au jour 1 (20 messages), sur la passerelle comme dans Trackily, qui relève la date d'appairage à chaque connexion (voir Rotation). Tant qu'elle n'est pas réappairée, une SIM déconnectée n'envoie rien : dans un groupe, ses sœurs prennent sa file.

Les plafonds

Deux autres gardes s'ajoutent sans réglage, compte par compte : pas plus d'un message toutes les 6 secondes vers un même destinataire, et une pause de 24 heures des modèles MARKETING vers un destinataire que le fournisseur a refusé pour préserver son écosystème.

Un plafond atteint n'est pas un échec : le message est reporté à la prochaine place libre, sans consommer de tentative. Les paliers qu'un fournisseur accorde à votre numéro sont fixés chez lui, pas dans Trackily : réglez ces deux champs en dessous de ce que votre fournisseur vous accorde réellement.

L'envoi d'essai

Comptes → Envoi d'essai. Choisissez le compte, le modèle, le numéro (avec le pays s'il est écrit en national) et, si le modèle a des variables, les paramètres en JSON. Le bouton dit Envoyer (facturé) : ce n'est pas une simulation. Sur l'API officielle, le fournisseur le facture ; sur une carte SIM, aucun fournisseur ne le facture, mais il part du vrai numéro ; le bac à sable, lui, n'envoie rien de réel.

• Le message est mis en file et part au prochain passage du moteur, qui tourne toutes les 30 secondes. Il compte dans les plafonds du compte, et sur une SIM dans son échauffement.
• Le modèle doit être approuvé et de catégorie UTILITY, et appartenir au compte choisi : un essai ne sert pas à contourner le consentement marketing.
• Il est tracé au journal avec la nature « Essai ».

Pour vérifier une règle de rotation sans rien envoyer, utilisez le simulateur de la page Groupes de SIM, pas l'envoi d'essai.

Supprimer un compte

La suppression est refusée tant qu'une liste vise ce compte, ou qu'une étape active de séquence utilise un de ses modèles : sinon ces séquences s'arrêteraient sans un mot. Rattachez-les ailleurs d'abord. Supprimer un compte WhatsApp Web ferme aussi sa session sur la passerelle ; si la passerelle ne répond pas, la réponse le dit et il faut couper la session à la main.

Erreurs courantes

• « Le secret ne peut pas être chiffré » — la clé maître SECRETS_MASTER_KEY manque sur le serveur. Aucun secret WhatsApp n'est enregistré en clair : posez la clé, redémarrez, recommencez.
• « Le secret … ne se déchiffre pas » — la clé maître a changé depuis l'enregistrement. Remettez l'ancienne, ou ressaisissez les secrets du compte.
• Compte WhatsApp Web qui reste unverified après création — l'URL publique n'est pas réglée, ou la passerelle ne répondait pas. Réglez l'URL publique, vérifiez que la passerelle tourne, puis Appairage → Appairer par QR : ce geste déclare la session.
• « Vérifier » répond « Appaire ce numéro… » sur un compte WhatsApp Web — la session n'est pas connectée. La vérification lit l'état, elle ne crée rien, et cet échec passe le compte en error. Passez par Appairage : dès que la session est « Connectée », le compte repasse en connected.
• « La passerelle refuse le jeton du compte » — le Jeton de la passerelle ne correspond pas à PASSERELLE_JETON. Recollez-le d'un seul tenant.
• Rien ne revient dans le journal (tout reste « Parti ») — le webhook n'est pas configuré chez le fournisseur, ou l'URL publique est fausse. Voir la section sur le webhook ci-dessus.
• « Le webhook n'a pas pu être posé chez le fournisseur (360dialog) » dans la dernière erreur d'un compte 360dialog — tant qu'il ne l'est pas, toutes ses notifications sont refusées. Si le message parle de l'URL publique, renseignez-la (en https, sans port) puis relancez Vérifier ; sinon, 360dialog a refusé ou n'a pas répondu : relancez Vérifier quand il répond.
• « L'identifiant de session d'un compte WhatsApp Web ne se modifie pas » — il est fixé à la création. Pour une autre SIM, créez un nouveau compte ; pour ce numéro, déconnectez-le puis réappairez-le.
• « Le compte est utilisé par … liste(s) » à la suppression — rattachez ces listes à un autre compte (ou à un groupe) d'abord.

Voir aussi

• Modèles — synchroniser ou écrire les textes d'un compte
• Passerelle — le service des cartes SIM
• Rotation — ranger ses SIM par métier
• Suppressions — ce que le webhook bloque tout seul