Hey đź‘‹, how can we help you?
Search for the articles here or browse the categories below.
Browse by topic
Find guides, tutorials, and answers organised by category.
Chatwoot 101
Start here to understand Chatwoot, key concepts, and how the platform helps you manage customer conversations.
Browse
Setup account
Set up your account, workspace, teams, users, and basic configuration before going live.
Browse
Website live chat
Learn how to install, configure, and customize the Chatwoot live chat widget on your website or app.
Browse
Other channels
Connect and manage channels such as email, WhatsApp, Facebook, Instagram, Telegram, and more.
Browse
Features explained
Understand the main Chatwoot features used for inbox management, conversations, contacts, teams, and workflows.
Browse
Advanced features explained
Explore advanced capabilities such as automation, assignment rules, custom attributes, macros, SLAs, and webhooks.
Browse
Apps and Integrations
Connect Chatwoot with external tools and services to extend your support workflows.
Browse
Reports
Use reports and analytics to measure team performance, conversation volume, response times, and customer support quality.
Browse
Help Center
Create, organize, and publish help center articles so customers can find answers on their own.
Browse
Best practices
Practical recommendations to help your team get better results from Chatwoot.
Browse
Captain
Learn how to set up and use Captain, Chatwoot’s AI agent for customer support.
Browse
Migrations
Guides to help with a smooth transition from other platforms, such as Zendesk, Freshdesk, Intercom, etc, to Chatwoot.
Browse
Other topics
Additional guides and references to help you get the most out of Chatwoot.
Browse
How To
Step-by-step guides for common tasks and specific use cases in Chatwoot.
Browse
Popular articles
What other people are reading right now.
How to use Agent bots?
AgentBot can seamlessly integrate with your Chatwoot inbox as a customer query handling bot. With Chatwoot, you can easily connect your custom bot logic to conversation handling via AgentBot's API. By connecting AgentBot to your inbox, all new conversations will automatically be assigned a 'bot' status. Chatwoot will send conversation events to your bot URL as webhook events, allowing AgentBot to respond through the Chatwoot API in real-time. How does the AgentBot work? Explained below in a typical workflow of an AgentBot. 1. The AgentBot receives events such as widget_triggered, message_created, and message_updated based on customer interactions. 2. The AgentBot processes the received information to generate an appropriate response. 3. The AgentBot can also utilize external system APIs to gather additional customer information, such as order status or booking triggers. 4. The AgentBot can utilize services such as Rasa, Dialogflow, or Lex for intent detection. 5. The AgentBot can post the generated response back into the widget by utilizing Chatwoot APIs such as message_create. 6. The AgentBot can toggle a conversation status to open to hand off the conversation to a human agent. 7. It continues to monitor open conversations to provide contextual information to the support agent. How does the Human-Agent handoff work? When an agent bot is connected to an inbox, conversations are created with a "pending" status, allowing it to triage the conversation before passing it on to a human agent. If the bot determines that a human agent's assistance is needed, it can use the conversation update API to change the status to "open." Sometimes the agents would want to push back a conversation which was handed off, back again into the bot queue. Agents can return a handed-off conversation to the bot queue by changing the status back to "pending”. How can I use the AgentBot? Listed below are a few examples. 1. Businesses with high volume customer support queries can utilize an AgentBot to authenticate and filter queries, reducing the workload on human agents and improving the efficiency of customer support. 2. E-commerce websites can integrate the AgentBot with their existing databases, providing customers with real-time updates on order and shipping status, as well as answering other related queries. 3. News and content websites can use the AgentBot to send recommendations to users via card messages. 4. Hotel and movie booking websites can use the AgentBot to handle bookings, reservations and answering related queries, providing customers with a seamless and convenient booking experience. Examples 1. Hotel booking implementation using Dialogflow. 2. Example implementation using Rasa. Also, look into interesting ways to leverage bot-message types on Chatwoot. Creating agent bots How to create agent bots in your Chatwoot account? You can create agent bots from the account settings. Go to Settings -> Bots. You will see an option like the one below. Click on "Add Bot" to create a new bot. You will see an option to provide a name, avatar and a webhook URL. How to connect an inbox to a bot? Open the inbox where you want to link the bot. In Bot Configuration, pick the bot that should manage the conversations. After you click Save, you’ll start getting webhook events each time a new conversation or message is created. For more details about the events that are supported in the webhooks, please visit the Webhook documentation here. Webhook Verification Once you create an agent bot, we automatically generate a secret that you can use to verify the payload your application receives. You can read more about webhook verification here.
🪵 Other channelsHow to setup a WhatsApp channel?
You can manage your WhatsApp Business Account conversations directly from Chatwoot. To connect your WhatsApp number, Chatwoot supports two onboarding methods: - Embedded Signup (recommended) – a guided flow powered by Meta that auto-configures your number, webhooks, and tokens. - Manual Setup – an advanced option for tech providers and cases where Embedded Signup cannot be used. This guide gives you an overview of both methods, their differences, and links to detailed step-by-step instructions. Prerequisites - A Meta (Facebook) developer or business account - A valid phone number (not already tied to another WhatsApp Embedded Signup flow, unless migrating) - A Chatwoot workspace with WhatsApp feature enabled Step 1: Go to Inboxes 1. Log into your Chatwoot account. 2. Navigate to Settings › Inboxes › Add Inbox. 3. Choose WhatsApp as the channel. Step 2: Choose Your Setup Method When creating a WhatsApp Inbox, you’ll see two options: Connect with Whatsapp Business (Embedded Signup) - Redirects you to Meta’s Embedded Signup flow. - You log in with your Facebook account, select or create a WhatsApp Business Account (WABA), and add your phone number. - Chatwoot automatically receives the webhook, tokens, and phone number configuration. Use this option if you are: - Adding a new WhatsApp number - Looking for the fastest, no-configuration setup - Not a tech provider onboarding your own number Read the full guide on WhatsApp Embedded Signup Manual Setup - You configure everything through the Meta Developer Console. - Requires generating tokens, creating a system user, assigning assets, and setting up webhooks manually. - You copy/paste the Phone Number ID, Business Account ID, and API key into Chatwoot. Use this option if you are: - A tech provider onboarding your own number - Reusing a number that is already linked to Embedded Signup - Comfortable working with the Meta Developer dashboard Read the full guide on Manual Setup
⚡ Apps and IntegrationsHow to use webhooks?
Webhooks are HTTP callbacks that are set up for each account. These are triggered when actions such as creating a message occur in Chatwoot. Multiple webhooks can be created for a single account. How to add a webhook? Step 1. Go to Settings → Integrations → Webhooks. Click on the "Configure" button. Step 2. Click on the "Add new webhook" button. A modal will open up. Here, input the URL to which the POST request should be sent. Next, you need to select the events you want to subscribe. This option would allow you to only listen to the relevant events in Chatwoot. Chatwoot will send a POST request with the following payload to the configured URLs for various updates in your account. A sample webhook payload { "event": "message_created", // The name of the event "id": "1", // Message ID "content": "Hi", // Content of the message "created_at": "2020-03-03 13:05:57 UTC", // Time at which the message was sent "message_type": "incoming", // This will have a type incoming, outgoing or template. The user from the widget sends incoming messages, and the agent sends outgoing messages to the user. "content_type": "enum", // This is an enum, it can be input_select, cards, form or text. The message_type will be template if content_type is one og these. Default value is text "content_attributes": {} // This will an object, different values are defined below "source_id": "", // This would the external id if the inbox is a Twitter or Facebook integration. "sender": { // This would provide the details of the agent who sent this message "id": "1", "name": "Agent", "email": "[email protected]" }, "contact": { // This would provide the details of the user who sent this message "id": "1", "name": "contact-name" }, "conversation": { // This would provide the details of the conversation "display_id": "1", // This is the ID of the conversation which you can see in the dashboard. "additional_attributes": { "browser": { "device_name": "Macbook", "browser_name": "Chrome", "platform_name": "Macintosh", "browser_version": "80.0.3987.122", "platform_version": "10.15.2" }, "referer": "<http://www.chatwoot.com>", "initiated_at": "Tue Mar 03 2020 18:37:38 GMT-0700 (Mountain Standard Time)" } }, "account": { // This would provide the details of the account "id": "1", "name": "Chatwoot", } } Supported webhook events in Chatwoot Chatwoot publishes various events to the configured webhook endpoints. If you want to configure a webhook, refer to the guide here. Each event has its payload structure based on the type of model they are acting on. The following section describes the main objects we use in Chatwoot and their attributes. Objects An event payload may include any of the following objects. The various types of objects supported by Chatwoot are listed below. Account { "id": "integer", "name": "string" } Inbox { "id": "integer", "name": "string" } Contact { "id": "integer", "name": "string", "avatar": "string", "type": "contact", "account": { // <...Account Object> } } User { "id": "integer", "name": "string", "email": "string", "type": "user" } 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" } Message { "id": "integer", "content": "string", "message_type": "integer", "created_at": "unix-timestamp", "private": "boolean", "source_id": "string / null", "content_type": "string", "content_attributes": "object", "sender": { "type": "string - contact/user" // User or Contact Object }, "account": { // Account Object }, "conversation": { // Conversation Object }, "inbox": { // Inbox Object } } A sample webhook payload { "event": "event_name" // Attributes related to the event } Webhook Events Chatwoot supports the following webhook events. You can subscribe to them while configuring a webhook in the dashboard or using the API. conversation_created This event will be triggered when a new conversation is created in the account. The payload for the event is as follows. { "event": "conversation_created" // <...Conversation Attributes> } conversation_updated This event will be triggered when there is a change in any of the attributes in the conversation. { "event": "conversation_updated", "changed_attributes": [ { "<attribute_name>": { "current_value": "", "previous_value": "" } } ] // <...Conversation Attributes> } conversation_status_changed This event will be triggered when the status of the conversation is changed. Note: If you are using agent bot APIs instead of webhooks, this event is not supported yet. { "event": "conversation_status_changed" // <...Conversation Attributes> } message_created This event will be triggered when a message is created in a conversation. The payload for the event is as follows. { "event": "message_created" // <...Message Attributes> } message_updated This event will be triggered when a message is updated in a conversation. The payload for the event is as follows. { "event": "message_updated" // <...Message Attributes> } webwidget_triggered This event will be triggered when the end user opens the live-chat widget. { "event": "webwidget_triggered", "id": "", "contact": { // <...Contact Object> }, "inbox": { // <...Inbox Object> }, "account": { // <...Account Object> }, "current_conversation": { // <...Conversation Object> }, "source_id": "string", "event_info": { "initiated_at": { "timestamp": "date-string" }, "referer": "string", "widget_language": "string", "browser_language": "string", "browser": { "browser_name": "string", "browser_version": "string", "device_name": "string", "platform_name": "string", "platform_version": "string" } } } conversation_typing_on This event is triggered when an agent starts typing in a conversation. It could be either a private note or a message to the customer. You can use the is_private flag to distinguish between the two. { "event": "conversation_typing_on", "conversation": { ...<Conversation Object> }, "user": { ... <User / AgentBot / Captain Object> }, "is_private": true } conversation_typing_off This event is triggered when an agent stops typing or when they leave the conversation window. { "event": "conversation_typing_off", "conversation": { ...<Conversation Object> }, "user": { ... <User / AgentBot / Captain Object> }, "is_private": true } Verifying webhooks Chatwoot signs every outgoing webhook request so your server can verify that the payload was sent by Chatwoot and has not been tampered with. The secret is shown to you once the webhook is created, and you can view it again on the webhook edit form. Every webhook request sends the following headers, which can be used to compute the HMAC signature of the payload - X-Chatwoot-Signature: HMAC-SHA256 signature prefixed with sha256= - X-Chatwoot-Timestamp: Unix timestamp (seconds) when the request was signed - X-Chatwoot-Delivery: Unique delivery ID for the webhook event (when available) The signature is computed as: sha256=HMAC-SHA256(webhook_secret, "{timestamp}.{raw_body}") Where: - webhook_secret is the secret associated with the webhook - timestamp is the value of the X-Chatwoot-Timestamp header - raw_body is the raw JSON request body (not parsed/re-serialized) Verification Steps 1. Extract X-Chatwoot-Signature and X-Chatwoot-Timestamp from the request headers 2. Read the raw request body as bytes (do not parse and re-serialize) 3. Compute the expected signature: sha256=HMAC-SHA256(secret, "{timestamp}.{raw_body}") 4. Compare the computed signature with the received signature using a constant-time comparison 5. Optionally, reject requests where the timestamp is too old to prevent replay attacks Examples Ruby def verify_signature(raw_body, timestamp, received_signature, secret) expected = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp}.#{raw_body}")}" ActiveSupport::SecurityUtils.secure_compare(expected, received_signature) end Python import hmac import hashlib def verify_signature(raw_body: bytes, timestamp: str, received_signature: str, secret: str) -> bool: message = f"{timestamp}.".encode() + raw_body expected = "sha256=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, received_signature) Node.js const crypto = require("crypto"); function verifySignature(rawBody, timestamp, receivedSignature, secret) { const message = `${timestamp}.${rawBody}`; const expected = "sha256=" + crypto.createHmac("sha256", secret).update(message).digest("hex"); return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(receivedSignature) ); } Go import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "fmt" ) func verifySignature(rawBody []byte, timestamp, receivedSignature, secret string) bool { mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(fmt.Sprintf("%s.%s", timestamp, rawBody))) expected := "sha256=" + hex.EncodeToString(mac.Sum(nil)) return hmac.Equal([]byte(expected), []byte(receivedSignature)) } Important Notes - Always use the raw request body for verification. Parsing the JSON and re-serializing it may change key ordering, whitespace, or unicode escaping, which will produce a different signature. - Always use constant-time comparison (e.g., hmac.compare_digest, crypto.timingSafeEqual, ActiveSupport::SecurityUtils.secure_compare) to prevent timing attacks. - Consider rejecting requests with timestamps older than 5 minutes to mitigate replay attacks.
đź‘ť Setup accountHow to invite agents and manage your support team?
An agent is anyone on your team who has access to Chatwoot to handle customer conversations. Every person who logs into your Chatwoot account is an agent — there is no separate "user" concept beyond agents and the role each one holds. Each agent has: - A name and email — used to log in and to display on customer-facing replies - A role that determines what they can see and do in the account - An availability state — Online, Busy, or Offline — shown to teammates and used to influence auto-assignment The two built-in roles Out of the box, Chatwoot has exactly two roles: | Role | What they can do | |------|------------------| | Administrator | Full access. Can change account settings, manage agents, configure inboxes, build automations, view all conversations. | | Agent | Standard support role. Can handle conversations on inboxes they're a member of, but cannot change account settings or manage other agents. | If you need more granular control, for example, "this person can manage contacts and view reports, but can't see other agents' conversations". You can define your own roles via the Custom Roles feature. See Custom Roles for the full guide. When custom roles exist, they appear in the same role dropdown wherever you'd otherwise pick Administrator or Agent. Permissions: only administrators can invite, edit, or delete agents. Regular agents can see who's on the team but cannot manage the team list. Managing agents How to invite a new agent and assign their role Adding an agent in Chatwoot is a single-screen modal — not a multi-step wizard. The agent isn't fully active until they accept the invite via email and set up their password. Step 1 — Open the invite modal. Go to Settings → Agents and click the Add Agent button at the top right of the page. Step 2 — Fill in the agent's details. The "Add agent to your team" modal opens. Fill in: | Field | What it's for | |-------|---------------| | Agent Name | The full name your customers will see on outgoing replies. | | Role | A dropdown listing Administrator, Agent, and any custom roles you've defined. Pick whichever level of access this person needs. | | Email Address | The email the invite is sent to and that the agent will use to log in. | Click Add Agent to submit. Step 3 — The agent confirms via email. Chatwoot creates the account in an unconfirmed state and emails the new agent a confirmation link. Until they click that link and set a password, they appear in the agents list with a Verification Pending badge. Once confirmed, the badge changes to Verified and they can log in normally. Tip: if a teammate says they didn't get the invite, check their spam folder first, then have an admin open their row, click Edit, and resend the invite by re-saving — or use Reset Password to send them a fresh login link. How to edit an agent's role, name, or availability 1. Go to Settings → Agents. 2. Find the agent and click the edit (pencil) icon next to their row (tooltip: Edit). 3. The "Edit agent" modal opens. You can change: - Agent Name - Role — switch between Administrator, Agent, or any custom role - Availability — Online, Busy, or Offline 4. Click Update to save. You can also use the Reset Password button inside the edit modal to email the agent a new password-reset link. (This button is hidden for accounts that authenticate via SAML / SSO.) Note: changing an agent's role is instant. If you demote an admin to a standard agent while they're logged in, their access to settings will disappear on their next page navigation. How to remove an agent 1. Go to Settings → Agents. 2. Find the agent and click the delete (trash bin) icon next to their row (tooltip: Delete). The icon turns red on hover. 3. Confirm the deletion in the modal. Who you can't delete: - Yourself. The delete button is hidden on your own row. - The last verified administrator on the account. Chatwoot enforces at least one admin at all times. What happens when an agent is deleted? A background worker handles cleanup atomically: - They're removed from every team they were a member of. - They're removed from every inbox they were a collaborator on. - Every conversation they were the assignee of is unassigned. The conversations are not deleted, not re-routed automatically, and not re-assigned to anyone — they sit in the unassigned queue until a human or auto-assignment picks them up. Plan accordingly: if a high-volume agent is leaving, consider re-assigning their open conversations before you delete them, so nothing slips through the unassigned queue. Agent availability: Online, Busy, Offline Every agent has one of three availability states. The state shows on their avatar throughout the dashboard so teammates know who's around. | State | Meaning | |-------|---------| | Online | Available — auto-assignment routes new conversations to them. | | Busy | They're at the desk but heads-down. Auto-assignment would skip them. | | Offline | They're done for the day. Auto-assignment doesn't pick them. | Agents set their own availability from the avatar dropdown in the top-right of the dashboard. Admins can change anyone's availability from the Edit agent modal. How to use agents Once an agent exists in your account, they become available wherever a person can be selected, mentioned, or filtered. Here's the full set of places. 1. Inbox membership Agents are added as members of specific inboxes (Settings → Inboxes → [an inbox] → Collaborators). Only inbox members can see and reply to conversations on that inbox. Adding someone to your account does not automatically give them access to every inbox — you grant inbox access deliberately. 2. Team membership Agents can belong to one or more teams (Settings → Teams). Team membership is what makes them eligible for team-scoped auto-assignment. See Teams for the full picture. 3. Conversation assignee The Assignee field in the conversation actions sidebar is a dropdown of eligible agents (those on the conversation's inbox). The assignee is the one person currently responsible for replying. 4. Conversation participants Beyond the assignee, you can add agents as participants so they can follow along, get notifications, and chime in privately without taking ownership. Useful for shadowing, escalations, or looping in subject-matter experts. 5. @-mentions in private notes Inside a conversation's Private Notes tab, type @ and start typing a teammate's name to tag them. Mentioned agents get a notification and the conversation appears in their Mentions view in the navigation rail. 6. Macros The macro action picker (Settings → Macros) includes Assign Agent as an action. So a "Refund issued" macro can in one click reassign the conversation to whichever agent should handle finance follow-up. 7. Automation rules Automation rules (Settings → Automation) can both filter on an agent (as a condition: "if assigned agent is X") and assign an agent (as an action: "assign agent X") or remove an existing assignment. 8. Reports - Agent Reports show the same six core metrics (conversations created, incoming/outgoing messages, avg first response time, avg resolution time, resolutions count, avg reply time) scoped to one agent. - CSAT and SLA reports both accept an agent filter so you can drill into one person's CSAT score or SLA hit-rate. Frequently asked questions What's the difference between Administrator and Agent in practical terms? Administrators can change settings, manage agents, configure inboxes, build automations, and see every conversation in the account. Agents can handle conversations on inboxes they're members of and edit their own profile, but can't manage account-level settings or other people. If you need shades in between (e.g. "can manage contacts but not settings"), use Custom Roles. Where does an agent go to set their own availability? Bottom left avatar dropdown on the dashboard → Online / Busy / Offline. Admins can also set availability from the edit modal on the agents list. Does Busy stop me from getting any conversations? Busy is a softer signal than Offline, but it would take you out of the pool the way Offline does. Can custom roles be mixed with the built-in Administrator and Agent roles? Yes — the role dropdown on the agent invite/edit modal lists both built-in roles and every custom role you've defined. You pick exactly one. If you assign a custom role, it replaces the built-in role for that agent. An agent left the company. What's the safest deletion order? 1. Reassign their open conversations to a teammate. 2. Remove them from any teams where their absence would cause auto-assignment confusion. 3. Delete the agent — the cleanup job removes them from inboxes/teams and unassigns anything left.
🪵 Other channelsHow to create an API channel inbox?
To create and configure an API channel inbox in Chatwoot installations, follow the step described below. Setup the API channel Step 1. Go to Settings → Inboxes → “Add Inbox”. Step 2. Click on the "API" icon. Step 3. Provide a name for the channel and a callback URL. Here is an example: Step 4. "Add agents" to your API inbox. The inbox setup is complete. Send messages to the API channel To send messages to the API channel, ensure you understand the following models and nomenclature used in Chatwoot. 1. Channel: Channel defines the type of source of conversations. E.g., Facebook, Twitter, API, etc. 2. Inbox: You can create multiple sources of conversations of the same channel type. E.g., You can have more than one Facebook page connected to a Chatwoot account. Each page is called the inbox in Chatwoot. 3. Conversation: A Conversation is a collection of messages. 4. Contact: Each conversation has a real-life person associated with it, called a contact. 5. Contact Inboxes: This is the session for each contact in an inbox. A contact can have multiple sessions and multiple conversations in the same inbox. How to send a message in an API Channel? To send a message in an API channel, create a contact, initiate a conversation, and finally send the message. APIs require api_access_token in the request header. You can get this token by visiting your Profile settings → Access Token. 1. Create a contact Ref: API documentation Pass the inbox ID of the API channel along with other params specified. This would create a session for you automatically. A sample response would look like the one below. { "email": "string", "name": "string", "phone_number": "string", "thumbnail": "string", "additional_attributes": {}, "contact_inboxes": [ { "source_id": "string", "inbox": { "id": 0, "name": "string", "website_url": "string", "channel_type": "string", "avatar_url": "string", "widget_color": "string", "website_token": "string", "enable_auto_assignment": true, "web_widget_script": "string", "welcome_title": "string", "welcome_tagline": "string", "greeting_enabled": true, "greeting_message": "string" } } ], "id": 0, "availability_status": "string" } As you can see in the payload, you will be able to see the contact_inboxes and each contact_inbox will have a source_id. Source ID can be seen as the session identifier. You will use this source_id to create a new conversation as defined below. 2. Create a conversation Ref: API documentation Use the source_id received in the previous API call. You will receive a conversation ID which can be used to create a message. { "id": 0 } 3. Create a new message Ref: API documentation There are 2 types of messages. 1. Incoming: Messages sent by the end user is classified as an incoming message. 2. Outgoing: Messages sent by the agent is classified as an outgoing message. If you call the API with the correct content, you will receive a payload similar to this one: { "id": 0, "content": "This is a incoming message from API Channel", "inbox_id": 0, "conversation_id": 0, "message_type": 0, "content_type": null, "content_attributes": {}, "created_at": 0, "private": false, "sender": { "id": 0, "name": "Pranav", "type": "contact" } } If everything is successful, you will see the conversation on the dashboard as follows. You will be notified when a new message is created on the URL specified while creating the API channel. You can read about the message payload here. Receive messages using callback URL When a new message is created in the API channel, you will get a POST request to the Callback URL specified while creating the API channel. The payload would look like this. Find the full list of events supported by the webhook here. Event type: message_created { "id": 0, "content": "This is a incoming message from API Channel", "created_at": "2020-08-30T15:43:04.000Z", "message_type": "incoming", "content_type": null, "content_attributes": {}, "source_id": null, "sender": { "id": 0, "name": "contact-name", "avatar": "", "type": "contact" }, "inbox": { "id": 0, "name": "API Channel" }, "conversation": { "additional_attributes": null, "channel": "Channel::Api", "id": 0, "inbox_id": 0, "status": "open", "agent_last_seen_at": 0, "contact_last_seen_at": 0, "timestamp": 0 }, "account": { "id": 1, "name": "API testing" }, "event": "message_created" } Create Interfaces using client APIs Client APIs available for the API channel will help you build customer-facing interfaces for Chatwoot. These APIs are useful for cases like the ones listed below. 1. Use a custom chat interface instead of the Chatwoot chat widget. 2. Build conversational interfaces into your mobile apps. 3. Add Chatwoot to other platforms for which Chatwoot doesn't have an official SDK. Creating customer objects You can create and retrieve customer data objects using the inbox_identifier and customer_identifier. Inbox Identifier You can obtain the inbox_identifier from your API channel -> Settings -> Configuration. Customer Identifier The customer_identifier or the source_id can be obtained when creating the customer using the create API. You will need to store this identifier on your client-side to make further requests on behalf of the customer. This can be done in cookies, local storage etc. Available APIs The Available Client APIs are documented here. Some of the things you can do with the APIs are: - Create, View and Update Contact - Create and List Conversations - Create, List and Update Messages HMAC Authentication The Client APIs also support HMAC Authentication. The HMAC token for the Channel can be obtained via running the following on your rails console. # replace api_inbox_id with your inbox id Inbox.find(api_inbox_id).channel.hmac_token Connecting to the Chatwoot WebSockets To get real-time updates from the agent dashboard, connect to Chatwoot WebSockets using the following URL. <your installation url>/cable Authenticating your WebSocket connection After subscribing using the customer's pubsub_token, you will receive events directed toward your customer object. The pubsub_token is provided during the customer creation API call. Example const connection = new WebSocket('ws://localhost:3000/cable'); connection.send(JSON.stringify({ command:"subscribe", identifier: "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\""+ customer_pubsub_token+"\\"}" })); Find the full list of events supported by WebSockets here. Webhook Verification Once you create an API channel, we automatically generate a secret that you can use to verify the payload your application receives. You can read more about webhook verification here. Implementation Here is an example chat interface build over the Client APIs.
⚡ Apps and IntegrationsHow to use Dashboard Apps?
With Dashboard apps, you can integrate an app within the Chatwoot dashboard for agents' use. This feature enables you to create an application independently, which can then be embedded to provide customers' information, orders, past payment history, etc. When embedded in Chatwoot's dashboard, your application will get the context of the conversation and contact as a window event. Implement a listener for the message event on your page to receive the context. P.S. Check out our YouTube live on building a Dashboard App. How to create a dashboard app? Step 1. Go to Settings → Integrations → Dashboard apps. Click on the “Configure” button corresponding to the Dashboard Apps. Step 2. Add your app name and the URL on which your app is hosted. Once you are done, a new tab with the name you gave to the app will appear in the conversation window. In this case, it is “Customer Orders”. When you click on the new tab, you will be able to see your application fetching data on the Chatwoot dashboard. Receiving data from Chatwoot into your app Chatwoot will deliver the conversation and contact context as a window event. This can be accessed within your app by implementing a listener for the event, as shown here: window.addEventListener("message", function (event) { if (!isJSONValid(event.data)) { return; } const eventData = JSON.parse(event.data); }); On-demand request for data from Chatwoot If you need to request the conversation data on demand from Chatwoot, you can send a message to the parent window using the javascript postMessage API. Chatwoot will be listening to this key: chatwoot-dashboard-app:fetch-info. Example The following code can be used to query the dashboard app. Chatwoot will respond to this request by providing the updated conversation payload promptly. window.parent.postMessage('chatwoot-dashboard-app:fetch-info', '*') // You would get a message in the on message listener with the appContext payload. Event Payload conversation object​ { "meta": { "sender": { "additional_attributes": { "description": "string", "company_name": "string", "social_profiles": { "github": "string", "twitter": "string", "facebook": "string", "linkedin": "string" } }, "availability_status": "string", "email": "string", "id": "integer", "name": "string", "phone_number": "string", "identifier": "string", "thumbnail": "string", "custom_attributes": "object", "last_activity_at": "integer" }, "channel": "string", "assignee": { "id": "integer", "account_id": "integer", "availability_status": "string", "auto_offline": "boolean", "confirmed": "boolean", "email": "string", "available_name": "string", "name": "string", "role": "string", "thumbnail": "string" }, "hmac_verified": "boolean" }, "id": "integer", "messages": [ { "id": "integer", "content": "Hello", "inbox_id": "integer", "conversation_id": "integer", "message_type": "integer", "content_type": "string", "content_attributes": {}, "created_at": "integer", "private": "boolean", "source_id": "string", "sender": { "additional_attributes": { "description": "string", "company_name": "string", "social_profiles": { "github": "string", "twitter": "string", "facebook": "string", "linkedin": "string" } }, "custom_attributes": "object", "email": "string", "id": "integer", "identifier": "string", "name": "string", "phone_number": "string", "thumbnail": "string", "type": "string" } } ], "account_id": "integer", "additional_attributes": { "browser": { "device_name": "string", "browser_name": "string", "platform_name": "string", "browser_version": "string", "platform_version": "string" }, "referer": "string", "initiated_at": { "timestamp": "string" } }, "agent_last_seen_at": "integer", "assignee_last_seen_at": "integer", "can_reply": "boolean", "contact_last_seen_at": "integer", "custom_attributes": "object", "inbox_id": "integer", "labels": "array", "muted": "boolean", "snoozed_until": null, "status": "string", "timestamp": "integer", "unread_count": "integer", "allMessagesLoaded": "boolean", "dataFetched": "boolean" } contact object​ { "additional_attributes": { "description": "string", "company_name": "string", "social_profiles": { "github": "string", "twitter": "string", "facebook": "string", "linkedin": "string" } }, "availability_status": "string", "email": "string", "id": "integer", "name": "string", "phone_number": "+91 9000000001", "identifier": "string || null", "thumbnail": "+91 9000000001", "custom_attributes": {}, "last_activity_at": "integer" } currentAgent object​ { "email": "string", "id": "integer", "name": "string" } Final Payload​ { "event": "appContext", "data": { "conversation": { // <...Conversation Attributes> }, "contact": { // <...Contact Attributes> }, "currentAgent": { // <...Current agent Attributes> } } }