Mirror importado do GitHub: https://github.com/Rodribm10/iachat
Go to file
Muhsin Keloth d827e66453
feat: Instagram Inbox using Instagram Business Login (#11054)
This PR introduces basic minimum version of **Instagram Business
Login**, making Instagram inbox setup more straightforward by removing
the Facebook Page dependency. This update enhances user experience and
aligns with Meta’s recommended best practices.

Fixes
https://linear.app/chatwoot/issue/CW-3728/instagram-login-how-to-implement-the-changes


## Why Introduce Instagram as a Separate Inbox?


Currently, our Instagram integration requires linking an Instagram
account to a Facebook Page, making setup complex. To simplify this
process, Instagram now offers **Instagram Business Login**, which allows
users to authenticate directly with their Instagram credentials.

The **Instagram API with Instagram Login** enables businesses and
creators to send and receive messages without needing a Facebook Page
connection. While an Instagram Business or Creator account is still
required, this approach provides a more straightforward integration
process.

| **Existing Approach (Facebook Login for Business)** | **New Approach
(Instagram Business Login)** |
| --- | --- |
| Requires linking Instagram to a Facebook Page | No Facebook Page
required |
| Users log in via Facebook credentials | Users log in via Instagram
credentials |
| Configuration is more complex | Simpler setup |

Meta recommends using **Instagram Business Login** as the preferred
authentication method due to its easier configuration and improved
developer experience.

---

## Implementation Plan

The core messaging functionality is already in place, but the transition
to **Instagram Business Login** requires adjustments.

### Changes & Considerations

- **API Adjustments**: The Instagram API uses `graph.instagram`, whereas
Koala (our existing library) interacts with `graph.facebook`. We may
need to modify API calls accordingly.
- **Three Main Modules**:
  1. **Instagram Business Login** – Handle authentication flow.
2. **Permissions & Features** – Ensure necessary API scopes are granted.
  3. **Webhooks** – Enable real-time message retrieval.

![CleanShot 2025-03-10 at 21 32
28@2x](https://github.com/user-attachments/assets/1b019001-8d16-4e59-aca2-ced81e98f538)


---

## Instagram Login Flow

1. User clicks **"Create Inbox"** for Instagram.
2. App redirects to the [Instagram Authorization
URL](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/business-login#embed-the-business-login-url).
3. After authentication, Instagram returns an authorization code.
5. The app exchanges the code for a **long-lived token** (valid for 60
days).
6. Tokens are refreshed periodically to maintain access.
7. Once completed, the app creates an inbox and redirects to the
Chatwoot dashboard.

---

## How to Test the Instagram Inbox

1. Create a new app on [Meta's Developer
Portal](https://developers.facebook.com/apps/).
2. Select **Business** as the app type and configure it.
3. Add the Instagram product and connect a business account.
4. Copy Instagram app ID and Instagram app secret
5. Add the Instagram app ID and Instagram app secret to your app config
via `{Chatwoot installation
url}/super_admin/app_config?config=instagram`
6. Configure Webhooks:
   - Callback URL: `{your_chatwoot_url}/webhooks/instagram`
   - Verify Token: `INSTAGRAM_VERIFY_TOKEN`
- Subscribe to `messages`, `messaging_seen`, and `message_reactions`
events.
7. Set up **Instagram Business Login**:
   - Redirect URL: `{your_chatwoot_url}/instagram/callback`
8. Test inbox creation via the Chatwoot dashboard.


## 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.
---


## To-Do List

- [x] Basic integration setup completed.  
- [x] Enable sending messages via [Messaging
API](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/messaging-api).
- [x] Implement automatic webhook subscriptions on inbox creation.  
- [x] Handle **canceled authorization errors**.  
- [x] Handle all the errors
https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/error-codes
- [x] Dynamically fetch **account IDs** instead of hardcoding them.  
- [x] Prevent duplicate Instagram channel creation for the same account.
- [x] Use **Global Config** instead of environment variables.  
- [x] Explore **Human Agent feature** for message handling.  
- [x] Write and refine **test cases** for all scenarios.  
- [x] Implement **token refresh mechanism** (tokens expire after 60
days).
Fixes https://github.com/chatwoot/chatwoot/issues/10440

---------

Co-authored-by: Sivin Varghese <64252451+iamsivin@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Co-authored-by: Shivam Mishra <scm.mymail@gmail.com>
2025-04-08 10:47:41 +05:30
__mocks__ Feature: Agent Profile Update with avatar (#449) 2020-02-16 17:20:38 +05:30
.circleci fix: Corepack pnpm issue (#10840) 2025-02-05 10:12:29 -08:00
.dependabot Add Dependabot config (#217) 2019-11-25 09:48:11 +05:30
.devcontainer fix: Corepack pnpm issue (#10840) 2025-02-05 10:12:29 -08:00
.github chore: Update readme (#11154) 2025-03-21 18:14:51 -07:00
.husky chore: Update translations, add pnpm sync:i18n command (#10893) 2025-02-12 17:43:46 -08:00
.vscode feat: Add the option for consent form (#6511) 2023-02-28 13:57:05 +05:30
app feat: Instagram Inbox using Instagram Business Login (#11054) 2025-04-08 10:47:41 +05:30
bin chore: Update translations, add pnpm sync:i18n command (#10893) 2025-02-12 17:43:46 -08:00
clevercloud feat: Add support for Clever cloud deployments (#1703) 2021-01-29 17:08:40 +05:30
config chore: Clean up report & knowledge base policies (#11234) 2025-04-03 16:00:32 -07:00
db chore: Clean up report & knowledge base policies (#11234) 2025-04-03 16:00:32 -07:00
deployment chore: bump up cwctl version to 3.2.0 (#10850) 2025-02-06 17:44:18 +05:30
docker fix: Corepack pnpm issue (#10840) 2025-02-05 10:12:29 -08:00
enterprise feat: Instagram Inbox using Instagram Business Login (#11054) 2025-04-08 10:47:41 +05:30
lib feat: use nocookie version of youtube & vimeo for help center embeds (#11061) 2025-03-12 10:32:25 +05:30
log Initial Commit 2019-08-14 15:18:44 +05:30
public feat: Instagram Inbox using Instagram Business Login (#11054) 2025-04-08 10:47:41 +05:30
rubocop fix: Add custom rubocop rules for email fetch (#8987) 2024-02-23 11:58:02 -08:00
spec feat: Instagram Inbox using Instagram Business Login (#11054) 2025-04-08 10:47:41 +05:30
swagger chore: Add Swagger endpoint for updating custom attributes (#10995) 2025-02-27 16:57:25 -08:00
theme revert: Next bubble improvements (#10795) 2025-01-29 20:04:45 -08:00
tmp Initial Commit 2019-08-14 15:18:44 +05:30
vendor feat: Sentiment model download and upload to vendor (#7526) 2023-07-18 12:17:50 +05:30
.all-contributorsrc [docs] Move contributors section to docs (#120) 2019-10-06 09:23:24 +05:30
.browserslistrc Initial Commit 2019-08-14 15:18:44 +05:30
.bundler-audit.yml chore: mitigate CVE-2021-41098 (#3101) 2021-09-28 19:34:11 +05:30
.codeclimate.yml feat(ee): Add Captain features (#10665) 2025-01-14 16:15:47 -08:00
.dockerignore chore: add build id to settings page (#6873) 2023-04-18 00:35:35 +05:30
.editorconfig fix: Update .editorconfig to fix spaces and indent_style (#5612) 2022-10-12 14:00:42 -07:00
.env.example feat: move Linear config to installation_config (#10999) 2025-02-28 14:20:27 +05:30
.eslintrc.js feat: setup eslint for vue-i18n (#10889) 2025-02-27 16:53:57 +05:30
.gitignore chore(refactor): Improve conversation permission filtering (#11166) 2025-03-31 19:30:02 -07:00
.nvmrc chore: Upgrade Node.js to v20 (#7759) 2023-08-28 19:20:35 +05:30
.prettierrc chore: Execute campaigns based on matching URL (#2254) 2021-05-17 21:38:35 +05:30
.rspec Fix url in emails, add frontendURL helper (#19) 2019-08-25 19:59:28 +05:30
.rubocop.yml fix: Add custom rubocop rules for email fetch (#8987) 2024-02-23 11:58:02 -08:00
.ruby-version chore: Upgrade ruby to 3.3.3 (#9664) 2024-07-05 12:20:07 +05:30
.scss-lint.yml feat(apps): Shopify Integration (#11101) 2025-03-19 15:37:55 -07:00
.slugignore chore: Upgrade to Rails 7 (#6719) 2023-05-06 10:44:52 +05:30
app.json chore(heroku): Switch heroku stack to the latest stack heroku-24 (#10085) 2024-12-02 18:53:59 -08:00
Capfile 🚨Fix Rubocop lint errors 2019-10-20 14:17:26 +05:30
CODE_OF_CONDUCT.md General updates and add CODEOWNERS (#3685) 2022-01-05 12:37:22 +05:30
config.ru Initial Commit 2019-08-14 15:18:44 +05:30
CONTRIBUTING.md General updates and add CODEOWNERS (#3685) 2022-01-05 12:37:22 +05:30
crowdin.yml chore: Update Crowdin Config (#7375) 2023-06-23 23:02:55 +05:30
docker-compose.production.yaml feat: switch to postgres docker images with pgvector support (v4.0) (#10658) 2025-01-14 19:45:42 +05:30
docker-compose.test.yaml feat: switch to postgres docker images with pgvector support (v4.0) (#10658) 2025-01-14 19:45:42 +05:30
docker-compose.yaml feat: switch to postgres docker images with pgvector support (v4.0) (#10658) 2025-01-14 19:45:42 +05:30
Gemfile feat: Add support for multi-language support for Captain (#11068) 2025-03-19 18:25:33 -07:00
Gemfile.lock chore(deps): Bump nokogiri from 1.18.3 to 1.18.4 (#11153) 2025-03-24 13:55:45 +05:30
histoire.config.ts feat: Add histoire for component playground (#10256) 2024-10-09 22:10:53 -07:00
LICENSE chore: Update year in LICENSE (#8835) 2024-02-01 15:37:05 +05:30
Makefile fix: Use pnpm in make setup command (#10289) 2024-10-15 12:57:29 -07:00
package.json chore(deps-dev): Bump vite from 5.4.12 to 5.4.15 (#11199) 2025-03-27 21:11:43 -07:00
pnpm-lock.yaml chore(deps-dev): Bump vite from 5.4.12 to 5.4.15 (#11199) 2025-03-27 21:11:43 -07:00
postcss.config.js feat: Vite + vue 3 💚 (#10047) 2024-10-02 00:36:30 -07:00
Procfile chore: add build id to settings page (#6873) 2023-04-18 00:35:35 +05:30
Procfile.dev feat: Vite + vue 3 💚 (#10047) 2024-10-02 00:36:30 -07:00
Procfile.test feat: Vite + vue 3 💚 (#10047) 2024-10-02 00:36:30 -07:00
Rakefile Initial Commit 2019-08-14 15:18:44 +05:30
README.md chore: Update readme (#11154) 2025-03-21 18:14:51 -07:00
SECURITY.md chore: Update SECURITY.md (#10705) 2025-01-16 10:59:33 -08:00
semantic.yml Chore: Update copy on Signup page (#1023) 2020-07-09 16:28:09 +05:30
tailwind.config.js fix: Fix issues in bubble design (#10940) 2025-02-21 09:51:54 +05:30
VERSION_CW feat: support vite build for linux installations(cwctl) (#10231) 2024-10-04 16:50:44 +05:30
VERSION_CWCTL chore: bump up cwctl version to 3.2.0 (#10850) 2025-02-06 17:44:18 +05:30
vite.config.ts feat: Add new sidebar for Chatwoot V4 (#10291) 2024-10-23 18:32:37 -07:00
vitest.setup.js chore: Update buttons in dashboard (#11145) 2025-03-31 17:21:32 -07:00
workbox-config.js [Feature] Add PWA support (#157) 2019-10-18 12:37:09 +05:30

Header light mode Header dark mode

Chatwoot

The modern customer support platform, an open-source alternative to Intercom, Zendesk, Salesforce Service Cloud etc.

Maintainability CircleCI Badge Docker Pull Badge Docker Build Badge Commits-per-month Discord uptime response time Artifact HUB

Deploy Deploy to DO

Chat dashboard dark mode Chat dashboard

Chatwoot is the modern, open-source, and self-hosted customer support platform designed to help businesses deliver exceptional customer support experience. Built for scale and flexibility, Chatwoot gives you full control over your customer data while providing powerful tools to manage conversations across channels.

Captain AI Agent for Support

Supercharge your support with Captain, Chatwoots AI agent. Captain helps automate responses, handle common queries, and reduce agent workload—ensuring customers get instant, accurate answers. With Captain, your team can focus on complex conversations while routine questions are resolved automatically. Read more about Captain here.

💬 Omnichannel Support Desk

Chatwoot centralizes all customer conversations into one powerful inbox, no matter where your customers reach out from. It supports live chat on your website, email, Facebook, Instagram, Twitter, WhatsApp, Telegram, Line, SMS etc.

📚 Help center portal

Publish help articles, FAQs, and guides through the built-in Help Center Portal. Enable customers to find answers on their own, reduce repetitive queries, and keep your support team focused on more complex issues.

🗂️ Other features

Collaboration & Productivity

  • Private Notes and @mentions for internal team discussions.
  • Labels to organize and categorize conversations.
  • Keyboard Shortcuts and a Command Bar for quick navigation.
  • Canned Responses to reply faster to frequently asked questions.
  • Auto-Assignment to route conversations based on agent availability.
  • Multi-lingual Support to serve customers in multiple languages.
  • Custom Views and Filters for better inbox organization.
  • Business Hours and Auto-Responders to manage response expectations.
  • Teams and Automation tools for scaling support workflows.
  • Agent Capacity Management to balance workload across the team.

Customer Data & Segmentation

  • Contact Management with profiles and interaction history.
  • Contact Segments and Notes for targeted communication.
  • Campaigns to proactively engage customers.
  • Custom Attributes for storing additional customer data.
  • Pre-Chat Forms to collect user information before starting conversations.

Integrations

  • Slack Integration to manage conversations directly from Slack.
  • Dialogflow Integration for chatbot automation.
  • Dashboard Apps to embed internal tools within Chatwoot.
  • Shopify Integration to view and manage customer orders right within Chatwoot.
  • Use Google Translate to translate messages from your customers in realtime.
  • Create and manage Linear tickets within Chatwoot.

Reports & Insights

  • Live View of ongoing conversations for real-time monitoring.
  • Conversation, Agent, Inbox, Label, and Team Reports for operational visibility.
  • CSAT Reports to measure customer satisfaction.
  • Downloadable Reports for offline analysis and reporting.

Documentation

Detailed documentation is available at chatwoot.com/help-center.

Translation process

The translation process for Chatwoot web and mobile app is managed at https://translate.chatwoot.com using Crowdin. Please read the translation guide for contributing to Chatwoot.

Branching model

We use the git-flow branching model. The base branch is develop. If you are looking for a stable version, please use the master or tags labelled as v1.x.x.

Deployment

Heroku one-click deploy

Deploying Chatwoot to Heroku is a breeze. It's as simple as clicking this button:

Deploy

Follow this link to understand setting the correct environment variables for the app to work with all the features. There might be breakages if you do not set the relevant environment variables.

DigitalOcean 1-Click Kubernetes deployment

Chatwoot now supports 1-Click deployment to DigitalOcean as a kubernetes app.

Deploy to DO

Other deployment options

For other supported options, checkout our deployment page.

Security

Looking to report a vulnerability? Please refer our SECURITY.md file.

Community

If you need help or just want to hang out, come, say hi on our Discord server.

Contributors

Thanks goes to all these wonderful people:

Chatwoot © 2017-2025, Chatwoot Inc - Released under the MIT License.