# Clés API (SyBox)

Où : Paramètres > Intégrations > Clés API

À quoi ça sert :

"Attribuez à un programme externe sa propre clé d'envoi via SyBox : le jeton WhatsApp ne quitte jamais le serveur, et une clé compromise peut être révoquée isolément." Votre ERP, votre caisse ou votre logiciel de bureau utilise une clé SyBox, sans jamais avoir besoin de vos identifiants WhatsApp réels.

Ce qu'un programme peut effectuer avec une clé (détaillé dans la Documentation développeur publique) :

- Envoyer des messages WhatsApp depuis votre propre numéro connecté. Le format de requête est identique à l'API Cloud WhatsApp de Meta : un outil déjà développé pour Meta n'a besoin que d'une nouvelle adresse et d'une clé SyBox. Le texte, les modèles, les images, les documents et les messages interactifs sont tous pris en charge. Les réponses et les erreurs sont transmises telles que Meta les renvoie.
- Enregistrer une réclamation depuis votre propre système, par exemple un litige consigné dans votre ERP. Le client doit déjà exister dans SyBox.
- Importer des SMS depuis un téléphone directement dans la boîte de réception.
- Lancer vos automatisations depuis un autre système (une clé de type "Lancer une automatisation").
- Rechercher, lire et modifier vos contacts depuis un autre système (une clé de type "Lire et mettre à jour les contacts").

Qui peut y accéder : l'administrateur principal et les membres de l'équipe ayant la permission "Gérer les canaux".

L'interrupteur "Passerelle API" :

En haut de l'écran des clés API se trouve l'interrupteur "Passerelle API". Il est désactivé par défaut. Tant qu'il est inactif, aucune clé ne fonctionne et vous ne pouvez pas en créer de nouvelles. Si vous essayez, le message suivant apparaît : "La passerelle API est désactivée. Activez-la avec l'interrupteur en haut de cet écran avant de créer des clés." Le réglage est sauvegardé dès que vous cliquez dessus.

### Comment activer la passerelle et créer une clé

1. Allez dans Paramètres > Intégrations > Clés API.
2. Activez l'interrupteur "Passerelle API".
3. Cliquez sur "Nouvelle clé".
   ![Settings, API keys: keys that let another program send through SyBox, and the "New key" button](https://www.sybox.io/res/sybox/help/fr/turn-on-the-gateway-and-create-a-key-3.webp?v=7663d326)
4. Choisissez le "Type de clé" :
   - "Envoyer via WhatsApp" : le programme envoie des messages à vos clients.
   - "Enregistrer une réclamation" : le programme ouvre des dossiers dans SyBox. Il ne peut pas envoyer de messages.
   - "Importer des SMS depuis un téléphone" : un téléphone transfère ses SMS reçus vers la boîte de réception.
   - "Lancer une automatisation" : le programme lance les automatisations dont le champ "Démarre quand" est "Un autre programme appelle SyBox" (POST /v1/automation avec le "phone" du client, ainsi que "event" et "data" en option). Il ne peut pas envoyer de messages. Voir Paramètres > IA et automatisation > Automatisations.
   - "Lire et mettre à jour les contacts" : le programme recherche des contacts, en lit un et modifie son nom, son e-mail, ses champs de contact et ses libellés (POST /v1/contacts/search, /get, /update et /labels). Il ne peut pas envoyer de messages. La clé agit au nom de la personne qui l'a créée : elle ne voit que les contacts que cette personne est autorisée à voir, ne fonctionne que si cette personne peut ouvrir la liste des contacts et voir les numéros, et ne peut modifier les contacts que si cette personne est autorisée à les modifier. Si cette personne est désactivée, la clé cesse de fonctionner.
5. Renseignez le "Nom de l'appareil ou du programme", par exemple "Poste bureau" ou "Logiciel comptable". Attribuez une clé dédiée à chaque appareil ou programme.
6. Pour une clé "Envoyer via WhatsApp", paramétrez aussi :
   - "Envoie depuis" : le numéro WhatsApp expéditeur utilisé par cette clé (obligatoire).
   - "Autoriser les messages libres" : activé ou désactivé.
   - "Autoriser les modèles approuvés" : activé ou désactivé. Au moins une de ces deux options doit être active, sinon vous verrez : "Autorisez au moins les messages libres ou les modèles — sinon la clé ne pourra rien envoyer."
   - "Autoriser l'envoi de médias" : activé ou désactivé.
   - "Modèles" (facultatif) : noms des modèles, séparés par des virgules. Laissez vide pour autoriser tous les modèles.
   - "Pays des destinataires autorisés" (facultatif) : codes pays à deux lettres, par exemple MA,FR,EG. Laissez vide pour autoriser tous les pays.
   - "Envoi autorisé de" ... "À" : la plage horaire durant laquelle la clé peut émettre. Indiquez la même heure aux deux champs pour lever toute restriction horaire. Les heures s'appliquent selon le fuseau de l'espace de travail.
   - "Limite quotidienne de messages (0 = illimité)".
7. Pour une clé "Importer des SMS depuis un téléphone", activez "Contacts et clients uniquement". Lorsqu'elle est active, les SMS de tout autre numéro restent sur le téléphone sans arriver dans la boîte de réception. Désactivez-la uniquement si le téléphone sert exclusivement pour le travail.
8. Cliquez sur Enregistrer.
9. Une fenêtre affiche l'"URL de base" et la "Clé API". Copiez-les sans attendre. "Copiez cette clé maintenant — elle ne s'affiche qu'une seule fois." Intégrez-les ensuite dans les paramètres de votre programme.

Ce que la carte d'une clé affiche :

- Le nom de la clé, ainsi que le numéro expéditeur (ou son badge de type, pour une clé sans envoi).
- Les derniers caractères de la clé, pour vous permettre de les identifier.
- La mention "dernière utilisation", avec date et heure, ou "jamais".
- Les restrictions actives : "Texte libre uniquement", "Modèles uniquement", "sans média", "Modèles", pays autorisés, plages d'envoi et la limite journalière sous la forme envoyés aujourd'hui / limite / jour. Une clé SMS sans restriction de numéro affiche "Tous les numéros".

### Comment modifier, suspendre ou supprimer une clé

1. Cliquez sur Modifier sur la carte de la clé. Vous pouvez ajuster son nom, son numéro et ses limites. Le type de clé ne peut plus être modifié une fois créé, et la clé elle-même ne s'affichera plus jamais.
   ![To change, pause or delete a key: "Edit" marked on the screen in SyBox](https://www.sybox.io/res/sybox/help/fr/change-pause-or-delete-a-key-1.webp?v=4a9cb026)
2. Cliquez sur Activer / Désactiver pour suspendre temporairement une clé.
3. Cliquez sur Supprimer, puis confirmez : "Supprimer cette clé API ? Tout programme qui l'utilise encore cesse de fonctionner immédiatement."

**Q: J'ai égaré ma clé API. Puis-je la revoir ?**

Non. Elle n'est affichée qu'une seule fois. Générez une nouvelle clé, intégrez-la dans votre programme, puis supprimez l'ancienne.

**Q: Je crains qu'une clé ait fuité. Que faire ?**

Supprimez ou désactivez immédiatement cette clé. Seule cette clé cessera de fonctionner. Votre numéro WhatsApp et vos autres clés ne risquent rien.

**Q: La liste "Envoie depuis" est vide.**

Cette liste n'affiche que les numéros WhatsApp connectés et activés. Connectez d'abord un numéro dans Paramètres > Messagerie > Canaux.

**Q: Les envois de mon programme sont rejetés.**

Assurez-vous que l'interrupteur "Passerelle API" est activé et que la clé est active. Vérifiez également les restrictions de la clé : texte libre ou modèles, médias, modèles autorisés, pays permis, plages horaires et limite journalière. Les règles propres à WhatsApp continuent aussi de s'appliquer. Par exemple, le texte libre n'est possible que dans les 24 heures suivant le dernier message du client.

**Q: Une clé "Enregistrer une réclamation" peut-elle aussi envoyer des messages ?**

Non, c'est intentionnel. Une clé qui enregistre des dossiers ne peut pas envoyer de messages aux clients, et une clé d'envoi ne peut pas ouvrir de dossiers. Créez une clé distincte pour chaque usage.

**Q: Je possède une ancienne clé de type "Recevoir d'un programme". Est-elle encore utilisable ?**

Oui, les clés existantes de ce type restent fonctionnelles. Il n'est simplement plus possible d'en créer de nouvelles. Utilisez plutôt "Enregistrer une réclamation" pour ce type d'usage.

Source: https://www.sybox.io/fr/help/api-keys