Search Results for 'wordpress'
Found 143 results
How to send additional user information to Chatwoot using SDK?
The Chatwoot website SDK enables you to send additional user information to Chatwoot. If you have installed our code on your website, the SDK would expose window.$chatwoot object. To make sure that the SDK has been loaded completely, please make sure that you listen to chatwoot:ready event as follows: window.addEventListener("chatwoot:ready", function () { // Use window.$chatwoot here // ... }); If you would like to listen to the messages in the widget you can use the following event. window.addEventListener('chatwoot:on-message', function(e) { console.log('chatwoot:on-message', e.detail) }) SDK settings​ To hide the bubble, you can use the setting mentioned below. Note: If you use this, you must also trigger the widget. window.chatwootSettings = { hideMessageBubble: false, showUnreadMessagesDialog: false, // Disable the unread message dialog position: "left", // This can be left or right locale: "en", // Language to be set useBrowserLanguage: false, // Set widget language from user's browser type: "standard", // [standard, expanded_bubble] darkMode: "auto", // [light, auto] // baseDomain: "yourdomain.com" // configure if you want to track users across subdomains }; Use browser language in your live chat widget automatically To show the live chat widget in the user's browser locale, set the useBrowserLanguage to true in the window.chatwootSettings mentioned above. Note: If useBrowserLanguage is set to true, The locale mentioned will be ignored. If the browser language is not supported by chatwoot, the locale mentioned under locale will be used. If that's also missing, the widget will fall back to the locale of the agent dashboard. Dark Mode​ Chatwoot live-chat widget supports dark mode v2.4.0 onwards. To enable the dark mode, follow the steps mentioned here. Widget designs​ Chatwoot supports two designs for the widget. 1. Standard (default) 2. Expanded bubble If you are using expanded bubble, you can customize the text used in the bubble by setting launcherTitle parameter on chatwootSettings as described below. window.chatwootSettings = { type: "expanded_bubble", launcherTitle: "Chat with us", }; Enable popout window​ In order to enable the popout window, add the following configuration to chatwootSettings. This option is disabled by default. window.chatwootSettings = { // ...Other Config showPopoutButton: true, } You can also popout the chat window programatically with the `popoutChatWindow()` method. Custom messages​ Customize the welcome and availability messages shown in the widget header and team status indicators. window.chatwootSettings = { // ...Other Config welcomeTitle: "Need help?", // Custom widget header welcomeDescription: "We’re here to support you.", // Header subtitle availableMessage: "We’re online and ready to chat!", // When team is online unavailableMessage: "We’re currently offline." // When team is unavailable }; Feature toggles Enable or disable optional UI features inside the widget: window.chatwootSettings = { // ...Other Config enableFileUpload: true, // Show file attachment button enableEmojiPicker: true, // Enable emoji picker in the chat input enableEndConversation: true // Let users end the conversation }; Programatically open the popout window​ You can open the popout window programatically with the popoutChatWindow() method. To initiate this, call the method like below. window.$chatwoot.popoutChatWindow(); Toggle the widget bubble visibility​ If you want to hide/show the Chatwoot widget bubble, you can do so with toggleBubbleVisibility('show/hide') Example window.$chatwoot.toggleBubbleVisibility("show"); // to display the bubble window.$chatwoot.toggleBubbleVisibility("hide"); // to hide the bubble Trigger widget programmatically If you want to open the chat window by clicking a link on the website, follow the method below. In your action, call the Chatwoot SDK as described below. window.$chatwoot.toggle(); // Toggle widget by passing state window.$chatwoot.toggle("open"); // To open widget window.$chatwoot.toggle("close"); // To close widget Set the user in the widget​ window.$chatwoot.setUser("<unique-identifier-key-of-the-user>", { email: "<email-address-of-the-user@your-domain.com>", name: "<name-of-the-user>", avatar_url: "<avatar-url-of-the-user>", phone_number: "<phone-number-of-the-user>", }); setUser accepts an identifier which can be a user_id in your database or any unique parameter which represents a user. You can pass email, name, avatar_url, phone_number as params. Support for additional parameters is in progress. Ensure you reset the session when the user logs out of your app. Identity validation using HMAC​ To disallow impersonation and to keep the conversation with your customers private, we recommend setting up the identity validation in Chatwoot. Identity validation is enabled by generating an HMAC(hash based message authentication code) based on the identifier attribute, using SHA256. Along with the identifier you can pass identifier_hash also as shown below to make sure that the user is correct one. window.$chatwoot.setUser(`<unique-identifier-key-of-the-user>`, { name: "", // Name of the user avatar_url: "", // Avatar URL email: "", // Email of the user identifier_hash: "", // Identifier Hash generated based on the webwidget hmac_token phone_number: "", // Phone Number of the user description: "", // description about the user country_code: "", // Two letter country code city: "", // City of the user company_name: "", // company name social_profiles: { twitter: "", // Twitter user name linkedin: "", // LinkedIn user name facebook: "", // Facebook user name github: "", // Github user name }, }); To generate HMAC, read identity validation. Note that implementing HMAC authentication will allow chat history to persist across sessions. Set custom attributes​ To set additional information about the customer, you can use customer custom attributes field. Read more about custom attributes here. To set a custom attribute, call setCustomAttributes as follows window.$chatwoot.setCustomAttributes({ accountId: 1, pricingPlan: "paid", // Here the key which is already defined in custom attribute // Value should be based on type (Currently support Number, Date, String and Number) }); You can view these information in the sidepanel of a conversation. To delete a custom attribute, use deleteCustomAttribute as follows window.$chatwoot.deleteCustomAttribute("attribute-key"); Set language manually​ window.$chatwoot.setLocale("en"); To set the language manually, use the setLocale function. Set labels on the conversation​ Please note that the labels will be set on a conversation if the user has not started a conversation. In that case, the following items will not have any effect: window.$chatwoot.setLabel("support-ticket"); window.$chatwoot.removeLabel("support-ticket"); Refresh the session (use this while you logout the user from your app)​ window.$chatwoot.reset(); Widget errors​ To see any errors in the widget, please make sure that you listen to chatwoot:event event as follows: window.addEventListener("chatwoot:error", function () { // ... }); Note: This feature is available in v2.3.0 and later. Customize the welcome header, description You can change: - The welcome title and description - Messages shown when your team is online or offline - Selectively enable UI features like file upload, emoji picker, and end conversation button window.chatwootSettings = { welcomeTitle: 'Need help?', welcomeDescription: 'We’re here to support you.', availableMessage: 'We’re online and ready to chat!', unavailableMessage: 'We’re currently offline.', enableFileUpload: true, enableEmojiPicker: true, enableEndConversation: true };
đź‘ť Setup accountUpdating your Account settings
The Account Settings page is where an administrator sets top-level details about the Chatwoot account itself — its name, default language etc. Where to find it: Settings → Account Settings. The page header reads "Account settings". Who can access it: administrators only. Regular agents and custom roles cannot view or edit this page. General settings All fields are saved together using the Update settings button at the bottom. Field Required Description Account name Yes Display name for the account, shown in account switchers and on email transcripts. Site language Yes Default UI language for the dashboard. Individual users can override this in Profile Settings. Transcribe Audio Messages When enabled, Chatwoot automatically generates a text transcript whenever an audio message is sent or received in a conversation, and shows it inline alongside the audio. This section only appears when Captain is enabled on your account. Saving is automatic on toggle. Account ID A read-only display of your account's unique numeric ID, shown in a copyable code block. You'll need it whenever you build an integration against the Chatwoot Application API. Click the code to copy. Delete your Account Only displayed on Chatwoot Cloud installations. Clicking Delete Your Account opens a confirmation modal. To confirm, type the account's exact name into the field and click Delete. The account is then marked for deletion at a future scheduled date — not removed immediately. If the account is already marked for deletion, this section instead shows a red banner with the deletion date and a Cancel Scheduled Deletion button. Two banner variants exist: - "This account is scheduled for deletion on {date}. This was requested by an administrator." — manual deletion - "This account is scheduled for deletion on {date} due to account inactivity." — inactivity-based deletion Cancelling reverts the deletion as long as the scheduled date hasn't passed. Build info A small footer at the bottom of the page showing: - The current Chatwoot version (e.g. v3.16.0) - The Git build identifier, clickable to copy the full value If a newer version is available, an additional line appears above on self-hosted installations: "An update {version} for Chatwoot is available. Please update your instance." Useful for support tickets — paste the version and build identifier when reporting an issue.
WhatsappChoose how to connect WhatsApp
Which method is right for you? Your situation Use You are connecting a new number on Chatwoot Cloud, or on a self-hosted installation that has Quick setup configured Quick setup with Meta Your number is in the WhatsApp Business app and you want to keep using the app on your phone Quick setup with Meta and choose to connect your existing app. This is called Coexistence. Your number is already on the WhatsApp Business Platform (API) , you are a tech provider onboarding your own number, or you are self-hosted without Quick setup configured Manual setup You already send SMS or WhatsApp through Twilio and want to keep billing there Twilio . Note that campaigns and calling are not available with Twilio. Not sure which features you need? Check Your connection method decides what you can use in WhatsApp in Chatwoot. Before you start (all methods) - You are an administrator in Chatwoot. - For WhatsApp Cloud API: you can sign in to Facebook with an account that is an admin of the Meta business portfolio that owns (or will own) the WhatsApp Business Account. - Your number can receive a verification SMS or voice call. Landlines need voice verification. Numbers that answer with an automated phone menu (IVR) are not supported by Meta. - You have your business details ready, and a display name that follows Meta's display name guidelines. See Display name in Manage your WhatsApp number. Can I switch methods later? - Quick setup to manual setup: possible in some cases, without losing conversations. Chatwoot support checks eligibility first, and it is not available for numbers using Coexistence (the WhatsApp Business app). See Move a Quick setup inbox to manual setup. - Manual setup to Quick setup: not available from the dashboard. - Between Twilio and WhatsApp Cloud API: this means creating a new inbox. Conversations stay in the old inbox. Start Go to Settings › Inboxes › Add Inbox › WhatsApp. You will see two choices: - WhatsApp Cloud: Quick setup with Meta (or manual setup, via the link at the bottom of that screen) - Twilio
🔎 Advanced features explainedHow to use Campaigns?
The Campaigns feature is a way for you to send outbound messages to your customers. There are two types of campaigns in Chatwoot: I. Ongoing campaigns You can use ongoing campaigns to send frequent outbound messages via website live chat. You can set specific conditions that trigger these messages, like when a user spends a certain amount of time on a specific page. By sending these messages, you can increase the likelihood of conversions and keep the conversation flowing with your prospects. II. One-off campaigns You can use one-off campaigns to send an SMS campaign to a group of contacts. This is an effective way to reach many customers at once and make announcements or promote your products/services or specific offers. How to create an Ongoing Campaign? Step 1. Click on the "Campaigns" tab in the sidebar. Select "Ongoing" -> "Create an ongoing campaign" button. Step 2. You will see a modal where you can input the campaign details. Here is an example of creating a campaign for the Pricing page: The fields seen in the form are explained below. 1. Title Name your campaign for internal reference. 2. Message Type your outbound message. This is precisely what your customers will see when the campaign is triggered. 3. Select Inbox Select your website inbox from the dropdown. 4. Sent by You can send your outbound messages either by a bot or an agent. Make your pick. 5. URL Enter the URL of the page where this campaign should be triggered. Imp: You can also enter wildcard URLs to run the campaign on subdomains or sub-directories. See this guide to learn more about building a wildcard pattern. 6. Time on page (seconds) How many seconds should the visitor spend on the given URL before triggering the campaign? 7. Enable campaign The flag shows whether the campaign is enabled or not. Step 3. Test it out. Visit the URL specified in the campaign and wait for the time configured in the campaign. How to create a One-off Campaign? Step 1. Click on the "Campaigns" tab in the sidebar. Select "One off" -> "Create a one off campaign" button. Step 2. You will see a modal where you can input the campaign details. The fields seen in the form are explained below. 1. Title Name your campaign for internal reference. 2. Message Type your SMS message to be sent to the customers. 3. Select Inbox Select your SMS inbox from the dropdown. 4. Audience You can send this campaign to your contacts grouped under a specific label. 5. Scheduled time Set a Campaign execution time. Once you have filled out the fields, click the "Create" button. It will appear on your One-off campaigns page. How to edit or delete campaigns? To edit or delete campaigns, open the list of campaigns by visiting "Campaigns" -> Selecting the campaign type. Scroll laterally to find the edit and delete options.
🔥 CaptainHow to auto-translate messages in a conversation?
Auto-translate lets your team support customers in any language. Customer messages appear in your language, and your replies reach the customer in theirs, automatically. This article shows you how to turn it on and how to work with translated conversations. Before you begin - Auto-translate is available on all paid plans on both self-hosted and Chatwoot Cloud. - You need to be an administrator to turn it on. - Messages are translated into the language your Chatwoot dashboard is set to. Each agent can change this under Profile Settings → Preferred Language. If an agent hasn't picked one, the account's default language is used. Step 1: Turn on Auto-translate 1. Go to Settings → Conversation Workflows. 2. In the Translation section, choose a translation service: - Captain: AI translations that sound natural and keep your tone. - Google Translate: quick, reliable translations from Google. If it shows Not connected, click Connect and follow the steps first. 3. Turn on the Auto-translate conversations toggle. Settings → Conversation Workflows → Translation That's it. Auto-translate now works in every conversation in your account. Agents don't need to set anything up. Step 2: Read customer messages in your language Open any conversation. When a customer writes in another language, their message appears already translated, with a View original link underneath that names the language they wrote in. In the example below, Sophie writes in French and the agent reads her messages in English. Sophie's French messages appear in English. The agent's English reply is sent to her in French. Step 3: Reply in your own language Type your reply in your own language and send it as usual. Chatwoot translates it into the customer's language before it reaches them. A View translated link appears under your reply. Step 4: Check the original or translated text You can always see exactly what was written or sent: - On a customer message, click View original to see their exact words. - On your reply, click View translated to see the version the customer received. - Click the link again to switch back. Sophie's original French message, and the French version of the agent's reply What you'll see on messages What you see What it means Purple shimmering text with Translating… A customer message is being translated into your language. This usually takes a second or two. Purple shimmering text with Translating to French… Your reply is being translated into the customer's language before it's delivered. View original (French) The customer's message was translated. Click to see what they wrote. View translated (French) Your reply was translated. Click to see what the customer received. Could not translate A customer message couldn't be translated and is shown as they wrote it. Could not translate, sent as typed Your reply couldn't be translated, so the customer received your original text. A new customer message is being translated into English Sophie's English message shows no translation line. The agent's latest reply is being translated to French. Frequently asked questions How does Chatwoot know which language to reply in? Chatwoot detects the language the customer is writing in and translates your replies into that language. What happens if the customer switches to my language? Their messages appear exactly as written, with nothing extra underneath. Your replies follow whatever language the customer is using in the conversation. Are private notes translated? No. Only messages the customer can see are translated. Private notes stay exactly as you wrote them. Do I still need the Translate option in the message menu? No. With Auto-translate on, messages are translated for you, so the manual Translate option is hidden for those messages. Can I switch between Captain and Google Translate? Yes. Go back to Settings → Conversation Workflows and pick the other service. New messages use the service you choose.
WhatsappWhatsApp campaigns
Send one approved template to every contact with the labels you choose, at a scheduled time, and see who received and read it. Plan & access - Chatwoot Cloud: WhatsApp campaigns are available on the Business plan and above. They are on automatically; you do not need to request them. - Self-hosted: sending campaigns is not a premium feature. It works on Community Edition and is on by default. - Campaign analytics: Business plan and above on Cloud. On self-hosted, it needs a paid self-hosted plan. Your installation's super admin turns on Campaign Analytics in Super Admin › Accounts › open the account › Edit, under Premium features, then clicks Save changes. - Inbox: WhatsApp Cloud API only (Quick setup or manual). Twilio and 360dialog inboxes cannot send campaigns. - Who: administrators. See Pricing & Plans. How to check you have it: open Campaigns in the sidebar. If WhatsApp appears under it, campaigns are available for your account. Before you start - At least one approved template in your WhatsApp Cloud API inbox. See Templates and the 24-hour window. - The contacts you want to reach have a label, and either a phone number or a WhatsApp Business-Scoped User ID (BSUID) from an earlier conversation in this inbox. See How to add labels?, contact filters and segments, and WhatsApp usernames and Business-Scoped User IDs. - Every contact you send to has opted in to receive WhatsApp messages from your business. See Meta's opt-in rules. Create a campaign 1. Go to Campaigns › WhatsApp and click Create campaign. 2. Basic settings: enter a Title and pick your WhatsApp Inbox. The Account information panel shows the number's messaging tier, account status and quality rating from Meta. 3. Audience: choose one or more Labels. Contacts with any of the labels are included. Click View to see exactly who is included. The panel shows how many customers your WhatsApp account can message. Labels only select who receives the campaign. They do not record consent, so add only contacts who have opted in. 4. Template: pick an approved template and fill in its header, variables and buttons. Check the Message preview. 5. Click Schedule campaign, pick a time and click Create. Test it: send the first campaign to a test label that contains only your own number. The Live test button at the top of the form is not available (its tooltip reads Live test will be available soon). What to expect - The campaign sends once, at the scheduled time. Its status moves from Scheduled to Processing to Completed. - You can edit it while it is Scheduled. Once it starts sending, it cannot be changed. - Chatwoot sends to the contact's phone number. If the contact has no phone number, it sends to the contact's BSUID for this inbox instead. A contact is skipped when: - it has neither a phone number nor a BSUID for this inbox - it has no phone number and more than one BSUID for this inbox (Chatwoot does not choose between them) - it has only a BSUID and the template is an Authentication template, or Chatwoot cannot find the template among the inbox's synced templates to check its category (authentication templates need a phone number) - the template variables cannot be filled in for that contact - Only approved templates can be sent. Free-text broadcasts are not possible on WhatsApp. - Meta charges for template messages, including every campaign message delivered. The rate depends on the template category and the recipient's country. Meta bills these charges to your WhatsApp Business account, separately from your Chatwoot subscription. Estimate costs with the WhatsApp pricing calculator and see Meta's current pricing. - How many customers you can message in a day is set by Meta's messaging limit, shared across all numbers in your business portfolio. See Manage your WhatsApp number. - When customers reply, a new conversation opens in the inbox and the 24-hour window starts. - Campaign messages sent to a contact appear in their WhatsApp conversation, marked Campaign. See results Analytics is available on the Business plan and above on Chatwoot Cloud, or a paid self-hosted plan. Click View analytics on the campaign to see: - Audience, Submitted to WhatsApp, Delivered, Read, Failed and Skipped - The Deliveries table: each contact's status and, for failures and skips, the Reason. Filter it by status. - While a campaign is still sending, the numbers are partial. Analytics may be unavailable for campaigns sent before delivery tracking was introduced. Good practice - Create a dedicated label for each campaign instead of reusing a broad one. - Use Utility templates for updates and Marketing templates only for contacts who opted in. - Watch your quality rating after each campaign. Many blocks or reports can lower your messaging limit. Troubleshoot Symptom Likely cause What to do No WhatsApp under Campaigns Your plan does not include campaigns, or you are not an administrator On Chatwoot Cloud, check you are on the Business plan or above. Check you are signed in as an administrator. If both are true and the tab is still missing, contact Chatwoot support. My inbox is not in the list It is a Twilio or 360dialog inbox Campaigns need a WhatsApp Cloud API inbox. See Choose how to connect WhatsApp This inbox has no approved templates that can be used in a campaign No approved templates, or they have not synced Click Sync Templates . See Templates and the 24-hour window Some contacts did not receive it No phone number or BSUID, missing label, or Meta rejected the message Open View analytics , filter by Failed or Skipped , and read the reason. For error codes, see Troubleshoot WhatsApp . I cannot edit the campaign It has already started sending Create a new campaign.
🔎 Advanced features explainedSetting per-agent conversation caps with Agent Capacity Policies
An Agent Capacity Policy is a bundle of rules that caps how many open conversations a single agent can hold at a time. It's how you stop one agent from drowning while another sits idle, and how you keep auto-assignment fair when conversation volumes spike. When auto-assignment looks for an eligible agent, it checks each candidate's capacity policy (if they have one) before assigning. Agents at or over their cap are skipped; the next eligible agent under cap is assigned instead. A policy has: - A name (required) - An optional description - A set of per-inbox capacity limits — different caps per inbox if you want - Optional exclusion rules — labels and conversation age that should be ignored when counting open conversations Permissions: only administrators can create, edit, or delete capacity policies, and only admins can attach them to agents. Managing capacity policies How to create a capacity policy? 1. Go to Settings → Agent Capacity and click Create agent capacity policy. 2. Fill in: - Policy name — required, max 255 characters. - Description — optional. - Inbox capacity limits — for each inbox you want to cap, set a maximum number of open conversations an agent under this policy can hold on that inbox. - Exclusion rules (optional): - Excluded labels — conversations with these labels don't count toward the cap. - Exclude older than — conversations older than N hours don't count toward the cap. 3. Add the agents who should be governed by this policy under Assigned agents. 4. Save. How to edit a capacity policy? 1. Go to Settings → Agent Capacity and open the policy. 2. Change the limits, exclusions, or assigned agents. 3. Save. Delete a capacity policy Deleting a policy unassigns it from every agent. The agents revert to having no cap and become eligible for unrestricted auto-assignment. How exclusion rules work The point of exclusions is to make caps measure real, active workload — not just any open conversation that happens to still exist. Excluded labels Add labels like waiting-on-customer or parked to the exclusion list. Conversations with those labels still belong to the agent but don't count toward the cap. So if your cap is 10 and an agent has 7 active + 5 waiting-on-customer, they still have capacity for 3 new ones. Age exclusion Set "exclude older than 24 hours" and conversations created more than a day ago drop out of the count. Useful for long-running conversations (e.g. multi-day enterprise tickets) that you don't want monopolizing an agent's capacity number. Tip: start with a generous cap and no exclusions. Add exclusions only when you can point to a specific kind of conversation that's distorting the count. How to attach a policy to an agent? You can attach the policy when creating it (under Assigned agents in the policy form) or after the fact: 1. Open the policy. 2. Click Add agent. 3. Pick the agents you want under this policy. Multiple agents can share one policy. A given agent can be on at most one capacity policy at a time. Assigning a new policy replaces any prior one. How auto-assignment uses capacity? When a new conversation arrives in an inbox with auto-assignment enabled: 1. Chatwoot finds eligible agents (inbox members, available status). 2. For each candidate with a capacity policy, count their currently-open conversations on that inbox, applying exclusion rules. 3. Filter out agents at or over their cap. 4. Pick the next eligible agent using the configured assignment strategy (Round Robin or Balanced). If no agent is under cap, the conversation stays unassigned in the queue until somebody's count drops or capacity frees up. Capacity is per inbox. An agent can be at cap on Inbox A while still having capacity on Inbox B — they'll be skipped for A but eligible for B. A practical example A 12-agent support team has these inboxes: - Website — high volume, short conversations - Email — lower volume, longer conversations You create two capacity policies: Policy Website cap Email cap Standard agent 10 5 Senior agent 15 8 Junior agents go on Standard; senior agents on Senior. Add exclusion: waiting-on-customer (so parked conversations don't count). Add age exclusion: 48 hours (so a week-old enterprise email isn't blocking an agent's slot). The result: traffic gets distributed without any single agent being overwhelmed, and the senior team takes a heavier share without manual intervention. Frequently asked questions What happens to a conversation that's already assigned when an agent hits their cap? Nothing. Caps only affect new auto-assignments. Existing assignments stay put. Can an agent reassign a conversation away to free up capacity? Yes — manual reassignment works as normal. If you reassign a conversation to a teammate, your open count drops by one and the next inbound auto-assignment can target you again. What if every agent is at cap? The conversation stays unassigned in the queue until somebody's count drops (a conversation gets resolved, snoozed, or reassigned). Pair this with monitoring of unassigned-queue length — if it grows, you need either more headcount or a higher cap. Can I set per-team capacity? Capacity is configured per agent, not per team. To approximate team capacity, attach the same capacity policy to every agent on the team. Are exclusions applied at the agent level or the policy level? Policy level. All agents on a given policy share the same exclusion rules.
🔎 Advanced features explainedHow to setup a WebSocket connection?
WebSockets establish a continuous connection between the client and server, enabling bi-directional communication. Chatwoot utilizes this connection to provide real-time updates about platform events. To connect to the Chatwoot WebSocket, simply provide a token and follow the setup instructions outlined in this guide. Note: This feature is experimental, and the documentation may change with each release. Additionally, backward compatibility cannot be guaranteed, so it is important to ensure you are using the latest version of the implementation. Why should I use a WebSocket connection? A WebSocket connection allows for real-time data updates, making it ideal for clients such as an Android or iOS client SDK for Chatwoot. This helps update the dashboard without the need to reload the page. Hence, it can enhance the user experience and improve an agent's productivity. How to set up a WebSocket connection with Chatwoot? To set up a WebSocket connection with Chatwoot, you need to initiate a connection with the authentication PubSub token provided by Chatwoot. The URL for the connection is wss://<your-installation-url>/cable. If you are using Chatwoot Cloud, you can use wss://app.chatwoot.com/cable as the URL. A PubSub token is a token that is used to authenticate a client when connecting to a PubSub (publish-subscribe) service. The client must present this token to the service in order to establish a connection and begin publishing or subscribing to messages. There are two types of PubSub tokens available in Chatwoot, as listed below. 1. User PubSub Token: This token has the privileges of an agent/admin and would receive all of the events listed later on the page. You can get the PubSub token by calling the Profile API. 2. Contact PubSub Token: Chatwoot generates a unique PubSub token for each session a contact has. This token can be used to connect to the WebSocket and receive real-time updates for the same session. When a contact is created through the public APIs, the pubsub_token is included in the response payload. This token only grants access to events related to the current session, such as conversation.created,  conversation.status_changed, message.created, message.updated, conversation_typing_on, conversation_typing_off and presence.update. Please refer Client APIs to build real time customer facing integrations using Chatwoot. Note: This token may be rotated regularly based on your installation type. Please ensure that you are using the latest token. How to connect to Chatwoot WebSocket? To connect to the Chatwoot WebSocket, use the command subscribe and include your pubSubToken, accountId, and userId (if using a user token) in the connection request. Here is an example of how you can connect with Chatwoot. // Add a helper method to convert JSON to a string const stringify = (payload = {}) => JSON.stringify(payload); const pubSubToken = "<contact/user-pub-sub-token>"; const accountId = "<your-account-id-in-integer>"; const userId = "<user-id-in-integer-if-using-user-token>"; const connection = new WebSocket( "wss://app.chatwoot.com/cable" ); connection.send( stringify({ command: "subscribe", identifier: stringify({ channel: "RoomChannel", pubsub_token: pubSubToken, account_id: accountId, user_id: userId, }), }) ); // The expected string in connection.send is of the format: // {"command":"subscribe","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer }"} Publishing presence to the WebSocket server To keep your users’ status online in Chatwoot, you can send a presence update event to Chatwoot every 30 seconds. This action would keep the status of the agent/contact online. How to update the presence of an agent/admin? To update the presence of an agent or admin, send the following payload to the server: const userPayload = stringify({ command: "message", identifier: stringify({ channel: "RoomChannel", pubsub_token: "<user-pubsub-token>", account_id: accountId, user_id: userId, }), data: stringify({ action: "update_presence" }), }); connection.send(userPayload); // The expected string in connection.send is of the format: // {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer ","data":"{\\"action\\":\\"update_presence\\"}"} How to update the presence of a contact? To update the presence of a contact, send the following payload to the server: const agentPayload = stringify({ command: "message", identifier: stringify({ channel: "RoomChannel", pubsub_token: "<user-pubsub-token>", }), data: stringify({ action: "update_presence" }), }); connection.send(agentPayload); // The expected string in connection.send is of the format: // {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\","data":"{\\"action\\":\\"update_presence\\"}"} WebSocket Payload Objects An event can contain any of the following objects as payload. Different types of objects supported in Chatwoot are as follows. Conversation The following payload will be returned for a conversation. { "additional_attributes": { "browser": { "device_name": "string", "browser_name": "string", "platform_name": "string", "browser_version": "string", "platform_version": "string" }, "referer": "string", "initiated_at": { "timestamp": "iso-datetime" } }, "can_reply": "boolean", "channel": "string", "id": "integer", "inbox_id": "integer", "contact_inbox": { "id": "integer", "contact_id": "integer", "inbox_id": "integer", "source_id": "string", "created_at": "datetime", "updated_at": "datetime", "hmac_verified": "boolean" }, "messages": ["Array of message objects"], "meta": { "sender": { // Contact Object }, "assignee": { // User Object } }, "status": "string", "unread_count": "integer", "agent_last_seen_at": "unix-timestamp", "contact_last_seen_at": "unix-timestamp", "timestamp": "unix-timestamp", "account_id": "integer" } Contact The following payload will be returned for a contact. { "additional_attributes": "object", "custom_attributes": "object", "email": "string", "id": "integer", "identifier": "string or null", "name": "string", "phone_number": "string or null", "thumbnail": "string" } User The following payload will be returned for an agent/admin. { "id": "integer", "name": "string", "available_name": "string", "avatar_url": "string", "availability_status": "string", "thumbnail": "string" } Message The following payload will be returned for a message. { "id": "integer", "content": "string", "account_id": "integer", "inbox_id": "integer", "message_type": "integer", "created_at": "unix-timestamp", "updated_at": "datetime", "private": "boolean", "status": "string", "source_id": "string / null", "content_type": "string", "content_attributes": "object", "sender_type": "string", "sender_id": "integer", "external_source_ids": "object", "sender": { "type": "string - contact/user" // User or Contact Object } } Notification The following payload will be returned for a notification. { "id": "integer", "notification_type": "string", "primary_actor_type": "string", "primary_actor_id": "integer", "primary_actor": { "can_reply": "boolean", "channel": "string", "id": "integer", "inbox_id": "integer", "meta": { "assignee": { "id": "integer", "name": "string", "available_name": "string", "avatar_url": "string", "type": "user", "availability_status": "string", "thumbnail": "string" }, "hmac_verified": "boolean" }, "agent_last_seen_at": "unix-timestamp", "contact_last_seen_at": "unix-timestamp", "timestamp": "unix-timestamp", }, "read_at": "unix-timestamp", "secondary_actor": "object/null", "created_at":"unix-timestamp", "account_id": "integer", "push_message_title": "string" } Identifier Each event will have an identifier attribute in the following format. { "identifier": "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"token\\",\\"account_id\\":id,\\"user_id\\":user_id}" } Message Each event will include a message attribute which we return the event name as well as the data associated with it. To see the list of events, refer the documentation below. Types of Events conversation.created This event is triggered when a new conversation is initiated. If subscribing to the contact's PubSub token, this event will only include data related to the specific session associated with the PubSub token. Available to: agent/admin, contact { "message": { "event": "conversation.created", "data": { // Conversation object will be available here } } } conversation.read This event is triggered and sent to the agents/admins who have access to the inbox, when a contact has read a message. Available to: agent/admin { "message": { "event": "conversation.read", "data": { // Conversation object will be available here } } } message.created This event is triggered and sent to the agents, admins, contacts when a new message is created in a conversation they have access to. Available to: agent/admin, contact { "message": { "event": "message.created", "data": { // Message object will be available here } } } message.updated This event is triggered and sent to the agents, admins, contacts when a message is updated in a conversation they have access to. Available to: agent/admin, contact { "message": { "event": "message.updated", "data": { // Message object will be available here } } } conversation.status_changed This event is sent to the agents, admins, contacts when a conversation status is updated. Available to: agent/admin, contact { "message": { "event": "conversation.status_changed", "data": { // Conversation object will be available here } } } conversation.typing_on This event is sent to the agents, admins, contacts when a contact or an agent starts typing a response. Available to: agent/admin, contact { "message": { "event": "conversation.typing_on", "data": { "conversation": { // Conversation object will be available here }, "user": { // Contact / Agent,Admin User object will be available here. }, "is_private": "boolean", // Shows whether the agent is typing a private note or not. "account_id": "integer" } } } conversation.typing_off This event is sent to the agents, admins, contacts when a contact or an agent ends typing a response. Available to: agent/admin, contact { "message": { "event": "conversation.typing_off", "data": { "conversation": { // Conversation object will be available here }, "user": { // Contact / User object will be available here. }, "account_id": "integer" } } } assignee.changed This event is sent to the agents/admins with access to an inbox when the assigned agent is changed. Available to: agent/admin { "message": { "event": "assignee.changed", "data": { // Conversation object will be available here } } } team.changed This event is sent to the agents/admins with access to an inbox when the assigned team is changed. Available to: agent/admin { "message": { "event": "team.changed", "data": { // Conversation object will be available here } } } conversation.contact_changed This event is sent to the agents/admins when two contacts are merged all their conversations are consolidated under one contact. Available to: agent/admin { "message": { "event": "conversation.contact_changed", "data": { // Conversation object will be available here } } } contact.created This event is sent to the agents/admins when a contact is created. Available to: agent/admin { "message": { "event": "contact.created", "data": { // Contact object will be available here } } } contact.updated This event is sent to the agents/admins when a contact is updated. Available to: agent/admin { "message": { "event": "contact.updated", "data": { // Contact object will be available here } } } presence.update Available for both agent and the contact, this event provides real-time updates on the availability status of the users in the system. The event delivered to contacts will not include information about other contacts' availability status. Available to: agent/admin { "message": { "event": "presence.update", "data": { "account_id": "integer", "users": { "user-id": "string" }, "contacts": { "contact-id": "string" } } } } notification_created This event is sent to the agents/admins when a notification is created. Available to: agent/admin
🛳️ MigrationsHow to migrate from Freshdesk to Chatwoot?
If you are moving from Freshdesk to Chatwoot, you can use Chatwoot's built-in importer to bring your contacts and past tickets into your Chatwoot account. The import runs in the background, so you can continue setting up Chatwoot while it completes. Availability: The built-in Freshdesk importer is available on Chatwoot paid plans. You must be an account administrator to start and manage an import. What the Freshdesk import brings over You can choose to import: - Contacts - Conversations, which imports Freshdesk tickets, their replies and private notes, and the contacts associated with those tickets Chatwoot preserves the available source timestamps and source details so the imported records remain useful as historical context. Imported tickets are added as resolved historical conversations in source-specific Freshdesk import inboxes. These inboxes preserve history; they do not replace the live channels you will configure in Chatwoot. Before you begin Make sure that: - You have a Chatwoot account on a paid plan. If you are new to Chatwoot, create your account first. - You are an administrator in the Chatwoot account. - You know your original Freshdesk domain, such as acme.freshdesk.com. Use the Freshdesk domain, not a custom support-portal domain. - You have an API key from a verified Freshdesk agent with access to the contacts and tickets you want to migrate. We recommend using an administrator's API key so the import can read the complete available history. - You have planned your channel cutover. The import is a one-time migration, not a continuous sync. Only one Intercom or Freshdesk integration import can run in a Chatwoot account at a time. Freshdesk ticket limit: Freshdesk's List All Tickets API returns a maximum of 300 pages, or 30,000 tickets. If your account has 30,000 or more tickets, Chatwoot stops the import when the API can no longer confirm that the history is complete. The remaining history requires a Freshdesk Account Export, which the built-in importer does not currently support. Step 1: Get your Freshdesk domain and API key Your Freshdesk domain is the hostname you use to open Freshdesk. For example, if you sign in at https://acme.freshdesk.com, enter acme.freshdesk.com in Chatwoot. To find your API key: 1. Sign in to Freshdesk as the verified agent whose API access you will use. 2. Click your profile picture in the upper-right corner. 3. Select Profile Settings. 4. In the right pane, click View API key. 5. Complete Freshdesk's CAPTCHA verification and copy the API key. For more information, see Freshdesk's guide to finding your API key. Treat the API key like a password. Freshdesk lets you reset the key after the migration, but resetting it also disconnects every other app that uses the same key. Check for other integrations before you reset it. Step 2: Open Data settings in Chatwoot 1. Sign in to Chatwoot. 2. Go to Settings → Data. 3. Open the Import tab. 4. Click Import. Step 3: Configure and start the import In the New import dialog: 1. Select Freshdesk as the source. 2. Enter an import name. This helps you identify the migration later. 3. Enter your Freshdesk domain, for example acme.freshdesk.com. 4. Paste your key into Freshdesk API key. 5. Under Data to import, select one or both of the following: - Contacts imports contacts from Freshdesk. - Conversations imports tickets, their replies and notes, and the contacts required for those tickets. 6. Move out of the API-key field and wait for Chatwoot to validate the credentials. 7. When you see Access key validated, click Import. If validation fails, check the domain, confirm that you copied the complete API key, and verify that the Freshdesk agent's role can read the selected data. Step 4: Monitor and verify the import Chatwoot opens the import details page after the import starts. The page updates automatically while the import runs and shows separate progress for contacts, conversations, and messages. Freshdesk applies API rate limits based on your Freshdesk plan. Chatwoot waits and retries when Freshdesk asks it to slow down, so large imports can take time. Depending on the outcome, the import can finish as Completed or Completed with errors. Review the following before you cut over: - The imported counts for contacts, conversations, and messages - A sample of imported contacts and tickets - The Errors section for records Chatwoot could not import - The Skip logs section for records that were intentionally skipped You can download error and skip logs as CSV files. If an import becomes stalled, use Retry when the option appears. You can also abandon an active import if you need to stop it. Step 5: Move your live channels to Chatwoot The data import brings over historical records. It does not recreate your Freshdesk widget or connect it as a live Chatwoot channel. To move your website chat: 1. Create a website live chat inbox in Chatwoot. 2. Add the Chatwoot widget code to your website. 3. Remove the Freshdesk widget code as close as possible to the Chatwoot launch to avoid a gap in coverage. 4. Start a test conversation from your website and confirm that it reaches the correct Chatwoot inbox and team. If you use other Freshdesk channels, set up the corresponding Chatwoot channels and test each one before completing the cutover. Important behaviour and limitations - The import is a one-time historical migration. New changes in Freshdesk are not continuously synced to Chatwoot. - Historical imports do not send messages or notifications to your customers. - Imported conversations are resolved and stored in source-specific import inboxes. Configure new Chatwoot inboxes for ongoing customer communication. - File attachments are not transferred. When a Freshdesk message has attachments, Chatwoot adds a note to the message indicating how many attachments were skipped. - Freshdesk agents, groups, assignments, routing rules, automations, apps, SLAs, and widget settings are not recreated in Chatwoot. - Deleted and spam tickets are not returned by Freshdesk's List All Tickets API and are not included in the import. - Freshdesk limits that API to 300 pages, or 30,000 tickets. The importer cannot currently ingest the separate Freshdesk Account Export required for any remaining history. - Some source-specific fields are retained as metadata but may not appear as equivalent Chatwoot fields. - Keep access to Freshdesk until you have reviewed the imported counts, sample records, and any error or skip logs. Make Chatwoot your own Once the import and channel cutover are complete, these resources will help your team get started: - Chatwoot 101 tutorials - Set up an omnichannel inbox - Chatwoot best practices For anything else, reach out to us through the support chat. Happy chatting!
⚡ Apps and IntegrationsHow to translate messages with Google Translate?
If you frequently receive queries in languages you/your team members don't understand, you can utilize the Google Translate integration in Chatwoot. When enabled, you can instantly translate incoming messages using the right-click menu. This way, you can easily communicate with customers in their native language, even if you don't speak it yourself. How to enable Google Translate in Chatwoot? Step 1. Go to Settings -> Applications -> Google Translate. Click the corresponding "Configure" button. Step 2. You'll see the Google Translate app page. Click the "Connect" button. Step 3. Enter your Google Cloud Project ID and Project Key File. If you need help obtaining these values, refer to this doc from Google. Once you have entered the values, click the "Create" button. Now, your Google Translate integration is complete. How to change the translation language? Your messages get translated into your site language. To select your site language, visit the "Account Settings" page. Step 1. Go to Settings -> Account Settings -> Site Language. Open the dropdown and select your preferred language. Step 2. Click the "Update Settings" button on the top-right corner of the page. This will translate your entire dashboard to the selected language. Note: Agents can select their individual preferred languages too. How to translate incoming messages? Whenever you receive a message in a language you need help with, click the 3 dots beside the message to open the menu and select "Translate". Find the translated content inline. How to create a service account in Google Cloud Console? To create a service account for the Google Translate API, start by signing in to the Google Cloud Console and selecting or creating a new project. Once your project is ready, enable the Cloud Translation API by navigating to “APIs & Services” > “Library” and searching for “Cloud Translation API.” Click “Enable” to activate it for your project. Enabling billing is also necessary if you haven’t done so already. Next, go to “IAM & Admin” > “Service Accounts” and click “Create Service Account.” Provide a name (e.g., translate-api-user) and continue to assign the “Cloud Translation API User” role. After creating the service account, navigate to the “Keys” section, click “Add Key,” and select “Create New Key” in JSON format. Download and securely store this JSON file. Use the contents of the file you received above in the Google Cloud Project Key file input field in Chatwoot.