# Create an Agent Bot Source: https://developers.chatwoot.com/api-reference/account-agentbots/create-an-agent-bot https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/agent_bots Create an agent bot in the account # Delete an AgentBot Source: https://developers.chatwoot.com/api-reference/account-agentbots/delete-an-agentbot https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/agent_bots/{id} Delete an AgentBot from the account # Get an agent bot details Source: https://developers.chatwoot.com/api-reference/account-agentbots/get-an-agent-bot-details https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/agent_bots/{id} Get the details of an agent bot in the account # List all AgentBots Source: https://developers.chatwoot.com/api-reference/account-agentbots/list-all-agentbots https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/agent_bots List all agent bots available for the current account # Update an agent bot Source: https://developers.chatwoot.com/api-reference/account-agentbots/update-an-agent-bot https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/agent_bots/{id} Update an agent bot's attributes # Create an Account User Source: https://developers.chatwoot.com/api-reference/account-users/create-an-account-user https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json post /platform/api/v1/accounts/{account_id}/account_users Create an Account User # Delete an Account User Source: https://developers.chatwoot.com/api-reference/account-users/delete-an-account-user https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json delete /platform/api/v1/accounts/{account_id}/account_users Delete an Account User # List all Account Users Source: https://developers.chatwoot.com/api-reference/account-users/list-all-account-users https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json get /platform/api/v1/accounts/{account_id}/account_users List all account users # Get account details Source: https://developers.chatwoot.com/api-reference/account/get-account-details https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id} Get the details of the current account # Update account Source: https://developers.chatwoot.com/api-reference/account/update-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id} Update account details, settings, and custom attributes # Create an Account Source: https://developers.chatwoot.com/api-reference/accounts/create-an-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json post /platform/api/v1/accounts Create an Account # Delete an Account Source: https://developers.chatwoot.com/api-reference/accounts/delete-an-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json delete /platform/api/v1/accounts/{account_id} Delete an Account # Get an account details Source: https://developers.chatwoot.com/api-reference/accounts/get-an-account-details https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json get /platform/api/v1/accounts/{account_id} Get the details of an account # Update an account Source: https://developers.chatwoot.com/api-reference/accounts/update-an-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json patch /platform/api/v1/accounts/{account_id} Update an account's attributes # Create an Agent Bot Source: https://developers.chatwoot.com/api-reference/agentbots/create-an-agent-bot https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json post /platform/api/v1/agent_bots Create an agent bot # Delete an AgentBot Source: https://developers.chatwoot.com/api-reference/agentbots/delete-an-agentbot https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json delete /platform/api/v1/agent_bots/{id} Delete an AgentBot # Get an agent bot details Source: https://developers.chatwoot.com/api-reference/agentbots/get-an-agent-bot-details https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json get /platform/api/v1/agent_bots/{id} Get the details of an agent bot # List all AgentBots Source: https://developers.chatwoot.com/api-reference/agentbots/list-all-agentbots https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json get /platform/api/v1/agent_bots List all agent bots available # Update an agent bot Source: https://developers.chatwoot.com/api-reference/agentbots/update-an-agent-bot https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json patch /platform/api/v1/agent_bots/{id} Update an agent bot's attributes # Add a New Agent Source: https://developers.chatwoot.com/api-reference/agents/add-a-new-agent https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/agents Add a new Agent to Account # List Agents in Account Source: https://developers.chatwoot.com/api-reference/agents/list-agents-in-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/agents Get Details of Agents in an Account # Remove an Agent from Account Source: https://developers.chatwoot.com/api-reference/agents/remove-an-agent-from-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/agents/{id} Remove an Agent from Account # Update Agent in Account Source: https://developers.chatwoot.com/api-reference/agents/update-agent-in-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/agents/{id} Update an Agent in Account # List Audit Logs in Account Source: https://developers.chatwoot.com/api-reference/audit-logs/list-audit-logs-in-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/audit_logs Get Details of Audit Log entries for an Account. This endpoint is only available in Enterprise editions and requires the audit_logs feature to be enabled. # Add a new automation rule Source: https://developers.chatwoot.com/api-reference/automation-rule/add-a-new-automation-rule https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/automation_rules Add a new automation rule to account # Get a automation rule details Source: https://developers.chatwoot.com/api-reference/automation-rule/get-a-automation-rule-details https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/automation_rules/{id} Get the details of a automation rule in the account # List all automation rules in an account Source: https://developers.chatwoot.com/api-reference/automation-rule/list-all-automation-rules-in-an-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/automation_rules Get details of automation rules in an Account # Remove a automation rule from account Source: https://developers.chatwoot.com/api-reference/automation-rule/remove-a-automation-rule-from-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/automation_rules/{id} Remove a automation rule from account # Update automation rule in Account Source: https://developers.chatwoot.com/api-reference/automation-rule/update-automation-rule-in-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/automation_rules/{id} Update a automation rule in account # Add a New Canned Response Source: https://developers.chatwoot.com/api-reference/canned-responses/add-a-new-canned-response https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/canned_responses Add a new Canned Response to Account # List all Canned Responses in an Account Source: https://developers.chatwoot.com/api-reference/canned-responses/list-all-canned-responses-in-an-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/canned_responses Get Details of Canned Responses in an Account # Remove a Canned Response from Account Source: https://developers.chatwoot.com/api-reference/canned-responses/remove-a-canned-response-from-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/canned_responses/{id} Remove a Canned Response from Account # Update Canned Response in Account Source: https://developers.chatwoot.com/api-reference/canned-responses/update-canned-response-in-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/canned_responses/{id} Update a Canned Response in Account # Add Labels Source: https://developers.chatwoot.com/api-reference/contact-labels/add-labels https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/contacts/{id}/labels Add labels to a contact. Note that this API would overwrite the existing list of labels associated to the conversation. # List Labels Source: https://developers.chatwoot.com/api-reference/contact-labels/list-labels https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/contacts/{id}/labels Lists all the labels of a contact # Create a contact Source: https://developers.chatwoot.com/api-reference/contacts-api/create-a-contact https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json post /public/api/v1/inboxes/{inbox_identifier}/contacts Create a contact # Get a contact Source: https://developers.chatwoot.com/api-reference/contacts-api/get-a-contact https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json get /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier} Get the details of a contact # Update a contact Source: https://developers.chatwoot.com/api-reference/contacts-api/update-a-contact https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json patch /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier} Update a contact's attributes # Contact Conversations Source: https://developers.chatwoot.com/api-reference/contacts/contact-conversations https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/contacts/{id}/conversations Get conversations associated with that contact # Contact Filter Source: https://developers.chatwoot.com/api-reference/contacts/contact-filter https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/contacts/filter Filter contacts with custom filter options and pagination # Create Contact Source: https://developers.chatwoot.com/api-reference/contacts/create-contact https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/contacts Create a new Contact # Create contact inbox Source: https://developers.chatwoot.com/api-reference/contacts/create-contact-inbox https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes Create a contact inbox record for an inbox # Delete Contact Source: https://developers.chatwoot.com/api-reference/contacts/delete-contact https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/contacts/{id} Delete a contact belonging to the account using ID # Get Contactable Inboxes Source: https://developers.chatwoot.com/api-reference/contacts/get-contactable-inboxes https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/contacts/{id}/contactable_inboxes Get List of contactable Inboxes # List Contacts Source: https://developers.chatwoot.com/api-reference/contacts/list-contacts https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/contacts Listing all the resolved contacts with pagination (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number # Merge Contacts Source: https://developers.chatwoot.com/api-reference/contacts/merge-contacts https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/actions/contact_merge Merge two contacts into a single contact. The base contact remains and receives all data from the mergee contact. After the merge, the mergee contact is permanently deleted. This action is irreversible. All conversations, labels, and custom attributes from the mergee contact will be moved to the base contact. # Search Contacts Source: https://developers.chatwoot.com/api-reference/contacts/search-contacts https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/contacts/search Search the resolved contacts using a search key, currently supports email search (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number # Show Contact Source: https://developers.chatwoot.com/api-reference/contacts/show-contact https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/contacts/{id} Get a contact belonging to the account using ID # Update Contact Source: https://developers.chatwoot.com/api-reference/contacts/update-contact https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json put /api/v1/accounts/{account_id}/contacts/{id} Update a contact belonging to the account using ID # Assign Conversation Source: https://developers.chatwoot.com/api-reference/conversation-assignments/assign-conversation https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments Assign a conversation to an agent or a team # Create a conversation Source: https://developers.chatwoot.com/api-reference/conversations-api/create-a-conversation https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json post /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations Create a conversation # Get a single conversation Source: https://developers.chatwoot.com/api-reference/conversations-api/get-a-single-conversation https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json get /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id} Retrieves the details of a specific conversation # List all conversations Source: https://developers.chatwoot.com/api-reference/conversations-api/list-all-conversations https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json get /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations List all conversations for the contact # Resolve a conversation Source: https://developers.chatwoot.com/api-reference/conversations-api/resolve-a-conversation https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json post /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/toggle_status Marks a conversation as resolved # Toggle typing status Source: https://developers.chatwoot.com/api-reference/conversations-api/toggle-typing-status https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json post /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/toggle_typing Toggles the typing status in a conversation # Update last seen Source: https://developers.chatwoot.com/api-reference/conversations-api/update-last-seen https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json post /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/update_last_seen Updates the last seen time of the contact in a conversation # Add Labels Source: https://developers.chatwoot.com/api-reference/conversations/add-labels https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/conversations/{conversation_id}/labels Add labels to a conversation. Note that this API would overwrite the existing list of labels associated to the conversation. # Conversation Details Source: https://developers.chatwoot.com/api-reference/conversations/conversation-details https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/conversations/{conversation_id} Get all details regarding a conversation with all messages in the conversation # Conversation Reporting Events Source: https://developers.chatwoot.com/api-reference/conversations/conversation-reporting-events https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/conversations/{conversation_id}/reporting_events Get reporting events for a specific conversation. This endpoint returns events such as first response time, resolution time, and other metrics for the conversation, sorted by creation time in ascending order. # Conversations Filter Source: https://developers.chatwoot.com/api-reference/conversations/conversations-filter https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/conversations/filter Filter conversations with custom filter options and pagination # Conversations List Source: https://developers.chatwoot.com/api-reference/conversations/conversations-list https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/conversations List all the conversations with pagination # Create New Conversation Source: https://developers.chatwoot.com/api-reference/conversations/create-new-conversation https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/conversations Creating a conversation in chatwoot requires a source id. Learn more about source_id: https://www.chatwoot.com/hc/user-guide/articles/1677839703-how-to-create-an-api-channel-inbox#send-messages-to-the-api-channel # Destroy Custom Attributes Source: https://developers.chatwoot.com/api-reference/conversations/destroy-custom-attributes https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/conversations/{conversation_id}/destroy_custom_attributes Removes the given custom attribute keys from a conversation # Get Conversation Counts Source: https://developers.chatwoot.com/api-reference/conversations/get-conversation-counts https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/conversations/meta Get open, unassigned and all Conversation counts # List Labels Source: https://developers.chatwoot.com/api-reference/conversations/list-labels https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/conversations/{conversation_id}/labels Lists all the labels of a conversation # Toggle Priority Source: https://developers.chatwoot.com/api-reference/conversations/toggle-priority https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_priority Toggles the priority of conversation # Toggle Status Source: https://developers.chatwoot.com/api-reference/conversations/toggle-status https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_status Toggle the status of a conversation. Pass `status` to explicitly set the conversation state. Use `snoozed` along with `snoozed_until` to snooze a conversation until a specific time. If `snoozed_until` is omitted, the conversation is snoozed until the next reply from the contact. Regardless of the value provided, snoozed conversations always reopen on the next reply from the contact. # Toggle Typing Status Source: https://developers.chatwoot.com/api-reference/conversations/toggle-typing-status https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_typing_status Toggles the typing status for a conversation. # Update Conversation Source: https://developers.chatwoot.com/api-reference/conversations/update-conversation https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/conversations/{conversation_id} Update Conversation Attributes # Update Custom Attributes Source: https://developers.chatwoot.com/api-reference/conversations/update-custom-attributes https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/conversations/{conversation_id}/custom_attributes Updates the custom attributes of a conversation # Get CSAT survey page Source: https://developers.chatwoot.com/api-reference/csat-survey-page/get-csat-survey-page https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/other_swagger.json get /survey/responses/{conversation_uuid} You can redirect the client to this URL, instead of implementing the CSAT survey component yourself. # Add a new custom attribute Source: https://developers.chatwoot.com/api-reference/custom-attributes/add-a-new-custom-attribute https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/custom_attribute_definitions Add a new custom attribute to account # Get a custom attribute details Source: https://developers.chatwoot.com/api-reference/custom-attributes/get-a-custom-attribute-details https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/custom_attribute_definitions/{id} Get the details of a custom attribute in the account # List all custom attributes in an account Source: https://developers.chatwoot.com/api-reference/custom-attributes/list-all-custom-attributes-in-an-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/custom_attribute_definitions Get details of custom attributes in an Account # Remove a custom attribute from account Source: https://developers.chatwoot.com/api-reference/custom-attributes/remove-a-custom-attribute-from-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/custom_attribute_definitions/{id} Remove a custom attribute from account # Update custom attribute in Account Source: https://developers.chatwoot.com/api-reference/custom-attributes/update-custom-attribute-in-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/custom_attribute_definitions/{id} Update a custom attribute in account # Create a custom filter Source: https://developers.chatwoot.com/api-reference/custom-filters/create-a-custom-filter https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/custom_filters Create a custom filter in the account # Delete a custom filter Source: https://developers.chatwoot.com/api-reference/custom-filters/delete-a-custom-filter https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/custom_filters/{custom_filter_id} Delete a custom filter from the account # Get a custom filter details Source: https://developers.chatwoot.com/api-reference/custom-filters/get-a-custom-filter-details https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/custom_filters/{custom_filter_id} Get the details of a custom filter in the account # List all custom filters Source: https://developers.chatwoot.com/api-reference/custom-filters/list-all-custom-filters https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/custom_filters List all custom filters in a category of a user # Update a custom filter Source: https://developers.chatwoot.com/api-reference/custom-filters/update-a-custom-filter https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/custom_filters/{custom_filter_id} Update a custom filter's attributes # Add a new article Source: https://developers.chatwoot.com/api-reference/help-center/add-a-new-article https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/portals/{id}/articles Add a new article to portal # Add a new category Source: https://developers.chatwoot.com/api-reference/help-center/add-a-new-category https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/portals/{id}/categories Add a new category to portal # Add a new portal Source: https://developers.chatwoot.com/api-reference/help-center/add-a-new-portal https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/portals Add a new portal to account # List all portals in an account Source: https://developers.chatwoot.com/api-reference/help-center/list-all-portals-in-an-account https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/portals Get details of portals in an Account # Update a portal Source: https://developers.chatwoot.com/api-reference/help-center/update-a-portal https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/portals/{id} Update a portal to account # Add a New Agent Source: https://developers.chatwoot.com/api-reference/inboxes/add-a-new-agent https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/inbox_members Add a new Agent to Inbox # Add or remove agent bot Source: https://developers.chatwoot.com/api-reference/inboxes/add-or-remove-agent-bot https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/inboxes/{id}/set_agent_bot To add an agent bot pass agent_bot id, to remove agent bot from an inbox pass null # Create an inbox Source: https://developers.chatwoot.com/api-reference/inboxes/create-an-inbox https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/inboxes You can create more than one website inbox in each account # Get account branded email layout Source: https://developers.chatwoot.com/api-reference/inboxes/get-account-branded-email-layout https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/branded_email_layout Get the account-scoped Liquid HTML layout used as the fallback for branded email replies. # Get an inbox Source: https://developers.chatwoot.com/api-reference/inboxes/get-an-inbox https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/inboxes/{id} Get an inbox available in the current account # List Agents in Inbox Source: https://developers.chatwoot.com/api-reference/inboxes/list-agents-in-inbox https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/inbox_members/{inbox_id} Get Details of Agents in an Inbox # List all inboxes Source: https://developers.chatwoot.com/api-reference/inboxes/list-all-inboxes https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/inboxes List all inboxes available in the current account # Remove an Agent from Inbox Source: https://developers.chatwoot.com/api-reference/inboxes/remove-an-agent-from-inbox https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/inbox_members Remove an Agent from Inbox # Show Inbox Agent Bot Source: https://developers.chatwoot.com/api-reference/inboxes/show-inbox-agent-bot https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/inboxes/{id}/agent_bot See if an agent bot is associated to the Inbox # Update account branded email layout Source: https://developers.chatwoot.com/api-reference/inboxes/update-account-branded-email-layout https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/branded_email_layout Update or clear the account-scoped Liquid HTML layout used as the fallback for branded email replies. # Update Agents in Inbox Source: https://developers.chatwoot.com/api-reference/inboxes/update-agents-in-inbox https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/inbox_members All agents except the one passed in params will be removed # Update Inbox Source: https://developers.chatwoot.com/api-reference/inboxes/update-inbox https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/inboxes/{id} Update an existing inbox # Create an integration hook Source: https://developers.chatwoot.com/api-reference/integrations/create-an-integration-hook https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/integrations/hooks Create an integration hook # Delete an Integration Hook Source: https://developers.chatwoot.com/api-reference/integrations/delete-an-integration-hook https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/integrations/hooks/{hook_id} Delete an Integration Hook # List all the Integrations Source: https://developers.chatwoot.com/api-reference/integrations/list-all-the-integrations https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/integrations/apps Get the details of all Integrations available for the account # Update an Integration Hook Source: https://developers.chatwoot.com/api-reference/integrations/update-an-integration-hook https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/integrations/hooks/{hook_id} Update an Integration Hook # Introduction to Chatwoot APIs Source: https://developers.chatwoot.com/api-reference/introduction Learn how to use Chatwoot APIs to build integrations, customize chat experiences, and manage your installation. Welcome to the Chatwoot API documentation. Whether you're building custom workflows for your support team, integrating Chatwoot into your product, or managing users across installations, our APIs provide the flexibility and power to help you do more with Chatwoot. Chatwoot provides three categories of APIs, each designed with a specific use case in mind: * **Application APIs** – For account-level automation and agent-facing integrations. * **Client APIs** – For building custom chat interfaces for end-users * **Platform APIs** – For managing and administering installations at scale *** ## Application APIs Application APIs are designed for interacting with a Chatwoot account from an agent/admin perspective. Use them to build internal tools, automate workflows, or perform bulk operations like data import/export. * **Authentication**: Requires a user `access_token`, which can be generated from **Profile Settings** after logging into your Chatwoot account. * **Availability**: Supported on both **Cloud** and **Self-hosted** Chatwoot installations. * **Example**: [Google Cloud Functions Demo](https://github.com/chatwoot/google-cloud-functions-demo) *** ## Client APIs Client APIs are intended for building custom messaging experiences over Chatwoot. If you're not using the native website widget or want to embed chat in your mobile app, these APIs are the way to go. * **Authentication**: Uses `inbox_identifier` (from **Settings → Configuration** in API inboxes) and `contact_identifier` (returned when creating a contact). * **Availability**: Supported on both **Cloud** and **Self-hosted** Chatwoot installations. * **Examples**: * [Client API Demo](https://github.com/chatwoot/client-api-demo) * [Flutter SDK](https://github.com/chatwoot/chatwoot-flutter-sdk) *** ## Platform APIs Platform APIs are used to manage Chatwoot installations at the admin level. These APIs allow you to control users, roles, and accounts, or sync data from external authentication systems. > **Note:** Platform APIs cannot access accounts or users created via the Chatwoot UI, or by other API keys. They can only access accounts, users, and other objects created by the specific platform API key used for authentication, or objects explicitly permitted to that API key. * **Authentication**: Requires an `access_token` generated by a **Platform App**, which can be created in the **Super Admin Console**. * **Availability**: Available on **Self-hosted** / **Managed Hosting** Chatwoot installations only. *** Use the right API for your use case, and you'll be able to extend, customize, and integrate Chatwoot into your stack with ease. *** ## FAQ ### Why do I get a 401 'Non permissible resource' error when using Platform API tokens? Platform APIs cannot access accounts or users created via the Chatwoot UI, or by other API keys. They can only access accounts, users, and other objects created by the same API key, or objects explicitly permitted to that API key. If you need to grant a Platform App access to an object (such as an Account) that it did not create, you can manually add the permission using the following command in a Rails console (replace the numbers with the correct IDs): ```ruby theme={null} PlatformAppPermissible.create!(platform_app: PlatformApp.find(1), permissible: Account.find(1)) ``` ### What should I do if the API documentation appears outdated? If you encounter discrepancies between the API documentation and actual API behavior, we recommend inspecting the actual requests made by the Chatwoot UI through your browser's developer console Network tab to see the exact request format and payload structure that works with the current API, then replicate the same request structure in your integration. You can contribute back by submitting a [pull request](/contributing-guide/api-documentation) with documentation corrections or by [raising an issue](https://github.com/chatwoot/chatwoot/issues) in our GitHub repository to help keep our API documentation current for everyone. # Create a label Source: https://developers.chatwoot.com/api-reference/labels/create-a-label https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/labels Create a label in the account # Delete a label Source: https://developers.chatwoot.com/api-reference/labels/delete-a-label https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/labels/{id} Delete a label from the account # Get a label Source: https://developers.chatwoot.com/api-reference/labels/get-a-label https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/labels/{id} Get the details of a label in the account # List all labels Source: https://developers.chatwoot.com/api-reference/labels/list-all-labels https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/labels List all labels available in the current account # Update a label Source: https://developers.chatwoot.com/api-reference/labels/update-a-label https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/labels/{id} Update a label's attributes # Create a message Source: https://developers.chatwoot.com/api-reference/messages-api/create-a-message https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json post /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages Create a message # List all messages Source: https://developers.chatwoot.com/api-reference/messages-api/list-all-messages https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json get /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages List all messages in the conversation # Update a message Source: https://developers.chatwoot.com/api-reference/messages-api/update-a-message https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/client_swagger.json patch /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages/{message_id} Update a message # Create New Message Source: https://developers.chatwoot.com/api-reference/messages/create-new-message https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages Create a new message in the conversation. Use `application/json` for text messages and `multipart/form-data` when the message includes file attachments. ### Multipart attachment request Send files with the `attachments[]` form field. `curl -F` sets the `multipart/form-data` content type and boundary automatically. ```bash curl -X POST "https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages" \ -H "api_access_token: " \ -F "content=Here is the screenshot" \ -F "message_type=outgoing" \ -F "private=false" \ -F "attachments[]=@/path/to/screenshot.png" ``` ## WhatsApp Template Messages For WhatsApp channels, you can send structured template messages using the `template_params` field. Templates must be pre-approved in WhatsApp Business Manager. ### Example Templates **Text with Image Header:** ```json { "content": "Hi your order 121212 is confirmed. Please wait for further updates", "template_params": { "name": "order_confirmation", "category": "MARKETING", "language": "en", "processed_params": { "body": { "1": "121212" }, "header": { "media_url": "https://picsum.photos/200/300", "media_type": "image" } } } } ``` **Text with Copy Code Button:** ```json { "content": "Special offer! Get 30% off your next purchase. Use the code below", "template_params": { "name": "discount_coupon", "category": "MARKETING", "language": "en", "processed_params": { "body": { "discount_percentage": "30" }, "buttons": [{ "type": "copy_code", "parameter": "SAVE20" }] } } } ``` # Delete a message Source: https://developers.chatwoot.com/api-reference/messages/delete-a-message https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id} Delete a message and it's attachments from the conversation. # Get messages Source: https://developers.chatwoot.com/api-reference/messages/get-messages https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages List all messages of a conversation # Fetch user profile Source: https://developers.chatwoot.com/api-reference/profile/fetch-user-profile https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/profile Get the user profile details # Update user profile Source: https://developers.chatwoot.com/api-reference/profile/update-user-profile https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json put /api/v1/profile Update the user profile details # Account Conversation Metrics Source: https://developers.chatwoot.com/api-reference/reports/account-conversation-metrics https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/reports/conversations Get conversation metrics for Account # Account Reporting Events Source: https://developers.chatwoot.com/api-reference/reports/account-reporting-events https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/reporting_events Get paginated reporting events for the account. This endpoint returns reporting events such as first response time, resolution time, and other metrics. Only administrators can access this endpoint. Results are paginated with 25 items per page. # Agent Conversation Metrics Source: https://developers.chatwoot.com/api-reference/reports/agent-conversation-metrics https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/reports/conversations/ Get conversation metrics for Agent # Get Account reports Source: https://developers.chatwoot.com/api-reference/reports/get-account-reports https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/reports Get Account reports for a specific type, metric and date range # Get Account reports summary Source: https://developers.chatwoot.com/api-reference/reports/get-account-reports-summary https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/reports/summary Get Account reports summary for a specific type and date range # Get conversation statistics grouped by agent Source: https://developers.chatwoot.com/api-reference/reports/get-conversation-statistics-grouped-by-agent https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/summary_reports/agent Get conversation statistics grouped by agent for a given date range. Returns metrics for each agent including conversation counts, resolution counts, average first response time, average resolution time, and average reply time. # Get conversation statistics grouped by channel type Source: https://developers.chatwoot.com/api-reference/reports/get-conversation-statistics-grouped-by-channel-type https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/summary_reports/channel Get conversation counts grouped by channel type and status for a given date range. Returns statistics for each channel type including open, resolved, pending, snoozed, and total conversation counts. **Note:** This API endpoint is available only in Chatwoot version 4.10.0 and above. The date range is limited to a maximum of 6 months. # Get conversation statistics grouped by inbox Source: https://developers.chatwoot.com/api-reference/reports/get-conversation-statistics-grouped-by-inbox https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/summary_reports/inbox Get conversation statistics grouped by inbox for a given date range. Returns metrics for each inbox including conversation counts, resolution counts, average first response time, average resolution time, and average reply time. # Get conversation statistics grouped by team Source: https://developers.chatwoot.com/api-reference/reports/get-conversation-statistics-grouped-by-team https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/summary_reports/team Get conversation statistics grouped by team for a given date range. Returns metrics for each team including conversation counts, resolution counts, average first response time, average resolution time, and average reply time. # Get first response time distribution by channel Source: https://developers.chatwoot.com/api-reference/reports/get-first-response-time-distribution-by-channel https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/reports/first_response_time_distribution Get the distribution of first response times grouped by channel type. Returns conversation counts in different time buckets (0-1h, 1-4h, 4-8h, 8-24h, 24h+) for each channel type. **Note:** This API endpoint is available only in Chatwoot version 4.11.0 and above. # Get inbox-label matrix report Source: https://developers.chatwoot.com/api-reference/reports/get-inbox-label-matrix-report https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/reports/inbox_label_matrix Get a matrix showing the count of conversations for each inbox-label combination. Returns a list of inboxes, labels, and a 2D matrix where each cell contains the count of conversations in a specific inbox that have a specific label applied. **Note:** This API endpoint is available only in Chatwoot version 4.11.0 and above. # Get outgoing messages count grouped by entity Source: https://developers.chatwoot.com/api-reference/reports/get-outgoing-messages-count-grouped-by-entity https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v2/accounts/{account_id}/reports/outgoing_messages_count Get the count of outgoing messages grouped by a specified entity (agent, team, inbox, or label). When grouped by agent, messages sent by bots (AgentBot, Captain::Assistant) are excluded. **Note:** This API endpoint is available only in Chatwoot version 4.11.0 and above. # Add a New Agent Source: https://developers.chatwoot.com/api-reference/teams/add-a-new-agent https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/teams/{team_id}/team_members Add a new Agent to Team # Create a team Source: https://developers.chatwoot.com/api-reference/teams/create-a-team https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/teams Create a team in the account # Delete a team Source: https://developers.chatwoot.com/api-reference/teams/delete-a-team https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/teams/{team_id} Delete a team from the account # Get a team details Source: https://developers.chatwoot.com/api-reference/teams/get-a-team-details https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/teams/{team_id} Get the details of a team in the account # List Agents in Team Source: https://developers.chatwoot.com/api-reference/teams/list-agents-in-team https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/teams/{team_id}/team_members Get Details of Agents in an Team # List all teams Source: https://developers.chatwoot.com/api-reference/teams/list-all-teams https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/teams List all teams available in the current account # Remove an Agent from Team Source: https://developers.chatwoot.com/api-reference/teams/remove-an-agent-from-team https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/teams/{team_id}/team_members Remove an Agent from Team # Update a team Source: https://developers.chatwoot.com/api-reference/teams/update-a-team https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/teams/{team_id} Update a team's attributes # Update Agents in Team Source: https://developers.chatwoot.com/api-reference/teams/update-agents-in-team https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/teams/{team_id}/team_members All agents except the one passed in params will be removed # Create a User Source: https://developers.chatwoot.com/api-reference/users/create-a-user https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json post /platform/api/v1/users Create a User # Delete a User Source: https://developers.chatwoot.com/api-reference/users/delete-a-user https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json delete /platform/api/v1/users/{id} Delete a User # Get an user details Source: https://developers.chatwoot.com/api-reference/users/get-an-user-details https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json get /platform/api/v1/users/{id} Get the details of an user # Get User SSO Link Source: https://developers.chatwoot.com/api-reference/users/get-user-sso-link https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json get /platform/api/v1/users/{id}/login Get the sso link of a user # Update a user Source: https://developers.chatwoot.com/api-reference/users/update-a-user https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/platform_swagger.json patch /platform/api/v1/users/{id} Update a user's attributes # Add a webhook Source: https://developers.chatwoot.com/api-reference/webhooks/add-a-webhook https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json post /api/v1/accounts/{account_id}/webhooks Add a webhook subscription to the account # Delete a webhook Source: https://developers.chatwoot.com/api-reference/webhooks/delete-a-webhook https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json delete /api/v1/accounts/{account_id}/webhooks/{webhook_id} Delete a webhook from the account # List all webhooks Source: https://developers.chatwoot.com/api-reference/webhooks/list-all-webhooks https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json get /api/v1/accounts/{account_id}/webhooks List all webhooks in the account # Update a webhook object Source: https://developers.chatwoot.com/api-reference/webhooks/update-a-webhook-object https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json patch /api/v1/accounts/{account_id}/webhooks/{webhook_id} Update a webhook object in the account # Chatwoot CLI Source: https://developers.chatwoot.com/cli Install and configure the Chatwoot CLI to manage your inbox from the terminal. A terminal client for Chatwoot. Most things you'd do in the agent dashboard (read conversations, reply, assign, resolve) work as commands you can script or pipe into other tools. You can also search help center articles from the terminal. It's handy with coding agents: tools like Claude Code or Cursor can call `chatwoot` directly to look up conversations, post replies, search help center content when asked, or automate repetitive triage, without needing a custom integration. * **[Commands](/cli/commands)** — the full command reference: conversations, contacts, inboxes, agents, help centers. * **[Scripting & output](/cli/scripting)** — JSON / CSV / quiet mode, shell completions, automation recipes. ## Install ```bash theme={null} # macOS / Linux curl -fsSL https://chwt.app/install-cli | sh ``` Installs to `~/.local/bin/chatwoot`. Override with `CHATWOOT_VERSION` or `CHATWOOT_INSTALL_DIR`: ```bash theme={null} CHATWOOT_VERSION=v0.2.0 CHATWOOT_INSTALL_DIR=/usr/local/bin curl -fsSL https://chwt.app/install-cli | sh ``` **Windows:** download `chatwoot__Windows_x86_64.zip` from the [releases page](https://github.com/chatwoot/cli/releases/latest) and extract `chatwoot.exe`. **From source** (Go 1.25+): ```bash theme={null} go install github.com/chatwoot/cli/cmd/chatwoot@latest ``` ## Log in ```bash theme={null} chatwoot auth login ``` You'll be asked for: * **Base URL** — your Chatwoot instance, e.g. `https://app.chatwoot.com` * **API Key** — from your agent profile → API access token * **Account ID** — the number in your dashboard URL Credentials are validated before saving. The API key is stored in your OS keyring; non-secret config lives at `~/.chatwoot/config.yaml`. For CI or headless use, set `CHATWOOT_API_KEY` to override the saved token. ```bash theme={null} chatwoot auth status # who am I, which instance chatwoot auth logout # remove saved credentials chatwoot config view # show config and credential source ``` ## Shell completions The install script offers to set this up interactively. To do it manually: ```bash theme={null} # bash chatwoot completion bash -c > ~/.local/share/bash-completion/completions/chatwoot # fish chatwoot completion fish -c > ~/.config/fish/completions/chatwoot.fish # zsh — append a source line to your .zshrc echo 'source <(chatwoot completion zsh -c)' >> ~/.zshrc ``` Restart your shell (or `source` your rc file). Tab-completion works for commands, subcommands, and flags. Run `chatwoot completion --help` for details. ## Help ```bash theme={null} chatwoot --help chatwoot conv --help chatwoot convs --help chatwoot hc --help ``` Issues and feedback: [github.com/chatwoot/cli](https://github.com/chatwoot/cli). ## Uninstalling ```bash theme={null} chatwoot auth logout # remove API key from the OS keyring rm -rf ~/.chatwoot # delete config (~/.chatwoot/config.yaml) rm "$(command -v chatwoot)" # delete the binary ``` If you set up shell completions, also remove them: ```bash theme={null} rm -f ~/.local/share/bash-completion/completions/chatwoot # bash rm -f ~/.config/fish/completions/chatwoot.fish # fish # zsh: delete the `source <(... completion zsh -c)` line from ~/.zshrc ``` On Windows, delete the extracted `chatwoot.exe` and the `%USERPROFILE%\.chatwoot` folder. If `CHATWOOT_API_KEY` is set in your environment, unset it in your shell rc — `auth logout` can't remove env-provided credentials. # Agent skill Source: https://developers.chatwoot.com/cli/agent-skill Install the Chatwoot CLI agent skill so coding tools like Claude Code, Cursor, and Codex can use chatwoot effectively. The Chatwoot CLI ships with an [agent skill](https://skills.sh) — a small instruction file that teaches AI coding tools (Claude Code, Cursor, Codex, Gemini CLI, and 50+ others) how to use `chatwoot` correctly. With the skill installed, a prompt like *"find conversations tagged refund and assign the unassigned ones to me"* runs the right commands, parses JSON properly, and pauses for confirmation before sending customer-visible replies. It can also search help center articles when you explicitly ask for knowledge-base context. ## Install The skill is published in the [chatwoot/cli](https://github.com/chatwoot/cli) repository. Use the [skills CLI](https://skills.sh) to install it into whichever AI tool you use: ```bash theme={null} npx skills add chatwoot/cli ``` The skills CLI auto-detects the coding agents you have installed and offers to install the skill into each. Add `--global` (or `-g`) to install the skill once for every project: ```bash theme={null} npx skills add chatwoot/cli --global ``` The skill activates automatically when you ask the agent to do something Chatwoot-related — *"triage my inbox"*, *"reply to conv 123"*, *"find conversations tagged refund"*, *"search the help center for API channel docs"*. ## Authenticate the agent Coding agents run commands non-interactively, so `chatwoot auth login` has to be run separately. In certain scenarios, agents might be run in a sandbox environment so the API token may not be accessible to them. In this case, you can set the `CHATWOOT_API_KEY` in your shell or the agent's environment: ```bash theme={null} export CHATWOOT_API_KEY=your_token_here ``` ## What the skill teaches the agent * **The id-first grammar** — `chatwoot conv 123 reply "..."` instead of guessing flag layouts. * **The output contract** — parse `-o json`, never the human-readable text format. * **Help center lookup** — use `hc articles` and `hc article` when the user asks for help center content, without making it the default step for ordinary triage. * **Safety rules** — `reply` is customer-visible and irreversible, so the agent shows the full text and asks before sending. * **Common pitfalls** — `label` replaces rather than appends, `--query` searches message content (not contacts), `assign --agent ` is a case-insensitive substring match, list endpoints paginate. * **Composable patterns** — `-q | xargs` for bulk operations, `jq` chaining for lookups, and `chatwoot api` for authenticated raw API reads when no first-class command exists. The full skill source lives at [chatwoot/cli/skills/chatwoot-cli](https://github.com/chatwoot/cli/tree/main/skills/chatwoot-cli) read it directly to see exactly what behavior is shaped. ## Example prompts Once the skill is installed, prompts like these work without further setup: * *"What's in my open inbox today? Group by priority."* * *"Find conversations tagged `refund` that have been pending for more than 48 hours and assign them to Alice."* * *"Read the last five messages on conv 412 and draft a reply — show it to me before sending."* * *"Search the help center for API channel setup docs."* * *"Resolve every open conversation tagged `spam`."* The agent composes `chatwoot` commands, parses JSON, and stops to confirm before any write that affects customers. For raw API calls, agents should check the application Swagger first: [application\_swagger.json](https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json). ## Remove the skill ```bash theme={null} npx skills remove chatwoot-cli # all agents npx skills remove chatwoot-cli --agent claude-code # one agent ``` # CLI Commands Source: https://developers.chatwoot.com/cli/commands Learn the Chatwoot CLI command grammar and commonly used commands. Full command reference. New here? Start with **[Getting started](/cli)**. For output formats and automation, see **[Scripting & output](/cli/scripting)**. ## Grammar at a glance * **Plural noun = list:** `chatwoot convs`, `chatwoot contacts`, `chatwoot agents` * **Singular + id = view:** `chatwoot conv 123` shows conversation 123 * **Singular + id + verb = act:** `chatwoot conv 123 reply "thanks"` — id before verb, the way you'd say it Verb-first form (`chatwoot conv reply 123 "thanks"`) also works. ## Conversations ### List ```bash theme={null} chatwoot convs # open conversations assigned to you (default) chatwoot convs -s resolved # by status: open | resolved | pending | snoozed chatwoot convs --assignee all # me (default) | unassigned | all | | chatwoot convs --inbox 5 # filter by inbox ID chatwoot convs -l billing,urgent # filter by labels chatwoot convs --query "refund" # search by message content ``` ### Act on one ```bash theme={null} chatwoot conv 123 # view (default) chatwoot conv 123 messages # list messages ``` **Reply:** ```bash theme={null} chatwoot conv 123 reply "Thanks, looking into it" chatwoot conv 123 reply "internal note" --private ``` **Status:** ```bash theme={null} chatwoot conv 123 resolve chatwoot conv 123 open chatwoot conv 123 pending chatwoot conv 123 snooze # snooze until next reply chatwoot conv 123 snooze --until 24h # 7d, 2026-05-10, ... ``` **Assignment:** ```bash theme={null} chatwoot conv 123 assign --agent me # yourself chatwoot conv 123 assign --agent alice # case-insensitive substring on name chatwoot conv 123 assign --agent 42 # by agent ID chatwoot conv 123 assign --team 7 # assign to a team chatwoot conv 123 unassign ``` **Labels & priority:** ```bash theme={null} chatwoot conv 123 label billing,urgent # sets labels (replaces existing) chatwoot conv 123 priority urgent # urgent | high | medium | low | none ``` **Contact:** ```bash theme={null} chatwoot conv 123 contact # view the contact (sender) for this conversation ``` ## Contacts ```bash theme={null} chatwoot contacts # list chatwoot contacts --search "john" # name, email, or phone chatwoot contact 456 # view chatwoot contact 456 conversations # this contact's conversations ``` ## Inboxes, agents, labels, teams ```bash theme={null} chatwoot inboxes # list inboxes chatwoot inbox 5 # view one chatwoot agents # list agents chatwoot labels # list account-level labels chatwoot teams # list teams ``` ## Help centers `hc articles` uses the saved default help center and locale. Pass `--portal` or `--locale` when you want to override them for one command. ```bash theme={null} chatwoot hcs # list help centers chatwoot hc default user-guide # save default help center and locale chatwoot hc default # show current default chatwoot hc default --clear # clear current default chatwoot hc articles --query "api channel" # search articles chatwoot hc articles --category channels # list/search within a category chatwoot hc article 1677839703-how-to-create-an-api-channel-inbox chatwoot hc articles --portal user-guide --locale en ``` ## Profile ```bash theme={null} chatwoot me # your profile (alias of auth status) chatwoot whoami # same ``` ## Raw API Use `chatwoot api` for authenticated API calls that do not have a first-class CLI command yet. Account-relative paths are expanded under `/api/v1/accounts/`, so do not include the `/api/v1/accounts/...` prefix. ```bash theme={null} chatwoot api /conversations/123 # GET /api/v1/accounts//conversations/123 chatwoot api -X PATCH /conversations/123 --data '{"status":"open"}' chatwoot api --exact /api/v1/profile # non-account-scoped endpoint ``` Use the application Swagger as the endpoint reference before raw API calls: [application\_swagger.json](https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json). ## Auth & config ```bash theme={null} chatwoot auth login # interactive login (caches user_id) chatwoot auth logout # remove saved credentials chatwoot auth status # current user and instance chatwoot config path # print config file path chatwoot config view # print config and credential source ``` ## Version ```bash theme={null} chatwoot version # print the CLI version chatwoot version --check # check GitHub for a newer release chatwoot --version # same as `version`, as a flag ``` ## Global flags | Flag | Short | Description | | ------------ | ----- | ------------------------------------ | | `--output` | `-o` | Output format: `text`, `json`, `csv` | | `--account` | `-a` | Override account ID | | `--quiet` | `-q` | Print only IDs (for scripting) | | `--no-color` | | Disable colored output | | `--verbose` | `-v` | Show request/response details | | `--version` | | Print version | For pipelines and exports using these flags, see **[Scripting & output](/cli/scripting)**. # CLI Scripting Source: https://developers.chatwoot.com/cli/scripting Use Chatwoot CLI output formats and shell recipes to automate support workflows. Everything for automating chatwoot-cli: output formats and headless/CI use. Need a command? See **[Commands](/cli/commands)**. For shell completion setup, see **[Getting started](/cli#shell-completions)**. ## Output formats Every command takes `-o` / `--output`: | Format | Flag | Use it for | | ---------- | ---------------- | --------------------------------- | | Text table | *(default)* | reading at a glance | | JSON | `-o json` | piping to `jq`, full API response | | CSV | `-o csv` | spreadsheets, data exports | | IDs only | `-q` / `--quiet` | shell pipelines | ### Text (default) Human-readable tables: ``` ID Status Contact Assignee Inbox 194 open Jane Doe Shivam Mishra WebWidget 197 open Vinay K Shivam Mishra Whatsapp ``` ### JSON Full API response, ready for `jq`: ```bash theme={null} chatwoot convs -o json | jq '.data.payload[].id' chatwoot conv 123 -o json | jq '.assignee.name' ``` ### CSV ```bash theme={null} chatwoot agents -o csv > agents.csv chatwoot convs --assignee all -o csv > "convs-$(date +%F).csv" ``` ### Quiet — IDs only `-q` prints just the IDs, one per line — perfect for `xargs`: ```bash theme={null} chatwoot convs -q | xargs -I{} chatwoot conv {} resolve ``` ## Headless / CI use The OS keyring isn't available in most CI environments. Set `CHATWOOT_API_KEY` to override the saved token: ```bash theme={null} export CHATWOOT_API_KEY=your_token_here chatwoot convs --assignee all -o json ``` Combine with `--account` to target a specific account: ```bash theme={null} chatwoot --account 42 convs -o csv > convs.csv ``` Add `-v` / `--verbose` to print every HTTP request and response to stderr — handy when something looks wrong. ## Tips * `-q` is your friend — every list command supports it, every `xargs` pipeline starts with it. * Pipe to `jq` early and aggressively; `-o json` returns the full Chatwoot response, not a slimmed-down view. * Use `--no-color` when redirecting text output to a file or another program that doesn't strip ANSI codes. * `chatwoot --help` and `chatwoot --help` are exhaustive — the CLI's help is generated from the same definitions that drive the binary. # Contributing to Chatwoot Source: https://developers.chatwoot.com/contributing-guide Complete guide to contributing to Chatwoot - from setting up your development environment to submitting pull requests. # Contributing Guide Thank you for taking an interest in contributing to Chatwoot! This guide will help you get started with contributing to our open-source customer support platform. Before submitting your contribution, please make sure to take a moment and read through the following guidelines. ## Getting Started Before starting your work, ensure an issue exists for it. If not, feel free to create one. You can also take a look into the issues tagged [Good first issues](https://github.com/chatwoot/chatwoot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). ### Initial Steps 1. **Check for Existing Issues**: Browse the [GitHub issues](https://github.com/chatwoot/chatwoot/issues) to see if someone is already working on what you want to contribute. 2. **Comment on the Issue**: Add a comment on the issue and wait for the issue to be assigned before you start working on it. * This helps to avoid multiple people working on similar issues. 3. **Propose Complex Solutions**: If the solution is complex, propose the solution on the issue and wait for one of the core contributors to approve before going into the implementation. * This helps in shorter turn around times in merging PRs. 4. **Justify New Features**: For new feature requests, provide a convincing reason to add this feature. Real-life business use-cases will be super helpful. 5. **Join the Community**: Feel free to join our [Discord community](https://discord.com/invite/cJXdrwS) if you need further discussions with the core team. ## Pull Request Guidelines We use git-flow branching model. The base branch is `develop`. Please raise your PRs against the `develop` branch. ### Before Submitting * Please make sure that you have read the [issue triage guidelines](https://www.chatwoot.com/hc/handbook/articles/issue-triage-29) before you make a contribution. * It's okay and encouraged to have multiple small commits as you work on the PR - we will squash the commits before merging. * For other guidelines, see [PR Guidelines](https://www.chatwoot.com/hc/handbook/articles/pull-request-guidelines-32) * Ensure that all the text copies that you add into the product are i18n translatable. You are only required to add the `English` version of the strings. We pull in other language translations from our contributors on crowdin. See [Translation guidelines](/contributing-guide/translation-guidelines) to learn more. ## Development Workflow ### Developing a New Feature ```bash theme={null} # Create a branch in the following format: feature/- # Example: feature/235-contact-panel ``` **Requirements:** * Add accompanying test cases * Follow our coding standards * Include proper documentation ### Bug Fixes or Chores ```bash theme={null} # Branch naming for bug fixes: fix/- # Branch naming for chores: chore/ ``` **Requirements:** * If you are resolving a particular issue, add `fix: Fixes xxxx` (#xxxx is the issue) in your PR title * Provide a detailed description of the bug in the PR * Add appropriate test coverage if applicable ## Environment Setup Choose the guide that matches your operating system: Complete setup guide for macOS developers Step-by-step Ubuntu installation guide Windows 10/11 development environment setup Quick setup using Docker containers ### Speed Up Development Use our [Make commands](/contributing-guide/environment-setup/make) to speed up your local development workflow. ## Project Setup Once you have set up the environment, follow these guides to get Chatwoot running locally: 1. **[Quick Setup Guide](/contributing-guide/setup-guide)** - Step-by-step setup instructions 2. **[Environment Variables](/contributing-guide/environment-variables)** - Configuration options 3. **[Common Errors](/contributing-guide/common-errors)** - Troubleshooting guide ### Special App Integrations If you're working on specific integrations: * **[Telegram App Setup](/contributing-guide/telegram-channel-setup)** * **[Line App Setup](/contributing-guide/line-channel-setup)** * **[Mobile App Development](/contributing-guide/mobile-app)** ## Testing Your Contributions We use comprehensive testing to ensure code quality: ### Test Types * **Unit Tests**: Test individual components and functions * **Integration Tests**: Test component interactions * **End-to-End Tests**: Test complete user workflows with [Cypress](/contributing-guide/tests/cypress) ### Running Tests ```bash theme={null} # Run all tests bundle exec rspec # Run specific test file bundle exec rspec spec/models/user_spec.rb # Run Cypress tests npm run cypress:open ``` ## Documentation and Translation ### Documentation Guidelines * Keep documentation clear and concise * Include code examples where helpful * Update documentation when changing functionality * Follow our [translation guidelines](/contributing-guide/translation-guidelines) ### Internationalization * All user-facing text must be translatable * Only add English strings - other languages are handled via [Crowdin](https://translate.chatwoot.com/) * Use proper i18n keys and formatting ## Community Guidelines We strive to maintain a welcoming and inclusive community: * **[Code of Conduct](/contributing-guide/code-of-conduct)** - Our community standards * **[Community Guidelines](/contributing-guide/community-guidelines)** - How we interact * **[Security Reports](/contributing-guide/security-reports)** - Reporting security issues ## API Development If you're working on API-related features: * **[Chatwoot APIs](/contributing-guide/chatwoot-apis)** - API development guide * **[API Documentation](/contributing-guide/api-documentation)** - Documenting APIs * **[Platform APIs](/contributing-guide/chatwoot-platform-apis)** - Platform-level APIs ## Recognition We value all contributions to Chatwoot. Check out our [Contributors page](/contributing-guide/contributors) to see the amazing people who have helped make Chatwoot better. ## Getting Help Need assistance? Here are your options: * **GitHub Issues**: For bug reports and feature requests * **Discord Community**: For real-time discussions with the core team * **Documentation**: Comprehensive guides and API references * **Community Forums**: Connect with other contributors *** Ready to start contributing? Pick an issue that interests you and follow our guidelines above. Every contribution, no matter how small, helps make Chatwoot better for everyone! 🚀 # API Documentation Source: https://developers.chatwoot.com/contributing-guide/api-documentation Chatwoot uses [Swagger 2.0](https://swagger.io/specification/v2/) for documenting the API. ### File/Directory structure ```bash theme={null} - swagger/ ### folder in which all the API documentation is available - definitions/ - parameters/ - paths/ - index.yml - swagger.json ``` ### Build Swagger files A rake task is available to build `swagger.json` file after you have made changes to the swagger directory. ```bash theme={null} rake swagger:build ``` ### Testing In development mode, `http://localhost:3000/swagger` is available to test whether the API changes has been updated. # Chatwoot APIs Source: https://developers.chatwoot.com/contributing-guide/chatwoot-apis Chatwoot provides three types of APIs. This distinction is primarily based on the specific use cases for which these APIs are designed. 1. [Application APIs](#application-apis) 2. [Client APIs](#client-apis) 3. [Platform APIs](#platform-apis) Ref: [Chatwoot API Docs](https://www.chatwoot.com/developers/api/) ## Application APIs Application APIs are designed to interact with a Chatwoot account from a user's perspective. These APIs will help in building integrations for the support agents, bulk import/export of data into a Chatwoot account etc. To authenticate to this API, you will require a user `access_token`, which can be obtained from `profile_settings` after logging into your Chatwoot account. These APIs are available on both `cloud` and `self-hosted` Chatwoot Accounts. Ref: [Postman Collection](https://www.postman.com/chatwoot/workspace/chatwoot-apis/collection/162770-a7462388-50fd-4035-9bfc-5750f91c00cd) ### Example Implementations * [https://github.com/chatwoot/google-cloud-functions-demo](https://github.com/chatwoot/google-cloud-functions-demo) ## Client APIs The client APIs allow users to build custom conversational interfaces over Chatwoot. Not happy with the native Chatwoot Website widget? Want to create a customer Chat support option right into your mobile app? Client APIs are here to help. Client APIs use a combination of `inbox_identifier` and `contact_identifier` for authentication. The `inbox_identifier` can be obtained from the Settings->Configuration of API inboxes in Chatwoot. The `contact_identifier` can be obtained from the server on successful contact Create API requests, which can be cached to perform subsequent requests on behalf of the contact. These APIs are available on both `cloud` and `self-hosted` Chatwoot Accounts. Ref: [Postman Collection](https://www.postman.com/chatwoot/workspace/chatwoot-apis/collection/162770-9b283c34-96a9-494f-bb52-c5c6ab864a4a) ### Example Implementations * [https://github.com/chatwoot/client-api-demo](https://github.com/chatwoot/client-api-demo) * [https://github.com/chatwoot/chatwoot-flutter-sdk](https://github.com/chatwoot/chatwoot-flutter-sdk) ## Platform APIs The installation admin can use these APIs to manage users, accounts, and roles. These APIs could also be used to sync auth information from external systems into chatwoot. These APIs are particularly helpful if you plan to build a conversation management interface into your existing software stack. > **Note:** Platform APIs cannot access accounts or users created via the Chatwoot UI, or by other API keys. They can only access accounts, users, and other objects created by the specific platform API key used for authentication, or objects explicitly permitted to that API key. To authenticate these APIs, you must have an `access_token` issued on behalf of a `Platform app`. You can create a Platform App from [Super Admin Console](/self-hosted/monitoring/super-admin-sidekiq/). The access\_token can also be obtained from the `Access Tokens` tab in [Super Admin Console](/self-hosted/monitoring/super-admin-sidekiq/). These APIs are available on `self-hosted` Chatwoot installations. Ref: [Postman Collection](https://www.postman.com/chatwoot/workspace/chatwoot-apis/collection/162770-e5451b69-9f97-489b-b352-4ca7d8d82aff) ### FAQ #### Why do I get a 401 'Non permissible resource' error when using Platform API tokens? Platform APIs cannot access accounts or users created via the Chatwoot UI, or by other API keys. They can only access accounts, users, and other objects created by the same API key, or objects explicitly permitted to that API key. If you need to grant a Platform App access to an object (such as an Account) that it did not create, you can manually add the permission using the following command in a Rails console (replace the numbers with the correct IDs): ```ruby theme={null} PlatformAppPermissible.create!(platform_app: PlatformApp.find(1), permissible: Account.find(1)) ``` #### What should I do if the API documentation appears outdated? If you encounter discrepancies between the API documentation and actual API behavior, we recommend inspecting the actual requests made by the Chatwoot UI through your browser's developer console Network tab to see the exact request format and payload structure that works with the current API, then replicate the same request structure in your integration. You can contribute back by submitting a [pull request](/contributing-guide/api-documentation) with documentation corrections or by [raising an issue](https://github.com/chatwoot/chatwoot/issues) in our GitHub repository to help keep our API documentation current for everyone. # Chatwoot Platform APIs Source: https://developers.chatwoot.com/contributing-guide/chatwoot-platform-apis # Chatwoot Platform APIs The Chatwoot Platform APIs allow you to integrate a conversation management interface into your existing software stack. Installation admins can use these APIs to manage users, accounts, and roles. Additionally, these APIs can be used to sync authentication information from external systems into Chatwoot. > **Note:** These APIs are available only on `self-hosted` Chatwoot installations. ## Creating a Platform App To create a platform app, follow these steps: 1. Go to the super admin portal and navigate to `super_admin/platform_apps`. Super Admin Portal 2. Click on the "New platform app" button. Platform Apps Home 3. Fill in the platform app name and click the "Create" button. Create Platform App 4. After creating the platform app, open it to view and copy the access token. Platform App Access Token ## Using the Access Token The `access_token` is required to authenticate all API requests. Please use the Postman collection to test these APIs. ### Testing the APIs To test the APIs: 1. Copy the access token from the platform app. 2. Use it in the `Authorization` header of your API requests. Here's an example of creating a user using the API: Create User API Similarly, you can create `Account` and `Role` entities using the APIs. ## Reference For more detailed information and to test the APIs, refer to our [Postman Collection](https://www.postman.com/chatwoot/workspace/chatwoot-apis/collection/162770-e5451b69-9f97-489b-b352-4ca7d8d82aff). # Contributor Covenant Code of Conduct Source: https://developers.chatwoot.com/contributing-guide/code-of-conduct Code of conduct for Chatwoot community members and contributors # Contributor Covenant Code of Conduct ## Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. ## Our Standards Examples of behavior that contributes to a positive environment for our community include: * Demonstrating empathy and kindness toward other people * Being respectful of differing opinions, viewpoints, and experiences * Giving and gracefully accepting constructive feedback * Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience * Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: * The use of sexualized language or imagery, and sexual attention or advances of any kind * Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment * Publishing others' private information, such as a physical or email address, without their explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. ## Scope This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at **[hello@chatwoot.com](mailto:hello@chatwoot.com)**. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. ## Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: ### 1. Correction **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. **Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. ### 2. Warning **Community Impact**: A violation through a single incident or series of actions. **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. ### 3. Temporary Ban **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. ### 4. Permanent Ban **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at [https://www.contributor-covenant.org/version/2/0/code\_of\_conduct.html](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html). Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). *** By participating in the Chatwoot community, you agree to abide by this Code of Conduct. Thank you for helping us create a welcoming and inclusive environment for everyone. # Common Errors and Solutions Source: https://developers.chatwoot.com/contributing-guide/common-errors Troubleshooting guide for common errors during Chatwoot development setup # Common Errors and Solutions This guide covers the most common errors encountered during Chatwoot development setup and their solutions. Use this as a quick reference when troubleshooting issues. ## Installation and Setup Errors ### Ruby and Bundler Issues **Error Message**: ``` An error occurred while installing pg (1.5.4), and Bundler cannot continue. Make sure that `gem install pg -v '1.5.4'` succeeds before bundling. ``` **Cause**: Missing PostgreSQL development headers or incorrect pg\_config path. **Solutions**: ```bash theme={null} # Install PostgreSQL with Homebrew brew install postgresql # Configure bundle to use correct pg_config bundle config build.pg --with-pg-config=/opt/homebrew/bin/pg_config # For Intel Macs bundle config build.pg --with-pg-config=/usr/local/bin/pg_config # Retry bundle install bundle install ``` ```bash theme={null} # Install PostgreSQL development headers sudo apt-get update sudo apt-get install libpq-dev postgresql-client # Install build essentials sudo apt-get install build-essential # Retry bundle install bundle install ``` ```bash theme={null} # Install PostgreSQL development packages sudo yum install postgresql-devel # Install development tools sudo yum groupinstall "Development Tools" # Retry bundle install bundle install ``` **Error Message**: ``` Your Ruby version is 3.1.0, but your Gemfile specified 3.3.3 ``` **Cause**: Wrong Ruby version installed. **Solutions**: ```bash theme={null} # Install correct Ruby version rbenv install 3.3.3 # Set as global version rbenv global 3.3.3 # Verify version ruby --version # Rehash to update shims rbenv rehash ``` ```bash theme={null} # Install correct Ruby version rvm install 3.3.3 # Use the version rvm use 3.3.3 --default # Verify version ruby --version ``` ```bash theme={null} # Install correct Ruby version asdf install ruby 3.3.3 # Set as global version asdf global ruby 3.3.3 # Verify version ruby --version ``` **Error Message**: ``` Bundler could not find compatible versions for gem "bundler" ``` **Cause**: Incompatible Bundler version. **Solution**: ```bash theme={null} # Check current Bundler version bundler --version # Install specific Bundler version (check Gemfile.lock) gem install bundler:2.4.22 # Update Bundler gem update bundler # Clean bundle cache bundle clean --force # Retry installation bundle install ``` ### Node.js and Package Manager Issues **Error Message**: ``` error @chatwoot/chatwoot@1.0.0: The engine "node" is incompatible with this module. ``` **Cause**: Wrong Node.js version. **Solutions**: ```bash theme={null} # Install correct Node.js version nvm install 20 # Use the version nvm use 20 # Set as default nvm alias default 20 # Verify version node --version ``` ```bash theme={null} # Install correct Node.js version n 20 # Verify version node --version ``` ```bash theme={null} # Install correct Node.js version asdf install nodejs 20.10.0 # Set as global version asdf global nodejs 20.10.0 # Verify version node --version ``` **Error Message**: ``` pnpm: command not found ``` **Cause**: pnpm not installed. **Solutions**: ```bash theme={null} # Install pnpm globally npm install -g pnpm # Or using corepack (Node.js 16.10+) corepack enable corepack prepare pnpm@latest --activate # Or using Homebrew (macOS) brew install pnpm # Verify installation pnpm --version ``` **Error Message**: ``` ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies ``` **Cause**: Peer dependency conflicts or corrupted cache. **Solutions**: ```bash theme={null} # Clear pnpm cache pnpm store prune # Remove node_modules and lock file rm -rf node_modules pnpm-lock.yaml # Reinstall with legacy peer deps pnpm install --legacy-peer-deps # Or force installation pnpm install --force # Alternative: use npm npm install ``` ## Database Errors ### PostgreSQL Connection Issues **Error Message**: ``` PG::ConnectionBad: could not connect to server: Connection refused ``` **Cause**: PostgreSQL service not running or incorrect connection parameters. **Solutions**: ```bash theme={null} # Check if PostgreSQL is running brew services list | grep postgresql # Start PostgreSQL brew services start postgresql # Check connection psql postgres -c "SELECT 1;" # If user doesn't exist, create it createuser -s chatwoot ``` ```bash theme={null} # Check PostgreSQL status sudo systemctl status postgresql # Start PostgreSQL sudo systemctl start postgresql sudo systemctl enable postgresql # Switch to postgres user and create chatwoot user sudo -u postgres createuser -s chatwoot # Set password for chatwoot user sudo -u postgres psql -c "ALTER USER chatwoot PASSWORD 'password';" ``` ```bash theme={null} # Start PostgreSQL container docker run --name postgres-chatwoot \ -e POSTGRES_USER=chatwoot \ -e POSTGRES_PASSWORD=password \ -e POSTGRES_DB=chatwoot_development \ -p 5432:5432 \ -d postgres:15 # Check if container is running docker ps | grep postgres ``` **Error Message**: ``` ActiveRecord::NoDatabaseError: FATAL: database "chatwoot_development" does not exist ``` **Cause**: Database not created. **Solution**: ```bash theme={null} # Create databases bundle exec rails db:create # If that fails, create manually createdb chatwoot_development createdb chatwoot_test # Or using psql psql postgres -c "CREATE DATABASE chatwoot_development;" psql postgres -c "CREATE DATABASE chatwoot_test;" ``` **Error Message**: ``` ActiveRecord::PendingMigrationError: Migrations are pending ``` **Cause**: Database schema is not up to date. **Solutions**: ```bash theme={null} # Run pending migrations bundle exec rails db:migrate # If migrations fail, check status bundle exec rails db:migrate:status # Reset database (WARNING: destroys data) bundle exec rails db:drop db:create db:migrate db:seed # For specific migration issues bundle exec rails db:migrate:up VERSION=20231201000000 ``` ### Redis Connection Issues **Error Message**: ``` Redis::CannotConnectError: Error connecting to Redis on localhost:6379 ``` **Cause**: Redis service not running. **Solutions**: ```bash theme={null} # Check if Redis is running brew services list | grep redis # Start Redis brew services start redis # Test connection redis-cli ping ``` ```bash theme={null} # Check Redis status sudo systemctl status redis # Start Redis sudo systemctl start redis sudo systemctl enable redis # Test connection redis-cli ping ``` ```bash theme={null} # Start Redis container docker run --name redis-chatwoot \ -p 6379:6379 \ -d redis:7-alpine # Test connection docker exec redis-chatwoot redis-cli ping ``` ## Application Runtime Errors ### Rails Server Issues **Error Message**: ``` Address already in use - bind(2) for "127.0.0.1" port 3000 ``` **Cause**: Another process is using port 3000. **Solutions**: ```bash theme={null} # Find process using port 3000 lsof -ti:3000 # Kill the process kill -9 $(lsof -ti:3000) # Or use a different port bundle exec rails server -p 3001 # Check what's running on the port netstat -tulpn | grep :3000 ``` **Error Message**: ``` ArgumentError: Missing `secret_key_base` for 'development' environment ``` **Cause**: SECRET\_KEY\_BASE not set in environment. **Solution**: ```bash theme={null} # Generate a new secret key bundle exec rails secret # Add to .env file echo "SECRET_KEY_BASE=$(bundle exec rails secret)" >> .env # Or set temporarily export SECRET_KEY_BASE=$(bundle exec rails secret) bundle exec rails server ``` **Error Message**: ``` Webpacker::Manifest::MissingEntryError: Webpacker can't find application.js ``` **Cause**: Webpack assets not compiled or compilation failed. **Solutions**: ```bash theme={null} # Check if webpack dev server is running ps aux | grep webpack # Start webpack dev server pnpm run dev # Or compile assets manually bundle exec rails assets:precompile # Clear webpack cache rm -rf tmp/cache/webpacker rm -rf public/packs # Reinstall node modules rm -rf node_modules pnpm install ``` ### Sidekiq Worker Issues **Error Message**: ``` Jobs are queued but not being processed ``` **Cause**: Sidekiq worker not running. **Solutions**: ```bash theme={null} # Check if Sidekiq is running ps aux | grep sidekiq # Start Sidekiq bundle exec sidekiq # Check Sidekiq web interface open http://localhost:3000/sidekiq # Clear failed jobs bundle exec rails runner "Sidekiq::Queue.new.clear" ``` **Error Message**: ``` Redis::CommandError: OOM command not allowed when used memory > 'maxmemory' ``` **Cause**: Redis running out of memory. **Solutions**: ```bash theme={null} # Check Redis memory usage redis-cli info memory # Clear Redis cache redis-cli flushall # Increase Redis memory limit (redis.conf) # maxmemory 256mb # Or restart Redis brew services restart redis # macOS sudo systemctl restart redis # Linux ``` ## Testing Errors ### RSpec Test Failures **Error Message**: ``` ActiveRecord::StatementInvalid: PG::UndefinedTable: ERROR: relation "users" does not exist ``` **Cause**: Test database not set up properly. **Solution**: ```bash theme={null} # Prepare test database RAILS_ENV=test bundle exec rails db:create RAILS_ENV=test bundle exec rails db:migrate # Or use the combined command bundle exec rails db:test:prepare # Reset test database if needed RAILS_ENV=test bundle exec rails db:drop db:create db:migrate ``` **Error Message**: ``` FactoryBot::DuplicateDefinitionError: Factory already registered ``` **Cause**: Factory definitions loaded multiple times. **Solution**: ```bash theme={null} # Clear Spring cache bundle exec spring stop # Restart test suite bundle exec rspec # Check for duplicate factory definitions grep -r "FactoryBot.define" spec/ ``` **Error Message**: ``` Selenium::WebDriver::Error::WebDriverError: unable to connect to chromedriver ``` **Cause**: ChromeDriver not installed or incompatible version. **Solutions**: ```bash theme={null} # Install ChromeDriver # macOS brew install chromedriver # Ubuntu/Debian sudo apt-get install chromium-chromedriver # Or use webdrivers gem (should be automatic) bundle exec rails runner "Webdrivers::Chromedriver.update" # Run tests in headless mode HEADLESS=true bundle exec rspec spec/system/ ``` ## Development Environment Issues ### IDE and Editor Problems **Error**: Ruby IntelliSense not working, no syntax highlighting. **Solutions**: ```bash theme={null} # Install Ruby LSP gem install ruby-lsp # Or add to Gemfile echo 'gem "ruby-lsp", group: :development' >> Gemfile bundle install # Restart VS Code # Install recommended extensions: # - Ruby LSP # - Ruby Solargraph # - Ruby Test Explorer ``` **Error**: Ruby documentation and autocomplete not working. **Solutions**: ```bash theme={null} # Install Solargraph gem install solargraph # Generate documentation bundle exec yard gems bundle exec solargraph bundle # Create .solargraph.yml config solargraph config # Restart your editor ``` ### Git and Version Control Issues **Error**: Git commit rejected due to linting errors. **Solutions**: ```bash theme={null} # Fix RuboCop issues bundle exec rubocop -a # Fix ESLint issues pnpm run lint:fix # Format code pnpm run format # Skip hooks temporarily (not recommended) git commit --no-verify -m "Your commit message" # Update pre-commit hooks pre-commit autoupdate ``` **Error**: Git LFS or large file warnings. **Solutions**: ```bash theme={null} # Install Git LFS git lfs install # Track large files git lfs track "*.png" git lfs track "*.jpg" git lfs track "*.pdf" # Add .gitattributes git add .gitattributes # Check LFS status git lfs status ``` ## Performance Issues ### Slow Application Startup **Cause**: Large codebase, slow database, or memory issues. **Solutions**: ```bash theme={null} # Use Spring for faster Rails commands bundle exec spring binstub --all # Check Spring status bundle exec spring status # Restart Spring if needed bundle exec spring stop # Increase memory if needed export RUBY_GC_HEAP_INIT_SLOTS=10000 export RUBY_GC_HEAP_FREE_SLOTS=10000 # Profile startup time time bundle exec rails runner "puts 'Rails loaded'" ``` **Cause**: Database setup, factory creation, or inefficient tests. **Solutions**: ```bash theme={null} # Use parallel testing bundle exec rspec --parallel # Profile slow tests bundle exec rspec --profile # Use database cleaner strategies # Add to spec/rails_helper.rb: # config.use_transactional_fixtures = true # Optimize factories # Use build_stubbed instead of create when possible ``` ## Email and Communication Issues ### Email Delivery Problems **Cause**: SMTP configuration or email service issues. **Solutions**: ```bash theme={null} # Install and start MailHog brew install mailhog # macOS mailhog # Configure .env MAILER_SENDER_EMAIL=dev@chatwoot.local SMTP_ADDRESS=localhost SMTP_PORT=1025 # Check web interface open http://localhost:8025 ``` ```bash theme={null} # Add to Gemfile echo 'gem "letter_opener", group: :development' >> Gemfile bundle install # Configure in development.rb # config.action_mailer.delivery_method = :letter_opener # Emails will open in browser ``` ```bash theme={null} # Use app password, not regular password MAILER_SENDER_EMAIL=your-email@gmail.com SMTP_ADDRESS=smtp.gmail.com SMTP_PORT=587 SMTP_USERNAME=your-email@gmail.com SMTP_PASSWORD=your-app-password SMTP_DOMAIN=gmail.com SMTP_ENABLE_STARTTLS_AUTO=true ``` ### WebSocket Connection Issues **Error**: Real-time features not working, WebSocket connection failed. **Solutions**: ```bash theme={null} # Check if ActionCable is mounted grep -r "mount ActionCable" config/routes.rb # Check Redis connection redis-cli ping # Configure ActionCable for development # In config/environments/development.rb: # config.action_cable.url = "ws://localhost:3000/cable" # config.action_cable.allowed_request_origins = ["http://localhost:3000"] # Test WebSocket connection # Open browser console and check for WebSocket errors ``` ## Debugging and Logging Issues ### Log File Problems **Cause**: Excessive logging in development. **Solutions**: ```bash theme={null} # Clear log files > log/development.log > log/test.log # Configure log rotation in development.rb # config.logger = ActiveSupport::Logger.new("log/development.log", 5, 10.megabytes) # Reduce log level # config.log_level = :info # Use logrotate (Linux) sudo logrotate -f /etc/logrotate.conf ``` ### Debugging Tool Issues **Cause**: Debugger not properly configured or running in wrong context. **Solutions**: ```bash theme={null} # Make sure gems are in Gemfile echo 'gem "pry-rails", group: [:development, :test]' >> Gemfile echo 'gem "pry-byebug", group: [:development, :test]' >> Gemfile bundle install # Use correct debugger syntax # binding.pry # for Pry # debugger # for built-in debugger # byebug # for byebug # Check if running in correct environment puts Rails.env ``` ## Quick Diagnostic Commands ### System Health Check ```bash theme={null} #!/bin/bash # health_check.sh - Quick system diagnostic echo "=== Chatwoot Development Health Check ===" # Check Ruby version echo "Ruby version: $(ruby --version)" # Check Node.js version echo "Node.js version: $(node --version)" # Check database connection if bundle exec rails runner "ActiveRecord::Base.connection.execute('SELECT 1')" > /dev/null 2>&1; then echo "✅ Database connection: OK" else echo "❌ Database connection: FAILED" fi # Check Redis connection if redis-cli ping > /dev/null 2>&1; then echo "✅ Redis connection: OK" else echo "❌ Redis connection: FAILED" fi # Check if services are running echo "Running processes:" ps aux | grep -E "(rails|sidekiq|webpack|mailhog)" | grep -v grep # Check ports echo "Port usage:" lsof -i :3000,3035,6379,5432,8025 2>/dev/null || echo "No processes found on common ports" echo "=== Health Check Complete ===" ``` ### Environment Validation ```bash theme={null} #!/bin/bash # validate_env.sh - Validate development environment required_vars=( "RAILS_ENV" "DATABASE_URL" "REDIS_URL" "SECRET_KEY_BASE" "FRONTEND_URL" ) echo "=== Environment Variable Check ===" for var in "${required_vars[@]}"; do if [ -z "${!var}" ]; then echo "❌ Missing: $var" else echo "✅ Set: $var" fi done echo "=== Dependency Check ===" commands=("ruby" "node" "psql" "redis-cli" "git") for cmd in "${commands[@]}"; do if command -v $cmd > /dev/null 2>&1; then echo "✅ $cmd: $(command -v $cmd)" else echo "❌ $cmd: Not found" fi done ``` ## Getting Additional Help If you're still experiencing issues after trying these solutions: 1. **Search GitHub Issues**: Check if others have reported similar problems 2. **Check Logs**: Look at `log/development.log` for detailed error messages 3. **Discord Community**: Join the Chatwoot Discord for real-time help 4. **Documentation**: Review the official documentation 5. **Create an Issue**: If it's a bug, create a detailed GitHub issue ### Creating a Good Bug Report When reporting issues, include: ```markdown theme={null} ## Environment - OS: [e.g., macOS 13.0, Ubuntu 22.04] - Ruby version: [e.g., 3.3.3] - Node.js version: [e.g., 20.10.0] - Database: [e.g., PostgreSQL 15.0] ## Steps to Reproduce 1. Step one 2. Step two 3. Step three ## Expected Behavior What you expected to happen ## Actual Behavior What actually happened ## Error Messages Full error message and stack trace ## Additional Context Any other relevant information ``` *** This guide covers the most common development issues. For production deployment issues, see the [Self-hosted documentation](/self-hosted/). # Chatwoot Community Guidelines Source: https://developers.chatwoot.com/contributing-guide/community-guidelines Guidelines for participating in the Chatwoot community across all platforms # Chatwoot Community Guidelines Welcome to the Chatwoot community! These guidelines help ensure our community remains welcoming, productive, and inclusive for everyone. ## General Principles ### 1. Respect and Inclusivity Everyone is welcome here. Treat all members with respect, regardless of their background, identity, or level of experience. ### 2. Collaboration Over Conflict Always approach discussions and feedback with a constructive attitude. We're all here to learn and grow together. ### 3. No Spam or Self-Promotion Unsolicited advertisements, promotions, or spammy links are not allowed. Share valuable content that benefits the community. ## Platform-Specific Guidelines ### Discord-Specific Guidelines Our Discord server is where the community gathers for real-time discussions, support, and collaboration. #### Channel Etiquette 1. **Stay On Topic**: Each channel has its purpose. Ensure your discussions are relevant to the channel topic. 2. **Use Thread Responses**: For lengthy discussions, use thread replies to keep channels organized. 3. **Search Before Asking**: Check pinned messages and recent discussions before asking questions. #### Content Guidelines 1. **No NSFW Content**: This is a professional community. Do not share or promote any NSFW content. 2. **Quality Over Quantity**: Focus on helpful, meaningful contributions rather than frequent low-value messages. 3. **Appropriate Language**: Keep language professional and appropriate for a business environment. #### Voice Channels 1. **Microphone Etiquette**: Ensure your microphone is muted when not speaking. 2. **Respect Speaking Time**: Avoid interrupting others and allow everyone to participate. 3. **Background Noise**: Use push-to-talk if you're in a noisy environment. #### Reporting and Support 1. **Report Violations**: If you see someone violating these guidelines, don't engage. Instead, report it to the moderators. 2. **Use Private Messages**: For sensitive issues, reach out to moderators via private message. ### GitHub-Specific Guidelines GitHub is our primary platform for code collaboration, issue tracking, and project management. #### Issue Reporting 1. **Search First**: Before reporting a bug or requesting a feature, search the issues to ensure it hasn't been addressed already. 2. **Use Templates**: Follow the provided issue templates for bug reports and feature requests. 3. **Provide Details**: Include clear steps to reproduce, expected behavior, and actual behavior. 4. **Stay Updated**: Monitor your issues for questions from maintainers and respond promptly. #### Pull Requests 1. **Clear Descriptions**: Ensure your PRs are concise, have a clear title, and are linked to relevant issues. 2. **Follow Style Guide**: Adhere to the existing coding style and conventions. 3. **Test Thoroughly**: Test your changes in multiple scenarios before submitting. 4. **Respond to Reviews**: Address feedback constructively and make requested changes promptly. #### Code Review Guidelines 1. **Be Constructive**: Provide specific, actionable feedback rather than general criticism. 2. **Explain Reasoning**: When suggesting changes, explain why the change would improve the code. 3. **Appreciate Good Work**: Acknowledge good code and clever solutions. 4. **Stay Professional**: Keep discussions focused on the code, not the person. #### Documentation 1. **Update Documentation**: If your PR introduces a new feature, ensure that it's documented. 2. **Fix What You See**: If you spot outdated or missing documentation, consider updating it or raising an issue. 3. **Clear Examples**: Provide clear, working examples in documentation. ## Community Support ### Helping Others #### In Discord * **Be Patient**: Remember that people have different experience levels * **Provide Context**: When helping, explain not just what to do, but why * **Share Resources**: Link to relevant documentation or previous discussions * **Follow Up**: Check if your help resolved the issue #### In GitHub * **Helpful Comments**: Provide constructive feedback on issues and PRs * **Share Knowledge**: Contribute to discussions with your expertise * **Test Solutions**: Help test proposed fixes when possible ### Getting Help #### Before Asking 1. **Check Documentation**: Review the official docs first 2. **Search History**: Look through previous discussions and issues 3. **Try Solutions**: Attempt basic troubleshooting steps #### When Asking 1. **Be Specific**: Provide clear details about your issue 2. **Include Context**: Share relevant environment information 3. **Show Effort**: Explain what you've already tried 4. **Be Patient**: Allow time for community members to respond ## Consequences for Violating Guidelines We enforce these guidelines to maintain a positive community environment. ### Warning System 1. **First Violation**: For most violations, you will receive a warning from the moderators. 2. **Repeated Minor Violations**: Additional warnings may lead to temporary restrictions. ### Immediate Actions For serious violations, immediate actions may be taken: * **Spam or Self-Promotion**: Immediate ban or removal * **Harassment or Abuse**: Immediate removal from the community * **Sharing Inappropriate Content**: Content removal and potential ban ### Appeal Process If you believe you've been unfairly moderated: 1. **Contact Moderators**: Reach out via private message 2. **Provide Context**: Explain your perspective respectfully 3. **Accept Decisions**: Respect final moderation decisions Refer to [enforcement guidelines](/contributing-guide/code-of-conduct#enforcement-guidelines) for more details. ## Moderator and Admin Privileges ### Selection Process Active contributors to the Chatwoot community, those who consistently offer valuable insights, help, and engagement, may be handpicked as moderators or granted specific privileges. ### Criteria for Moderators * **Consistent Contribution**: Regular, helpful participation in the community * **Good Judgment**: Demonstrated ability to handle conflicts constructively * **Technical Knowledge**: Understanding of Chatwoot and related technologies * **Time Commitment**: Ability to dedicate time to moderation duties ### Responsibilities Moderators are expected to: * **Enforce Guidelines**: Apply community guidelines fairly and consistently * **Facilitate Discussions**: Help keep conversations productive and on-topic * **Support Users**: Provide assistance and guidance to community members * **Report Issues**: Escalate serious violations to administrators ### Discretionary Decisions * **Appointment Process**: The appointment of moderators and the granting of additional privileges are at the sole discretion of the Chatwoot team. * **Review Process**: Moderator performance is reviewed regularly to ensure community standards are maintained. ### Admin Privileges For compliance and security reasons, admin privileges in all Chatwoot communities are reserved exclusively for Chatwoot employees. ## Building a Positive Community ### Encouraging Participation * **Welcome Newcomers**: Help new members feel included and valued * **Celebrate Contributions**: Acknowledge helpful contributions and achievements * **Share Knowledge**: Contribute your expertise to help others learn * **Provide Feedback**: Offer constructive feedback on ideas and solutions ### Creating Inclusive Environment * **Use Inclusive Language**: Choose words that welcome all community members * **Respect Differences**: Value diverse perspectives and experiences * **Avoid Assumptions**: Don't assume others' backgrounds or knowledge levels * **Learn Together**: Approach discussions as learning opportunities ## Resources for Community Members ### Getting Started * **Community Onboarding**: [Discord community](https://discord.com/invite/cJXdrwS) * **Contributor Guide**: [Contributing documentation](/contributing-guide) * **Code of Conduct**: [Detailed guidelines](/contributing-guide/code-of-conduct) ### Stay Connected * **Discord Server**: Real-time community discussions * **GitHub Discussions**: Long-form technical discussions * **Twitter**: [@chatwootapp](https://twitter.com/chatwootapp) for updates * **Blog**: [Chatwoot Blog](https://www.chatwoot.com/blog) for articles and insights *** Together, we can build an amazing community that supports Chatwoot users and contributors worldwide. Thank you for being part of our journey! 🚀 # Contributors Source: https://developers.chatwoot.com/contributing-guide/contributors Meet the amazing people who contribute to Chatwoot # Contributors Chatwoot is made possible by the amazing community of developers, designers, translators, and supporters who contribute their time and expertise to make it better every day. ## Our Contributors You can find the full list of contributors at [https://contributors.chatwoot.com](https://contributors.chatwoot.com) ## Join Our Contributors Ready to make your mark on Chatwoot? Here's how to get started: ### Quick Start 1. **Star the Repository**: [Star Chatwoot on GitHub](https://github.com/chatwoot/chatwoot) 2. **Join Discord**: [Join our Discord community](https://discord.com/invite/cJXdrwS) 3. **Pick an Issue**: Find a [good first issue](https://github.com/chatwoot/chatwoot/labels/good%20first%20issue) 4. **Make Your First Contribution**: Follow our [contribution guide](/contributing-guide) ### Stay Connected * **GitHub**: [github.com/chatwoot/chatwoot](https://github.com/chatwoot/chatwoot) * **Discord**: [discord.com/invite/cJXdrwS](https://discord.com/invite/cJXdrwS) * **Twitter**: [@chatwootapp](https://twitter.com/chatwootapp) * **LinkedIn**: [Chatwoot Company Page](https://www.linkedin.com/company/chatwoot) *** Every contribution, no matter how small, makes Chatwoot better for thousands of users worldwide. Thank you for considering joining our contributor community! 🙏 # Docker Development Setup Source: https://developers.chatwoot.com/contributing-guide/environment-setup/docker Complete guide to setting up Chatwoot development environment using Docker and Docker Compose. # Docker Development Setup This guide will help you set up a complete Chatwoot development environment using Docker and Docker Compose. ## Pre-requisites Before proceeding, make sure you have the latest version of `docker` and `docker-compose` installed. As of now, we recommend a version equal to or higher than the following: ```bash theme={null} $ docker --version Docker version 25.0.4, build 1a576c5 $ docker compose --version docker-compose version 2.24.7 ``` ### Install Docker #### Windows 1. **Download Docker Desktop** from [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/) 2. **Run the installer** and follow setup instructions 3. **Enable WSL2 backend** (recommended) 4. **Restart your computer** when prompted #### macOS ```bash theme={null} # Option 1: Download from website # Go to https://www.docker.com/products/docker-desktop/ # Option 2: Using Homebrew brew install --cask docker ``` #### Linux (Ubuntu/Debian) ```bash theme={null} # Update package index sudo apt update # Install dependencies sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release # Add Docker's official GPG key curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # Add Docker repository echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # Install Docker sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # Add user to docker group sudo usermod -aG docker $USER # Start Docker service sudo systemctl start docker sudo systemctl enable docker ``` After adding yourself to the docker group on Linux, log out and log back in for the changes to take effect. ## Development Environment 1. **Clone the repository.** ```bash theme={null} git clone https://github.com/chatwoot/chatwoot.git ``` 2. **Make a copy of the example environment file and modify it as required.** ```bash theme={null} # Navigate to Chatwoot cd chatwoot cp .env.example .env # Update redis and postgres passwords nano .env # Update docker-compose.yaml with the same postgres password nano docker-compose.yaml ``` 3. **Build the images.** ```bash theme={null} # Build base image first docker compose build base # Build the server and worker docker compose build ``` 4. **After building the image or destroying the stack, you would have to reset the database using the following command.** ```bash theme={null} docker compose run --rm rails bundle exec rails db:chatwoot_prepare ``` 5. **To run the app:** ```bash theme={null} docker compose up ``` * Access the rails app frontend by visiting `http://0.0.0.0:3000/` * Access Mailhog inbox by visiting `http://0.0.0.0:8025/` (You will receive all emails going out of the application here) #### Login with credentials ``` url: http://localhost:3000 user_name: john@acme.inc password: Password1! ``` 6. **To stop the app:** ```bash theme={null} docker compose down ``` ## Running RSpec Tests For running the complete RSpec tests: ```bash theme={null} docker compose run --rm rails bundle exec rspec ``` For running specific test: ```bash theme={null} docker compose run --rm rails bundle exec rspec spec/: ``` ## Production Environment To debug the production build locally, set `SECRET_KEY_BASE` environment variable in your `.env` file and then run the below commands: ```bash theme={null} docker compose -f docker-compose.production.yaml build docker compose -f docker-compose.production.yaml up ``` ## Debugging Mode To use debuggers like `byebug` or `binding.pry`, use the following command to bring up the app instead of `docker compose up`: ```bash theme={null} docker compose run --rm --service-port rails ``` ## Development Workflow ### Daily Development Commands ```bash theme={null} # Start development environment docker compose up # View logs docker compose logs -f rails # Access Rails console docker compose exec rails bundle exec rails console # Run migrations docker compose exec rails bundle exec rails db:migrate # Install new gems docker compose exec rails bundle install # Restart a service docker compose restart rails # Stop all services docker compose down # Stop and remove volumes (reset database) docker compose down -v ``` ## Troubleshooting If there is an update to any of the following: * `dockerfile` * `gemfile` * `package.json` * schema change Make sure to rebuild the containers and run `db:reset`. ```bash theme={null} docker compose down docker compose build docker compose run --rm rails bundle exec rails db:reset docker compose up ``` ### Common Issues **Solution**: Check service dependencies and logs: ```bash theme={null} # Check service status docker compose ps # Check logs for specific service docker compose logs rails # Restart problematic service docker compose restart rails ``` **Solution**: Ensure PostgreSQL container is healthy: ```bash theme={null} # Check postgres health docker compose exec postgres pg_isready # Restart postgres if needed docker compose restart postgres ``` **Solution**: Stop other services using the same ports: ```bash theme={null} # Check what's using port 3000 lsof -i :3000 # Or change ports in docker-compose.yaml ``` **Solution**: Clean up Docker resources: ```bash theme={null} # Remove unused containers, networks, images docker system prune -f # Remove volumes (WARNING: This deletes data) docker volume prune -f # Remove everything (nuclear option) docker system prune -a --volumes ``` **Solution**: Clear Docker cache and rebuild: ```bash theme={null} # Clear build cache docker builder prune # Rebuild without cache docker compose build --no-cache ``` ## Getting Help If you encounter Docker-specific issues: * **Docker Documentation**: [https://docs.docker.com/](https://docs.docker.com/) * **Docker Compose Reference**: [https://docs.docker.com/compose/](https://docs.docker.com/compose/) * **Chatwoot Issues**: [GitHub Issues](https://github.com/chatwoot/chatwoot/issues) * **Community Support**: [Discord](https://discord.com/invite/cJXdrwS) *** Your Docker development environment is now ready for Chatwoot development! 🐳 # macOS Development Setup Source: https://developers.chatwoot.com/contributing-guide/environment-setup/mac-os Complete guide to setting up your macOS development environment for Chatwoot contribution. # macOS Development Setup This guide will help you set up your macOS development environment for contributing to Chatwoot. Open Terminal app and run the following commands. ## Installing the Standalone Command Line Tools Open Terminal app and run: ```bash theme={null} xcode-select --install ``` This installs essential development tools including Git, GCC, and other command line utilities. ## Install Homebrew Homebrew is the missing package manager for macOS: ```bash theme={null} /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" ``` After installation, add Homebrew to your PATH (if not automatically added): ```bash theme={null} echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)" ``` ## Install Git ```bash theme={null} brew update brew install git ``` Configure Git with your information: ```bash theme={null} git config --global user.name "Your Name" git config --global user.email "your.email@example.com" ``` ## Install Ruby Version Manager Choose between RVM or rbenv for managing Ruby versions. ### Option 1: Install RVM (Recommended) ```bash theme={null} curl -L https://get.rvm.io | bash -s stable source ~/.rvm/scripts/rvm ``` ### Option 2: Install rbenv (Alternative) ```bash theme={null} brew install rbenv ruby-build echo 'eval "$(rbenv init -)"' >> ~/.zshrc source ~/.zshrc ``` ## Install Ruby Chatwoot APIs are built on Ruby on Rails. You need to install Ruby 3.2.2. ### If using RVM: ```bash theme={null} rvm install ruby-3.2.2 rvm use 3.2.2 --default source ~/.rvm/scripts/rvm ``` ### If using rbenv: ```bash theme={null} rbenv install 3.2.2 rbenv global 3.2.2 ``` rbenv identifies the ruby version from `.ruby-version` file on the root of the project and loads it automatically. Verify Ruby installation: ```bash theme={null} ruby --version # Should output: ruby 3.2.2 ``` ## Install Node.js Chatwoot requires Node.js version 20: ```bash theme={null} brew install node@20 ``` If you need to link Node.js 20: ```bash theme={null} brew link node@20 echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc source ~/.zshrc ``` Verify Node.js installation: ```bash theme={null} node --version # Should output: v20.x.x ``` ## Install pnpm We use `pnpm` as our package manager for better performance: ```bash theme={null} brew install pnpm ``` Verify pnpm installation: ```bash theme={null} pnpm --version ``` ## Install PostgreSQL The database used in Chatwoot is PostgreSQL. ### Option 1: PostgresApp (Recommended) 1. Download and install PostgresApp from [https://postgresapp.com](https://postgresapp.com) 2. This is the easiest way to get started with PostgreSQL on macOS 3. Follow the setup instructions on their website ### Option 2: Homebrew Installation ```bash theme={null} brew install postgresql@14 ``` Start PostgreSQL service: ```bash theme={null} brew services start postgresql@14 ``` Create a PostgreSQL user: ```bash theme={null} createuser -s postgres ``` Connect to PostgreSQL to verify installation: ```bash theme={null} psql postgres # Type \q to exit ``` ## Install Redis Server Chatwoot uses Redis server for agent assignments and reporting: ```bash theme={null} brew install redis ``` Start the Redis service: ```bash theme={null} brew services start redis ``` Verify Redis installation: ```bash theme={null} redis-cli ping # Should output: PONG ``` ## Install ImageMagick Chatwoot uses ImageMagick library to resize images for previews and thumbnails: ```bash theme={null} brew install imagemagick ``` Verify ImageMagick installation: ```bash theme={null} convert --version ``` ## Install Additional Dependencies Install other useful development tools: ```bash theme={null} # Install Yarn (alternative to pnpm if needed) brew install yarn # Install SQLite (for testing) brew install sqlite # Install libvips (for image processing) brew install libvips ``` ## Install Docker (Optional) For development and testing with containers: ```bash theme={null} # Install Docker Desktop brew install --cask docker ``` Or download Docker Desktop from [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/). ## Environment Verification Verify all installations are working: ```bash theme={null} # Check versions ruby --version # Should be 3.2.2 node --version # Should be v20.x.x pnpm --version # Should show pnpm version psql --version # Should show PostgreSQL version redis-cli --version # Should show Redis version convert --version # Should show ImageMagick version git --version # Should show Git version ``` ## Configure Shell Environment Add useful aliases to your shell configuration file (`~/.zshrc` for Zsh): ```bash theme={null} # Add to ~/.zshrc echo '# Chatwoot Development Aliases' >> ~/.zshrc echo 'alias cw-server="bundle exec rails server"' >> ~/.zshrc echo 'alias cw-console="bundle exec rails console"' >> ~/.zshrc echo 'alias cw-test="bundle exec rspec"' >> ~/.zshrc echo 'alias cw-migrate="bundle exec rails db:migrate"' >> ~/.zshrc # Reload shell configuration source ~/.zshrc ``` ## Troubleshooting Common Issues **Solution**: Update macOS to the latest version and try again. You can also download Xcode from the App Store. **Solution**: ```bash theme={null} sudo chown -R $(whoami) /opt/homebrew ``` **Solution**: ```bash theme={null} # Install missing dependencies brew install openssl readline libyaml rvm reinstall 3.2.2 --with-openssl-dir=$(brew --prefix openssl) ``` **Solution**: ```bash theme={null} # Restart PostgreSQL brew services restart postgresql@14 # Check if it's running brew services list | grep postgresql ``` **Solution**: ```bash theme={null} # If you encounter issues, try: brew uninstall imagemagick brew install imagemagick ``` ## Getting Help If you encounter issues: * **Common Errors**: Check [Common Errors](/contributing-guide/common-errors) * **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS) * **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues) *** Your macOS development environment is now ready for Chatwoot development! 🚀 # Make Commands Setup Source: https://developers.chatwoot.com/contributing-guide/environment-setup/make Speed up your local development workflow with Make commands for Chatwoot. # Speed up your local development with Make Speed up your local development workflow with make commands for Chatwoot. ## Clone the repo and cd to the Chatwoot directory Clone the repository and navigate to the Chatwoot directory: ```bash theme={null} git clone https://github.com/chatwoot/chatwoot.git cd chatwoot ``` ## Install Ruby & JavaScript dependencies Install Ruby and JavaScript dependencies using the following command. This command runs Bundler and pnpm: ```bash theme={null} make burn ``` ## Run database migrations Apply necessary database schema changes to your development environment by running the following command: ```bash theme={null} make db ``` ## Run database seed Load some seed data to your development environment for testing by running the following command: ```bash theme={null} make db_seed ``` ## Run dev server using Overmind Start the development server using Overmind, a process manager that can run multiple processes concurrently: ```bash theme={null} make run ``` ## Force run if ./.overmind.sock file exists If the `make run` command fails due to the existence of a `./.overmind.sock` file, you can try using the following command: ```bash theme={null} make force_run ``` ## Debug - Attach to backend via Overmind tmux session For debugging purposes, you can attach to the backend via the Overmind tmux session using the following command: ```bash theme={null} make debug ``` ## Debug worker To debug the worker, use the following command: ```bash theme={null} make debug_worker ``` ## Get Rails console Access the Rails console, which provides an interactive environment for interacting with the Chatwoot application: ```bash theme={null} make console ``` ## Build Docker image Build the Docker image for the Chatwoot project: ```bash theme={null} make docker ``` ## Workflow after pulling in the latest changes from `develop` To update your development environment after pulling the latest changes from the `develop` branch, follow these steps: ```bash theme={null} make burn # Install dependencies make db # Run migrations make run # Start the server ``` ## Getting Help If you encounter issues with Make commands: * **Makefile Documentation**: Check the project's `Makefile` for available commands * **Overmind Documentation**: [https://github.com/DarthSim/overmind](https://github.com/DarthSim/overmind) * **Chatwoot Issues**: [GitHub Issues](https://github.com/chatwoot/chatwoot/issues) * **Community Support**: [Discord](https://discord.com/invite/cJXdrwS) *** Your Make-based development workflow is now ready for efficient Chatwoot development! 🚀 # Ubuntu Development Setup Source: https://developers.chatwoot.com/contributing-guide/environment-setup/ubuntu Complete guide to setting up your Ubuntu development environment for Chatwoot contribution. # Ubuntu Development Setup This guide will help you set up your Ubuntu development environment for contributing to Chatwoot. These instructions work for Ubuntu 20.04, 22.04, and newer versions. ## Update System Packages Open a terminal and run the following commands to update your system packages: ```bash theme={null} sudo apt-get update ``` ## Install Git Install Git for version control: ```bash theme={null} sudo apt-get install git ``` Configure Git with your information: ```bash theme={null} git config --global user.name "Your Name" git config --global user.email "your.email@example.com" ``` Verify Git installation: ```bash theme={null} git --version ``` ## Install RVM You need software-properties-common installed in order to add PPA repositories: ```bash theme={null} sudo apt-get install software-properties-common ``` Install RVM (Ruby Version Manager): ```bash theme={null} sudo apt-add-repository -y ppa:rael-gc/rvm sudo apt-get update sudo apt-get install rvm sudo usermod -a -G rvm $USER ``` **Important**: Enable `Run command as a login shell` in terminal `Preferences`. Restart your computer after installation. ## Install Ruby Chatwoot APIs are built on Ruby on Rails. You need to install Ruby 3.3.3: ```bash theme={null} rvm install ruby-3.3.3 ``` Use Ruby 3.3.3 as default: ```bash theme={null} rvm use 3.3.3 --default ``` Verify Ruby installation: ```bash theme={null} ruby --version # Should output: ruby 3.3.3 ``` ## Install Node.js Chatwoot requires Node.js version `20`. Install Node.js from NodeSource using the following commands: ```bash theme={null} curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs ``` Verify Node.js installation: ```bash theme={null} node --version # Should output: v20.x.x npm --version ``` ## Install pnpm We use `pnpm` as the package manager: ```bash theme={null} curl -fsSL https://get.pnpm.io/install.sh | sh - ``` Verify pnpm installation: ```bash theme={null} pnpm --version ``` ## Install PostgreSQL The database used in Chatwoot is PostgreSQL. Use the following commands to install PostgreSQL: ```bash theme={null} sudo apt install postgresql postgresql-contrib ``` The installation procedure creates a user account called postgres that is associated with the default Postgres role. In order to use Postgres, you can log into that account: ```bash theme={null} sudo -u postgres psql ``` Install `libpq-dev` dependencies for Ubuntu: ```bash theme={null} sudo apt-get install libpq-dev ``` Verify PostgreSQL installation: ```bash theme={null} psql --version ``` ## Install Redis Server Chatwoot uses Redis server in agent assignments and reporting. You need to install `redis-server`: ```bash theme={null} sudo apt-get install redis-server ``` Next, enable Redis to start on system boot: ```bash theme={null} sudo systemctl enable redis-server.service ``` Verify Redis installation: ```bash theme={null} redis-cli ping # Should output: PONG ``` ## Install ImageMagick Install ImageMagick for image processing: ```bash theme={null} sudo apt-get install imagemagick ``` Verify ImageMagick installation: ```bash theme={null} convert --version ``` ## Troubleshooting Common Issues **Solution**: Ensure you have restarted your computer and enabled "Run command as a login shell": ```bash theme={null} # Check if RVM is loaded rvm --version # If not found, try loading manually source ~/.rvm/scripts/rvm ``` **Solution**: Install missing dependencies: ```bash theme={null} sudo apt-get install autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev rvm reinstall ruby-3.3.3 ``` **Solution**: Configure PostgreSQL user and database: ```bash theme={null} # Switch to postgres user and create a superuser sudo -u postgres createuser --superuser $USER # Set password for your user sudo -u postgres psql -c "ALTER USER $USER PASSWORD 'password';" # Create a database for your user sudo -u postgres createdb $USER ``` **Solution**: Clear cache and reinstall: ```bash theme={null} sudo apt-get remove nodejs npm sudo apt-get autoremove curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs ``` **Solution**: Fix ownership of common directories: ```bash theme={null} sudo chown -R $USER:$USER ~/.npm sudo chown -R $USER:$USER ~/.pnpm-store ``` ## Getting Help If you encounter issues: * **Common Errors**: Check [Common Errors](/contributing-guide/common-errors) * **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS) * **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues) * **Ubuntu Community**: [Ubuntu Forums](https://ubuntuforums.org/) *** Your Ubuntu development environment is now ready for Chatwoot development! 🐧 # Windows Development Setup Source: https://developers.chatwoot.com/contributing-guide/environment-setup/windows Complete guide to setting up your Windows development environment for Chatwoot contribution using WSL2. # Windows Development Setup This guide will walk you through setting up your Windows development environment for contributing to Chatwoot. We'll use Windows Subsystem for Linux 2 (WSL2) which provides the best development experience on Windows. ## Requirements You need to install the Windows Subsystem for Linux 2 (WSL2) on your Windows machine. ### Prerequisites * Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11 * Administrator privileges on your Windows machine ## Step 1: Enable Developer Mode The first step is to enable "Developer mode" in Windows. You can do this by opening up Settings and navigating to "Update & Security". In there, choose the tab on the left that reads "For Developers". Turn the "Developer mode" toggle on to enable it. Enable Developer Mode ## Step 2: Enable Windows Subsystem for Linux Next you have to enable the Windows Subsystem for Linux. Open the "Control Panel" and go to "Programs and Features". Click on the link on the left "Turn Windows features on or off". Look for the "Windows Subsystem for Linux" option and select the checkbox next to it. Enable WSL You'll also need to enable "Virtual Machine Platform" for WSL2. Make sure both checkboxes are selected: * ✅ Windows Subsystem for Linux * ✅ Virtual Machine Platform After enabling these features, restart your computer. ## Step 3: Install WSL2 and Ubuntu ### Option 1: Using Microsoft Store (Recommended) 1. **Open Microsoft Store** and search for "Ubuntu" 2. **Install Ubuntu 22.04 LTS** (or latest LTS version) 3. **Launch Ubuntu** from the Start Menu ### Option 2: Using Command Line Open PowerShell as Administrator and run: ```powershell theme={null} # Install WSL2 with Ubuntu wsl --install -d Ubuntu-22.04 # Set WSL2 as default version wsl --set-default-version 2 ``` ## Step 4: Initial Ubuntu Setup When you first launch Ubuntu, you'll be prompted to create a user account: ```bash theme={null} # Create a username and password when prompted # This will be your Linux user account ``` Update the system packages: ```bash theme={null} sudo apt update && sudo apt upgrade -y ``` ## Step 5: Install Core Dependencies You need core Linux dependencies installed in order to install Ruby and other tools. ```bash theme={null} sudo apt-get update sudo apt-get install -y git-core curl zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev ``` ## Installing RVM & Ruby Install additional dependencies required for RVM: ```bash theme={null} sudo apt-get install -y libgdbm-dev libncurses5-dev automake libtool bison libffi-dev ``` Install RVM & Ruby version 3.2.2: ```bash theme={null} # Add RVM GPG keys gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB # Install RVM curl -sSL https://get.rvm.io | bash -s stable # Load RVM into current session source ~/.rvm/scripts/rvm # Install Ruby 3.2.2 rvm install 3.2.2 rvm use 3.2.2 --default # Verify installation ruby -v ``` ## Install Node.js Chatwoot requires Node.js version 20. Install Node.js from NodeSource using the following commands: ```bash theme={null} curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs ``` Verify Node.js installation: ```bash theme={null} node --version # Should output: v20.x.x ``` ## Install pnpm We use `pnpm` as the package manager for better performance: ```bash theme={null} # Install pnpm globally npm install -g pnpm # Verify installation pnpm --version ``` ## Install PostgreSQL The database used in Chatwoot is PostgreSQL. Use the following commands to install PostgreSQL: ```bash theme={null} sudo apt install -y postgresql postgresql-contrib ``` The installation procedure created a user account called postgres that is associated with the default Postgres role. In order to use PostgreSQL, you can log into that account: ```bash theme={null} sudo -u postgres psql ``` Install `libpq-dev` dependencies for Ubuntu: ```bash theme={null} sudo apt-get install -y libpq-dev ``` Start PostgreSQL service: ```bash theme={null} sudo service postgresql start ``` Configure PostgreSQL to start automatically: ```bash theme={null} echo 'sudo service postgresql start' >> ~/.bashrc ``` Create a database user: ```bash theme={null} # Switch to postgres user and create a superuser sudo -u postgres createuser --superuser $USER # Set password for your user sudo -u postgres psql -c "ALTER USER $USER PASSWORD 'password';" ``` ## Install Redis Server Chatwoot uses Redis server for agent assignments and reporting. To install `redis-server`: ```bash theme={null} sudo apt-get install -y redis-server ``` Start Redis service: ```bash theme={null} sudo service redis-server start ``` Configure Redis to start automatically: ```bash theme={null} echo 'sudo service redis-server start' >> ~/.bashrc ``` Enable Redis to start on system boot: ```bash theme={null} sudo systemctl enable redis-server.service ``` ## Install ImageMagick Chatwoot uses ImageMagick for image processing: ```bash theme={null} sudo apt-get install -y imagemagick libmagickwand-dev ``` ## Configure Git Set up Git with your information: ```bash theme={null} git config --global user.name "Your Name" git config --global user.email "your.email@example.com" ``` ## Windows-Specific Configuration ### Install VS Code with WSL Extension 1. **Install Visual Studio Code** on Windows from [https://code.visualstudio.com/](https://code.visualstudio.com/) 2. **Install Remote - WSL extension** from the Extensions marketplace 3. **Open your project in WSL** by running `code .` from your WSL terminal ### Configure File Permissions WSL2 may have file permission issues. Fix them: ```bash theme={null} # Add to ~/.bashrc for better file permissions echo 'umask 022' >> ~/.bashrc # Configure Git to ignore file mode changes git config --global core.filemode false ``` ## Environment Verification Verify all installations are working correctly: ```bash theme={null} # Check all versions ruby --version # Should be 3.2.2 node --version # Should be v20.x.x pnpm --version # Should show pnpm version psql --version # Should show PostgreSQL version redis-cli ping # Should output: PONG convert --version # Should show ImageMagick version git --version # Should show Git version ``` ## Troubleshooting Common Issues **Solution**: Ensure virtualization is enabled in BIOS and Windows features are properly enabled: 1. Restart computer and enter BIOS settings 2. Enable Intel VT-x or AMD-V virtualization 3. Enable Hyper-V in Windows Features 4. Restart and try installation again **Solution**: Reset WSL or reinstall Ubuntu: ```powershell theme={null} # Reset Ubuntu (will delete all data) wsl --unregister Ubuntu-22.04 wsl --install -d Ubuntu-22.04 ``` **Solution**: Check if Windows PostgreSQL service is conflicting: ```bash theme={null} # Stop Windows PostgreSQL service first (run in Windows Command Prompt as Admin) net stop postgresql-x64-14 # Then start WSL2 PostgreSQL sudo service postgresql start ``` **Solution**: Fix file permissions: ```bash theme={null} # For the entire project find . -type f -exec chmod 644 {} \; find . -type d -exec chmod 755 {} \; # For executable files chmod +x bin/* ``` **Solution**: Ensure code is stored in WSL2 filesystem: ```bash theme={null} # Good: Store code here (fast) /home/username/projects/chatwoot # Avoid: Storing code here (slow) /mnt/c/Users/Username/projects/chatwoot ``` If you encounter issues during setup: * **Common Errors**: Check [Common Errors](/contributing-guide/common-errors) * **WSL2 Documentation**: [Microsoft WSL Documentation](https://docs.microsoft.com/en-us/windows/wsl/) * **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS) * **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues) *** Your Windows development environment with WSL2 is now ready for Chatwoot development! 🪟🐧 # Environment Variables for Development Source: https://developers.chatwoot.com/contributing-guide/environment-variables Complete guide to environment variables for Chatwoot development and testing # Environment Variables for Development This guide covers environment variables specifically for development and testing environments. For production environment variables, see the [Self-hosted Environment Variables](/self-hosted/configuration/environment-variables) guide. ### Use letter opener instead of mailhog/SMTP Set the following variable to open emails in letter opener instead of SMTP ```bash theme={null} LETTER_OPENER=true ``` # Line App Integration Setup Source: https://developers.chatwoot.com/contributing-guide/line-channel-setup Setup Line app integration on your local machine for development # Setup Line app integration on your local machine Please follow the steps if you are trying to work with the Line integration on your local machine. ## Prerequisites * Line Developer Account * Access to [Line Developer Console](https://developers.line.biz/console) * Ngrok or similar tunneling service * Running Chatwoot development environment ## Setup Steps ### 1. Start Ngrok Server Start a Ngrok server listening at port `3000` or the port you will be running the Chatwoot installation: ```bash theme={null} # Install ngrok if you haven't already # Download from https://ngrok.com/download # Start ngrok tunnel ngrok http 3000 ``` ### 2. Update Environment Variables Update the `.env` variable `FRONTEND_URL` in Chatwoot with the `https` version of the Ngrok URL: ```bash theme={null} # In your .env file FRONTEND_URL=https://your-ngrok-subdomain.ngrok.io ``` ### 3. Configure Line Developer Console 1. **Access Line Developer Console**: Go to [Line Developer Console](https://developers.line.biz/console) 2. **Create a Provider** (if you don't have one) 3. **Create a New Channel** and select "Messaging API" 4. **Configure Basic Settings**: * Channel name * Channel description * Category * Subcategory ### 4. Get Required Credentials From the Line Developer Console under the "Messaging API" channel, collect the following values: 1. **Channel Name** 2. **LINE Channel ID** 3. **LINE Channel Secret** 4. **LINE Channel Token** ### 5. Start Chatwoot Server Start the Chatwoot server and create a new Line channel with the values obtained from Line Developer Console: ```bash theme={null} # Start the development server make run # or foreman start -f Procfile.dev ``` ### 6. Create Line Channel in Chatwoot 1. **Access Chatwoot**: Go to your Chatwoot instance ([http://localhost:3000](http://localhost:3000)) 2. **Navigate to Settings** → **Inboxes** → **Add Inbox** 3. **Select Line** as the channel type 4. **Enter Line Credentials**: * Channel Name * LINE Channel ID * LINE Channel Secret * LINE Channel Token 5. **Save Configuration** ## Configure Webhook in Line Developer Console After creating the channel, Chatwoot will provide a webhook URL for the channel. You need to configure this webhook URL in the Line Developer Console: ### Steps to Configure Webhook 1. **Go to Line Developer Console** → Your Channel → **Messaging API** 2. **Find Webhook Settings** 3. **Set Webhook URL**: Use the URL provided by Chatwoot ``` https://your-ngrok-subdomain.ngrok.io/webhooks/line/your-channel-id ``` 4. **Enable Webhook**: Toggle the webhook to "Enabled" 5. **Verify Webhook**: Use the "Verify" button to test the connection ### Additional Line Settings Configure these settings in the Line Developer Console: * **Auto-reply messages**: Disable (so Chatwoot can handle responses) * **Greeting messages**: Optional * **Webhook redelivery**: Enable for reliability ## Testing the Integration If the webhook is registered correctly with Line, your Ngrok server should receive events for new Line messages, and new conversations will be created in Chatwoot. ### Test Steps 1. **Add your Line bot as a friend** using the QR code or bot ID 2. **Send a message** to your Line bot 3. **Check Ngrok logs** to see if the webhook request is received 4. **Check Chatwoot** to see if a new conversation is created 5. **Reply from Chatwoot** to test bidirectional communication ## Troubleshooting **Problem**: Line webhook verification fails in Developer Console **Solution**: * Ensure your Ngrok URL is accessible publicly * Check that `FRONTEND_URL` is set correctly in your `.env` file * Verify the webhook URL format is correct * Restart Chatwoot after updating environment variables **Problem**: Line messages don't create conversations in Chatwoot **Solution**: * Check Ngrok logs for incoming webhook requests * Verify webhook is enabled in Line Developer Console * Check Chatwoot logs for any error messages * Ensure all Line credentials are entered correctly * Verify the channel is enabled in Chatwoot **Problem**: SSL certificate issues with webhook **Solution**: * Use the `https` version of your Ngrok URL * Ensure Ngrok is running properly * Line requires HTTPS for webhook URLs * Try restarting Ngrok and updating the webhook **Problem**: Line API authentication failures **Solution**: * Verify Channel ID, Channel Secret, and Channel Token are correct * Check that the channel is published and not in development mode * Ensure the Messaging API is enabled for your channel * Regenerate Channel Token if necessary ## Line API Features Line offers various features you can integrate: * **Rich Messages**: Cards, carousels, quick replies * **Flex Messages**: Custom layouts * **LIFF (Line Frontend Framework)**: Web apps within Line * **Line Login**: User authentication ## Next Steps After successful setup: 1. **Test message flow** between Line and Chatwoot 2. **Configure agent assignments** for Line conversations 3. **Set up automated responses** if needed 4. **Explore rich message features** for enhanced user experience 5. **Review webhook logs** for debugging ## Getting Help If you encounter issues: * **Check Logs**: Review both Chatwoot and Ngrok logs * **Line Developers Documentation**: [Official Line API Docs](https://developers.line.biz/en/docs/) * **Common Errors**: See [Common Errors](/contributing-guide/common-errors) * **Community Support**: [Discord](https://discord.com/invite/cJXdrwS) ## Useful Resources * **Line Messaging API Documentation**: [https://developers.line.biz/en/docs/messaging-api/](https://developers.line.biz/en/docs/messaging-api/) * **Line Developer Console**: [https://developers.line.biz/console](https://developers.line.biz/console) * **Webhook Test Tool**: Available in Line Developer Console *** Your Line integration is now ready for development and testing! 💬 # Mobile App Development Setup Source: https://developers.chatwoot.com/contributing-guide/mobile-app/setup-guide Setup guide for Chatwoot mobile app development # Setup guide for mobile app Complete guide to setting up the Chatwoot mobile app for development and contribution. ## Installation and setup ### Prerequisites Before starting, ensure you have the following installed: * [Node.js](https://nodejs.org/en/download/) (Latest LTS version) * [React Native CLI](https://reactnative.dev/docs/environment-setup) * [Expo CLI](https://docs.expo.dev/get-started/installation/) * [Expo Account](https://expo.dev/signup) To learn more about the most up-to-date instructions, please refer to the guide available [here](https://docs.expo.dev/get-started/set-up-your-environment/). ### Clone the repository ```bash theme={null} git clone git@github.com:chatwoot/chatwoot-mobile-app.git cd chatwoot-mobile-app ``` ### Install dependencies ```bash theme={null} pnpm install ``` ### Install Expo CLI ```bash theme={null} pnpm install -g expo-cli ``` ## Environment Variables Create your environment configuration file: ```bash theme={null} cp .env.example .env ``` Configure the following environment variables: | Name | Description | Default Value | Required | | --------------------------------------------- | ------------------------------------------- | ---------------------------------------------------- | -------- | | EXPO\_PUBLIC\_CHATWOOT\_WEBSITE\_TOKEN | Web widget token for in-app support | - | No | | EXPO\_PUBLIC\_CHATWOOT\_BASE\_URL | Self-hosted installation URL | [https://app.chatwoot.com](https://app.chatwoot.com) | Yes | | EXPO\_PUBLIC\_JUNE\_SDK\_KEY | June analytics SDK key | - | No | | EXPO\_PUBLIC\_MINIMUM\_CHATWOOT\_VERSION | Minimum supported Chatwoot version | - | Yes | | EXPO\_PUBLIC\_SENTRY\_DSN | Sentry DSN URL for error reporting | - | No | | EXPO\_PUBLIC\_PROJECT\_ID | Expo project identifier | - | Yes | | EXPO\_PUBLIC\_APP\_SLUG | Application slug for Expo | - | Yes | | EXPO\_PUBLIC\_SENTRY\_PROJECT\_NAME | Project name in Sentry | - | No | | EXPO\_PUBLIC\_SENTRY\_ORG\_NAME | Organization name in Sentry | - | No | | EXPO\_PUBLIC\_IOS\_GOOGLE\_SERVICES\_FILE | Path to iOS Google Services config file | - | No | | EXPO\_PUBLIC\_ANDROID\_GOOGLE\_SERVICES\_FILE | Path to Android Google Services config file | - | No | | EXPO\_APPLE\_ID | Apple Developer account ID | - | No | | EXPO\_APPLE\_TEAM\_ID | Apple Developer team ID | - | No | | EXPO\_STORYBOOK\_ENABLED | Enable/disable Storybook | false | No | ## Generate the native code ```bash theme={null} pnpm generate ``` This command generates native Android and iOS directories using [Prebuild](https://docs.expo.dev/workflow/continuous-native-generation/). You need to run pre-build if you add a new native dependency to your project or change the project configuration in Expo app config (app.config.ts). ## How to run the app Connect your iPhone/Android device and run the following command to install the app on your device. ### iOS Development ```bash theme={null} pnpm run:ios ``` ### Android Development ```bash theme={null} pnpm run:android ``` ## Package Installation Please always install packages using the command `npx expo install package-name` instead of `pnpm install package-name`. This is crucial for native dependencies because Expo will automatically install the correct compatible version, while pnpm/yarn/npm may install the latest version, which may not be compatible. ```bash theme={null} # Correct way to install packages npx expo install package-name # Incorrect way (may cause compatibility issues) pnpm install package-name ``` ## Push notifications If you are using the community edition of Chatwoot with the [official mobile app](https://www.chatwoot.com/mobile-apps), push notifications work out of the box with no additional configuration. If you are building a custom-branded app, refer to the [custom mobile app guide](/self-hosted/custom-mobile-app) for Firebase, deep linking, and build setup. ## Troubleshooting **Problem**: Metro bundler fails to start or bundle **Solution**: ```bash theme={null} # Clear cache and restart pnpm clear pnpm start --reset-cache ``` **Problem**: iOS build or simulator issues **Solution**: * Ensure Xcode is properly installed * Check iOS simulator version compatibility * Clear derived data in Xcode * Restart Metro bundler **Problem**: Android build or emulator issues **Solution**: * Verify Android Studio setup * Check SDK versions and build tools * Ensure emulator is running * Clear Gradle cache **Problem**: Expo commands fail **Solution**: ```bash theme={null} # Update Expo CLI npm install -g @expo/cli@latest # Login to Expo expo login # Clear Expo cache expo r -c ``` ## Contributing Guidelines When contributing to the mobile app: 1. **Follow coding standards**: Use ESLint and Prettier configurations 2. **Write tests**: Include unit tests for new features 3. **Test on both platforms**: Ensure iOS and Android compatibility 4. **Update documentation**: Document new features and changes 5. **Check performance**: Monitor app performance impact ## Getting Help If you encounter issues: * **Expo Documentation**: [Official Expo Docs](https://docs.expo.dev/) * **React Native Documentation**: [React Native Docs](https://reactnative.dev/docs/getting-started) * **GitHub Issues**: [Mobile App Issues](https://github.com/chatwoot/chatwoot-mobile-app/issues) * **Community Support**: [Discord](https://discord.com/invite/cJXdrwS) ## Useful Resources * **Expo Development**: [https://docs.expo.dev/](https://docs.expo.dev/) * **React Native**: [https://reactnative.dev/](https://reactnative.dev/) * **EAS Build**: [https://docs.expo.dev/build/introduction/](https://docs.expo.dev/build/introduction/) * **EAS Submit**: [https://docs.expo.dev/submit/introduction/](https://docs.expo.dev/submit/introduction/) *** Your Chatwoot mobile app development environment is now ready! 📱 # Reporting Security Issues Source: https://developers.chatwoot.com/contributing-guide/security-reports How to report security vulnerabilities in Chatwoot # Reporting Security Issues Chatwoot is looking forward to working with security researchers worldwide to keep Chatwoot and our users safe. If you have found an issue in our systems/applications, please reach out to us. ## Reporting a Vulnerability We use GitHub for security issues that affect our project. If you believe you have found a vulnerability, please disclose it via this [form](https://github.com/chatwoot/chatwoot/security/advisories/new). This will enable us to review the vulnerability, fix it promptly, and reward you for your efforts. If you have any questions about the process, contact **[security@chatwoot.com](mailto:security@chatwoot.com)**. Please try your best to describe a clear and realistic impact for your report, and please don't open any public issues on GitHub or social media; we're doing our best to respond through GitHub as quickly as possible. Please use the email for questions related to the process. Disclosures should be done via [GitHub](https://github.com/chatwoot/chatwoot/security/advisories/new). ## Report Quality and Duplicates Please include clear steps to reproduce, a realistic impact, the affected version, and any required configuration details. We may close reports that are theoretical, scanner-only, AI-generated without verification, or missing enough detail for us to reproduce the issue. If the same vulnerability was reported before, we will close later reports as duplicates and link them to the canonical report. The canonical report is the earliest valid report we received for that issue. ## Supported Versions | Version | Supported | | --------- | --------- | | latest | ️✅ | | \< latest | ❌ | ## Vulnerabilities We Care About 🫣 Please do not perform testing against Chatwoot production services. Use a `self-hosted instance` to perform tests. We consider the following vulnerabilities as high priority: * Remote command execution * SQL Injection * Authentication bypass * Privilege Escalation * Cross-site scripting (XSS) * Performing limited admin actions without authorization * CSRF ## Non-Qualifying Vulnerabilities We consider the following out of scope, though there may be exceptions: * Missing HTTP security headers * Incomplete/Missing SPF/DKIM * Reports from automated tools or scanners * Theoretical attacks without proof of exploitability * Social engineering * Reflected file download * Physical attacks * Weak SSL/TLS/SSH algorithms or protocols * Attacks involving physical access to a user's device or a device or network that's already seriously compromised (e.g., man-in-the-middle) * The user attacks themselves * Denial of Service attacks * Brute force attacks * DNSSEC If you are unsure about the scope, please create a [report](https://github.com/chatwoot/chatwoot/security/advisories/new). ## Triaging Process Chatwoot team triages the issues in GitHub weekly. We're doing our best to respond through GitHub as quickly as we can, so please don't open any public issues on GitHub or social media and avoid duplicate reports over emails. * Based on reviewing the report, the team will assign a priority to the issue and move it into the internal backlog to prioritize a fix. * In cases where the team needs more information or disagreements of severity, the team will communicate the same over GitHub before completing the triaging. After triage, the team will start working on the issue based on the following severity and timelines: ## Response Timeline | Severity | Timeline | | ------------- | --------- | | Critical (P0) | ️ 7 Days | | High | 30 Days | | Medium | 60 Days | | Low | 90 Days | ## Advisory and CVE Publishing We publish security advisories and CVEs at [GitHub Security Advisories](https://github.com/chatwoot/chatwoot/security). We request or publish a CVE when the issue is a confirmed, externally exploitable vulnerability in a supported Chatwoot release, and users or operators need a stable public identifier to assess impact, upgrade, or track exposure. We usually request a CVE for: * Critical or high-impact vulnerabilities such as remote command execution, SQL injection, authentication bypass, privilege escalation, meaningful XSS, or CSRF with real impact * Cross-tenant data exposure, token or credential exposure, and account takeover paths * Fixed vulnerabilities where affected versions and patched versions are known * Unrelated vulnerabilities reported together, if they are independently fixable We do not request a new CVE for: * Duplicate reports of an already-covered vulnerability * Scanner-only or theoretical reports without demonstrated exploitability * Out-of-scope items such as missing headers, SPF/DKIM, brute force, DNSSEC, or broad denial-of-service reports * Issues that only affect unsupported old versions, unless there is strong public coordination value * Dependency vulnerabilities already covered by an upstream CVE * Pure hardening or defense-in-depth changes without a demonstrated vulnerability Multiple reports of the same issue will be covered by one advisory or CVE, using the canonical earliest report. During triage and fix work, we keep the GitHub Security Advisory private. Once the issue is confirmed and likely publishable, we may request or reserve a CVE. We publish the advisory and CVE when the fix is released, ideally with affected versions, the patched version, impact, workaround, and credits. If there is active exploitation or unavoidable disclosure pressure, we may publish earlier with mitigation guidance. ## Security Best Practices ### For Researchers * **Test Responsibly**: Only test on your own self-hosted instances * **Provide Clear Details**: Include steps to reproduce, impact assessment, and suggested fixes * **Be Patient**: Allow time for our team to investigate and respond * **Follow Responsible Disclosure**: Don't publish vulnerabilities publicly until they're fixed ### For Users * **Keep Updated**: Always use the latest version of Chatwoot * **Secure Configuration**: Follow security best practices for your deployment * **Monitor Logs**: Regularly check logs for suspicious activity * **Report Issues**: If you notice anything unusual, report it through proper channels ## Bounty Program While we don't currently have a formal bug bounty program, we do recognize and appreciate security researchers who help us improve Chatwoot's security: * **Hall of Fame**: Recognition on our security acknowledgments page * **Direct Communication**: Work directly with our security team * **Early Access**: Get early access to security updates and patches ## Getting Help If you need assistance with security reporting: * **Process Questions**: Contact [security@chatwoot.com](mailto:security@chatwoot.com) * **Technical Issues**: Use our [Discord community](https://discord.com/invite/cJXdrwS) * **General Support**: Check our [documentation](/contributing-guide/common-errors) ## Thanks Thank you for keeping Chatwoot and our users safe. 🙇 Your efforts help us maintain a secure platform for thousands of businesses worldwide. We appreciate the time and expertise you contribute to making Chatwoot better for everyone. *** Remember: Security is a shared responsibility. Together, we can make Chatwoot safer for everyone. # Project Setup Guide Source: https://developers.chatwoot.com/contributing-guide/setup-guide Complete guide to setting up and running Chatwoot in development mode # Project Setup This guide will help you to setup and run Chatwoot in development mode. Please make sure you have completed the environment setup. ## Clone the repo ```bash theme={null} # change location to the path you want chatwoot to be installed cd ~ # clone the repo and cd to chatwoot dir git clone https://github.com/chatwoot/chatwoot.git cd chatwoot ``` ## Install Ruby & Javascript dependencies Use the following command to run `bundle && pnpm install` to install ruby and Javascript dependencies. ```bash theme={null} make burn ``` This would install all required dependencies for Chatwoot application. If you face issue with pg gem, please refer to [Common Errors](/contributing-guide/common-errors#pg-gem-installation-error) ## Setup environment variables ```bash theme={null} cp .env.example .env ``` Please refer to [environment-variables](/contributing-guide/environment-variables) to read on setting environment variables. ## Setup rails server ```bash theme={null} # run db migrations make db # fireup the server foreman start -f Procfile.dev ``` If you have overmind installed, use `make run` to run the server. ## Login with credentials ```bash theme={null} http://localhost:3000 user name: john@acme.inc password: Password1! ``` ## Testing chat widget in your local environment When running Chatwoot in development environment, the chat widget can be accessed under the following URL. ``` http://localhost:3000/widget_tests ``` You can also test the `setUser` method by using ``` http://localhost:3000/widget_tests?setUser=true ``` To use those URLs, you first need to compile the assets. Run: ```bash theme={null} bundle exec rails assets:precompile ``` ## Docker for development Follow this section only if you are trying to setup Chatwoot via docker. Else skip this. The first time you start your development environment run the following two commands: ```bash theme={null} # build base image first docker compose build base # build the server and worker docker compose build # prepare the database docker compose exec rails bundle exec rails db:chatwoot_prepare # docker compose up ``` Then browse [http://localhost:3000](http://localhost:3000) ```bash theme={null} # To stop your environment use Control+C (on Mac) CTRL+C (on Win) or docker compose down # start the services docker compose up ``` When you change the service's Dockerfile or the contents of the build directory, run stop then build. (For example after modifying package.json or Gemfile) ```bash theme={null} docker compose stop docker compose build ``` The docker-compose environment consists of: * chatwoot server * postgres * redis * webpacker-dev-server If in case you encounter a seeding issue or you want reset the database you can do it using the following command: ```bash theme={null} docker compose run --rm rails bundle exec rake db:reset ``` This command essentially runs postgres and redis containers and then run the rake command inside the chatwoot server container. #### Testing chat widget in your local environment with Docker First,compile the assets. Run: ```bash theme={null} docker compose exec rails bundle exec rails assets:precompile ``` Then use the URLs from [#testing-chat-widget-in-your-local-environment](/contributing-guide/project-setup#testing-chat-widget-in-your-local-environment) ### Running Cypress Tests First,compile the assets. Run: ```bash theme={null} docker compose exec rails bundle exec rails assets:precompile ``` ## Running Cypress Tests Refer the docs to learn how to write cypress specs: * [https://github.com/shakacode/cypress-on-rails](https://github.com/shakacode/cypress-on-rails) * [https://docs.cypress.io/guides/overview/why-cypress.html](https://docs.cypress.io/guides/overview/why-cypress.html) ```bash theme={null} # in terminal tab1 overmind start -f Procfile.test # in terminal tab2 pnpm cypress open --project ./test ``` ## Debugging Docker for production You can use our official Docker image from [https://hub.docker.com/r/chatwoot/chatwoot](https://hub.docker.com/r/chatwoot/chatwoot) ```bash theme={null} docker pull chatwoot/chatwoot ``` You can create an image yourselves by running the following command on the root directory. ```bash theme={null} docker compose -f docker-compose.production.yaml build ``` This will build the image which you can deploy in Kubernetes (GCP, Openshift, AWS, Azure or anywhere), Amazon ECS or Docker Swarm. You can tag this image and push this image to docker registry of your choice. Remember to make the required environment variables available during the deployment. ## Next Steps After completing this setup: 1. **Verify Installation**: Access [http://localhost:3000](http://localhost:3000) and log in with the provided credentials 2. **Explore the Code**: Start making changes and see them reflected in your development environment 3. **Run Tests**: Execute the test suite to ensure everything works correctly 4. **Check Troubleshooting**: If you encounter issues, refer to [Common Errors](/contributing-guide/common-errors) ## Getting Help If you encounter issues during setup: * **Common Errors**: Check [Common Errors](/contributing-guide/common-errors) * **Environment Variables**: See [Environment Variables](/contributing-guide/environment-variables) * **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS) * **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues) *** Your Chatwoot development environment is now ready for contribution! 🚀 # Telegram App Integration Setup Source: https://developers.chatwoot.com/contributing-guide/telegram-channel-setup Setup Telegram app integration on your local machine for development # Setup Telegram app integration on your local machine Please follow the steps if you are trying to work with the Telegram integration on your local machine. ## Prerequisites * Telegram Bot Token from [BotFather](https://t.me/botfather) * Ngrok or similar tunneling service * Running Chatwoot development environment ## Setup Steps ### 1. Start Ngrok Server Start a Ngrok server listening at port `3000` or the port you will be running the Chatwoot installation: ```bash theme={null} # Install ngrok if you haven't already # Download from https://ngrok.com/download # Start ngrok tunnel ngrok http 3000 ``` ### 2. Update Environment Variables Update the `.env` variable `FRONTEND_URL` in Chatwoot with the `https` version of the Ngrok URL: ```bash theme={null} # In your .env file FRONTEND_URL=https://your-ngrok-subdomain.ngrok.io ``` ### 3. Start Chatwoot Server Start the Chatwoot server and create a new Telegram channel with the token obtained from Telegram BotFather. ```bash theme={null} # Start the development server make run # or foreman start -f Procfile.dev ``` ### 4. Create Telegram Channel 1. **Access Chatwoot**: Go to your Chatwoot instance ([http://localhost:3000](http://localhost:3000)) 2. **Navigate to Settings** → **Inboxes** → **Add Inbox** 3. **Select Telegram** as the channel type 4. **Enter Bot Token**: Paste the token you received from BotFather 5. **Configure Channel**: Set up the channel name and other settings ## Verify Webhook Registration While creating the channel, Chatwoot should have registered a webhook callback URL in Telegram for your Bot. You can verify whether this URL registration was done successfully by calling the Telegram API: ```bash theme={null} GET https://api.telegram.org/bot{your_bot_token}/getWebhookInfo ``` ## Testing the Integration If the webhook is registered correctly with Telegram, your Ngrok server should receive events for new Telegram messages, and new conversations will be created in Chatwoot. ### Test Steps 1. **Send a message** to your Telegram bot 2. **Check Ngrok logs** to see if the webhook request is received 3. **Check Chatwoot** to see if a new conversation is created 4. **Reply from Chatwoot** to test bidirectional communication ## Troubleshooting **Problem**: Telegram webhook registration fails **Solution**: * Ensure your Ngrok URL is accessible publicly * Check that `FRONTEND_URL` is set correctly in your `.env` file * Verify the bot token is correct * Restart Chatwoot after updating environment variables **Problem**: Telegram messages don't create conversations in Chatwoot **Solution**: * Check Ngrok logs for incoming webhook requests * Verify the webhook URL in Telegram using the API call above * Check Chatwoot logs for any error messages * Ensure the channel is properly configured and enabled **Problem**: SSL certificate issues with webhook **Solution**: * Use the `https` version of your Ngrok URL * Ensure Ngrok is running properly * Try restarting Ngrok and updating the webhook ## Next Steps After successful setup: 1. **Test message flow** between Telegram and Chatwoot 2. **Configure agent assignments** for Telegram conversations 3. **Set up automated responses** if needed 4. **Review webhook logs** for debugging ## Getting Help If you encounter issues: * **Check Logs**: Review both Chatwoot and Ngrok logs * **Telegram Bot API**: [Official Documentation](https://core.telegram.org/bots/api) * **Common Errors**: See [Common Errors](/contributing-guide/common-errors) * **Community Support**: [Discord](https://discord.com/invite/cJXdrwS) *** Your Telegram integration is now ready for development and testing! 📱 # End-to-end testing with Cypress Source: https://developers.chatwoot.com/contributing-guide/tests/cypress Guide to running Cypress end-to-end tests for Chatwoot # End-to-end testing with Cypress Chatwoot uses [Cypress](https://www.cypress.io/) for end-to-end testing. Use the following steps to run the tests on your local machine. ## Prepare the Test Server Choose any of the given methods to run your Chatwoot test server. ### Using Local Chatwoot Installation You have to install the necessary dependencies as described in [setup guide](/contributing-guide/setup-guide) for this method to work. Navigate to Chatwoot codebase in your local machine and execute the following steps: #### Create a fresh test database ```bash theme={null} RAILS_ENV=test bin/rake db:drop RAILS_ENV=test bin/rake db:create RAILS_ENV=test bin/rake db:schema:load ``` #### Start Chatwoot in the test environment ```bash theme={null} RAILS_ENV=test foreman start -f Procfile.test ``` Load the URL in the browser and wait for it to start up: ``` http://localhost:5050/app/login ``` ### Using Docker Follow the [docker setup guide](/contributing-guide/environment-setup/docker) until you build the images. #### Change the Rails Environment Open `docker-compose.yaml` and update all the `RAILS_ENV` values from `development` to `test`: ```yaml theme={null} # In docker-compose.yaml environment: - RAILS_ENV=test # Change from development to test ``` #### Update the Port Under rails section in your `docker-compose.yaml` update the port value as given below: ```yaml theme={null} # In docker-compose.yaml ports: - 5050:3000 # Change from 3000:3000 to 5050:3000 ``` #### Reset the Database ```bash theme={null} docker-compose run --rm rails bundle exec rails db:reset ``` #### Start Chatwoot Docker in the test environment ```bash theme={null} docker-compose up ``` Load the URL in the browser and wait for it to start up: ``` http://localhost:5050/app/login ``` ## Run Cypress Load `localhost:5050` on your browser and ensure that the Chatwoot server is running. Navigate to your Chatwoot local directory and execute the following command to run the Cypress tests: ```bash theme={null} pnpm cypress open --project ./spec ``` This will open the Cypress Test Runner where you can: 1. **Choose a browser** for running tests 2. **Select test files** to run individual or all tests 3. **Watch tests run** in real-time with step-by-step execution 4. **Debug failed tests** with detailed error information ## Getting Help If you encounter issues with Cypress testing: * **Cypress Documentation**: [Official Cypress Docs](https://docs.cypress.io/) * **Cypress Best Practices**: [Testing Guide](https://docs.cypress.io/guides/references/best-practices) * **Common Errors**: See [Common Errors](/contributing-guide/common-errors) * **Community Support**: [Discord](https://discord.com/invite/cJXdrwS) ## Useful Resources * **Cypress API Reference**: [https://docs.cypress.io/api/table-of-contents](https://docs.cypress.io/api/table-of-contents) * **Testing Library**: [Testing utilities for better element selection](https://testing-library.com/) * **Cypress Examples**: [Real-world examples](https://github.com/cypress-io/cypress-example-recipes) *** Your Cypress testing environment is now ready for comprehensive end-to-end testing! 🧪 # Translate Chatwoot to Your Language Source: https://developers.chatwoot.com/contributing-guide/translation-guidelines Guide to translating Chatwoot using Crowdin translation platform # Translate Chatwoot to Your Language Chatwoot uses American English by default. Each and every string available in Chatwoot can be translated to the language of your choice. Chatwoot uses Crowdin to manage the translation process. The updates from Crowdin are also included along with every release. ## How do I see the strings that need to be translated? In the codebase, the strings are placed in the following locations: * `app/javascript/dashboard/i18n` - The strings related to the agent dashboard * `app/javascript/widget/i18n` - The strings related to the web widget * `app/javascript/survey/i18n` - The strings related to CSAT surveys * `config/locales` - The strings used in backend messages or API responses You can login to **Crowdin** ([https://translate.chatwoot.com](https://translate.chatwoot.com)) and create an account to view the strings that need to be translated. ## How to contribute? If you don't find your language on Crowdin, please create an issue on [GitHub](https://github.com/chatwoot/chatwoot/issues) to add the language. ### Translate Strings The translation process for Chatwoot web and mobile app is managed at [https://translate.chatwoot.com](https://translate.chatwoot.com) using Crowdin. You will have to create an account at Crowdin before you can select a language and contribute. New to Crowdin? Check out their [getting started guide](https://support.crowdin.com/crowdin-intro/) to learn the basics of translation management. ### Translation Guidelines #### Formal vs Informal Context At Chatwoot, we prefer to use formal form of language wherever possible. For instance in German there are two forms of "you" where one is rather used in formal contexts ("Sie") and the other one is used among friends ("Du"). "Sie" is preferred over "Du" in translating Chatwoot. #### Consistency Guidelines * **Maintain consistency** across similar contexts and features * **Use standard terminology** for technical terms when available in your language * **Keep placeholders intact** - Don't translate variables like `{name}` or `%{count}` * **Preserve formatting** - Maintain HTML tags, markdown, and line breaks * **Consider context** - UI strings may need to be shorter than descriptive text #### Brand and Product Names * **Chatwoot** - Always keep as "Chatwoot" (don't translate) * **Feature names** - Translate feature names but maintain consistency * **Third-party services** - Keep original names (GitHub, Slack, etc.) ### Proofreading Proofreading helps ensure the accuracy and consistency of translations. Right now, the translations are being accepted without a proofreading step. This would be changed in the future as and when there are more contributors for each language. If you are the only person contributing to a language, make sure that you inform any of the Chatwoot members to gain access to manage the language. ### Releasing a New Language All the translated strings would be included in the next release. If a language has **60% or more translated strings** in Crowdin, we would enable the language in Chatwoot app during the next release. #### Steps to Raise a Pull Request for New Language Please use this [pull request](https://github.com/chatwoot/chatwoot/pull/7905) as a reference for enabling a new language into Chatwoot. * Ensure language is added and enabled in `config/initializers/languages.rb` * Include the language in `i18n/index.js` for all the packs → `dashboard, widget, survey` * Select the language from Chatwoot settings UI and confirm the PR to be working ## Translation Progress and Metrics ### Current Status You can check the translation progress for different languages on our [Crowdin project page](https://translate.chatwoot.com). This shows: * **Overall completion percentage** for each language * **Component-wise progress** (Dashboard, Widget, Survey, API) * **Recent activity** and contributor statistics ### Quality Metrics We track several quality indicators: * **Translation coverage** - Percentage of strings translated * **Review coverage** - Percentage of translations reviewed * **Consistency score** - How consistent terminology is across the platform * **Community engagement** - Number of active translators ## Best Practices for Translators ### Before You Start 1. **Review existing translations** in your language for consistency 2. **Understand the context** - Test the feature in Chatwoot if possible 3. **Check for existing glossaries** or style guides for your language 4. **Join the community** discussions for your language ### During Translation 1. **Focus on user experience** - How will end users understand this? 2. **Maintain professional tone** appropriate for business communication 3. **Ask questions** if context is unclear 4. **Suggest improvements** for source text if needed ### After Translation 1. **Test your translations** in a live Chatwoot instance 2. **Report issues** if translations don't fit in the UI 3. **Help review** other contributors' work 4. **Stay updated** with new strings added ## Getting Help and Support ### Community Resources * **GitHub Discussions**: [Translation category](https://github.com/chatwoot/chatwoot/discussions/categories/translations) * **Discord**: Join our [Discord community](https://discord.gg/uPtCrFfb9B) (#translations channel) * **Crowdin Comments**: Use comments feature in Crowdin for context-specific questions ### Technical Support For technical issues with translations: * **Missing context**: Create an issue on GitHub * **UI layout problems**: Report in Discord with screenshots * **Crowdin access issues**: Contact the maintainers ### Recognition We recognize and appreciate our translation contributors: * **Contributors page**: Featured on our contributors page * **Release notes**: Mentioned in release announcements * **Community highlights**: Featured in community updates ## Multilingual Support Features Chatwoot's internationalization supports: * **Right-to-left (RTL) languages** - Arabic, Hebrew, etc. * **Pluralization rules** - Correct plural forms for different languages * **Date and time formatting** - Localized date/time display * **Number formatting** - Currency and number format localization *** Ready to help make Chatwoot accessible to users worldwide? [Start translating today](https://translate.chatwoot.com)! 🌍 # Welcome to Chatwoot Developer Docs Source: https://developers.chatwoot.com/introduction Your comprehensive guide to installing, configuring, developing with, and integrating Chatwoot - the open-source customer support platform. ## What You'll Find Here Deploy Chatwoot on your infrastructure with Docker, Kubernetes, or cloud providers Contribute to Chatwoot with our development setup, testing guidelines, and best practices Manage your inbox from the terminal or coding agents Build powerful integrations with our comprehensive REST APIs ## Getting Started Paths Choose your path based on what you want to accomplish: ### 🚀 **I want to install Chatwoot** Perfect! Head to our [Installation Guide](/self-hosted) to deploy Chatwoot on your preferred platform. We support: * Docker containers for quick setup * Kubernetes for scalable deployments * Major cloud providers (AWS, GCP, Azure) * Traditional Linux VMs ### 🛠️ **I want to contribute to Chatwoot** Check out our [Contributing Guide](/contributing-guide) to: * Set up your development environment * Understand our coding standards * Learn our testing practices * Submit your first pull request ### 🔌 **I want to build integrations** Great! Explore our [API Reference](/api-reference/introduction) with three categories of APIs: * **Application APIs** - Manage accounts, agents, and conversations * **Platform APIs** - Administrative control for installations * **Client APIs** - Build custom chat interfaces ### 📚 **I want to understand the architecture** Excellent! Our [Architecture Guide](/self-hosted/deployment/architecture) covers: * System components and their interactions * Database schemas and relationships * Scalability considerations * Security best practices ## Why Chatwoot? Chatwoot is built with modern technologies and follows industry best practices: * **Open Source**: Full transparency and community-driven development * **Multi-channel**: Support customers across web, mobile, email, and social platforms * **Scalable**: From small teams to enterprise deployments * **Extensible**: Rich APIs and webhook system for custom integrations * **Modern Stack**: Ruby on Rails backend, Vue.js frontend, PostgreSQL database ## Community & Support Join our thriving community of developers and users: * **GitHub**: [github.com/chatwoot/chatwoot](https://github.com/chatwoot/chatwoot) * **Community**: [chatwoot.com/community](https://chatwoot.com/community) * **Discussions**: [GitHub Discussions](https://github.com/chatwoot/chatwoot/discussions) * **Twitter**: [@chatwootapp](https://twitter.com/chatwootapp) *** Ready to dive in? Choose your path above and let's build something amazing together! 🚀 # Self-Hosted Installation Guide Source: https://developers.chatwoot.com/self-hosted Complete guide to install and setup a production-ready Chatwoot instance on your own infrastructure. Welcome to the Chatwoot self-hosted installation guide. This comprehensive documentation will help you deploy, configure, and maintain your own Chatwoot instance with full control over your data and infrastructure. ## Why Self-Host Chatwoot? Self-hosting Chatwoot gives you complete control over your customer support platform: * **Data Privacy**: Keep all customer data on your own servers * **Customization**: Modify the platform to fit your specific needs * **Cost Control**: No per-agent pricing - scale as much as you need * **Compliance**: Meet specific regulatory requirements * **Integration**: Deep integration with your existing infrastructure ## Deployment Options Chatwoot supports multiple deployment methods to fit different infrastructure needs: ### 🐧 Linux VM Deployment Deploy directly on Ubuntu/Linux virtual machines with our automated installation script. * **Best for**: Traditional server environments * **Complexity**: Low to Medium * **Maintenance**: Manual updates required ### 🐳 Docker Deployment Use Docker containers for consistent, portable deployments. * **Best for**: Containerized environments * **Complexity**: Medium * **Maintenance**: Easy updates with container pulls ### ☸️ Kubernetes Deployment Deploy on Kubernetes clusters for enterprise-scale operations. * **Best for**: Large-scale, high-availability deployments * **Complexity**: High * **Maintenance**: Automated with proper CI/CD ### ☁️ Cloud Provider Deployments One-click deployments on major cloud platforms: * **AWS**: EC2, ECS, and Marketplace options * **Azure**: Container Instances and VM deployments * **DigitalOcean**: Droplets and App Platform * **Google Cloud**: Compute Engine and Cloud Run * **Heroku**: Simple one-click deployment ## System Requirements ### Minimum Requirements * **CPU**: 2 cores * **RAM**: 4GB * **Storage**: 20GB SSD * **OS**: Ubuntu 20.04+ or compatible Linux distribution ### Recommended for Production * **CPU**: 4+ cores * **RAM**: 8GB+ * **Storage**: 50GB+ SSD * **Database**: PostgreSQL 12+ * **Cache**: Redis 6+ * **Reverse Proxy**: Nginx or similar ## What You'll Need Before starting your Chatwoot installation, ensure you have: ### Technical Requirements * [ ] Server or cloud instance meeting minimum requirements * [ ] Domain name (recommended for production) * [ ] SSL certificate (Let's Encrypt recommended) * [ ] SMTP server for email notifications ### Access Requirements * [ ] SSH access to your server * [ ] Root or sudo privileges * [ ] Firewall configuration access ### Optional but Recommended * [ ] Object storage (AWS S3, Google Cloud Storage, etc.) * [ ] CDN for static assets * [ ] Monitoring tools (APM, logging) * [ ] Backup solution ## Security Considerations When self-hosting Chatwoot, consider these security aspects: * **Regular Updates**: Keep Chatwoot and system packages updated * **Firewall Configuration**: Only expose necessary ports * **SSL/TLS**: Always use HTTPS in production * **Database Security**: Secure PostgreSQL with strong passwords * **Backup Encryption**: Encrypt sensitive backup data * **Access Control**: Implement proper user access controls ## Getting Started Ready to deploy Chatwoot? Choose your preferred deployment method: Get up and running quickly with Docker containers Traditional server deployment with our automated script Enterprise-scale deployment on Kubernetes One-click deployments on major cloud platforms ## Community and Support * **Documentation**: Comprehensive guides and API references * **GitHub**: [Source code and issue tracking](https://github.com/chatwoot/chatwoot) * **Discord**: [Community chat and support](https://discord.gg/cJXdrwS) * **Forum**: [Community discussions and Q\&A](https://github.com/chatwoot/chatwoot/discussions) # Environment Variables Source: https://developers.chatwoot.com/self-hosted/configuration/environment-variables Complete reference for Chatwoot environment variables and configuration options ## The .env File We use the `dotenv-rails` gem to manage the environment variables. There is a file called `env.example` in the root directory of this project with all the environment variables set to empty values. You can set the correct values as per the following options. Once you set the values, you should rename the file to `.env` before you start the server. ## Configure frontend URL (domain) Provide your chatwoot domain as frontend URL. ```bash theme={null} FRONTEND_URL='https://your-chatwoot-domain.tld' ``` ## Rails production variables For production deployment, you have to set the following variables ```bash theme={null} RAILS_ENV=production SECRET_KEY_BASE=replace_with_your_own_secret_string ``` You can generate `SECRET_KEY_BASE` using `rake secret` command from the project root folder. If you dont have rails installed, use `head /dev/urandom | tr -dc A-Za-z0-9 | head -c 63 ; echo ''`. SECRET\_KEY\_BASE should be alphanumeric. Avoid special characters or symbols. ## Database configuration Postgres can be configured in two ways: via `DATABASE_URL` or setting up independent Postgres variables. ### Configure Postgres Set the `DATABASE_URL` variable with value as Postgres connection URI to connect to the database. The URI is of the format ```bash theme={null} postgresql://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...] ``` Or you can set the following environment variables to configure Postgres. Replace the values here with yours. Skip this if you have configured `DATABASE_URL`. ```bash theme={null} POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DATABASE=chatwoot_production POSTGRES_USERNAME=admin POSTGRES_PASSWORD=password ``` ### Configure Redis For development, you can use the following URL to connect to Redis. For production, configure your Redis URL. ```bash theme={null} REDIS_URL='redis://127.0.0.1:6379' ``` To authenticate Redis connections made by the app server and sidekick, if it's protected by a password, use the following environment variable to set the password. ```bash theme={null} REDIS_PASSWORD= ``` ## Configure emails For development, you don't need an email provider. Chatwoot uses the [letter-opener](https://github.com/ryanb/letter_opener) gem to test emails locally For production use, please configure the following variables. ```bash theme={null} # could user either `email@yourdomain.com` or `BrandName ` MAILER_SENDER_EMAIL= ``` and based on your SMTP server the following variables ```bash theme={null} SMTP_ADDRESS= SMTP_USERNAME= SMTP_PASSWORD= SMTP_TLS= SMTP_SSL= ``` ### Postfix Follow these steps if you want to use a selfhosted mail server with Chatwoot. This is the default behavior starting from `v2.12.0` and relies on `SMTP_ADDRESS` environment variable not being set. ``` sudo apt install -y postfix ``` Choose internet-site when prompted and enter the domain name you used with Chatwoot setup for `System mail name`. By default, all major cloud provider have blocked port 25 used for sending emails as part of their spam combat effects. Please raise a support ticket with your cloud provider to enable outbound access on port 25 for this to work. Refer [AWS](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle), [GCP](https://cloud.google.com/compute/docs/tutorials/sending-mail), [Azure](https://learn.microsoft.com/en-us/azure/virtual-network/troubleshoot-outbound-smtp-connectivity) and [DigitalOcean](https://www.digitalocean.com/blog/smtp-restricted-by-default) for more details. Also please add MX and PTR records for your domain. If your emails are being flagged by `Gmail` and `Outlook`, setup [SPF and DKIM records](https://www.linuxbabe.com/mail-server/setting-up-dkim-and-spf) for your domain as well. This should improve your email reputation. ### Amazon SES ```bash theme={null} SMTP_ADDRESS=email-smtp..amazonaws.com SMTP_AUTHENTICATION=plain SMTP_ENABLE_STARTTLS_AUTO=true SMTP_USERNAME= SMTP_PASSWORD= ``` ### SendGrid For clarification, the `SMTP_USERNAME` should be set to the literal text apikey—this is not the actual API key. SendGrid uses 'apikey' as the standard username for its services. ```bash theme={null} SMTP_ADDRESS=smtp.sendgrid.net SMTP_AUTHENTICATION=plain SMTP_DOMAIN= SMTP_ENABLE_STARTTLS_AUTO=true SMTP_PORT=587 SMTP_USERNAME=apikey SMTP_PASSWORD= ``` ### MailGun ```bash theme={null} SMTP_ADDRESS=smtp.mailgun.org SMTP_AUTHENTICATION=plain SMTP_DOMAIN= SMTP_ENABLE_STARTTLS_AUTO=true SMTP_PORT=587 SMTP_USERNAME= SMTP_PASSWORD= ``` ### Mandrill If you would like to use Mailchimp to send your emails, use the following environment variables: Mandrill is the transactional email service for Mailchimp. You need to enable transactional email and login to mandrillapp.com. ```bash theme={null} SMTP_ADDRESS=smtp.mandrillapp.com SMTP_AUTHENTICATION=plain SMTP_DOMAIN= SMTP_ENABLE_STARTTLS_AUTO=true SMTP_PORT=587 SMTP_USERNAME= SMTP & API info> SMTP_PASSWORD= SMTP & API Info> ``` ## Configure default language ```bash theme={null} DEFAULT_LOCALE='en' ``` ## Configure storage Chatwoot uses [active storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) for storing attachments. The default storage option is the local storage on your server. But you can change it to use any of the cloud providers like amazon s3, microsoft azure, google gcs etc. Refer [configuring cloud storage](/self-hosted/deployment/storage/supported-providers) for additional environment variables required. ```bash theme={null} ACTIVE_STORAGE_SERVICE=local ``` When `local` storage is used the files are stored under `/storage` directory in the chatwoot root folder. It is recommended to use a cloud provider for your chatwoot storage to ensure proper backup of the stored attachments and prevent data loss. ## Rails Logging Variables By default, Chatwoot will capture `info` level logs in production. Ref [rails docs](https://guides.rubyonrails.org/debugging_rails_applications.html#log-levels) for the additional log-level options. We will also retain 1 GB of your recent logs and your last shifted log file. You can fine-tune these settings using the following environment variables ```bash theme={null} # possible values: 'debug', 'info', 'warn', 'error', 'fatal' and 'unknown' LOG_LEVEL= # value in megabytes LOG_SIZE= 1024 ``` ## Configure FB Channel To use FB Channel, you have to create a Facebook app in the developer portal. You can find more details about creating FB channels [here](https://developers.facebook.com/docs/apps/#register) ```bash theme={null} FB_VERIFY_TOKEN= FB_APP_SECRET= FB_APP_ID= ``` ## Using CDN for asset delivery With the release v1.8.0, we are enabling CDN support for Chatwoot. If you have a high traffic website, we recommend to setup a CDN for your asset delivery. Read setting up [CloudFront as your CDN](/self-hosted/deployment/performance/cloudfront-cdn) guide. ## Enable new account signup By default, Chatwoot will not allow users to create an account\[multi-tenancy] from the login page. However, if you are setting up a public server, you can enable signup using: ```bash theme={null} ENABLE_ACCOUNT_SIGNUP=true ``` ## Enable direct upload to storage cloud By default, Chatwoot will upload the files to the application server and then it will push them to the cloud storage. We have introduced the direct upload functionality so that we can upload the file directly to the cloud storage. This has been built according to rails new direct upload functionality documented [here](https://edgeguides.rubyonrails.org/active_storage_overview.html#direct-uploads). Set below environment variable to true to use the direct upload feature. Make sure to follow [this guide](https://edgeguides.rubyonrails.org/active_storage_overview.html#cross-origin-resource-sharing-cors-configuration) and set the appropriate CORS configuration on your cloud storage after setting `DIRECT_UPLOADS_ENABLED` to true. ```bash theme={null} DIRECT_UPLOADS_ENABLED=true ``` ## Google OAuth To enable Google OAuth in Chatwoot, you need to provide the client ID, client secret, and callback URL. You can find the instructions to generate the details [here](https://support.google.com/cloud/answer/6158849). Set the `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` environment variables in your Chatwoot installation using the values you copied from the Google API Console. Set the `GOOGLE_OAUTH_CALLBACK_URL` environment variable to the callback URL you used in the Google API Console. Here's an example of the same ```bash theme={null} GOOGLE_OAUTH_CLIENT_ID=369777777777-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com GOOGLE_OAUTH_CLIENT_SECRET=ABCDEF-GHijklmnoPqrstuvwX-yz1234567 GOOGLE_OAUTH_CALLBACK_URL=https:///omniauth/google_oauth2/callback ``` The callback URL should comply with the format in the example above. This endpoint cannot be changed at the moment. After setting these environment variables, restart your Chatwoot server to apply the changes. Now, users will be able to sign in using their Google accounts. ## LogRocket To enable LogRocket in Chatwoot, you need to provide the project ID from LogRocket. Here are the steps to follow: 1. Open the LogRocket [website](https://logrocket.com/) and create an account or sign in to your existing account. 2. After signing in, create a new project in LogRocket by clicking on "Create new project". 3. Enter a name for your project, and save the project ID. 4. Set the `LOG_ROCKET_PROJECT_ID` environment variable in your `.env` file with the project ID you copied from LogRocket. ```bash theme={null} LOG_ROCKET_PROJECT_ID=abcd12/pineapple-on-pizza ``` After setting this environment variable, restart your Chatwoot server to apply the changes. Now, LogRocket will start capturing user sessions on your Chatwoot installation. # Configuring Amazon SES as an Ingress Provider for Chatwoot Source: https://developers.chatwoot.com/self-hosted/configuration/features/email-channel/amazon-ses-ingress Guide to setting up conversation continuity, inbound emails with Amazon SES This guide explains how to set up Amazon SES as the incoming email (ingress) provider for your self-hosted Chatwoot installation. If you plan to use Chatwoot’s email forwarding option and want SES to handle inbound mail delivery into Chatwoot, this documentation is for you. ### Who is this for? This setup is intended for: * Teams running self‑hosted Chatwoot. * Users who want to use Amazon SES to receive inbound emails. * Workspaces that want to configure forwarding rules rather than using IMAP/OAuth connections to bring emails into Chatwoot. If you are using Chatwoot Cloud, you do not need this setup. ### Architecture At a high level, the flow looks like this: Architecture 1. An email is sent to your domain (e.g., [support@yourdomain.com](mailto:support@yourdomain.com)). 2. Amazon SES receives the email. 3. SES forwards the message to an SNS Topic. 4. SNS publishes the message payload to a Chatwoot email ingress endpoint. 5. Chatwoot processes the payload and creates/updates a conversation. ### Prerequisites Before you begin, you should have: * Access to AWS SES, SNS, Route53 (or your DNS provider). * A self‑hosted Chatwoot installation reachable over HTTPS. ### Step 1: Verify Your Domain in Amazon SES Amazon SES must verify that you own the domain before it can receive mail. 1. Log in to AWS Console → SES → Identities. 2. Click Create Identity. 3. Choose Domain. 4. Enter the domain you want to receive email for. 5. Amazon SES will show DNS records you must add: * DKIM (CNAME) records * SPF (TXT) record * DMARC (TXT) record (optional but recommended) 6. Add all records to your DNS provider. 7. Wait for the identity status to become verified. ### Step 2: Configure MX Records to Route Email to SES SES must become the inbound email handler for your domain. 1. In SES, open Configuration → Email Receiving. 2. Locate the MX record value for your region (example: 10 inbound-smtp.us-east-1.amazonaws.com). 3. Go to your DNS provider. 4. Add an MX record: * Priority: 10 * Value: `inbound-smtp..amazonaws.com` Once this is set, your domain will start routing incoming mail to SES. If you have any doubts about setting this up, read more at [AWS SES documentation](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-setting-up.html). ### Step 3: Configure SES to Publish Inbound Emails to SNS Chatwoot reads incoming messages via SNS notifications. Go to SES → Email Receiving → Rule Sets. SES Email Receiving Create a Rule Set if you don’t have one. SES Rule Sets Add a new rule: * Recipients → Add your inbound email (e.g. [support@yourdomain.com](mailto:support@yourdomain.com)) or ignore this field since it would forward every email to SNS (which is better if you have more than one email channel) * Actions → Publish to Amazon SNS topic * Select your SNS topic. * Make sure that you select the Encoding as UTF-8. SES Publish to SNS Save and enable the rule. Note: You don't have to turn on Transport Layer Security (TLS) or Spam and virus scanning for this setup. Now SES will publish every inbound email event to your SNS topic. ### Step 4: Configure Chatwoot Environment Variables Before creating the SNS subscription, you must configure two environment variables in your Chatwoot installation: ```bash theme={null} RAILS_INBOUND_EMAIL_SERVICE=ses # SNS topic ARN for ActionMailbox (format: arn:aws:sns:region:account-id:topic-name) # Configure only after you create the SNS topic in AWS ACTION_MAILBOX_SES_SNS_TOPIC= ``` Why this matters: Chatwoot needs to know that SES will be used for inbound email. Chatwoot must be ready to valid the SNS topic once the subscription is created. ### Step 5: Create SNS Subscription to Forward to Chatwoot SNS needs to send the email payload directly to Chatwoot. Go to SNS → Topics. Open the topic you created. Click Create Subscription. SES Create Subscription Set: * Protocol: HTTPS * Endpoint: Your Chatwoot email ingress endpoint `https://chatwoot.example.com/rails/action_mailbox/ses/inbound_emails` SES Create Subscription Save. Note: SNS will send a confirmation request. Chatwoot will automatically confirm the subscription. ### Step 6: Add Email Channel in Chatwoot 1. Go to your Chatwoot account. Settings → Inboxes → Add Inbox. 2. Choose Email -> Other Providers. 3. Use any email address from the domain that is configured in SES. After this you should see incoming email in your inbox. ### Troubleshooting Emails not appearing in Chatwoot: * Check SES → SNS → Subscription delivery logs. * Check SNS subscription status. * Check Chatwoot logs for any errors. * Ensure Chatwoot server is reachable publicly. * Check if MX records propagated. SNS subscription not confirmed: * Ensure Chatwoot server is reachable publicly. * Verify system time and SSL certificates on your server. If you are testing this in local environment, you can use tools like ngrok to expose your Chatwoot server to the internet. Make sure that you are using `openssl<=3.5`. # Outlook & Microsoft 365 Email Source: https://developers.chatwoot.com/self-hosted/configuration/features/email-channel/azure-app-setup Configure an OAuth app for Outlook & Microsoft 365 emails Microsoft no longer permits the use of username and password to retrieve emails from Outlook & Microsoft 365 accounts. They have deprecated the basic auth option. To enable the Outlook/Microsoft 365 email channel in your self-hosted instance, you must configure an OAuth app. This guide helps you set up an Entra ID App (formerly Azure Active Directory) and use the credentials in Chatwoot. By doing so, you can authenticate your Outlook/Microsoft 365 account as an email channel. ## Register the app For a more detailed guide on how to set up the Microsoft Identity platform, please refer to the [here](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). To access the Microsoft Entra Admin Center, go to [entra.microsoft.com](https://entra.microsoft.com/) and log in with your Microsoft account. Once logged in, navigate to the Identity section on the left-hand sidebar. In the Identity section, locate the "Applications" menu and click on "App Registrations" from the submenu. On the "App Registrations" page, click on the "New Registration" option. You will be able to see a page as shown below. register-an-app There are three options for supported account types. Ideally, you only need to select "Accounts in any organizational directory" as Chatwoot is generally used for business emails only. However, if you are connecting a personal account, select the second option. If you are using the applications outside your organization, you would need to register your account as a verified publisher. To configure a redirect URI with the Web platform, use the following URL: `https:///microsoft/callback`. Click on register, and your app will be created. You will see a screen as shown below. registration-complete Save the Application (Client) ID. We will configure this as `AZURE_APP_ID` in Chatwoot later. ## Configure the application To ensure proper functionality of Chatwoot, we need to configure the permissions and update the token configuration as follows. ### API permissions Click on the "API Permissions" menu under the "Manage" section. By default, this will have [User.Read](http://user.read/) permission. Click on the "Add permissions" button and add the following permissions from the Delegated permissions menu on Microsoft Graph APIs. * **email**: To view the user's email address. * **profile**: To view the name and picture etc. * **offline\_access**: To retrieve the emails even when you are not using the application. * **SMTP.Send, Mail.Send:** Send emails using the SMTP AUTH when you reply to customers from the Chatwoot dashboard. * **IMAP.AccessAsUser.All, Mail.ReadWrite:** Read and write access to mailboxes via IMAP. * **openid:** Sign users in permissions ### Token Configuration Now, let's proceed to the Token Configuration to set up "optional claims". Optional claims are a feature in Entra ID that enables you to specify additional pieces of information (claims) to include in the security tokens issued to the application. In Chatwoot, we use optional claims to minimize duplicate calls and retrieve some information in advance. Click on "Add optional claim" and add the following claims to the application. optional-claims.png ### Configure Client Secret Go to the Certificates & Secrets section to create a Client Secret. Click on the "New Client Secret" button and provide a description. You can also select an expiry time. Remember that you will need to regenerate the secret and update it in the Chatwoot environment variables once it expires. add-client-secret After clicking on the Add button, a client secret will be generated as shown below. client-secret-value Save the value somewhere save as you cannot see it after refreshing the page. This would be used `AZURE_APP_SECRET` in Chatwoot. ## Configure environment variables in Chatwoot After creating the Entra application, you need to configure the application credentials in Chatwoot. There are 2 variables that you need to configure, as shown in the steps above. * **AZURE\_APP\_ID:** As seen in the register the app step, use the Application (Client) ID here. * **AZURE\_APP\_SECRET:** Use the value obtained in the step configuring the client secret. After updating the environment variables, restart the Chatwoot service for the changes to take effect. Now, verify if the channel is enabled in the Inbox creation flow. If everything is configured properly, you will see "Microsoft" listed as an email provider in the flow. microsoft-channel Voila! That's it you can now receive the emails in your Chatwoot instance. ## Thoughts on multi-tenancy and going for production Note that the setup will not work for other emails under a different tenant until you have completed the Microsoft publisher verification process. During the authorization prompt, you will see "unverified" until the application is verified for production. To test the changes before the app is verified for production, use the Entra ID app registration email address in the Chatwoot channel. Publisher verification provides app users and organization admins with information about the authenticity of the developer's organization that publishes an app integrating with the Microsoft identity platform. If an app has a verified publisher, it means that Microsoft has verified the authenticity of the organization that publishes the app. Read the publishing guidelines [here](https://learn.microsoft.com/en-us/entra/identity-platform/howto-convert-app-to-be-multi-tenant). # Conversation Continuity Source: https://developers.chatwoot.com/self-hosted/configuration/features/email-channel/conversation-continuity Continue conversations between website live chat and email When a customer starts a conversation on your website, you don’t want the thread to break just because the user went offline. Chatwoot automatically maintains continuity between the website live chat and email, so the conversation stays in one place for both your agents and your customers. This guide explains how that flow works and what you should set up to ensure everything stays seamless. ### How Conversation Continuity Works #### 1. Customer starts a conversation The customer interacts with your widget and starts a conversation. If Email Collect is enabled, the widget asks the customer for their email address. This email becomes the identifier for all future messages. #### 2. Customer goes offline, agent replies If the agent replies when the customer is no longer online, Chatwoot delivers the agent’s reply to the customer via email. This ensures the user doesn’t miss the update. #### 3. Customer replies from their email The user sees your message in their inbox and simply replies to that email like any normal thread. They don’t need to come back to your website manually — replying from email is enough. #### 4. Chatwoot processes the email and links it to the conversation When Chatwoot receives the user’s email: • It reads the email headers (Message-ID / References / custom thread identifiers) • It maps the email to the correct conversation thread • It adds the user’s reply as a new message inside the same live-chat conversation To the agent, it looks like the user never left. To the user, it feels like replying to any normal email thread. ### What You Need to Enable #### 1. Email Collect Hook Make sure the widget is configured to collect the user’s email early in the conversation. This is the key to linking email replies back to the same thread. #### 2. Email channel configuration Make sure email forwarding is enabled as per this guide: [Forwarding Emails to Chatwoot](./forwarding-emails-to-chatwoot). #### 3. Mailer configuration Outbound emails should be properly configured so Chatwoot can notify the customer when the agent replies offline. After finishing the set up, the mail sent from Chatwoot will have a `replyto:` in the following format `reply+@` and reply to those would get appended to your conversation. # SendGrid Guide Source: https://developers.chatwoot.com/self-hosted/configuration/features/email-channel/conversation-continuity-using-sendgrid Guide to setting up Conversation Continuity with SendGrid This doc will help you set up [Conversation continuity](/self-hosted/configuration/features/email-channel/conversation-continuity) with SendGrid. ## Installation This example is based on a Heroku installation of Chatwoot, and using SendGrid for outgoing email. For more information about installing Chatwoot, go [here](/self-hosted). ## Configuring inbound reply emails Firstly, we need to tell our Chatwoot instance what mailer we're using to handle incoming emails. We do that with a config var. Go to your Heroku dashboard, click on your Chatwoot instance and click settings. ![Screenshot\_95](https://user-images.githubusercontent.com/34171640/128574548-7f2d6521-e79d-47bc-8f8d-6e8d7ca28ae1.png) Then scroll until you see two blank fields with an add button. There, enter: ```javascript theme={null} RAILS_INBOUND_EMAIL_SERVICE=sendgrid ``` ![Screenshot\_96](https://user-images.githubusercontent.com/34171640/128575349-493efe35-86b9-48ea-84ff-cab7020fd832.jpg) Next, we're going to set a password. We'll use this later on with SendGrid. For this example, we'll use something simple - like `potatosalad`, but like all passwords - you should always use a secure mixture of letters, numbers and symbols. ![Screenshot\_97](https://user-images.githubusercontent.com/34171640/128575151-9a3fe484-7f1d-43f9-968f-c9841c4d10d1.jpg) ## SendGrid Now we're going to set up the domain we're using for inbound emails. Because you're most likely going to have an email service like Google Workspace or Microsoft 365 for Business, you should use a subdomain for your inbound emails to Chatwoot. For example, let's say we used support.example.com as our domain. In this instance, we'd add an MX record pointing support.example.com to `mx.sendgrid.net` with a priority of `10`. You should wait a while (usually an hour will do). You can use [mxtoolbox.com](https://mxtoolbox.com) to check if the MX record has been propogated. If you see something like this, you can move onto the next step: ![Screenshot\_98](https://user-images.githubusercontent.com/34171640/128576943-7f8267b5-d81a-4583-8a40-4941c7700d2b.png) Now, go to the SendGrid dashboard at [app.sendgrid.com](https://app.sendgrid.com). Select Settings, and Inbound Parse. ![Screenshot\_99](https://user-images.githubusercontent.com/34171640/128578295-f62fed61-3401-4a4b-a564-f61f282b8c07.png) Then click "Add Host & URL". ![Screenshot\_100](https://user-images.githubusercontent.com/34171640/128581269-2728e8d4-9c5f-4361-ba4f-3543a0f9a9d8.png) **Receiving Subdomain** should be the domain you set up the MX record for earlier. ![Screenshot\_101](https://user-images.githubusercontent.com/34171640/128581298-1271781f-6985-48b2-9ef9-e210ed5b6ecb.png) Then add your **Destination URL**. Your Destination URL should look something like this: `https://actionmailbox:potatosalad@chatwoot.example.com/rails/action_mailbox/sendgrid/inbound_emails` `potatosalad` is the password we set earlier, and `chatwoot.example.com` is the URL of our Chatwoot instance. Everything else should stay the same. ![Screenshot\_102](https://user-images.githubusercontent.com/34171640/128581410-52834258-e826-4c2f-9868-a6c21c9a1ff9.png) Make sure to check "POST the raw, full MIME message". In order to function correctly, Action Mailbox needs the raw MIME message. ![Screenshot\_103](https://user-images.githubusercontent.com/34171640/128581457-ff5e385c-4d7e-4ebb-8f87-28fd5a243798.png) ## Setting the inbound domain variable in Heroku Finally, we need to tell our Chatwoot installation what domain we're using with SendGrid. Your variable should look like this: ```javascript theme={null} MAILER_INBOUND_EMAIL_DOMAIN=support.example.com ``` You should change `support.example.com` to the domain you used with SendGrid. ![Screenshot\_104](https://user-images.githubusercontent.com/34171640/128582096-766a2835-04b9-47f0-8662-c602742e11f9.jpg) ## Next steps You're done! Next, you should [enable the email channel](/self-hosted/configuration/features/email-channel/introduction). # Forwarding Emails to Chatwoot Source: https://developers.chatwoot.com/self-hosted/configuration/features/email-channel/forwarding-emails-to-chatwoot Guide to set up email forwarding to Chatwoot This guide explains how to set up email forwarding to Chatwoot when you prefer not to configure IMAP. Forwarding allows your email provider to push inbound messages directly to Chatwoot, which then processes them as incoming conversations in your inbox. Forwarding emails to Chatwoot requires a [cloud storage configured](/self-hosted/deployment/storage/supported-providers) ## When to Use Forwarding Forwarding is a good option if: * You don’t want to use IMAP or your provider does not allow IMAP access. * You want a simple, push‑based way to deliver inbound emails to Chatwoot. * Your provider supports routing or forwarding rules (Gmail, Google Workspace, Outlook, Fastmail, Zoho, custom servers, etc.). * You already use SMTP for outbound mail and just need a lightweight inbound setup. ## How Forwarding Works in Chatwoot Each email inbox in Chatwoot is assigned an ingress address—a unique, system‑generated email address. When your provider forwards an email to that address, Chatwoot. Note: For installations using an ingress provider (SES, SendGrid, Mailgun, etc.), you must configure an MX record pointing to the ingress provider so that inbound email is accepted and routed correctly. 1. Ingress provider receives the email and forwards it to the configured Chatwoot URL. 2. Chatwoot parses the content, attachments, headers, and thread references. 3. Creates or updates the conversation in the appropriate inbox. 4. Handles message threading properly via `Message-ID`, `References`, and `In-Reply-To`. Outbound email continues to use your configured SMTP provider. ## Requirements To use forwarding successfully, ensure: * **Email ingress is enabled on your Chatwoot installation.** Some self-hosted setups disable ingress by default for security. * **Your installation supports inbound processing** via the configured mailer/ingress pipeline. * **The forwarding rule is set to forward *all* relevant mail**, including replies. * **SPF, DKIM, and DMARC** are correctly configured on your domain for good deliverability. If ingress is disabled, Chatwoot will show a warning in the UI. Your administrator must enable it before forwarding works. The receiving domain should be configured in the environment variable `MAILER_INBOUND_EMAIL_DOMAIN`. ``` MAILER_INBOUND_EMAIL_DOMAIN= ``` ## Finding the Forwarding Address In Chatwoot: 1. Go to your inbox settings. 2. Select your email channel settings -> Configuration 3. Copy the provided **Chatwoot ingress email address**. This address is unique per inbox. ## Configuring Forwarding on Your Email Provider The setup varies slightly across providers, but the steps are generally: 1. Open your email provider's forwarding or routing settings. 2. Add the Chatwoot ingress email as a forwarding destination. 3. Verify the address if the provider requires confirmation. 4. Set a rule to forward all incoming email (or only relevant messages) to the ingress address. 5. Save the configuration. ## Configuring Ingress Provider For Chatwoot installations, a dedicated ingress provider (Amazon SES, SendGrid, Mailgun, etc.) is required. The provider acts as the first receiver of your domain’s email and then forwards it to the Chatwoot ingress URL. See more details [here](./ingress-providers). ## Outbound Email Behavior Forwarding affects **only inbound** messages. Outbound messages will still be sent using: * The SMTP provider you configured for the inbox (recommended), or * The default SMTP provider configured in the Chatwoot installation. ## Troubleshooting Common issues: ### 1. Forwarding Not Enabled in Chatwoot If you see: *“Support for forwarding emails is not configured. Contact your administrator.”* Your Chatwoot installation must enable email ingress. MAILER\_INBOUND\_EMAIL\_DOMAIN configuration is missing. ### 2. Emails Not Appearing in the Inbox Check: * Forwarding rule is enabled and active. * Provider is not suppressing or classifying forwarded mail. * No DMARC quarantine/reject issues. * The ingress address is correct. ### 3. Threading Issues Chatwoot relies on message headers for threading. Ensure your provider forwards headers intact. # Google Workspace Source: https://developers.chatwoot.com/self-hosted/configuration/features/email-channel/google-workspace-setup Configure an OAuth app for Gmail At present, Gmail integration operates through [less-secure](https://support.google.com/accounts/answer/6010255?hl=en) apps. However, as of June 15, 2024, Google Workspace will [cease to support](https://workspaceupdates.googleblog.com/2023/09/winding-down-google-sync-and-less-secure-apps-support.html) these less-secure apps. This will affect the Gmail integration in Chatwoot. To ensure that your Gmail integration continues to work, you will need to set up an OAuth app in Google Workspace. Existing setups will continue to work until September 30, 2024. However, we recommend setting up an OAuth app as soon as possible to avoid any disruptions. This guide will walk you through the process of setting up an OAuth app in Google Workspace. ## Register the app To enable Google OAuth in Chatwoot, you need to provide the client ID, client secret, and callback URL. You can find the instructions to generate these details [here](https://support.google.com/cloud/answer/6158849). Once you have followed these steps, you will be able to get a Client ID and Secret. register-an-app Use the callback URL `https:///google/callback` when registering the app. This URL is used to redirect the user back to the Chatwoot instance after authentication. Set the `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` environment variables in your Chatwoot installation using the values you copied from the Google API Console. ```bash theme={null} GOOGLE_OAUTH_CLIENT_ID=369777777777-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com GOOGLE_OAUTH_CLIENT_SECRET=ABCDEF-GHijklmnoPqrstuvwX-yz1234567 ``` If you have already setup [Google OAuth login flow](https://www.chatwoot.com/self-hosted/configuration/environment-variables#google-oauth) You can use the same app, by simply adding the new callback URL. **Do not remove the previous callback URL.** After setting these environment variables, restart your Chatwoot server to apply the changes. Now, users will be able to sign in using their Google accounts. You will notice that the app you are using is in testing mode; we will cover that later in the guide. For now, you can ignore it. ## Configure the application To fetch the emails from the client inbox, you need to configure the correct scopes. The following scopes are required: * `https://mail.google.com/`: To read, send, delete, and manage your email. * `email`: To view the user's email address. * `profile`: To view the name and picture etc. You can configure the scopes in the Google API Console by following the steps below: 1. Go to the [Google API Console](https://console.developers.google.com/). 2. Select the project you created earlier. 3. Click on the "OAuth consent screen" tab and click on the "Edit App" button. 4. Add the required scopes in the "Scopes for Google APIs" section. 5. Click on the "Save" button. Here's a demo showing how to add the `https://mail.google.com/` scope: Demo add scope ## Publishing the app If you're using Chatwoot within an organization with fewer than 100 users, you can continue to use the app in testing mode. However, if you're using Chatwoot in an organization with more than 100 users or using the app to serve multiple clients, you will need to publish the app to make it available to all users. To publish the app, you need to go through the verification process since we use a restricted scope. You can find the instructions to verify the app [here](https://support.google.com/cloud/answer/9110914). It's important to note that the verification process can take a few days to complete. Once the app is verified, you can publish it and make it available to all users. # Configuring inbound mails in Chatwoot Source: https://developers.chatwoot.com/self-hosted/configuration/features/email-channel/ingress-providers Guide to set up inbound emails in Chatwoot Chatwoot uses [Rails Action Mailbox](https://edgeguides.rubyonrails.org/action_mailbox_basics.html) to receive inbound emails. Action Mailbox supports multiple "ingress" providers out of the box, and Chatwoot builds on top of that. This guide walks you through: * Choosing and configuring an inbound email (ingress) provider * Setting the required environment variables * Using Mailgun, SendGrid, Mandrill, and local relay servers (Exim, Postfix, Qmail, Postmark) Supported ingress providers today: * Amazon SES * SendGrid * Mandrill * Mailgun * Exim * Postfix * Qmail * Postmark ## 1. Configure the ingress service First, tell Chatwoot which inbound email service (ingress) you are using. This is done via the `RAILS_INBOUND_EMAIL_SERVICE` environment variable. ```bash theme={null} # Set this to the appropriate ingress service. Options: # "relay" for Exim, Postfix, Qmail, Postmark # "mailgun" for Mailgun # "mandrill" for Mandrill # "sendgrid" for SendGrid # "ses" for Amazon SES RAILS_INBOUND_EMAIL_SERVICE=relay ``` This value configures how Action Mailbox will authenticate and route inbound messages into Chatwoot. ### Using a local relay (Postfix / Exim / Qmail / Postmark) If you are using a local MTA (for example Postfix) for both inbound relaying and outbound email, and you **do not** want to use SMTP authentication (SASL) — which is common when the server only handles its own mail — you need to adjust your outbound SMTP configuration. By default, Action Mailer will try to use SMTP authentication if the following environment variables are present: * `SMTP_AUTHENTICATION` * `SMTP_USERNAME` * `SMTP_PASSWORD` If you are sending mail through a local relay that does not require authentication: 1. Remove or comment out these variables from your `.env` file. 2. Ensure that your local MTA is correctly configured to send outbound mail. > ⚠️ **Important:** Running your own mail server comes with deliverability and security responsibilities: > > * Many ISPs block or restrict email servers on their networks. > * Configure proper DNS records (SPF, DKIM, DMARC) so that your emails are accepted by recipients and do not land in spam. ## 2. Configure ingress authentication Next, set the corresponding credentials for the ingress provider you’re using. ```bash theme={null} # Use one of the following based on the email ingress service # For SendGrid, Exim, Postfix, Qmail, or Postmark RAILS_INBOUND_EMAIL_PASSWORD= # For Mailgun MAILGUN_INGRESS_SIGNING_KEY= # For Mandrill MANDRILL_INGRESS_API_KEY= ``` Only the relevant variable for your chosen provider needs to be configured. ## 3. Provider-specific configuration ### Amazon SES If you are using Amazon SES as your email provider, you have configure the ingress provider as `ses` and set the `ACTION_MAILBOX_SES_SNS_TOPIC` to the SNS topic ARN of your SES account. See more details [here](./amazon-ses-ingress). ### Mailgun If you are using Mailgun as your email provider: 1. In your DNS, configure the **MX records** for your domain to point to Mailgun. 2. In the Mailgun dashboard, configure routing so that inbound emails are forwarded to: ```text theme={null} https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime ``` Replace `example.com` with the domain where your Chatwoot installation is hosted. #### Getting the Mailgun ingress signing key You can find the signing key in your Mailgun dashboard and set it as `MAILGUN_INGRESS_SIGNING_KEY`. mailgun-ingress-key ### SendGrid If you are using SendGrid: 1. Configure **MX records** for your domain (`your-domain.com`) to point to SendGrid. 2. In the SendGrid dashboard, set up **Inbound Parse** to forward inbound emails to the Action Mailbox endpoint. Use the following pattern as the Inbound Parse URL: ```bash theme={null} https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails ``` * Replace `PASSWORD` with the value of `RAILS_INBOUND_EMAIL_PASSWORD`. * Replace `example.com` with your Chatwoot host. > ✅ **Required:** When configuring the SendGrid Inbound Parse webhook, **enable** the option: > > **"Post the raw, full MIME message"**. > > Action Mailbox must receive the raw MIME message to correctly parse and process the email. See a detailed guide on [how to configure SendGrid Inbound Parse](./conversation-continuity-using-sendgrid). ### Mandrill If you are using Mandrill as your email service: 1. Configure your domain’s MX records to point to Mandrill. 2. In the Mandrill dashboard, configure an inbound route that forwards emails to: ```text theme={null} https://example.com/rails/action_mailbox/mandrill/inbound_emails ``` Replace `example.com` with the domain where your Chatwoot installation is hosted. Set `MANDRILL_INGRESS_API_KEY` with the appropriate API key from Mandrill. ## 4. IMAP via getmail If you already have an IMAP mailbox (for example on your own mail server or with a provider that doesn’t directly support Action Mailbox), you can still feed emails into Chatwoot using [getmail6](https://github.com/getmail6/getmail6) and the Action Mailbox HTTP ingress. ### How Action Mailbox ingress works Action Mailbox exposes HTTP endpoints for each ingress type. They are defined in the Rails source and can also be used directly. Example using the Rails rake task: ```bash theme={null} cat my_incoming_message | ./bin/rails action_mailbox:ingress:postfix \ RAILS_ENV=production \ URL=http://localhost:3000/rails/action_mailbox/relay/inbound_emails \ INGRESS_PASSWORD=... ``` This imports the contents of `my_incoming_message` (an [RFC 822](https://datatracker.ietf.org/doc/html/rfc822) compliant message) into a Chatwoot instance running on `localhost`. ### Calling the HTTP endpoint directly Instead of using the Rake task, you can call the ingress HTTP endpoint directly via `curl`. ```bash theme={null} INGRESS_PASSWORD=... URL=http://localhost:3000/rails/action_mailbox/relay/inbound_emails curl -sS -u "actionmailbox:$INGRESS_PASSWORD" \ -A "Action Mailbox curl relayer" \ -H "Content-Type: message/rfc822" \ --data-binary @- \ $URL ``` This sends the raw message from stdin to the Action Mailbox relay endpoint. ### Using getmail6 with IMAP [getmail6](https://github.com/getmail6/getmail6) can retrieve emails from an IMAP mailbox and pipe them into the `curl` script above. If the script is stored at `/home/chatwoot/bin/import_mail_to_chatwoot`, a minimal `getmail` configuration might look like this: ```ini theme={null} [retriever] type = SimpleIMAPSSLRetriever server = ... username = ... password = ... [destination] type = MDA_external path = /home/chatwoot/bin/import_mail_to_chatwoot [options] verbose = 0 read_all = false delete = false delivered_to = false received = false message_log = /home/chatwoot/logs/import_imap.log message_log_syslog = false message_log_verbose = true ``` ### Scheduling mail retrieval To continuously import mail into Chatwoot, you need to run `getmail` regularly. Common options: * Use `cron` to run `getmail` at a fixed interval (for example every minute). * For IMAP, you can use: ```bash theme={null} getmail --idle INBOX ``` This keeps a long-lived connection open and reacts to new mail immediately. You’ll need some supervision (systemd, runit, etc.) to handle restarts if the connection is interrupted. ## 5. Further reading For more details on configuring and customizing ingresses, refer to the official Rails documentation: * [Action Mailbox Basics – Configuration](https://edgeguides.rubyonrails.org/action_mailbox_basics.html#configuration) # Introduction to Email Channel Configuration Source: https://developers.chatwoot.com/self-hosted/configuration/features/email-channel/introduction Overview of email channel configuration for self-hosted Chatwoot Email is one of the core channels in Chatwoot, and for self-hosted installations the configuration depends entirely on how your mail infrastructure is set up. Different teams use different providers—Google Workspace, Microsoft 365, custom SMTP/IMAP servers, or even forwarding-based workflows. Because of this, Chatwoot provides multiple ways to connect a mailbox, each with slightly different requirements, security properties, and operational trade-offs. This guide introduces the five supported configurations available in Chatwoot for setting up email channels in a self-hosted environment. All of these methods allow Chatwoot to send and receive email, but the authentication flow, inbound routing, and outbound delivery differ based on your setup. ### Google (OAuth based) If you are using Gmail or Google Workspace, you can connect your mailbox using Google OAuth. This provides a secure, standards-based authentication flow without managing app passwords. Chatwoot will use Google's SMTP and IMAP servers for sending and receiving. Click here to learn more about [Google Workspace Setup](./google-workspace-setup). ### Microsoft (OAuth based) For organizations using Microsoft 365 or Outlook, you can connect your mailbox using Microsoft OAuth. Chatwoot integrates with Microsoft’s SMTP and IMAP endpoints for full send/receive capability. Click here to learn more about [Microsoft Setup](./azure-app-setup). ### Standard SMTP + IMAP This configuration supports any custom mail provider by allowing you to set standard SMTP credentials for outbound mail and IMAP credentials for inbound. This works with on‑prem servers, commercial providers, or any setup that supports username/password authentication. ### Forwarding Rule (Email → Chatwoot Ingress) Instead of configuring IMAP, some teams prefer to forward incoming emails directly to Chatwoot. If your mail provider supports forwarding rules, you can send inbound email to Chatwoot’s ingress address, which Chatwoot will process as incoming messages. Outbound email will use your configured SMTP provider. ### IMAP (Inbound Only) + Chatwoot Mailer (Outbound) In this mode, Chatwoot pulls inbound email through IMAP but sends outbound messages using Chatwoot’s mailer configuration. This is useful when your mail provider imposes SMTP restrictions or when you want a consistent outbound delivery method across channels. You just need to configure IMAP settings here. # Setting Up Facebook Source: https://developers.chatwoot.com/self-hosted/configuration/features/integrations/facebook-channel-setup Configure Facebook Messenger integration for Chatwoot To use Facebook Channel, you have to create a Facebook app in the developer portal. You can find more details about creating Facebook apps [here](https://developers.facebook.com/docs/apps/#register). ## Prerequisites 1. A valid facebook account. 2. A valid facebook page. ## Register A Facebook App 1. Go to [Facebook developer portal](https://developers.facebook.com/apps/) and click on the "Create App" button facebook_create_app 2. Select the option "Other". facebook_other_app 3. For the app type, choose "Business". facebook_business 3. Enter basic details like the app name and email. facebook_business_details Once you register your Facebook App, you will have to obtain the `App Id` and `App Secret`. These values will be available in the app settings and will be required while setting up Chatwoot environment variables. facebook_app_id ## Configuring the Environment Variables in Chatwoot Configure the following Chatwoot environment variables with the values you obtained during the Facebook app setup. The `FB_VERIFY_TOKEN` should be a unique and secure string that you provide when configuring the Facebook app. Generate a random string and set it as the `FB_VERIFY_TOKEN`. Facebook will include this string in all verification requests. Restart the Chatwoot server after updating the environment variables ```bash theme={null} FB_VERIFY_TOKEN= FB_APP_SECRET= FB_APP_ID= ``` ## Configure Facebook Login 1. Add the Facebook Login product via the Facebook app dashboard. facebook_app_login 2. Enable `Web OAuth Login`, `Login with Javascript SDK` and add your self-hosted domain to the `Allowed Domains for the JavaScript SDK` input. facebook_sdk_login ## Configure the Facebook App 1. In the app settings, add your `Chatwoot installation domain` as your app domain. facebook_app_domain 2. In the products section in your app settings page, Add "Messenger" facebook_messenger_product 3. Go to the Messenger settings and configure the call back URL Alt text 4. Provide the Callback URL as `{your_chatwoot_installation_url}/bot` and the Verify token as `FB_VERIFY_TOKEN` from your environment variable. facebook_callback_url 5. Head over to Chatwoot and create a Messenger inbox. Choose a page for which your Facebook developer account has admin access to. Please refer to this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677778588-how-to-setup-a-facebook-channel) for more details on creating a Messenger inbox in Chatwoot. ## Testing the Facebook channel Until the application is approved for production, Facebook wouldn't send the new messages on your page to Chatwoot. To test the changes until the app is approved for production. Follow the steps 1. Head over to the messenger section in your app settings page, in Facebook developers. facebook_messenger_settings 2. Click `Add or remove pages` and connect the page which you choose while creating the Chatwoot Messenger inbox. facebook_callback_pages 3. After connecting the pages, Click on `Add subscriptions` from the connected page. facebook_page_config 4. Subscribe to the following fields and save the subscription. ``` messages messaging_postbacks message_deliveries message_reads message_echoes ``` facebook_page_subscription 4. Send a message to the connected page from your Facebook account and it should appear in Chatwoot now. ## Going into production. Before you can start using your Facebook app in production, you will have to get it verified by Facebook. Refer to the [docs](https://developers.facebook.com/docs/apps/review/) on getting your app verified. Obtain advanced access to the required permissions mentioned below for your Facebook app ``` pages_messaging (To message on behalf of the page) pages_show_list (To list the pages to be connected in chatwoot) pages_manage_metadata (Subscribe webhooks on behalf of the page) business_management pages_read_engagement (Read followers data (including name, PSID), and profile ) Business Asset User Profile Access (For accessing user profile picture and name of people who contacts the page) ``` Make sure your facebook app subscription version is 17.0, we have updated the FB subscription with the latest version, so change the permission subscription version under the facebook app webhooks option. ## Developing or Testing Facebook Integration in your machine Install [ngrok](https://ngrok.com/docs) on your machine. This will be required since Facebook Messenger API's will only communicate via https. ```bash theme={null} brew cask install ngrok ``` Configure ngrok to route to your Rails server port. ```bash theme={null} ngrok http 3000 ``` Go to the Facebook developers page and navigate into your app settings. In the app settings, add `localhost` as your app domain. In the Messenger settings page, configure the callback url with the following value. ```bash theme={null} {your_ngrok_url}/bot ``` Update verify token in your Chatwoot environment variables. You will also have to add a Facebook page to your `Access Tokens` section in your Messenger settings page. Restart the Chatwoot local server. Your Chatwoot setup will be ready to receive Facebook messages. ## Facebook API version We support facebook API version v13.0 going forward, which you can update in the facebook app advanced settings. fb_api_version ## Test your local Setup 1. After finishing the set-up above, [create a Facebook inbox](https://www.chatwoot.com/hc/user-guide/articles/1677778588-how-to-setup-a-facebook-channel) after logging in to your Chatwoot Installation. 2. Send a message to your page from Facebook. 3. Wait and confirm incoming requests to `/bot` endpoint in your ngrok screen. # Instagram via Facebook Login Source: https://developers.chatwoot.com/self-hosted/configuration/features/integrations/instagram-channel-setup Set up Instagram integration using Facebook Login authentication We recommend Instagram Business Login as the preferred authentication method, as it provides simpler configuration and a better developer experience. Please refer to this [guide](./instagram-via-instagram-business-login) for more details. We will be stopping the support for Instagram via Facebook Login in the future from v4.1 onwards. ## Prerequisites 1. A valid facebook account. 2. A valid facebook page. 3. A valid instagram professional account. ## Register A Facebook App To use Instagram Channel, you have to create a Facebook app in the developer portal. You can find more details about creating Facebook developer app [here](./facebook-channel-setup). 1. Click on the "Create App" button facebook_create_app 2. Select the option "Other". facebook_other_app 3. For the app type, choose "Business" facebook_business 3. Enter basic details like the app name and email. facebook_business_details Once you register your Facebook App, you will have to obtain the `App Id` and `App Secret`. These values will be available in the app settings and will be required while setting up Chatwoot environment variables. facebook_app_id ## Configuring the Environment Variables in Chatwoot Configure the following Chatwoot environment variables with the values you obtained during the Facebook app setup. The `IG_VERIFY_TOKEN` should be a unique and secure string that you provide when configuring the Instagram app. Restart the Chatwoot server after updating the environment variables ```bash theme={null} IG_VERIFY_TOKEN= FB_APP_SECRET= FB_APP_ID= ``` ## Configure the Facebook App 1. In the app settings, add your "Chatwoot installation domain" as your app domain. facebook_app_domain 2. Add the "Instagram Graph API" product via the Facebook app dashboard. instagram_product 3. Go to the app settings and select "Webhooks". From there, choose Instagram and click on the "Subscribe to this object" button. instagram_webhooks 4. Provide the Callback URL as `{your_Chatwoot_installation_url}/webhooks/instagram` and the Verify token as `IG_VERIFY_TOKEN` from your environment variable. instagram_webhook_url ## Connect the facebook page with instagram account 1. Go to [Facebook pages](https://www.facebook.com/pages/?category=your_pages) and select your page and open the settings facebook_page_settings 2. Go to "Linked accounts" and connect your instagram professional account. facebook_connect_instagram 3. Select the option "Business" instagram_connect_facebook 4. Select the instgram account category select_category_instagram 5. If everything is okay, you will see the message "Instagram connected." instagram_connect_success ## Create Instagram Inbox in Chatwoot 1. Head over to Chatwoot and create a Messenger inbox. Please refer to this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677829420-how-to-setup-an-instagram-channel) for more details on creating a Messenger inbox in Chatwoot. So whenever you receive any message on Instagram, it will redirect to your Facebook page. ## Testing the Instagram channel Until the application is approved for production, Facebook wouldn't send the new messages on your instagram to Chatwoot. To test the changes until the app is approved for production. Follow the steps 1. Create a Test app for your app. facebook_instagram_test 2. Add the `Instagram Graph API` product via the Facebook app dashboard. instagram_product 3. Go to the app settings and select "Webhooks". From there, choose Instagram and click on the "Subscribe to this object" button. instagram_webhooks 4. Provide the Callback URL as `{your_chatwoot_installation_url}/webhooks/instagram` and the Verify token as `IG_VERIFY_TOKEN` from your environment variable. instagram_webhook_url 5. Open the test app and add extra product for the test app: Instagram Basic Display instagram_basic_display 6. In the app settings, add the platform "Website" and give `Site URL` as your installation URL. instagram_app_platform 7. Head over to the Instagram Basic Display section and create a new app. instagram_basic_display_settings 8. Add Instagram Testers by clicking "Add or Remove Instagram Testers" button. instagram_testers 9. Make sure that you have selected the role `Instagram Tester` while creating a new tester. instagram_tester_list 10. Click on Edit subscriptions under Webhook > Instagram and subscribe to the following, ``` message_reactions messages messaging_seen ``` instagram_subscription You should do this step for both normal and test apps. 1. Head over to Chatwoot and create a Messenger inbox. Please refer to this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677829420-how-to-setup-an-instagram-channel) for more details on creating a Messenger inbox in Chatwoot. 2. Send a message to the connected Instagram account from Instagram Testers, and it should appear in Chatwoot now ## Going into production. Before you can start using your Facebook app in production, you will have to get it verified by Facebook. Refer to the [docs](https://developers.facebook.com/docs/messenger-platform/instagram/app-review) on getting your app verified. Obtain advanced access to the required permissions mentioned below for your Facebook app ``` instagram_manage_messages instagram_basic pages_show_list (To list the pages to be connected in chatwoot) pages_manage_metadata (Subscribe webhooks on behalf of the page) pages_messaging (To message on behalf of the page) business_management (For accessing user profile picture and name of people who contacts the page) ``` If your facebook app's version is more than 7.0 then you will need extra permission according to facebook's updated policy. Make sure you get permission for. ``` pages_read_engagement ``` ## Developing or Testing Facebook Integration in your machine Install [ngrok](https://ngrok.com/docs) on your machine. This will be required since Facebook Messenger APIs will only communicate via https. ```bash theme={null} brew cask install ngrok ``` Configure ngrok to route to your Rails server port. ```bash theme={null} ngrok http 3000 ``` Go to the Facebook developers page and navigate into your app settings. Add `localhost` as your app domain and add a privacy policy URL in the app settings. In the Webhook > Instagram settings shown in the above image, configure the callback url with the following value. ```bash theme={null} {your_ngrok_url}/webhooks/instagram ``` Update verify token in your Chatwoot environment variables. You will also have to add a Facebook page to your `Access Tokens` section in your Messenger settings page. Restart the Chatwoot local server. Then, your Chatwoot setup will be ready to receive Facebook messages. ## Test your local Setup 1. After finishing the setup above, [create a Messenger inbox](https://www.chatwoot.com/hc/user-guide/articles/1677778588-how-to-setup-a-facebook-channel) after logging in to your Chatwoot Installation. 2. Send a message to your Facebook Page from your Instagram account. 3. Wait and confirm incoming requests to `/webhooks/instagram` endpoint in your ngrok screen. 4. You can also verify your callback URL by clicking on Test for the subscribed Instagram fields. Go to webhook Instagram and click on Test with `v11.0` subscribe You can have only one app connected to the Chatwoot for Instagram and Facebook combined as the Messenger platform is common. But suppose you want to have separate channels for Instagram and Facebook. In that case, you can have multiple Facebook pages inside your app that would be connected to Facebook users and Instagram users separately and then connected to the different inbox in the Chatwoot page. ## Checklist 1. Integrate the Facebook test app and Send a message from the Instagram tester to the connected account. 2. Make sure your Instagram account is a business account. 3. If the Instagram test account can receive the message and forward it to the webhook URL, then submit it for review. 4. If the Instagram test account is not able to receive the message and forward it to the webhook URL * Check the logs if you are receiving the message to `{your-app-url}/webhooks/Instagram` * If the logs are present for the above endpoint, if there are any errors, then reach out to us. We will help you out. * If the logs aren't present for the above endpoint, then raise a bug for the Facebook team or follow this bug [https://developers.facebook.com/support/bugs/468852858104743/](https://developers.facebook.com/support/bugs/468852858104743/) 5. If you are not facing the above issue and can get the message, but the review isn't passing, then reach out to the reviewer. * When your app gets rejected, open the rejected submission. You can see the messenger icon in the bottom right corner to support you with your rejected review. * You can talk to the support team and ask your questions about the submission and the reason for the rejection. 6. If your test app passed the review, it's good to go into production. 7. If you face an issue on production that you cannot receive the messages, then reach out to us with the error logs. # Set up Instagram Business Login for Chatwoot Source: https://developers.chatwoot.com/self-hosted/configuration/features/integrations/instagram-via-instagram-business-login Configure the Chatwoot Instagram integration for a self-hosted installation using Meta's recommended Instagram Business Login flow. Please ensure you have installed version v4.1 or above. If not, please refer to this [guide](./instagram-channel-setup) for the Facebook Login method. Use this guide to connect Instagram professional accounts to a self-hosted Chatwoot installation using Instagram Business Login. This is the recommended authentication method for Chatwoot Instagram inboxes from v4.1 onwards. ## Prerequisites 1. A valid Facebook account. 2. A valid Instagram professional account. ## Register a Facebook app To use the Chatwoot Instagram channel, create a Facebook app in the developer portal. You can find more details about creating Facebook apps [here](./facebook-channel-setup). 1. Click on the "Create App" button facebook_create_app 2. Select the option "Other". facebook_other_app 3. For the app type, choose "Business" facebook_business 4. Add app name and connect business account facebook_business_details 5. Add Instagram product from the Home page. instagram_product ## Configure Instagram settings for Chatwoot 1. Copy Instagram app ID and Instagram app secret instagram_app_id 2. Add the Instagram app ID and Instagram app secret to your app config via `{Chatwoot installation url}/super_admin/app_config?config=instagram` instagram_app_config 3. Configure Webhooks Set the callback URL to `{your_chatwoot_url}/webhooks/instagram`. The verify token should match your `INSTAGRAM_VERIFY_TOKEN`, which can be configured through `app_config` instagram_webhooks Subscribe to `messages`, `messaging_seen`, and `message_reactions` events. instagram_webhooks_subscribe To receive web hooks, app mode should be set to "Live". 4. Set up Instagram business login Set Redirect URL as `{your_chatwoot_url}/instagram/callback` instagram_business_login 5. Create a new Instagram tester account ## Create an Instagram inbox in Chatwoot Head over to Chatwoot and create an Instagram inbox. Please refer to this [guide](https://chatwoot.help/hc/user-guide/articles/1744361165-how-to-setup-an-instagram-channel-via-instagram-login) for more details on creating an Instagram inbox in Chatwoot. ## Test the Instagram integration before going live 1. Add Instagram Testers by clicking "Add People" button. facebook_instagram_test 2. Make sure that you have selected the role Instagram Tester while creating a new tester. instagram_tester_list ## Going into production. Before you can start using your Facebook app in production, you will have to get it verified by Facebook. Refer to the [docs](https://developers.facebook.com/docs/messenger-platform/instagram/app-review) on getting your app verified. ## Troubleshooting & Common Errors ### Insufficient Developer Role Error Ensure the Instagram user is added as a developer: `Meta Dashboard → App Roles → Roles → Add People → Enter Instagram ID` ### API Access Deactivated Ensure the **Privacy Policy URL** is valid and correctly set. ### Invalid request: Request parameters are invalid: Invalid redirect\_uri Please configure the Frontend URL. The Frontend URL does not match the authorization URL. ### Instagram Channel creation Error: Failed to exchange token Please make sure that the tester account has been added to the Facebook app settings. ### 400: Session Invalid when connecting the Instagram channel This might be an issue from Facebook's side. Please try again after some time. # Setting Up Linear Integration Source: https://developers.chatwoot.com/self-hosted/configuration/features/integrations/linear-integration-setup Configure Linear integration to track issues and features from Chatwoot Setting up Chatwoot Linear integration involves 5 steps. 1. Create a Linear app in the [developer portal](https://linear.app/settings/api/applications/new). 2. Add necessary details and save the app. 3. Configure Chatwoot with the `Client ID` and `Signing Secret` obtained from the Linear app. 4. Open Chatwoot UI, navigate to integrations, select Linear, and click connect. 5. Voila! You should now be able to use Linear in your Chatwoot account. ## Register and configure the Linear app To use Linear Integration, you need to create a Linear app in the developer portal. You can find more details about creating Linear apps at the [Linear developer portal](https://developers.linear.app/docs/oauth/authentication). 1. Create a Linear app. 2. Obtain the `Client ID` and `Client Secret` for the app and configure it in your app config via `{Chatwoot installation url}/super_admin/app_config?config=linear` 3. The callback URL should be `{Chatwoot installation url}/linear/callback`. 4. Toggle the `Public` switch to make the app public. linear_app_domain ## Configure Linear app config Obtain the `Client ID` and `Client Secret` for the app and configure it in your app config via `{Chatwoot installation url}/super_admin/app_config?config=linear`. These values will be available when you create the app in the developer portal. ```bash theme={null} LINEAR_CLIENT_ID= LINEAR_SIGNING_SECRET= ``` Restart the Chatwoot server. Linear will only show up in the integrations section once you have configured these values and restarted the server. ## Connect Chatwoot with your Linear account Follow this [guide](https://chatwoot.help/hc/user-guide/articles/1739949089-how-to-track-issues-and-features-with-linear-integration) to complete the Linear integration. # Setting Up Shopify Integration Source: https://developers.chatwoot.com/self-hosted/configuration/features/integrations/shopify-integration-setup Configure Shopify integration to track orders and customer information from Chatwoot Setting up Chatwoot Shopify integration involves 5 steps. 1. Create a Shopify app in the [shopify partner dashboard](https://partners.shopify.com/). 2. Add necessary details and save the app. 3. Configure Chatwoot with the `Client ID` and `Client secret` obtained from the Shopify app. 4. Open Chatwoot UI, navigate to integrations, select Shopify, and click connect. 5. Voila! You should now be able to use Shopify in your Chatwoot account. ## Register and configure the Shopify app To use Shopify Integration, you need to create a Shopify app in the [shopify partner dashboard](https://partners.shopify.com/). You can find more details about creating Shopify apps at the [Shopify developer portal](https://shopify.dev/docs/apps/build). 1. Create a Shopify app. shopify_app_create 2. Obtain the `Client ID` and `Client Secret` for the app and configure it in your app config via `{Chatwoot installation url}/super_admin/app_config?config=shopify` shopify_app_domain 3. Configure the redirect URL as `{Chatwoot installation url}/shopify/callback` in app configuration. shopify_app_redirect Shopify will only show up in the integrations section once you have configured these values. ## Connect Chatwoot with your Shopify account Follow this [guide](https://chatwoot.help/hc/user-guide/articles/1742395545-how-to-track-orders-with-shopify-integration) to complete the Shopify integration. # Setting Up Slack Integration Source: https://developers.chatwoot.com/self-hosted/configuration/features/integrations/slack-integration-setup Configure Slack integration to receive Chatwoot conversations in Slack channels Setting up Chatwoot Slack integration involves 5 steps. 1. Create a slack app in the developer portal. 2. Add necessary permissions for the slack app. 3. Configure Chatwoot with the `client ID` and `client Secret` obtained from the slack app. 4. Open Chatwoot UI, navigate to integrations, Slack and click connect. 5. Voila! You should be receiving new conversations in the #customer-conversations channel in Slack. ## Register a Slack app To use Slack Integration, you have to create a Slack app in the developer portal. You can find more details about creating Slack apps at the [Slack developer portal](https://api.slack.com/). Once you register your Slack App, you will have to obtain the `Client Id` and `Client Secret`. These values will be available in the app settings and will be required while setting up Chatwoot environment variables. ## Configure the Slack app 1. Create a Slack app and add it to your development workspace. 2. Obtain the `Client Id` and `Client Secret` for the app and configure it in your Chatwoot [environment variables](/self-hosted/configuration/environment-variables). 3. Head over to the `OAuth & permissions` section under `features` tab. 4. In the redirect URLs, Add your Chatwoot installation base URL. 5. In the scopes section configure the given scopes for bot token scopes: * `channels:history` * `channels:join` * `channels:manage` * `channels:read` * `chat:write` * `chat:write.customize` * `commands` * `files:read` * `files:write` * `groups:history` * `groups:write` * `im:history` * `im:write` * `links:read` * `links:write` * `mpim:history` * `mpim:write` * `users:read` * `users:read.email` 7. In the user access token section subscribe to: `files:read`, `files:write`, `remote_files:share` 8. Head over to the `Events Subscriptions` section in the `Features` tab. 9. Enable events and configure the given request url `{Chatwoot installation url}/api/v1/integrations/webhooks` 10. Subscribe to the following bot events: `link_shared`, `message.channels`, `message.groups`, `message.im`, `message.mpim`. 11. Add the installation URL as `domain` under the `App unfurl domains section` to display meta information about the conversation when the conversation URL is shared. 12. Connect Slack integration on Chatwoot app and get productive. ## Configure the environment variables in Chatwoot Obtain the `Client ID` and `Client Secret` for the app and configure it in your Chatwoot [environment variables](/self-hosted/configuration/environment-variables).These values will be available under `Settings` > `Basic Information`. ```bash theme={null} SLACK_CLIENT_ID= SLACK_CLIENT_SECRET= ``` Restart the Chatwoot server. Slack will only show up in the integrations section once you have configured these values and restarted the server. ## Connect Chatwoot with your Slack workspace Follow this [guide](https://www.chatwoot.com/hc/user-guide/articles/1677774874-how-to-answer-conversations-from-slack) to complete the Slack integration. ## Testing your setup 1. Create a new conversation. 2. Ensure that you are receiving the Chatwoot messages in the connected slack channel. 3. Add a message to that thread and ensure that it is coming back on to Chatwoot. 4. Add `note:` or `private:` in front of the Slack message to see if it is coming out as private notes. 5. If your Slack member's email matches their email on Chatwoot, the messages will be associated with their Chatwoot user account. # Setting Up TikTok Channel Source: https://developers.chatwoot.com/self-hosted/configuration/features/integrations/tiktok Configure TikTok Business Messaging integration to manage TikTok conversations from Chatwoot The TikTok channel integration enables you to manage TikTok Business Messaging conversations directly from Chatwoot. Agents can receive and reply to messages from TikTok users, view shared posts, and handle image attachments -all within the Chatwoot dashboard. Setting up the TikTok channel involves 7 steps. 1. Create a TikTok Developer Account. 2. Register an app in the TikTok Developer Portal. 3. Apply for Business Messaging API access. 4. Configure app permissions and redirect URLs. 5. Configure Chatwoot with the `App ID` and `App Secret` obtained from TikTok. 6. Set up the webhook for incoming messages. 7. Connect a TikTok Business Account from the Chatwoot dashboard. ## Prerequisites 1. A self-hosted Chatwoot instance accessible via a public HTTPS URL 2. A **TikTok Business Account** registered in an eligible region 3. Your TikTok Business Account must be set to **accept direct messages from everyone**. Otherwise, you will need to manually accept messages in the TikTok app. [Learn how to update your message settings](https://ads.tiktok.com/help/article/how-to-update-your-tiktok-direct-message-permission-for-tiktok-messaging-ads?lang=en). 4. A **TikTok Developer Account** at [developers.tiktok.com](https://developers.tiktok.com) 5. Access to the [TikTok Business Messaging API](https://business-api.tiktok.com/portal/docs?id=1832183871604753) (requires special permissions and approval) 6. Super Admin access to your Chatwoot instance The TikTok Business Messaging API is **region-restricted**. It is currently unavailable for accounts registered in the **European Economic Area (EEA), Switzerland, or the United Kingdom**. Personal TikTok accounts are not supported -only TikTok Business Accounts can use this integration. ## Step 1: Create a TikTok Developer Account 1. Go to [developers.tiktok.com](https://developers.tiktok.com) and sign up 2. Verify your email address 3. Accept the Terms of Service ## Step 2: Register Your App create_tiktok 1. Go to [business-api.tiktok.com/portal/apps](https://business-api.tiktok.com/portal/apps) and create a new app 2. Fill in the required fields: * **App Name**: e.g., "Your Company - Chatwoot" * **App Description**: Brief description of your messaging use case * **App Icon**: Upload your company logo * **Terms of Service URL**: Your company's ToS URL * **Privacy Policy URL**: Your company's privacy policy URL 3. Once created, note down your `App ID` (client key) and `App Secret` (client secret) ## Step 3: Apply for Business Messaging API Access You need to grant your app access to the Business Messaging API. For detailed instructions, refer to the [TikTok Business Messaging API access guide](https://business-api.tiktok.com/portal/docs?id=1832184145137922). 1. Open your app in the TikTok Developer Portal 2. Navigate to the **Business Messaging API** product 3. Submit an application with: * Your use case (e.g., customer support via Chatwoot) * How you will handle user data * Your organization details 4. Wait for TikTok's review and approval Approval typically takes a few days but can take longer for specialized access. You cannot proceed with the integration until your application is approved. ## Step 4: Configure App Permissions and URLs Once approved, configure the following in the TikTok Developer Portal. ### Required Permissions After your app is approved, ensure the **TikTok Accounts** permission is enabled under **Scope of permission** in your app settings. tiktok-accounts-permission ### Authorization Redirect URL Set the authorization redirect URL to: `{Chatwoot installation url}/tiktok/callback` ## Step 5: Configure Chatwoot ### Super Admin Configuration 1. Log in to your Chatwoot instance as a Super Admin 2. Navigate to `{Chatwoot installation url}/super_admin/app_config?config=tiktok` 3. Enter your `TikTok App ID` and `TikTok App Secret` 4. Click **Submit** Alternatively, you can set these as environment variables: ```bash theme={null} TIKTOK_APP_ID=your_tiktok_app_id TIKTOK_APP_SECRET=your_tiktok_app_secret ``` Restart the Chatwoot server after making changes. ### Enable TikTok Feature 1. In Super Admin, navigate to **Accounts** 2. Select the account where you want to enable TikTok 3. Under **Features**, enable the **TikTok** channel 4. Save the changes TikTok will only show up in the inbox channel options once you have configured the App ID and App Secret and enabled the feature for the account. ## Step 6: Configure Webhook Set up the TikTok webhook to receive incoming messages. Open a Rails console on your Chatwoot server: ```bash theme={null} bundle exec rails console ``` Run the following command to register the webhook callback URL: ```ruby theme={null} Tiktok::AuthClient.update_webhook_callback ``` This sets the webhook URL to `{Chatwoot installation url}/webhooks/tiktok`. You can verify the webhook configuration by running: ```ruby theme={null} Tiktok::AuthClient.webhook_callback ``` The webhook must be configured **after** setting the TikTok App ID and App Secret in Super Admin. If you change your Chatwoot domain, you will need to run this command again. ## Step 7: Connect Chatwoot with Your TikTok Account Follow the [TikTok channel user guide](https://www.chatwoot.com/hc/user-guide/articles/1769595702-how-to-setup-a-tik_tok-channel) to complete the TikTok integration. ## Troubleshooting ### TikTok channel not appearing in inbox options * Verify the TikTok feature is enabled for the account in Super Admin * Confirm `TIKTOK_APP_ID` and `TIKTOK_APP_SECRET` are set correctly * Restart the Chatwoot server after configuration changes ### OAuth authorization fails * Ensure the redirect URL in the TikTok Developer Portal exactly matches `{Chatwoot installation url}/tiktok/callback` * Verify your TikTok app has all required scopes enabled * Check that your TikTok app is approved for the Business Messaging API ### Not receiving incoming messages * Verify the webhook is configured by running `Tiktok::AuthClient.webhook_callback` in Rails console * Ensure the webhook URL is publicly accessible over HTTPS * Check that your TikTok Business Account is in an eligible region * Review Sidekiq logs for `Webhooks::TiktokEventsJob` errors ### Messages failing to send * Check if the 48-hour reply window has expired * Verify the access token is valid -Chatwoot automatically refreshes tokens, but if the refresh token expires (30 days), the channel will need reauthorization * Ensure you are sending a supported message type (text only, or a single image) * Check Sidekiq logs for `SendReplyJob` errors ### Channel shows "Reauthorization Required" This happens when both the access token (around 24 hours) and refresh token (around 30 days) have expired, typically due to inactivity. 1. Go to **Settings** → **Inboxes** → select the TikTok inbox 2. Click **Reauthorize** 3. Complete the TikTok OAuth flow again ### Webhook signature verification fails * Ensure `TIKTOK_APP_SECRET` matches the secret in your TikTok Developer Portal * Check server clock synchronization -TikTok's signature verification requires timestamps within 5 seconds # WhatsApp Embedded Signup Source: https://developers.chatwoot.com/self-hosted/configuration/features/integrations/whatsapp-embedded-signup Set up WhatsApp integration using Meta's streamlined embedded signup flow WhatsApp Embedded Signup enables users to connect their WhatsApp Business accounts through Meta's streamlined OAuth flow without manual webhook configuration. This significantly improves the user experience by automating the entire setup process. ## Prerequisites 1. A valid Facebook account 2. A WhatsApp Business account (or ability to create one) 3. Admin access to your Chatwoot installation ## Super Admin Configuration Before users can use WhatsApp Embedded Signup, administrators must configure the following environment variables via the Super Admin panel at `/super_admin/app_config?config=whatsapp_embedded`: * **WHATSAPP\_APP\_ID**: The Facebook App ID for WhatsApp Business API integration * **WHATSAPP\_CONFIGURATION\_ID**: The Configuration ID for WhatsApp Embedded Signup flow (obtained from Meta Developer Portal) * **WHATSAPP\_APP\_SECRET**: The App Secret for WhatsApp Embedded Signup flow (required for token exchange) These settings must be configured by a Super Admin before the WhatsApp Embedded Signup option becomes available to users. ### Retrieving Configuration Values from Meta Developer Portal To obtain the required configuration values: #### 1. Create or Access Your Facebook App 1. Go to [Meta for Developers](https://developers.facebook.com/) 2. Click on "My Apps" in the top navigation 3. Either select an existing app or click "Create App" 4. If creating a new app: * Choose "Business" as the app type * Select "Business" for "I want to connect my app to" * Provide app details (name, email, business portfolio) #### 2. Configure WhatsApp Product 1. In your app dashboard, click "Add Product" 2. Find "WhatsApp" and click "Set Up" 3. Accept the WhatsApp Business Terms #### 3. Retrieve App ID and App Secret * **App ID**: Found at the top of your app dashboard or in Settings → Basic * **App Secret**: Located in Settings → Basic (click "Show" and authenticate to reveal) #### 4. Obtain Configuration ID 1. Navigate to Facebook Login for Business → Configuration in the left sidebar 2. Click "Configurations" 3. Set up the configuration: * Select login variation to: WhatsApp Embedded Signup. * Select WhatsApp Account as an assets. (Give manage account permission) * Add required permissions. Mentioned below 4. Save the configuration 5. Copy the generated **Configuration ID** **Important:** Before overriding the current callback URI, your app must be subscribed to receive messages for the WhatsApp Business Account. This prevents error (#100) during webhook configuration. Ensure the messages webhook field is subscribed in your app's webhook settings. #### 5. Required Permissions Ensure your app has the following permissions enabled: * `whatsapp_business_management` - Manage WhatsApp business assets * `whatsapp_business_messaging` - Send and receive WhatsApp messages * `business_management` - Manage business assets For production use, your app may need to go through App Review to get advanced access to certain features. The embedded signup flow works with Standard Access for most use cases. ## Creating a WhatsApp Channel ### Step 1: Navigate to Channel Selection 1. Go to Settings → Inboxes in your Chatwoot dashboard 2. Click on "Add Inbox" 3. Select WhatsApp from the channel options whatsapp_channel_selection ### Step 2: Choose WhatsApp Cloud Select "WhatsApp Cloud" for the quick setup through Meta (embedded signup). whatsapp_provider_selection ### Step 3: Start Embedded Signup Click on "Connect with WhatsApp Business" to begin the embedded signup flow. whatsapp_embedded_signup_start ### Step 4: Facebook Authentication You'll be redirected to Facebook to authenticate. You need to log in with an existing Facebook account. whatsapp_facebook_authentication ### Step 5: Fill Business Information Select an existing business portfolio or create a new one to add your phone number. Fill in the required business information: * Business portfolio * Business name * Business website or profile page * Country * Address (optional) whatsapp_business_information ### Step 6: Select WhatsApp Business Account Choose an existing WhatsApp Business account or create a new one. You can also select or create a WhatsApp Business Profile. whatsapp_account_selection ### Step 7: Complete Setup Once you've completed all steps, you'll see the success screen. Your WhatsApp Business account is now connected and ready to receive messages. whatsapp_setup_complete whatsapp_app_config ## Key Features * **No manual configuration required**: The entire webhook and phone number setup is automated * **Secure OAuth based authentication**: Uses Meta's official OAuth 2.0 flow * **Automatic webhook and phone number configuration**: Webhooks are registered automatically * **Real-time progress tracking**: Visual feedback during the signup process * **Comprehensive error handling**: Clear error messages and guidance ## Commerce Policy Compliance Meta will review your business to ensure it complies with WhatsApp's Commerce Policy and will reach out within 24 hours if there's an issue. ## Reference Documentation For more technical details about WhatsApp Embedded Signup, refer to the official Meta documentation: * [WhatsApp Embedded Signup - Meta for Developers](https://developers.facebook.com/docs/whatsapp/embedded-signup/) ## Troubleshooting ### Common Issues 1. **"WhatsApp Embedded Signup not available"** * Ensure your Super Admin has configured the required environment variables * Check that all three values (App ID, Configuration ID, and App Secret) are properly set 2. **Authentication Errors** * Make sure you're using an existing Facebook account * Verify you have the necessary permissions for the business 3. **Business Verification Issues** * Ensure your business information is accurate and complete * Check that your business complies with WhatsApp's Commerce Policy ### Getting Help If you encounter issues during setup: 1. Check the Chatwoot logs for any error messages 2. Verify all environment variables are correctly configured 3. Ensure your Facebook/WhatsApp accounts meet the prerequisites 4. Contact Chatwoot support with specific error messages if the issue persists # Help Center Source: https://developers.chatwoot.com/self-hosted/configuration/help-center Set up a public-facing help center portal with custom domain and SSL certificate Help center allows you to create a portal and add articles from the chatwoot app dashboard. You can point to these help center portal articles from your main site and display them as your public-facing help center. ## How to get SSL certificate for your custom domain ### Create a Portal in Chatwoot's dashboard Follow these step to create your Portal. Refer to [this guide.](https://www.chatwoot.com/hc/user-guide/articles/1677861202-how-to-setup-a-help-center) ### Point your custom domain to your Chatwoot domain 1. Go to your DNS provider and add a new CNAME record. * For the above example, add docs as a CNAME record and point it to the your selfhosted chatwoot domain(FRONTEND\_URL). 2. This will ensure that your CNAME record points to the selfhosted Chatwoot installation. For your custom domain, we have your portal information. In this case, `docs.example.com` ### Setting up SSL 1. Use certbot to generate SSL certificates for your custom domain. ```bash theme={null} certbot certonly --agree-tos --nginx -d "docs.example.com" ``` 2. Create a new nginx config to route requests to this domain to Chatwoot. Make a copy of `/etc/nginx/sites-available/nginx_chatwoot.conf` and make necessary changes for the new domain. 3. Restart nginx server. ```bash theme={null} sudo systemctl restart nginx ``` Voila! `docs.yourdomain.com` is live with a secure connection, and your portal data is visible. ### How does this work? These are the engineering details to understand `How does docs.yourdomain.com` gets the portal data with SSL certificate. 1. `docs.yourdomain.com` resolves by customers nameserver and redirects to your Chatwoot domain. 2. Chatwoot check for the portal record with custom-domain `docs.yourdomain.com` 3. Redirects to the portal records for the domain `docs.yourdomain.com` Yaay!! Now you can have your own help-center, product-documentation related portal saved at Chatwoot dashboard and served at your domain with SSL certificate. # MFA Setup Guide Source: https://developers.chatwoot.com/self-hosted/configuration/multi-factor-authentication ## Overview Multi-Factor Authentication (MFA) adds an extra layer of security to your Chatwoot installation by requiring users to provide a time-based one-time password (TOTP) in addition to their regular password. This guide will help you enable MFA for your self-hosted Chatwoot instance. ## Prerequisites * Chatwoot version 4.6 or higher * Access to your server's environment variables * Ability to restart your Chatwoot application ## Configuration Steps ### Step 1: Generate Encryption Keys MFA requires Active Record Encryption keys to securely store user secrets. Use Rails' built-in encryption initialization command: ```bash theme={null} # SSH into your Chatwoot server cd /path/to/chatwoot # Generate all required encryption keys at once rails db:encryption:init ``` This command will output all three required keys: ```yaml theme={null} # Example output: active_record_encryption: primary_key: EGY8WhulUOXixybod7ZWwMIL68R9o5kC deterministic_key: aPA5XyALhf75NNnMzaspW7akTfZp0lPY key_derivation_salt: xEY0dt6TZcAMg52K7O84wYzkjvbA62Hz ``` **Important**: * Store these keys securely. You'll need them for the next step and for any future server migrations * Use different keys for each environment (development, staging, production) * Never share or commit these keys to version control ### Step 2: Configure Environment Variables Add the following variables to your `.env` file using the keys generated in Step 1: ```bash theme={null} # Active Record Encryption keys (required for MFA/2FA functionality) # Replace with the actual keys from rails db:encryption:init output ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=EGY8WhulUOXixybod7ZWwMIL68R9o5kC ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=aPA5XyALhf75NNnMzaspW7akTfZp0lPY ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=xEY0dt6TZcAMg52K7O84wYzkjvbA62Hz ``` ## User Setup Guide Once MFA is configured on your server, users can enable it for their accounts: ### For Users: Enabling MFA 1. **Log in** to your Chatwoot account 2. Navigate to **Profile Settings** → **Security** 3. Click **Enable Two-Factor Authentication** 4. **Scan the QR code** with an authenticator app: * Google Authenticator * Microsoft Authenticator * Authy * 1Password * Or any TOTP-compatible app 5. **Enter the 6-digit code** from your authenticator app 6. **Save your backup codes** in a secure location (10 alphanumeric 8-character codes) 7. Click **Verify and Enable** ### For Users: Logging in with MFA 1. Enter your email and password as usual 2. When prompted, enter the 6-digit code from your authenticator app 3. Alternatively, use a backup code if you don't have access to your authenticator ### For Users: Disabling MFA 1. Go to **Profile Settings** → **Security** 2. Click **Disable Two-Factor Authentication** 3. Enter your current 6-digit code and password 4. Confirm the action ## Troubleshooting ### MFA Not Available If users don't see MFA options: 1. **Check encryption keys are set**: ```bash theme={null} echo $ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY ``` Should display your key, not blank. 2. **Verify all three keys are configured**: ```bash theme={null} rails runner " puts 'Primary Key: ' + (ENV['ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY'].present? ? '✓' : '✗') puts 'Deterministic Key: ' + (ENV['ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY'].present? ? '✓' : '✗') puts 'Derivation Salt: ' + (ENV['ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT'].present? ? '✓' : '✗') " ``` 3. **Ensure application was restarted** after configuration ### Lost Authenticator Access If a user loses access to their authenticator: 1. **Using backup codes**: * Users can log in with one of their saved backup codes (8-character alphanumeric) * Each code can only be used once * Example format: `A1B2C3D4` 2. **Admin intervention** (if backup codes are also lost): ```bash theme={null} # Reset MFA for a specific user rake mfa:reset[user@example.com] # Generate new backup codes for a user rake mfa:generate_backup_codes[user@example.com] # Reset MFA for all users rake mfa:reset_all ``` ## Security Best Practices ### Key Management * **Never commit encryption keys** to version control * **Generate separate keys** for each environment using `rails db:encryption:init` * **Use different keys** for development, staging, and production environments * **Rotate keys periodically** (requires re-enrollment of all users) * **Backup keys securely** - losing them means users can't authenticate ### Server Security * **Use HTTPS only** - MFA codes can be intercepted over HTTP * **Enable rate limiting** - Chatwoot includes built-in rate limiting for login attempts * **Regular updates** - Keep Chatwoot and dependencies updated * **Monitor failed attempts** - Review logs for suspicious activity ## Migration and Disaster Recovery ### Migrating to a New Server 1. **Export environment variables** from old server (including encryption keys) 2. **Backup database** with MFA data 3. **Set up new server** with the same encryption keys (do NOT generate new ones) 4. **Restore database** 5. **Test MFA login** with a test account **Note**: You must use the exact same encryption keys on the new server. If you generate new keys with `rails db:encryption:init`, existing MFA secrets will become unreadable. ### Disaster Recovery If encryption keys are lost: 1. All users will need to re-enable MFA 2. Communicate the issue to users promptly *This guide applies to Chatwoot version 4.6 and above* # Custom Mobile App Build Source: https://developers.chatwoot.com/self-hosted/custom-mobile-app Guide to building a custom-branded Chatwoot mobile app with push notifications and deep linking # Custom mobile app build Guide to building a custom-branded Chatwoot mobile app with push notifications, deep linking, and app store submission. ## Push notifications Chatwoot supports mobile push notifications through Firebase Cloud Messaging (FCM). There are two delivery paths depending on your setup: * **Relay server (default)**: Self-hosted instances without Firebase credentials route notifications through the Chatwoot relay server, which forwards them to the **official Chatwoot mobile app**. * **Direct FCM**: Instances with Firebase configured send notifications directly to your **custom-built mobile app**. You must use either the official apps for both platforms or custom builds for both — mixing is not supported. For more details, refer to the [push notification documentation](https://www.chatwoot.com/hc/handbook/articles/1687935909-push-notification). ### Setting up Firebase To send push notifications to your custom-branded app, you need to configure Firebase on both the mobile app and the Chatwoot server. #### Step 1: Create a Firebase project 1. Go to the [Firebase Console](https://console.firebase.google.com/) and create a new project (or use an existing one). 2. Register your Android app with your package name (e.g., `com.yourcompany.app`). 3. Register your iOS app with your bundle identifier (e.g., `com.yourcompany.app`). #### Step 2: Download Firebase config files Download the platform-specific configuration files from your Firebase project settings: 1. In **Project Settings > General**, find your Android app and click **Download google-services.json**. 2. Place the file in the root of the mobile app repository. 1. In **Project Settings > General**, find your iOS app and click **Download GoogleService-Info.plist**. 2. Place the file in the root of the mobile app repository. #### Step 3: Configure mobile app environment variables Update your `.env` file to point to the Firebase config files: ```bash theme={null} EXPO_PUBLIC_ANDROID_GOOGLE_SERVICES_FILE=./google-services.json EXPO_PUBLIC_IOS_GOOGLE_SERVICES_FILE=./GoogleService-Info.plist ``` Then regenerate the native code so the new config is picked up: ```bash theme={null} pnpm generate ``` #### Step 4: Generate a Firebase service account The Chatwoot server needs a service account to send push notifications via the FCM v1 API. 1. In the Firebase Console, go to **Project Settings > Service accounts**. 2. Click **Generate new private key** to download a JSON credentials file. Keep this file secure. It grants access to send push notifications on behalf of your Firebase project. #### Step 5: Configure the Chatwoot server In your Chatwoot installation, navigate to **Super Admin > App Config** and set the following: | Config key | Value | | ---------------------- | --------------------------------------------------- | | `FIREBASE_PROJECT_ID` | Your Firebase project ID (e.g., `my-project-12345`) | | `FIREBASE_CREDENTIALS` | The full contents of the service account JSON file | Once both values are set, the server will send push notifications directly to FCM instead of using the relay server. #### Verifying the setup 1. Build and install the custom app on a device (`pnpm run:ios` or `pnpm run:android`). 2. Log in to your Chatwoot instance from the mobile app. 3. From another browser session, send a message to a conversation assigned to the logged-in agent. 4. The device should receive a push notification. Push notifications do not work on iOS simulators. You must use a physical device to test. ## Deep linking Deep linking allows users to tap a Chatwoot conversation URL (or a push notification) and be taken directly to that conversation in the mobile app. The app supports two mechanisms: * **Custom URL scheme**: `chatwootapp://` — used for SSO callbacks and internal routing. * **Universal Links (iOS) / App Links (Android)**: `https:///app/accounts/*/conversations/*` — used for opening web URLs directly in the app. ### How it works When the app receives a deep link, React Navigation matches it against the configured path pattern and navigates to the conversation screen: ``` https:///app/accounts/{accountId}/conversations/{conversationId} ``` This works across all app states — whether the app is in the foreground, backgrounded, or was terminated. Push notification taps also use this same flow to navigate to the relevant conversation. ### Mobile app configuration The app uses Expo's built-in deep linking support. In `app.config.ts`, update the following to match your domain: Update the [associated domain](https://docs.expo.dev/linking/ios-universal-links/) to your Chatwoot installation URL: ```typescript theme={null} ios: { associatedDomains: ['applinks:your-domain.com'], } ``` Expo prebuild writes this into the `.entitlements` file automatically. Update the [intent filter](https://docs.expo.dev/linking/android-app-links/) host to your Chatwoot installation URL: ```typescript theme={null} android: { intentFilters: [ { action: 'VIEW', autoVerify: true, data: [ { scheme: 'https', host: 'your-domain.com', pathPrefix: '/app/accounts/', }, ], category: ['BROWSABLE', 'DEFAULT'], }, ], } ``` Expo prebuild writes this into the `AndroidManifest.xml` automatically. After making changes, regenerate the native code: ```bash theme={null} pnpm generate ``` ### Server configuration The Chatwoot server dynamically serves the verification files that Android and iOS require to confirm your app owns the domain. Configure the following environment variables on your Chatwoot installation: The server serves an `apple-app-site-association` file at `https:///.well-known/apple-app-site-association`. No additional configuration is needed beyond ensuring your Chatwoot installation is accessible at the domain specified in `associatedDomains`. Set the following environment variables with your app's package name and signing certificate fingerprint: ```bash theme={null} ANDROID_BUNDLE_ID=com.yourcompany.app ANDROID_SHA256_CERT_FINGERPRINT=YOUR:SHA256:CERT:FINGERPRINT ``` This is served at `https:///.well-known/assetlinks.json` and tells Android to open matching URLs in your app. To obtain your SHA-256 certificate fingerprint, run: ```bash theme={null} keytool -list -v -keystore your-keystore.jks -alias your-alias ``` ## Build & Submit using EAS We use Expo Application Services (EAS) for building, deploying, and submitting the app to app stores. EAS Build and Submit is available to anyone with an Expo account, regardless of whether you pay for EAS or use our Free plan. You can sign up at [Expo EAS](https://expo.dev/eas). ### Build the app #### iOS Build ```bash theme={null} pnpm run build:ios:local ``` #### Android Build ```bash theme={null} pnpm run build:android:local ``` ### Submit the app #### iOS Submission ```bash theme={null} pnpm submit:ios ``` #### Android Submission ```bash theme={null} pnpm submit:android ``` When you run the above command, you will be prompted to provide a path to a local app binary file. Please select the file that you built in the previous step: * **iOS**: `.ipa` file * **Android**: `.aab` file It may take a while to complete the submission process. You will see the status of the submission on your terminal. # Chatwoot Production Deployment Guide Source: https://developers.chatwoot.com/self-hosted/deployment/architecture Understanding Chatwoot's production architecture and deployment requirements This guide will help you to deploy Chatwoot to production! ## Architecture Running Chatwoot in production requires the following set of services. * Chatwoot web servers * Chatwoot workers * PostgreSQL Database * Redis Database * Email service (SMTP servers / SendGrid / Mailgun etc) * Object Storage (S3, Azure Storage, GCS, etc) architecture ## Updating your Chatwoot installation A new version of Chatwoot is released around the first Monday of every month. We also release minor versions when there is a need for hotfixes or security updates. You can stay tuned to our [Roadmap](https://github.com/chatwoot/chatwoot/milestones) and [releases](https://github.com/chatwoot/chatwoot/releases) on GitHub. We recommend you to stay up to date with our releases to enjoy the latest features and security updates. The deployment process for a newer version involves updating your app servers and workers with the latest code. Most updates would involve database migrations as well which can be executed through the following Rails command. ```bash theme={null} bundle exec rails db:migrate ``` The detailed instructions can be found in respective deployment guides. ## Available deployment options If you want to self host Chatwoot, the recommended approach is to use one of the recommended one click installation options from the below list. If you are comfortable with Ruby on Rails applications, you can also make use of the other deployment options mentioned below. * **[Heroku](/self-hosted/deployment/heroku)** (recommended) * **[Docker](/self-hosted/deployment/docker)** (recommended) * **[Linux](/self-hosted/deployment/linux-vm)** * **[Kubernetes](/self-hosted/deployment/helm-chart)** * **[Chatwoot CTL](/self-hosted/deployment/chatwoot-ctl)** ### Cloud Providers * **[AWS](/self-hosted/deployment/aws)** * **[Azure](/self-hosted/deployment/azure)** * **[DigitalOcean](/self-hosted/deployment/digitalocean)** * **[Google Cloud](/self-hosted/deployment/gcp)** * **[Heroku](/self-hosted/deployment/heroku)** # AWS Chatwoot deployment guide Source: https://developers.chatwoot.com/self-hosted/deployment/aws Deploy Chatwoot on AWS with a reference HA architecture The following is a reference HA architecture guide for deploying Chatwoot on AWS. For a cloud-native deployment, use our [helm charts](https://github.com/chatwoot/charts) with AWS Elastic Kubernetes Service(EKS). ## Introduction We will use the Linux installation script to get a chatwoot instance running. Also instead of relying on Redis, Postgres and Nginx installed in the same ec2; we will proceed to make use of managed AWS services for the same viz Elasticache, RDS, and ALB. ### Prerequisites 1. AWS account 2. Domain to use with Chatwoot ### Architecture This guide will follow a standard 3-tier architecture on AWS. aws-architecture ## Network ### Create VPC 1. Sign in to the AWS console and pick the region you will deploy. 2. Navigate to the VPC console and create a new vpc for chatwoot. At the `name` tag, enter `chatwoot-vpc` and use the CIDR block `10.0.0.0/16`. 3. Leave the rest of the options as default and click on `Create VPC`. aws-create-vpc ### Subnets Create two public and private subnets in the vpc we created. Make sure to have them in different AZ's and have non-overlapping CIDR ranges. 1. Navigate to VPC > Subnets. 2. Click on `Create Subnet`. Select the `chatwoot-vpc` we created before, name it as `chatwoot-public-1`, select an availability zone (for example, ap-south-1a), and the CIDR block as `10.0.0.0/24`. aws-create-subnet 3. Follow the same to create the remaining subnets. | Name | Type | Availability Zone | CIDR Block | | -------------------- | ------- | ----------------- | ------------- | | `chatwoot-public-1` | public | `ap-south-1a` | `10.0.0.0/24` | | `chatwoot-public-2` | public | `ap-south-1b` | `10.0.1.0/24` | | `chatwoot-private-1` | private | `ap-south-1a` | `10.0.2.0/24` | | `chatwoot-private-2` | private | `ap-south-1b` | `10.0.3.0/24` | 4. After creating all subnets, enable `auto assign public ipv4 address` for public subnets under `Actions` > `Subnet Settings`. ### Internet Gateway 1. Select `Create Internet Gateway` , name it `chatwoot-igw`, and click create. 2. Select it from the internet gateways list, choose actions and then select `Attach to VPC`. 3. Choose `chatwoot-vpc` and click attach. aws-create-igw ### NAT Gateway Chatwoot app servers need to be deployed in the private subnet. For them to access the internet, we need to add NAT gateways to our public subnet and add a route from the private subnets. 1. Navigate the VPC dashboard and select `NAT gateways`. 2. Click `Create NAT Gateway`. 1. Name it `chatwoot-nat-1`. 2. Select the `chatwoot-public-1` subnet. 3. Click on `Allocate Elastic IP`. 4. Add additional tags as per your need. 5. Click `Create NAT gateway`. aws-create-nat 3. Follow the same to create a second NAT gateway (`chatwoot-nat-2`) and choose the `chatwoot-public-2` subnet. ### Route tables The route table controls the inbound and outbound access for a subnet. #### Public Route table We will create route tables so that our public subnets can reach the internet via the Internet gateway. Navigate to the VPC dashboard and select `Route Tables`. 1. Click `Create route table`. 2. Use the name `chatwoot-public-rt` and choose `chatwoot-vpc` under VPC. 3. Click `Create`. aws-create-rt Next, we need to add a route to the internet gateway we created earlier(`chatwoot-igw`). 1. Select the `chatwoot-public-rt` route table from the list and click on `Edit routes` > `Add Route`. 2. Set the destination as `0.0.0.0/0` and choose the target as `chatwoot-igw`. Click on `Save Changes`. Also, 1. Select the `chatwoot-public-rt` route table from the list and click on `Subnet Associations` > `Edit subnet associations`. 2. Select both the public subnets(`chatwoot-public-1`,`chatwoot-public-2`) and click `save`. #### Private Route table We will also create private route tables so that our private subnets can reach the internet via the NAT gateways. 1. Follow the above guide and create two private route tables, namely, `chatwoot-private-a` and `chatwoot-private-b`. 2. Select the route tables and add a route to the NAT gateway in their respective availability zone. 1. For `chatwoot-private-a`, add a route to `0.0.0.0/0` and target as `chatwoot-nat-1`. 2. For `chatwoot-private-b`, add a route to `0.0.0.0/0` and target as `chatwoot-nat-2`. Also, 1. Associate the private route tables with corresponding private subnets. 1. For `chatwoot-private-a`, associate `chatwoot-private-1` subnet. 2. For `chatwoot-private-b`, associate `chatwoot-private-2` subnet. ## Application Load Balancer (ALB) Create an application load balancer to receive traffic on port 80 and 443 and distribute it across Chatwoot instances. 1. Navigate to the EC2 section and choose the Load Balancer section. 2. Click `Create Load Balancer`. 1. Choose `Application Load Balancer`. 2. For the load balancer name, use `chatwoot-loadbalancer`. 3. Select the scheme as `internet-facing` and IP address type as `IPv4`. 4. For the network mapping section, 1. Select `chatwoot-vpc`. 2. Select the public subnets `chatwoot-public-1` and `chatwoot-public-2` under the mapping section. 5. For the Security group section, 1. Create a new security group, `chatwoot-loadbalancer-sg`. 2. Add rules to allow HTTP and HTTPS traffic from anywhere(`0.0.0.0/0`, `::/0`). 3. Also, add a rule to allow TCP on port 3000. This rule allows the load balancer health checks to pass since Chatwoot runs on port 3000. 4. Add a rule to allow SSH traffic from the bastion security group we will create at the latter stage of the guide. Revisit this section after completing the bastion step. 6. For the Listeners and routing section, create two listeners for 80 and 443. Set the forwarding rule on listener 80 to redirect `http` to `https`. 1. Also, create a target group, `chatwoot-tg`, that will forward the requests to port `3000`(Chatwoot listens on this port). 2. Add a health check to the endpoint `/api`. This endpoint is not authenticated and should return the application version. ``` { "version": "1.22.1", "timestamp": "2021-12-06 16:07:39" } ``` 7. Add any necessary tags and click create. Also, add if you have your domain on Route53 and use ACM to generate a certificate to use with ALB. ## Postgresql using AWS RDS Chatwoot uses Postgres as a DB layer, and we will use Amazon RDS with a multi-AZ option for reliability. ### RDS security group 1. Navigate to EC2 > Security groups and create a new sg. 2. Name it `chatwoot-rds-sg`. 3. Select the `chatwoot-vpc` and add an inbound rule for postgres port with source `chatwoot-loadbalancer-sg`. ### RDS subnet group 1. Navigate to the RDS section and select subnet groups. 2. Create `chatwoot-rds-group` and choose `chatwoot-vpc`. 3. Select both az's and the private subnets. ### RDS 1. Select create a database. 2. Use standard create and choose the Postgres engine. 3. Use the production template, and create a Postgres master username and password. 4. Enable Multi-AZ deployment. 5. Select `chatwoot-vpc` and select the rds security group we created earlier. 6. Enable password authentication. 7. Click create. 8. After completing the creation, note down the hostname, username, and password. We will need this to configure Chatwoot. ## Redis using AWS Elasticache 1. Follow similar steps like the rds to create Redis security and subnet groups. 2. Create the Redis cluster with a multi-AZ option. ## Creating Bastion servers Create bastion servers in both public subnets. These servers will be used to ssh into Chatwoot servers in private subnets. 1. Navigate to the EC2 dashboard and click launch instance. 2. Use an `Ubuntu 20.04 image` with a `t3.micro` type. 3. Choose `chatwoot-vpc` and subnet `chatwoot-public-1`. 4. Name it `chatwoot-bastion-a`. 5. Add a new sg, `chatwoot-bastion-sg` and enable ssh access from anywhere. 6. Leave the rest as defaults and click launch. 7. Once the instance is up, try to SSH into the instance. Repeat and create another bastion, `chatwoot-bastion-b` in the other AZ. ## Install Chatwoot 1. Navigate to the EC2 section, and click on launch instance. 2. Use an `Ubuntu 20.04 image` with a `c5.xlarge` instance type. 3. Choose the chatwoot-vpc and select the private subnet `chatwoot-private-1`. 4. Disable auto-assign public IP and increase the storage of root volume to 60 GB. 5. Add necessary tags. Set the `Name` tag to `chatwoot`. 6. Select the load balancer security group and click launch. 7. SSH into the bastion server and, from there, ssh to the chatwoot instance we created. 8. Switch to the `root` user. 9. Download the chatwoot Linux installation script. ```bash theme={null} wget https://get.chatwoot.app/linux/install.sh chmod 755 install.sh ``` 10. Run the script. ```bash theme={null} ./install.sh --install ``` ## Configure Chatwoot 11. Once the installation is complete, switch to the chatwoot user and navigate to the chatwoot folder. Edit the .env file and replace the Postgres and Redis credentials with RDS and elasticache values. ```bash theme={null} sudo -i -u chatwoot cd chatwoot vi .env ``` 12. Run the db migration. ```bash theme={null} RAILS_ENV=production bundle exec rake db:prepare ``` 13. Also modify the other necessary environment variable for your chatwoot setup. Refer to the [Linux VM environment configuration guide](/self-hosted/deployment/linux-vm#configure-the-required-environment-variables). 14. Restart the `chatwoot` service. ```bash theme={null} sudo cwctl --restart ``` ## Verify login 15. Add this instance to the target group attached to the alb. 16. Navigate to your chatwoot domain to see if everything is working. ## Create a custom AMI 1. If you are getting the onboarding page, complete the signup and verify the installation. 2. Voila !! Your chatwoot instance is up. 3. If everything looks good, proceed to create an ami from this instance and name it `chatwoot-base-ami`. ## Auto Scaling Groups (ASG) 1. Create a launch configuration using the above base image. 2. Proceed to create an auto-scaling group from this launch config. 3. Set the minimum and desired capacity to 2 and the maximum to 4. Modify this as per your requirement. 4. Create a scaling policy based on CPU utilization. 5. At this point, we are good to terminate the instance we created earlier. 6. Check the load balancer or target group to verify if two new chatwoot instances have come up. 7. That's it. ## Monitoring 1. Refer to the [APM and error monitoring guide](/self-hosted/monitoring/apm-and-error-monitoring). ## Updating Chatwoot 1. Log in to one of the application servers and complete the update instructions. Run migrations if needed. Refer to the [Linux VM upgrade guide](/self-hosted/deployment/linux-vm#upgrading-to-a-newer-version-of-chatwoot). 2. Create a new ami and update the launch config. ## Conclusion This document is a reference guideline for an HA chatwoot architecture on AWS. Modify or build upon this to suit your requirements. # AWS Marketplace AMI Deployment Source: https://developers.chatwoot.com/self-hosted/deployment/aws-marketplace Deploy Chatwoot on AWS using the marketplace AMI listing # AWS Chatwoot Deployment Guide The following is the guide for deploying Chatwoot on AWS using the marketplace listing. Use our helm charts with AWS Elastic Kubernetes Service(EKS) for a cloud-native deployment. ## Prerequisites * AWS account ## Install Chatwoot via AWS Marketplace AMI ### Step 1: Subscribe to Chatwoot 1. Go to [Chatwoot AWS marketplace listing](https://aws.amazon.com/marketplace/pp/prodview-tolblk4kmdqd4) and click on **Subscribe**. Subscribe to Chatwoot ### Step 2: Sign In 2. Sign in with your AWS account. AWS Sign In ### Step 3: Continue to Configuration 3. Click on **Continue to Configuration**. Continue to Configuration ### Step 4: Configure Software 4. Select the latest version in **Software Version** and pick your AWS **region**. Click **Continue to Launch**. Configure Software ### Step 5: Launch Configuration 5. Review the launch configuration. Leave the **Choose Action** field with the default value **Launch from Website**. Choose a VPC and subnet as per your AWS region preference. Launch Configuration ### Step 6: Create Security Group 6. Scroll down to the **Security Group** section and click **Create New Based On Seller Settings**. Create Security Group ### Step 7: Save Security Group 7. Save the new security group and choose it after creation. Save Security Group ### Step 8: Configure Key Pair 8. Pick a key pair you already have or create a new one in the region you are deploying. Click **Launch**. Configure Key Pair ### Step 9: Launch Confirmation 9. AWS should now display a congratulations screen confirming that Chatwoot instance is launched successfully. Click on the **EC2 Console** link. Launch Confirmation ### Step 10: Wait for Instance 10. Wait for a few minutes to let the instance come up. Wait for Instance ### Step 11: Get Public IP 11. Select the instance and copy the public IP. Get Public IP ### Step 12: Access Chatwoot 12. Visit `http://:3000`. This should bring up the Chatwoot UI. Congratulations. Woot! Woot!! Access Chatwoot ### Step 13: Configure Production URL and SSL For production deployments, associate an Elastic IP with the EC2 instance so the public IP does not change after restarts. Then create a DNS `A` record for your domain or subdomain pointing to that Elastic IP. After the DNS record resolves, connect to the instance and run: ```bash theme={null} sudo cwctl --webserver ``` This configures Nginx and SSL for your Chatwoot instance. ## Configuring Chatwoot To configure Chatwoot, we need to SSH into the instance. We will use **AWS Console Connect** for this. ### Step 1: Connect to Instance 1. Select the instance and click on **Connect**. Connect to Instance ### Step 2: Use Ubuntu User 2. Change the username from `root` to `ubuntu` and click **Connect**. Use Ubuntu User ### Step 3: Configure Environment Variables 3. Switch to the `chatwoot` user and configure the necessary environment variables. Refer to [Environment variables](/self-hosted/configuration/environment-variables) document for the complete list. ```bash theme={null} sudo -i -u chatwoot cd chatwoot vi .env ``` For production, configure Nginx and SSL after pointing your domain to the instance. See [Chatwoot CTL](/self-hosted/deployment/chatwoot-ctl#setup-nginx-with-ssl-after-installation). ## Updating the Instance Please follow the Chatwoot update process in the standard [Linux VM setup](/self-hosted/deployment/linux-vm). ## Security Recommendations ### SSL Configuration * Set up SSL certificates using Let's Encrypt or AWS Certificate Manager * Configure Nginx as a reverse proxy * Update security group rules to allow HTTPS traffic (port 443) ### Access Control * Restrict SSH access to specific IP addresses * Use IAM roles for EC2 instances where possible * Enable AWS CloudTrail for audit logging ### Backup Strategy * Set up automated EBS snapshots * Configure database backups * Store backups in S3 with appropriate lifecycle policies ## Troubleshooting ### Common Issues **Problem**: Cannot access Chatwoot on port 3000 **Solutions**: * Check security group allows inbound traffic on port 3000 * Verify instance is running and healthy * Check if Chatwoot service is running: `sudo systemctl status chatwoot` **Problem**: Chatwoot service fails to start **Solutions**: * Check logs: `sudo journalctl -u chatwoot -f` * Verify environment variables are correctly set * Ensure database connection is working * Check disk space and memory usage ### Support Resources * [AWS Support](https://aws.amazon.com/support/) * [Chatwoot Community Discord](https://discord.com/invite/cJXdrwS) * [GitHub Issues](https://github.com/chatwoot/chatwoot/issues) *** The AWS Marketplace AMI provides a quick way to deploy Chatwoot with pre-configured settings. For production use, ensure you implement proper security measures and backup strategies. # Azure Chatwoot deployment guide Source: https://developers.chatwoot.com/self-hosted/deployment/azure Deploy Chatwoot on a single VM in Azure This guide will deploy chatwoot on a single VM in Azure. For a cloud native deployment, use our [helm charts](https://github.com/chatwoot/charts) with Azure Kubernetes Service(AKS). This guide is a work in progress and your mileage may vary. ## Create a Virtual Machine 1. Login to the Azure portal and choose Virtual Machines. 2. Select create a VM from scratch. 3. In the Basics tab, create a subscription and a new resource group. 4. Name the virtual machine as `chatwoot` and select your preferred region. 5. Select `Ubuntu 20.04 LTS - Gen2` as the image. 6. For instance size, we recommend the type `Standard_D4s_v3`(4vCPU, 16GB RAM). 7. Under authentication, leave the defaults and create a new key pair if needed. 8. Allow HTTP, HTTPS and SSH under inbound port rules. 9. Click next and leave the defaults for Disks, Networking, Management, Advanced and Tags section. 10. Select `Review + create` to spin up the VM. azure-create-vm ## Install Chatwoot 1. SSH into the instance created from your local machine or create a bastion in azure to ssh via the browser. 2. Follow the [Linux VM instructions](/self-hosted/deployment/linux-vm). 3. Woot! Woot! Your Chatwoot Instance is ready and can be accessed at `http://:3000`. Or if you completed the domain setup during the installation, chatwoot should be available at `https://`. Browser access via port 3000 will only work if enabled under inbound rules. ## Configure Chatwoot 1. Follow the Chatwoot docs to configure your domain, email and other parameters you need. Refer to the [Linux VM environment configuration guide](/self-hosted/deployment/linux-vm#configure-the-required-environment-variables). # Backing Up Your Chatwoot Installation Source: https://developers.chatwoot.com/self-hosted/deployment/backup Complete guide to backing up and restoring your Chatwoot installation data Backups are crucial for any software system, including Chatwoot, for several reasons: 1. **Disaster Recovery**: Backups serve as your safety net in the event of catastrophic incidents like hardware failure, data center outage, or natural disasters. They allow you to restore your application to its previous state quickly. 2. **Data Loss Prevention**: Accidental data deletion or alteration due to human errors, software bugs, or malicious attacks can lead to significant losses. Backups provide a way to recover such lost or corrupted data. 3. **Audit and Compliance**: Certain regulations require businesses to maintain backups for a specific period. These backups may serve as reference points for audits or compliance checks. 4. **Business Continuity**: In situations where your primary data source becomes unavailable, having a backup allows your business to continue its operations with minimal disruption. In short, backups are an essential part of risk management and ensure the smooth operation of your software system. ## What Data Should Be Backed Up? * [Postgres Database](#postgres-database) * [Storage (File uploads/Other Assets in Your Installation)](#storage) * [Configuration Variables](#configuration) * [Code Customisations](#code-customisations) ### Postgres Database If you are managing the Postgres service yourself, you can use the `pg_dump` tool provided by PostgreSQL for this purpose. ```bash theme={null} pg_dump -U postgres -W -F t chatwoot_production > backup.tar ``` If you are using a managed provider like AWS, Google Cloud, or Azure, enable backups using the options provided by your provider. ### Storage Based on your [storage configuration](/self-hosted/configuration/environment-variables#configure-storage), you should take the appropriate steps. If you are using a managed provider like `S3`, `GCS`, etc., ensure backups using the options available with the provider. If you are using the `local` storage provider, ensure to take a disk backup of the `storage` folder in the root of your Chatwoot Installation. ### Configuration Important configuration might be stored in environment variables. You should back these up as well. Make a copy of the `.env` file or keep a backup of these configurations based on your setup. ### Code Customisations Official Chatwoot updates using tools like `cwctl` assume that there are no customisations done to the Chatwoot installation. We don't provide support for custom modifications of the Chatwoot codebase. If you are planning any such modifications, please ensure that you back up these customisations using `git` or other appropriate tooling. ## Guidelines The frequency of backups largely depends on the nature of your application and the amount of data you generate and can afford to lose. You can opt for `continuous` or `daily` backups as per your need. Remember, these backups should be stored in a different physical location to protect against hardware failures. Using a cloud storage provider could be a good solution. Please ensure that access to these backups is tightly controlled, as they contain sensitive data. ## Restoring a Backup To restore a backup into a new Chatwoot installation, please follow these steps: * Set up a new Chatwoot installation and finish the onboarding flow. * Ensure that the [configuration](#configuration) values match the ones in your backup. * Purge the database of this installation and replace it with the data from your [postgres](#postgres-database) backup. * Restore [Storage](#storage) with your backup data. * Restore any [Code Customisations](#code-customisations). * Restart Chatwoot services and you are good to go. # Caprover Chatwoot Production deployment guide Source: https://developers.chatwoot.com/self-hosted/deployment/caprover Deploy Chatwoot using Caprover's one-click application management ## Caprover Overview Caprover is an extremely easy to use application server management tool. It is blazing fast and uses Docker under the hood. Chatwoot has been made available as a one-click app in Caprover, and the deployment process is straightforward. This is a community contributed installation setup. This will only have community support for any issues in future. ## Setup Chatwoot Using Caprover ### 1. Install Caprover on your VM Finish your Caprover installation by referring to [Getting started guide](https://caprover.com/docs/get-started.html). ### 2. Install Chatwoot Chatwoot is available in the one-click apps option in Caprover. Search for Chatwoot in the list of one-click apps. Replace the default `version` with the latest `version` of chatwoot. Use appropriate values for the Postgres and Redis passwords and click install. It should only take a few minutes. ### 3. Finish the setup Head over to the `web` service in the Caprover applications and enable `Websocket Support` in the HTTP settings to true. You could also enable `https` for the application. caprover-enable-websocket ### 4. Configure environment variables Caprover will take care of Postgres and Redis installation, along with the app and worker servers. We would advise you to replace the Database/Redis services with managed/standalone servers once you start scaling. Also, ensure to set the appropriate environment variables for email, Object Store service etc. using our [Environment variables guide](/self-hosted/configuration/environment-variables) Chatwoot requires websocket support. Do enable it from `chatwoot-web` settings page in Caprover. ## Upgrading Chatwoot installation To update your chatwoot installation to the latest version in Caprover, run the following command in the deployment tab for web and worker in `method 5: deploy captain-definition`. Make sure to replace `[DESIRED VERSION HERE]` with the current latest stable version. Check [here](https://www.chatwoot.com/changelog/) and [here](https://hub.docker.com/r/chatwoot/chatwoot/tags) for possible version numbers first. ### web ```json theme={null} { "schemaVersion": 2, "dockerfileLines": [ "FROM chatwoot/chatwoot:[DESIRED VERSION HERE]", "RUN chmod +x docker/entrypoints/rails.sh", "ENTRYPOINT [\"docker/entrypoints/rails.sh\"]", "CMD bundle exec rake db:chatwoot_prepare; bundle exec rails s -b 0.0.0.0 -p 3000" ] } ``` ### worker ```json theme={null} { "schemaVersion": 2, "dockerfileLines": [ "FROM chatwoot/chatwoot:[DESIRED VERSION HERE]", "RUN chmod +x docker/entrypoints/rails.sh", "ENTRYPOINT [\"docker/entrypoints/rails.sh\"]", "CMD bundle exec sidekiq -C config/sidekiq.yml" ] } ``` ## Accessing Rails Console Login to the server where you have caprover installed and execute the following commands. ```bash theme={null} # access the shell inside the container docker exec -it $(docker ps --filter name=srv-captain--chatwoot-web -q) /bin/sh # start rails console RAILS_ENV=production bundle exec rails c ``` ## Common Errors ### API requests failing with "You need to sign in or sign up before continuing." Nginx by default strip of headers with `_` . Head over to the Nginx configuration option in caprover under the Chatwoot web and add the following directive. Access the Caprover `web dashboard` > `Apps` > `Apps Edit` > `Edit Default Nginx Configurations`. Refer [https://caprover.com/docs/nginx-customization.html](https://caprover.com/docs/nginx-customization.html) for more details. ```nginx theme={null} # Nginx strips out underscore in headers by default # Chatwoot relies on underscore in headers for API # Make sure that the config is set to on. underscores_in_headers on; ``` ### Issues related to storage persistance Please setup a cloud storage like s3 or gcs bucket or any s3 api compatible service as the active storage service. Caprover installation needs this for storage persistance. Refer the [storage guide](/self-hosted/deployment/storage/supported-providers). ## Further references * [https://isotropic.co/how-to-install-chatwoot-to-a-digitalocean-droplet/](https://isotropic.co/how-to-install-chatwoot-to-a-digitalocean-droplet/) # Chatwoot CTL Source: https://developers.chatwoot.com/self-hosted/deployment/chatwoot-ctl CLI tool to install and manage a self hosted Chatwoot Linux installation ## Introduction Chatwoot CTL(`cwctl`) is CLI tool to install and manage a self hosted Chatwoot Linux installation. `cwctl` aims to abstract away the common bash interactions with a Chatwoot installation and provide an easy to use syntax. This is not intended to be a full replacement. If you are running a Chatwoot v2.7.0 instance or later, `cwctl` would have been already installed for you as part of installation. Check if `cwctl` is already installed by ```bash theme={null} cwctl --version ``` If `cwctl` is not present, follow the steps below to install Chatwoot CTL. ### Install or Upgrade Chatwoot CTL If you used an older version of install script(\< 2.0), you will not have `cwctl` in your PATH. To install/upgrade Chatwoot CTL, ```bash theme={null} wget https://get.chatwoot.app/linux/install.sh -O /usr/local/bin/cwctl && chmod +x /usr/local/bin/cwctl cwctl --help ``` The above command requires root access to install `cwctl` to `/usr/local/bin`. ### Help To learn more about the options supported by `cwctl`, ```bash theme={null} sudo cwctl --help ``` ### Upgrading to a newer version of Chatwoot Whenever a new version of Chatwoot is released, use the following steps to upgrade your instance. ```bash theme={null} sudo cwctl --upgrade ``` This will upgrade your Chatwoot instance to the latest stable release. If you are running a custom branch in production do not use this to upgrade. ### Upgrading to a specific version or branch `cwctl` also supports experimental upgrades to a specific Chatwoot version or branch. This is useful when an instance is several releases behind and needs to be upgraded through intermediate versions instead of jumping directly to the latest release. You can also use this to upgrade from a branch such as `develop`. ```bash theme={null} # Upgrade to a specific released version sudo cwctl -U v4.3.0 # Upgrade from a branch sudo cwctl -U develop ``` `-U`/`--Upgrade` is experimental and is not recommended for production environments without testing. When using a release tag like `v4.3.0`, Git may print a pull warning because tags are checked out in a detached HEAD state. Before upgrading, take a backup, review the release notes for the target version, and keep the Chatwoot repository clean. The upgrade will abort if local code changes are detected. ### Setup Nginx with SSL after installation To set up Nginx with SSL after initial setup(if you answered `no` to webserver/SSL setup during the first install) Please add an A record pointing to your Chatwoot instance IP before proceeding. ```bash theme={null} sudo cwctl --webserver ``` ### Restart Chatwoot ```bash theme={null} sudo cwctl --restart ``` ### Running Rails Console ```bash theme={null} sudo cwctl --console ``` ### Viewing Logs For Chatwoot web(rails) server logs use, ```bash theme={null} sudo cwctl --logs web ``` For Chatwoot worker(sidekiq) server logs use, ```bash theme={null} sudo cwctl --logs worker ``` ### Version To check the version of Chatwoot CTL, ```bash theme={null} sudo cwctl --version ``` # Deploy Chatwoot to Clever Cloud Source: https://developers.chatwoot.com/self-hosted/deployment/clevercloud Deploy Chatwoot on Clever Cloud PaaS platform Clever Cloud is a PaaS platform where you can deploy your applications with ease. To setup Chatwoot on Clever Cloud, you can follow the steps described below. This is a community contributed installation setup. This will only have community support for any issues in future. ## 1. Create CleverCloud application * Login to Clever Cloud dashboard * Click on create an application * Select your deployment type (> 2GB recommended) * Provide an app name and select the zone ## 2. Select addons Chatwoot requires PostgreSQL and Redis to function properly. Select Postgres and Redis from CleverCloud addons. * Copy connection URI from Postgres Addon and set `DATABASE_URL` environment variable * Make sure you have set REDIS\_URL ## 3. Setup Clever cloud origin * Clone Chatwoot project from Github ```bash theme={null} git clone git@github.com:chatwoot/chatwoot.git ``` * Set Clever Cloud origin ```bash theme={null} git remote add clever git+ssh://git@.clever-cloud.com/.git ``` ## 4. Setup build hooks To install the dependencies, you have to setup builds hooks. Set the following in the environment variables of the application. ```bash theme={null} CC_POST_BUILD_HOOK="RAILS_ENV=production rails assets:precompile" CC_PRE_BUILD_HOOK="pnpm install" CC_PRE_RUN_HOOK="rake db:chatwoot_prepare" ``` ## 5. Push the latest changes Push the latest code from your local machine to Clever Cloud. ```bash theme={null} git push clever master ``` Voila! After the deployment, you would be able to access the application. ## Environment Variables Make sure you have the following environment variables configured in the application. ```bash theme={null} CC_POST_BUILD_HOOK="RAILS_ENV=production rails assets:precompile" CC_PRE_BUILD_HOOK="pnpm install" CC_PRE_RUN_HOOK="rake db:chatwoot_prepare" DATABASE_URL="" FRONTEND_URL="" PORT="8080" RAILS_ENV="production" REDIS_URL="" SECRET_KEY_BASE="" ``` # Cloudron Chatwoot deployment guide Source: https://developers.chatwoot.com/self-hosted/deployment/cloudron Deploy Chatwoot using Cloudron's 1-click app platform ## Cloudron Overview [Cloudron](https://cloudron.io) is a platform that makes it easy to install, manage and secure web apps on your server. Chatwoot is now available as a 1-click app in the Cloudron app store and the installation is blazing fast. This is a community contributed installation setup. This will only have community support for any issues in future. ## Setup Chatwoot using Cloudron ### 1. Install Cloudron on your server Finish your Cloudron installation by following the instructions at [Get Cloudron](https://www.cloudron.io/get.html). ### 2. Install Chatwoot Once Cloudron installation is complete, login to your cloudron web portal and click on the appstore icon. Search for `Chatwoot` and click install. That's it. Chatwoot should be up and running in a minute or two. Direct link to the cloudron app store listing --> [https://www.cloudron.io/store/com.chatwoot.cloudronapp.html](https://www.cloudron.io/store/com.chatwoot.cloudronapp.html) ### 3. Finish the setup Navigate to your chatwoot domain and complete the onboarding setup. ### 4. Configure environment variables Cloudron will take care of Postgres and Redis installation, along with the app and worker processes. We would advise you to replace the Database/Redis services with managed/standalone servers once you start scaling. Also, ensure to set the appropriate environment variables for email, Object Store service etc. using our [Environment variables guide](/self-hosted/configuration/environment-variables). Custom environment variables can be set in `/app/data/env` using the Cloudron File manager. Be sure to reboot the app after making any changes. ## Upgrading Chatwoot installation Chatwoot follows a monthly release pattern with a new release every 15th of the month. Use the built in [Cloudron app updates](https://docs.cloudron.io/updates/) to stay on the latest version. Read about the changelog [here](https://www.chatwoot.com/changelog/). # DigitalOcean Chatwoot deployment guide Source: https://developers.chatwoot.com/self-hosted/deployment/digitalocean Deploy Chatwoot on a single droplet in DigitalOcean This guide will deploy chatwoot on a single droplet in DigitalOcean. For a cloud native deployment, go with our [1-click k8s app on DigitalOcean Marketplace](https://marketplace.digitalocean.com/apps/chatwoot). ## Create a Droplet (VM) 1. Login to DigitalOcean console and choose create droplet. 2. Choose `Ubuntu 20.04` image. 3. Create an instance with a minimum of 4vCPU and 8GB RAM. 4. Make sure to choose the datacenter region you want to deploy. 5. Under authentication, choose your SSH key or create a new one. This is important as you will need this key to complete the next section. 6. Click create. do-create-droplet ## Install Chatwoot 1. SSH into the droplet created above. 2. Follow the [Linux VM instructions](/self-hosted/deployment/linux-vm). 3. Woot! Woot! Your Chatwoot Instance is ready and can be accessed at `http://:3000`. Or if you completed the domain setup during the installation, chatwoot should be available at `https://` ## Configure Chatwoot 1. Follow the Chatwoot docs to configure your domain, email and other parameters you need. Refer to the [Linux VM environment configuration guide](/self-hosted/deployment/linux-vm#configure-the-required-environment-variables). # Docker Chatwoot Production deployment guide Source: https://developers.chatwoot.com/self-hosted/deployment/docker Deploy Chatwoot using Docker containers for production environments ## Pre-requisites Before proceeding, make sure you have the latest version of `docker` and `docker-compose` installed. As of now \[at the time of writing this doc], we recommend a version equal to or higher than the following. ```bash theme={null} $ docker --version Docker version 20.10.10, build b485636 $ docker compose version Docker Compose version v2.14.1 ``` Container name uses dashes instead of underscores by default with new docker/compose versions. If you are using an older version of docker/compose, replace `-` with `_`. Also, use `docker-compose` instead of `docker compose`. ## Steps to deploy Chatwoot using docker-compose ### 1. Install Docker on your VM ```bash theme={null} # example in ubuntu apt-get update apt-get upgrade curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh apt install docker-compose-plugin ``` ### 2. Download the required files ```bash theme={null} # Download the env file template wget -O .env https://raw.githubusercontent.com/chatwoot/chatwoot/develop/.env.example # Download the Docker compose template wget -O docker-compose.yaml https://raw.githubusercontent.com/chatwoot/chatwoot/develop/docker-compose.production.yaml ``` ### 3. Configure environment variables Tweak the `.env` and `docker-compose.yaml` according to your preferences. Refer to the available [environment variables](/self-hosted/configuration/environment-variables). You could also remove the dependant services like `Postgres`, `Redis` etc., in favor of managed services configured via environment variables. ```bash theme={null} # update redis and postgres passwords nano .env # update docker-compose.yaml same postgres pass nano docker-compose.yaml ``` ### 4. Prepare the database ```bash theme={null} docker compose run --rm rails bundle exec rails db:chatwoot_prepare ``` ### 5. Start the services ```bash theme={null} docker compose up -d ``` ### 6. Access your installation Your Chatwoot installation is complete. Please note that the containers are not exposed to the internet and they only bind to the localhost. Setup something like Nginx or any other proxy server to proxy the requests to the container. If you want to verify whether the installation is working, try `curl -I localhost:3000/api` to see if it returns `200`. Also, you could temporarily drop the `127.0.0.1:3000:3000` for rails to `3000:3000` in the compose file to access your instance at `http://:3000`. It's recommended to revert this change back and use Nginx or some proxy server in the front. ## Additional Steps 1. Have an `Nginx` web server acting as a reverse proxy for Chatwoot installation. So that you can access Chatwoot from `https://chat.yourdomain.com` 2. Run `docker compose run --rm rails bundle exec rails db:chatwoot_prepare` whenever you decide to update the Chatwoot images to handle the migrations. ### Configure Nginx and Let's Encrypt #### 1. Configure Nginx to serve as a frontend proxy ```bash theme={null} sudo apt-get install nginx cd /etc/nginx/sites-enabled nano yourdomain.com.conf ``` #### 2. Use the following Nginx config Use the following Nginx config after replacing the `yourdomain.com` in `server_name`. ```nginx theme={null} server { server_name ; # Point upstream to Chatwoot App Server set $upstream 127.0.0.1:3000; # Nginx strips out underscore in headers by default # Chatwoot relies on underscore in headers for API # Make sure that the config is set to on. underscores_in_headers on; location /.well-known { alias /var/www/ssl-proof/chatwoot/.well-known; } location / { proxy_pass_header Authorization; proxy_pass http://$upstream; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Ssl on; # Optional proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_http_version 1.1; proxy_buffering off; client_max_body_size 0; proxy_read_timeout 36000s; proxy_redirect off; } listen 80; } ``` #### 3. Verify and reload Nginx config ```bash theme={null} nginx -t systemctl reload nginx ``` #### 4. Run Let's Encrypt to configure SSL certificate ```bash theme={null} apt install certbot apt-get install python3-certbot-nginx mkdir -p /var/www/ssl-proof/chatwoot/.well-known certbot --webroot -w /var/www/ssl-proof/chatwoot/ -d yourdomain.com -i nginx ``` #### 5. Access your installation Your Chatwoot installation should be accessible from the `https://yourdomain.com` now. ## Steps to build images yourself We publish our base images to the Docker hub. You should be able to build your Chatwoot web/worker images from these base images. ### Web ```dockerfile theme={null} FROM chatwoot/chatwoot:latest RUN chmod +x docker/entrypoints/rails.sh ENTRYPOINT ["docker/entrypoints/rails.sh"] CMD bundle exec rails s -b 0.0.0.0 -p 3000 ``` ### Worker ```dockerfile theme={null} FROM chatwoot/chatwoot:latest RUN chmod +x docker/entrypoints/rails.sh ENTRYPOINT ["docker/entrypoints/rails.sh"] CMD bundle exec sidekiq -C config/sidekiq.yml ``` The app servers will run available on port `3000`. Ensure the images connect to the same database and Redis servers. Provide the configuration for these services via [environment variables](/self-hosted/configuration/environment-variables). ### Initial database setup To set up the database for the first time, you must run `rails db:chatwoot_prepare`. You may get errors if you try to run `rails db:migrate` at this point. ## Upgrading If you're not using the `latest` or `latest-ce` tag, you first need to change the desired tag in your docker-compose file. If your installation is very old, upgrade iteratively through intermediate Docker image tags instead of jumping directly to the latest image. Review the release notes between versions and run `rails db:chatwoot_prepare` after each upgrade. After that you can pull the new image and start using them: ```bash theme={null} docker compose pull docker compose up -d ``` Finally you may need to update the database: ```bash theme={null} docker compose run --rm rails bundle exec rails db:chatwoot_prepare ``` ## Running Rails Console ```bash theme={null} docker exec -it $(basename $(pwd))-rails-1 sh -c 'RAILS_ENV=production bundle exec rails c' ``` ## Chatwoot CE edition docker images If you want to run Chatwoot CE edition, replace the docker image tag with equivalent foss version tag. Docker tag for current `master` would be `latest-ce`. Version specific tags would follow the pattern `v*-ce`. For example the docker ce edition tag for Chatwoot `v2.3.2` would be `v2.3.2-ce`. # Deploying Chatwoot on Easypanel Source: https://developers.chatwoot.com/self-hosted/deployment/easypanel Deploy Chatwoot using Easypanel's modern server control panel [Easypanel](https://easypanel.io) it's a modern server control panel. You can use it to deploy Chatwoot on your own server. [![Deploy to Easypanel](https://easypanel.io/img/deploy-on-easypanel-40.svg)](https://easypanel.io/docs/templates/chatwoot) ## Instructions 1. Create a VM that runs Ubuntu on your cloud provider. 2. Install Easypanel using the instructions from the website. 3. Create a new project. 4. Install Chatwoot using the dedicated template. # Elestio Chatwoot fully managed deployment guide Source: https://developers.chatwoot.com/self-hosted/deployment/elestio Deploy Chatwoot with Elestio's fully managed platform ## Deploy to Elestio with one-click [![Deploy](https://pub-da36157c854648669813f3f76c526c2b.r2.dev/deploy-on-elestio-black.png)](https://elest.io/open-source/chatwoot) ## Select the providers * Select cloud service provider of your choice. * Choose region of your choice * Select service plan. The smallest one offers 1 CPU, 2 GB RAM etc. * Confirm the details and hit "Next" Elestio Setup ## Configure * Select the support level * Name your application * Add admin email (You can add email you want to access your application from) * Click "Create Service" * Here you also get option to copy your terraform config (Optional) ## Use Chatwoot * Click on "Display Admin UI" * Go to Admin Ui link provided * Add username and password provided on dashboard. Elestio Dashboard ## Update Chatwoot * Go to Overview section in your Chatwoot service * Click "Change version" inside Software section * Choose the latest version or the version of your choice. * Additionally update the configs or restart the instance with single clink under same section Elestio Change version # GCP Chatwoot deployment guide Source: https://developers.chatwoot.com/self-hosted/deployment/gcp Deploy Chatwoot on a single VM in GCP This guide will deploy chatwoot on a single VM in GCP. For a cloud native deployment, use our [helm charts](https://github.com/chatwoot/charts) with Google Kubernetes Engine(GKE). This guide is a work in progress and your mileage may vary. ## Create Compute Engine (VM) 1. Navigate to VM > Compute Engine window. 2. Create an instance with a minimum of 4vCPU and 8GB RAM.(N2 General-Purpose) 3. Make sure to select the correct region you want to deploy. 4. Choose `Ubuntu 20.04` as your OS with a 120GB disk. 5. Click create. gcp-create-compute-engine ## Install Chatwoot 1. SSH into the instance created. 2. Follow the [Linux VM instructions](/self-hosted/deployment/linux-vm). 3. Woot! Woot! Your Chatwoot Instance is ready and can be accessed at `http://:3000`. Or if you completed the domain setup during the installation, chatwoot should be available at `https://` ## Configure Chatwoot 1. Follow the Chatwoot docs to configure your domain, email and other parameters you need. Refer to the [Linux VM environment configuration guide](/self-hosted/deployment/linux-vm#configure-the-required-environment-variables). # Deploy Chatwoot on Kubernetes using Helm Charts Source: https://developers.chatwoot.com/self-hosted/deployment/helm-chart Deploy Chatwoot on Kubernetes using our official Helm charts This guide will help you to deploy a production ready Chatwoot instance with Helm Charts. To quickly try out the charts, follow the two steps below. For a production deployment, please make sure to pass in the required arguments to helm using your custom `values.yaml` file. ```bash theme={null} helm repo add chatwoot https://chatwoot.github.io/charts helm install chatwoot chatwoot/chatwoot ```