Using the JavaScript SDK
How to use the $crisp chatbox Javascript SDK
Learn how the $crisp chatbox SDK lets you control the Crisp chatbox from JavaScript. The $crisp SDK is included with the Crisp chatbox. You can use it to listen to chatbox events, open or hide the chatbox, set user data, send session data, and customize the visitor experience from your website code. What the Javascript SDK can do $crisp is available in pages where the Crisp chatbox is installed. It uses a queue-based syntax, which means you can safely push many cFew readersHow to automatically set users email addresses
Learn how to set an authenticated visitor email address from your website code. When your website already knows the visitor email, you can pass it to Crisp so the customer does not need to type it again before starting a conversation. Set the visitor email Use the $crisp JavaScript SDK after the Crisp chatbox snippet is available on the page. // Replace this value with the email from your own authenticated user data. $crisp.push(["set", "user:email", ["uPopularHow to automatically set users phone numbers
Learn how to set an authenticated visitor phone number from your website code. When your website already knows the visitor's phone number, you can pass it to Crisp so agents have the right contact details without asking the customer to type them again. Set the visitor phone number Use the $crisp JavaScript SDK after the Crisp chatbox snippet is available on the page. // Replace this value with the phone number from your own authenticated user data. $crisFew readersHow to persist a single chatbox conversation across different devices, browsers and apps
Learn how to restore the same Crisp chat session for authenticated users with a secure token. Session continuity lets logged-in users recover the same Crisp conversation even when they change browser, switch device, or clear cookies. It works by associating each authenticated user with a private token generated by your own backend. When to use session continuity Use session continuity when your application has a reliable internal identifier for the visitor and youFew readersHow to programmatically hide and show the chatbox
Learn how to hide or show the Crisp chatbox from your website JavaScript. You can control Crisp visibility when some pages should not display the chatbox, or when your own interface decides when support should appear. Hide the chatbox Use chat:hide to make the chatbox invisible on the current page. $crisp.push(["do", "chat:hide"]); This hides the chatbox but does not permanently change your global chatbox settings. ${color}[#0080dd](Show thePopularHow to replace the default chatbox button with a custom one
Learn how to open the Crisp chatbox from a custom button on your website. You can create your own Chat with us button and use the Crisp JavaScript SDK to open the chatbox when the visitor clicks it. Open the chatbox with JavaScript Use chat:open to open the Crisp chatbox. $crisp.push(["do", "chat:open"]); Attach it to a custom button The simplest implementation is to call the method from a click handler. <buttPopularHow to reset a Crisp conversation when users log out
Learn how to reset the Crisp chatbox session when an authenticated user logs out. If you set user identity or session continuity from your website, you should clear the Crisp session during logout. This avoids showing the next visitor the previous user context on shared devices or reused browser sessions. Reset the session Call the $crisp JavaScript SDK during your logout routine, after your own application has confirmed the user is logging out. $crisp.pFew readersHow to create conversation threads from the chatbox
Threads let you separate a specific support topic inside a larger conversation timeline when you control the website integration. This is useful when a customer may have several distinct issues over time and you want the timeline to show a clearer beginning and end for each one. Threads are started and ended from your website code through the Crisp JavaScript SDK. Understand what a thread is A thread is a labeled sequence of messages inside a conversation that relaFew readers
APIs & Webhooks
How to use the REST API
This article explains where to start when you want to use the Crisp REST API. The REST API lets developers read and write Crisp data from a backend, plugin, or internal integration. Use it when you need to send messages, retrieve conversations, update people profiles, manage plugin settings, or automate workspace operations. Before you start You will need API credentials and the right token type for your use case. Development tokens are useful for testing from a trFew readersHow to use the RTM API
This article explains when to use the Crisp RTM API for real-time integration events. The RTM API runs over WebSocket and lets integrations receive asynchronous events from Crisp. It is often used together with the REST API: REST performs actions, while RTM receives real-time events and acknowledgements. When to use the RTM API Use the RTM API when your integration needs a live event stream, such as receiving new messages, tracking asynchronous confirmations, or reFew readersHow to use Webhooks
This article explains how Web Hooks help you receive real-time Crisp events on your own endpoint. Web Hooks are useful when you want Crisp to notify another system whenever something happens in your workspace, for example when a visitor sends a message or a conversation changes. For developer-heavy integrations, start from the Developer Hub so you can pick the right hook type and event namespaces. How Crisp Web Hooks work Crisp sends Web Hooks as JSON payloadsFew readersHow to push user events from your backend
Learn how to add a people event to a Crisp profile from your backend. Crisp can receive custom events from the chatbox, but backend events are often better for server-side actions such as purchases, invoices, order updates, trial changes, or account milestones. Before you start Your backend must be able to authenticate with the Crisp REST API. Start with the REST API quickstart and keep your API credentials serFew readersHow to migrate to the new Knowledge Base API
On September 22, 2026, Crisp migrated all workspaces to a new Knowledge Base system with a new interface and a new API. All existing Knowledge Base content was automatically converted during this migration. Your articles remain available, but integrations must now use the new tree-based API to create or update them. The legacy article API no longer accepts write operations. Until your API calls are migrated, website_cannot_write_to_legacy_helpdesk errors are expected. Update your integratFew readersHow do Plugin permissions work
Learn what Crisp plugin permissions mean and how they help you understand what a plugin can access or modify. Plugins can extend Crisp with integrations, marketplace apps, and custom workflows. Some plugins need to read or write Crisp data to work properly, so permissions make the requested access visible before a plugin is installed.Few readersHow to build Crisp plugins
Learn where to start when you want to build a Crisp plugin or integration. Crisp plugins let developers extend Crisp apps, connect Crisp with external platforms, and build private or public integrations for their own workflows or for the Crisp Marketplace. What plugins can do Plugins are useful when a standard Crisp feature or native integration does not cover your use case. They can connect your own platform to Crisp, add new operator tools, receive Crisp events,Few readersHow to send messages from your backend
Learn how to send Crisp messages from your own backend using the REST API and RTM API together. Backend messaging is useful when you build bots, automations, or internal systems that need to reply inside Crisp conversations. In most cases, your backend listens to live events with the RTM API, then sends replies with the REST API. Before you start Your backend needs to be connected to the Crisp APIs before it can listen to messages or send replies. __You will need:Some readersHow to create Crisp conversations externally with the REST API
Learn how to send website form submissions into Crisp as conversations. Instead of routing contact form messages to a private email inbox, you can centralize them in Crisp so your team can reply, assign, and track them from the shared inbox. Before you start This integration is handled from your backend. Do not expose Crisp REST API credentials in frontend JavaScript or public form code. You will need: A Crisp API token with the permissions required for convFew readers
Monitoring & Tracking
How to push Crisp events to product analytics solutions (Mixpanel, Posthog, Amplitude...)
Learn how to forward Crisp chatbox events to product analytics tools such as PostHog, Mixpanel, or Amplitude. Chat activity is a useful product signal. By listening to $crisp events from your website, you can measure how conversations relate to activation, conversion, retention, or support volume in your analytics stack. Before you start The examples below track the first visitor message in a browser tab and send it as a product analytics event. This is a pFew readersHow to use Google Tag Manager to track Crisp events in Google Analytics 4
Learn how to track Crisp chatbox events in Google Analytics 4 using Google Tag Manager. By combining $crisp event listeners with Google Tag Manager and GA4 events, you can measure how visitors interact with the chatbox and use that data in your analytics reports. In this guide, you will configure: Requirements → what needs to be ready before you start Set up GA4 tracking with Google Tag Manager → connectFew readersHow to track UTM sources with the Crisp chatbox
Learn how to capture UTM parameters and save them on the current Crisp session. UTM parameters help you understand which campaign, channel, or source brought a visitor to your website. With a small JavaScript snippet, you can attach those values to the Crisp customer profile so your team sees campaign context directly in the conversation. How UTM tracking works UTM parameters are URL parameters commonly used by marketing teams to measure campaign performance acrossFew readersHow to push conversions to Google Ads with Google Tag Manager
Learn how to send a Crisp chat interaction to Google Ads as a conversion through Google Tag Manager. This guide shows one common setup: listening for a Crisp chatbox event, pushing a custom event to the GTM data layer, then using that event to trigger a Google Ads conversion tag. Before you start You need access to Google Tag Manager and Google Ads before configuring this conversion flow. You will need: A Google Tag Manager container installed on your weFew readersHow to send events from Crisp to Facebook Pixel
Learn how to send Crisp chatbox events to Meta Pixel from your website JavaScript. Meta Pixel, formerly known as Facebook Pixel, can receive custom events from Crisp when visitors interact with the chatbox. This helps marketing and sales teams measure how live chat interactions relate to campaigns, leads, and conversions. Before you start Make sure the Meta Pixel base code is already installed on your website and that the fbq function is available before theFew readersHow to set Google Ads (Adwords) data on Crisp users profile
Learn how to store Google Ads attribution data on Crisp sessions and trigger a conversion from chat activity. If a visitor lands on your website with a GCLID parameter, you can mark the Crisp session as coming from Google Ads, then fire a Google Ads conversion when that visitor starts a relevant chat interaction. Before you start This example uses the $crisp JavaScript SDK and the Google Ads gtag conversion call. You should adapt the conversion rule to yoFew readers
Technical Use-cases
How to create an AI chatbot with Dialogflow
Learn how to connect Dialogflow with Crisp to build a custom AI chatbot integration. This guide is intended for teams that want to maintain their own Dialogflow-based bot and connect it to Crisp through the Crisp APIs. If you want a native Crisp AI support agent instead, start with Hugo. Before you start Dialogflow is a Google platform for building conversational agents. In this setup, Dialogflow handles intent detection, while Crisp reSome readersHow to display the Crisp chatbox situationally with Google Tag Manager data layers
Learn how to use Google Tag Manager Data Layer values to adapt when the Crisp chatbox appears. When your website already exposes plan, pricing, account, or lifecycle data through the Data Layer, Google Tag Manager can use that context to decide which visitors should see Crisp or which custom script should run. Before you start This setup is useful when your website already knows who the visitor is, for example an authenticated user with a plan, role, lifecycleFew readersHow to split incoming conversations into multiple workspaces
Use multiple Website IDs only when you need truly separate chatboxes on different parts of your site. If your goal is simply to separate teams inside one workspace, sub-inboxes are usually the better option. This guide covers the more advanced setup: showing different Crisp chatboxes on different website sections by loading a different Website ID depending on the current page. Before using this approach, consider [sub-inboxes](https://help.crisp.chat/en/article/how-can-i-create-sub-inboxeFew readersHow to whitelist Crisp servers
Learn what to whitelist when Crisp needs to run behind strict network, firewall, or CSP rules. Most companies do not need to whitelist Crisp manually. If your organization uses strict outbound filtering, bot protection, proxy rules, or a Content Security Policy, your IT team may need to allow Crisp domains, user agents, and sometimes server IP ranges. What to whitelist Start with the resource that matches your restriction, then keep the Developer Hub as the souFew readers