Créer vos identifiants API Crisp : token et website_id

Étape 1 : Création d’un plugin dans le Marketplace Crisp

Connectez-vous ou créez un compte sur le Marketplace Crisp

Rendez-vous sur le portail développeur pour initier la création de votre intégration.

Entrez un nom et une description pour votre plugin

Nous préconisons d’utiliser le nom officiel de votre application pour faciliter l’identification par les utilisateurs.

Copiez l’Identifier et la Key

Le plugin inclut des identifiants distincts pour votre espace de développement et votre application de production. Vous pouvez, à tout moment, copier ces identifiants depuis l’onglet Tokens de votre plugin.

Ces deux valeurs sont nécessaires pour construire le header d’authentification.

Ajouter votre application en tant qu’espace de confiance (Trusted Workspace)

Pour tester votre plugin avant sa publication officielle, vous devez déclarer votre instance Crisp comme application de confiance. Cela permet au plugin de communiquer avec votre espace de travail sans être publié sur le Marketplace.

1. Allez dans les Settings de votre compte Marketplace Crisp.
2. Localisez la section Trusted Workspace.
3. Renseignez votre website_id (voir la méthode de récupération à l’Étape 2).

---

Étape 2 : Récupérer le website_id

Le website_id est l’identifiant unique de votre espace Crisp. Il est nécessaire dans tous les endpoints API qui accèdent à vos conversations et contacts.

Méthode 1 : Via le menu “Mise en place et intégrations”

1. Dans les paramètres Crisp, allez dans Paramètres, puis développez la section Espace de travail.
2. Cliquez sur le menu Mise en place et intégrations.
3. Votre identifiant (website_id) s’affiche en première position dans les informations de la page.

Méthode 2 : Via l’URL des paramètres

1. Dans les paramètres Crisp, allez dans Paramètres, puis développez la section Espace de travail.
2. Cliquez sur le menu Configuration avancée.
3. L’URL de votre navigateur contient alors votre identifiant unique : https://app.crisp.chat/settings/website/{website_id}/

---

Étape 3 : Sécuriser et transmettre les identifiants

Format de l’authentification Crisp

L’API Crisp utilise HTTP Basic Auth avec deux headers spécifiques :

Authorization: Basic base64(identifier:key)
X-Crisp-Tier: plugin

Pour construire le header Authorization :

# Construire la chaîne d'authentification
echo -n "VOTRE_IDENTIFIER:VOTRE_KEY" | base64

# Exemple d'appel curl
curl -X GET https://api.crisp.chat/v1/website/WEBSITE_ID/conversations/1 \
  -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \
  -H "X-Crisp-Tier: plugin"

Stockage en variables d’environnement

# .env.local (jamais versionné dans git)
CRISP_IDENTIFIER=votre_identifier_crisp
CRISP_KEY=votre_key_crisp
CRISP_WEBSITE_ID=votre_website_id

Utilisation dans le code Symfony :

public function __construct(
    #[Autowire(env: 'CRISP_IDENTIFIER')] private string $identifier
    #[Autowire(env: 'CRISP_KEY')] private string $key
) {
}

$credentials = base64_encode("{$this->identifier}:{$this->key}");

// Headers pour tous les appels API Crisp
$headers = [
    'Authorization' => "Basic {$credentials}",
    'X-Crisp-Tier' => 'plugin',
];

Transmission des identifiants

Pour transmettre les identifiants lors de l’intégration :

• Utiliser un gestionnaire de mots de passe partagé (Bitwarden, 1Password, Dashlane)
• Créer une note sécurisée avec : l’identifier, la key, le website_id et l’environnement
• Ne jamais envoyer par email, Slack ou messagerie en clair

---

Étape 4 : Activation du plugin

Une fois vos développements terminés, il est nécessaire d’activer votre plugin pour l’utiliser en production. Cette étape consiste à demander des jetons (tokens) de production à Crisp.

Demander un token de production

1. Allez dans l’onglet Tokens de votre plugin.
2. Cliquez sur le bouton “Ask a production token”.

Configuration des Scopes (Permissions)

Lors de cette étape, vous devrez définir les scopes (niveaux d’accès) de votre plugin.

• Principe du moindre privilège : Il est fortement conseillé de n’activer que les scopes strictement nécessaires au fonctionnement de votre application. Par exemple, si votre plugin ne fait que lire les informations des contacts, n’activez que le scope read, et non write.
• Modification ultérieure : Vous pouvez modifier ces scopes plus tard, mais sachez qu’une nouvelle vérification de la part de Crisp sera requise.

Installation finale

Une fois le plugin activé par Crisp, rendez-vous dans le tableau de bord de votre espace de travail, recherchez votre application dans le catalogue des plugins et cliquez sur Installer.

---

Vérifier l’accès

Avant de lancer les développements, vérifiez que les identifiants fonctionnent avec un appel de test sur votre website :

curl -X GET https://api.crisp.chat/v1/website/VOTRE_WEBSITE_ID \
  -H "Authorization: Basic VOTRE_BASE64_CREDENTIALS" \
  -H "X-Crisp-Tier: plugin"

La réponse doit retourner les informations de votre site web Crisp (nom, domaine, plan). Une erreur 403 indique un problème d’authentification : vérifiez que le base64 est correct (identifier:key, sans espace, sans retour à la ligne).

---

Configurer les webhooks Crisp

Si votre intégration utilise des webhooks (enrichissement de contact en temps réel, création de tickets depuis les conversations), configurez l’URL de votre endpoint dans les paramètres Crisp :

1. Dans les paramètres Crisp, allez dans Paramètres, puis développez la section Espace de travail.
2. Cliquez sur le menu Configuration avancée.
3. Ajouter un webhook depuis la section Web Hooks
4. Nom : Donnez un nom explicite à votre webhook pour l’identifier facilement.
5. Ajoutez l’URL de votre endpoint de traitement
6. Sélectionnez les événements à recevoir (session:created, message:send, etc.)

SmartBooster développe le handler de webhook avec vérification du secret et traitement asynchrone pour éviter les timeouts Crisp.

---

Références

• Documentation API Crisp - Quickstart
• Crisp - Authentification REST API
• Crisp - Webhooks