L’API publique de nBot

L’API publique ouvre les données de votre organisation à vos outils (CRM, Zapier, n8n, votre propre code) : contacts, entreprises, conversations, réponses aux formulaires, affaires et tâches. Elle répond en JSON. Créer une clé est réservé aux administrateurs ; tout le monde peut lire la référence.

Créez une clé

1. Ouvrez Réglages › Réglages, puis la section API (groupe Facturation).
2. Dans la carte Clés API, donnez un nom à la clé, par exemple l’outil qui l’utilisera (Nom de la clé (ex : CRM, Zapier)).
3. Choisissez son droit :
   • Lecture seule : elle lit, mais toute route d’écriture (POST, PATCH, DELETE) lui répond par une erreur 403 ;
   • Lecture et écriture : elle lit et modifie.
4. Cliquez sur Créer.
5. La clé s’affiche une seule fois, sous Votre nouvelle clé « … » : cliquez sur Copier, rangez-la dans votre outil ou un gestionnaire de mots de passe, puis cliquez sur Je l’ai copiée.

nBot n’en garde qu’une empreinte : il ne pourra plus jamais vous la montrer. Une clé perdue se remplace par une nouvelle. Une clé commence par nbot_ et donne accès à toute l’organisation, toutes entités confondues.

Appelez l’API

L’adresse de base est https://chat.nbot.ma/api/v1. Envoyez la clé dans l’en-tête Authorization de chaque requête :

curl https://chat.nbot.ma/api/v1/contacts?limit=10 \
  -H "Authorization: Bearer nbot_votre_cle"

Ne mettez jamais la clé dans l’adresse (?api_key=…) : nBot refuse la requête, car les adresses finissent dans les journaux. Si cela vous est arrivé, révoquez la clé et créez-en une autre.

Pour écrire, envoyez un corps JSON :

curl -X POST https://chat.nbot.ma/api/v1/contacts \
  -H "Authorization: Bearer nbot_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"name": "Salma Bennani", "email": "salma@exemple.ma", "tags": ["salon-2026"]}'

Les routes

Données	Routes
Contacts	GET et POST /contacts ; GET, PATCH et DELETE /contacts/{id} ; POST /contacts/{id}/tags et DELETE /contacts/{id}/tags/{tag}
Entreprises	GET et POST /companies ; GET et PATCH /companies/{id}
Conversations	GET /conversations ; GET /conversations/{id} (avec ses 500 derniers messages) ; POST /conversations/{id}/messages (répondre au nom de l’équipe) ; POST /conversations/{id}/close
Réponses aux formulaires	GET /form-submissions ; GET /form-submissions/{id}
Affaires	GET et POST /deals ; GET et PATCH /deals/{id} (par exemple pour la changer d’étape)
Tâches	GET et POST /tasks
Flows	POST /flows/{id}/start
Webhooks	GET /webhooks : vos endpoints de webhooks sortants, en lecture, sans leur secret

La référence complète (paramètres, corps, réponses, exemples) est dans la même section API, sous Référence de l’API. Le document https://chat.nbot.ma/api/v1/openapi.json (lien Spécification OpenAPI 3.1) la décrit au format OpenAPI : importez-le dans Postman, Insomnia ou votre générateur de client. Il se lit sans clé.

Un message envoyé par POST /conversations/{id}/messages part comme une réponse de la Messagerie : en direct dans le widget, ou sur WhatsApp, Instagram ou Messenger. Si le canal le refuse (la fenêtre de 24 heures de Messenger, par exemple), le message est gardé, marqué en échec, et l’API répond 502 avec le motif.

Lancez un flow depuis votre outil

1. Dans nBot, donnez au flow le déclencheur Appel API, puis publiez-le (voir Automatiser les conversations avec les flows).
2. Son identifiant est dans l’adresse de son éditeur : /flows/{id}/edit.
3. Appelez la route avec une clé Lecture et écriture, pour un contact ou une conversation :

curl -X POST https://chat.nbot.ma/api/v1/flows/ID_DU_FLOW/start \
  -H "Authorization: Bearer nbot_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"contactId": "ID_DU_CONTACT"}'

Avec conversationId, le flow démarre dans cette conversation ; avec contactId seul, dans la dernière conversation du contact. Ses messages partent au visiteur. Un contact sans conversation : les actions du flow (tags, champs…) s’appliquent, rien n’est envoyé. message (facultatif) sert de message de départ au flow. Un flow non publié, ou sans déclencheur Appel API, répond 404.

Pages, erreurs et limites

• Pages : les listes renvoient les plus récents d’abord, 50 par page (jusqu’à 100 avec limit). Pour la page suivante, renvoyez nextCursor dans cursor ; null signale la dernière page.
• Dates : en ISO 8601 (UTC).
• Erreurs : toujours la même forme, {"error": {"code": "…", "message": "…"}}, avec les codes 401 (clé absente, invalide ou révoquée), 403 (clé en lecture seule, abonnement expiré), 404, 409 (doublon, par exemple une deuxième entreprise sur le même domaine), 422 (requête invalide) et 429. Les messages sont en anglais, pour les développeurs.
• Limite : 120 requêtes par minute et par clé. Au-delà, une erreur 429 avec l’en-tête Retry-After (en secondes).

Gérez vos clés

Chaque clé de la liste montre son droit, sa date de création et sa dernière utilisation (ou jamais utilisée).

• Le crayon (Renommer) change son nom, puis Enregistrer.
• Révoquer la coupe, après confirmation : les intégrations qui l’utilisent cessent de fonctionner tout de suite. Une clé révoquée reste dans la liste (Révoquée le …) et ne peut pas être réactivée.

La création, le renommage et la révocation d’une clé sont notés dans le journal d’audit.

Quand l’API fait une action que le journal d’audit retient (supprimer un contact, par exemple), elle y apparaît au nom de l’administrateur qui a créé la clé.

Astuce · Une clé par outil : si l’un d’eux est compromis ou abandonné, vous ne révoquez que la sienne.