| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
CRM (crm)
• Discuss (mail) • Calendar (calendar) • Contacts (contacts) |
| Community Apps Dependencies | Show |
| Lines of code | 6223 |
| Technical Name |
us_instagram_messenger |
| License | OPL-1 |
| Website | https://unitsoft.com.ua/ |
| Versions | 18.0 19.0 |
| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
CRM (crm)
• Discuss (mail) • Calendar (calendar) • Contacts (contacts) |
| Community Apps Dependencies | Show |
| Lines of code | 6223 |
| Technical Name |
us_instagram_messenger |
| License | OPL-1 |
| Website | https://unitsoft.com.ua/ |
| Versions | 18.0 19.0 |
Instagram Messaging Integration powered by UnitSoft
Communicate with Instagram Direct users directly within Odoo
Features
1. Convenient communication in Odoo
Chat with your Instagram Direct customers directly in Discuss. Get more options for working with leads, partners, and session statuses.
2. Easy Bot Creation
Connect any Instagram Business or Creator account to Odoo using your own Meta App. Multiple accounts can run side by side from the same Odoo instance.
3. Interaction Flows
Build your own communication flow with users using scripts with step-by-step logic. Collect email and phone via free-text input, and offer multiple-choice answers with native Instagram quick replies.
4. Chatter
Send and receive Instagram Direct messages directly from the chatter of any Odoo document (Leads, Orders, etc.).
5. Operator Management
Monitor operator activity, follow specific channels, and manage agent workloads efficiently.
6. Customer Session Tracking
Track all client sessions, bot interactions, and operator responses in a centralized history.
7. Private Replies to Comments
When a customer leaves a comment under your Instagram post or Reel, the integration creates a Discuss channel with the commenter, surfaces the comment text with a link to the original post, and routes the conversation to an available operator. The operator's first reply is delivered as an Instagram Private Reply — opening a Direct conversation with the customer in one tap.
Step-by-Step Instruction
1. Creating a Meta App
Each business connects its own Instagram Business or Creator account through its own Meta App. The Instagram Messaging API is a Meta product, so the App and the Instagram account must be set up directly in the Meta developer dashboard before Odoo can connect to them.
Before we begin
To implement the Instagram Messaging API, you need:
- A registered Meta developer account (https://developers.facebook.com/docs/development/register)
- A Meta app with the Instagram use case (https://developers.facebook.com/docs/development/create-an-app)
- An Instagram Business or Creator account connected to your app (https://help.instagram.com/502981923235522)
- Business Verification (if your app is used by people without a Role on the app) (https://developers.facebook.com/docs/development/release/business-verification)
- App Review (if your app needs Advanced Access). Not required if you only send and receive messages for your own Instagram account (https://developers.facebook.com/docs/resp-plat-initiatives/individual-processes/app-review)
App creation steps
After creating your developer account, you can move on to creating an App. Navigate to https://developers.facebook.com/apps/creation/ to begin the app creation process — the wizard walks you through six stages:
Navigate to https://developers.facebook.com/apps/creation/ to begin the app creation process.
Enter your app's name and a contact email address. Click Next.
Select one or more use cases for your app. For this integration choose the Instagram messaging use case. You can add additional, compatible use cases now or at any time during development. Incompatible use cases are greyed out. Some products, such as Facebook Login for Business or Webhooks, might be automatically included in your use case. If you need a use case not listed, select Other and follow the instructions in the Other App Types guide. Click Next.
Select an option: a verified business portfolio, an unverified business portfolio, or "I don't want to connect a business portfolio yet". To create a business portfolio, add your information in the pop-up. You can submit your business portfolio for verification now (Meta's Business Manager will open in a new browser window) or later. When complete, return to the dashboard and select your new business portfolio. Click Next.
Your app might need to complete certain requirements, such as App Review, to get and maintain data access for your app's use cases. Click Next.
Review your app's details, use cases, connected business, and requirements. If you need to make any changes, you can click App details, Use cases, Business, or Requirements at the top of the page or the Previous button in the lower-right. You can also review the Meta Platform Terms and Developer Policies by following the links at the bottom of the page. Click Go to dashboard to finalize the app creation process. You are redirected to the dashboard and can now customize each use case you've selected for your app.
- Instagram Messaging API Overview (https://developers.facebook.com/docs/messenger-platform/instagram/)
- Get Started — official step-by-step App creation walkthrough (https://developers.facebook.com/docs/messenger-platform/instagram/get-started/)
Permissions and features
In the Permissions and Features section, you need to set certain permissions.
Here is a list of the permissions you need to enable:
- instagram_business_basic
- instagram_business_manage_messages
- instagram_business_manage_comments
Connect Instagram account
In the Instagram API Settings section, you need to connect your Instagram Business or Creator account and subscribe to the instagram object's webhook fields: messages, message_reactions, comments.
2. Module Deployment
To ensure messengers work correctly in your system, you need to have the following modules: us_messenger and us_instagram_messenger.
Deployment Instructions
Please note that installing these modules through the standard Odoo interface (Apps → Import Module) will not work for the initial setup.
The correct way to install these modules is as follows:
- Upload the module folders directly to your server's custom addons directory.
- Restart the Odoo service via terminal to allow the system to detect the new files.
3. Module Activation
After installing the module, navigate to Apps menu and search for "Instagram Messaging Integration". Click Activate to activate the module in your Odoo instance.
4. Creating a New Bot
Once all the necessary modules are activated, we can create a bot in our system. Go to the Messengers menu and click the New button in the upper-left corner. Now we see the form for a new bot. To launch and continue working with the bot, you need to fill in the basic bot fields:
The type of bot you are creating. In our case, you need to select Instagram Messenger. If you are using integration modules with other messengers, there may be other options here.
Insert the Instagram Access Token generated directly from the Instagram Business or Creator account page (Settings and privacy → Apps and websites → Instagram API with Instagram Login → Generate token), authorising the integration to send and receive messages on behalf of that Instagram account. It typically starts with IGA....
The App Secret from the Meta App dashboard. Used to verify the X-Hub-Signature-256 header of every incoming webhook so that a third party cannot forge events. Strongly recommended in production.
A random secret generated automatically or you can write your own. Copy it as-is into the Verify Token field of the Instagram webhook configuration in the Meta App dashboard — Meta uses it during the initial subscription handshake.
Read-only URL generated for this bot. Paste it into the Callback URL field of the Instagram webhook configuration in the Meta App dashboard. The URL must be reachable over HTTPS.
In this field, you can select a script with specific steps for user interaction with the bot. In the script, you can configure the receipt of email, phone number, connection to the operator, as well as sending quick reply buttons. If you leave this field blank, an available operator will be added to the channel with the user, without any intermediate steps.
An optional field for storing a link to the Instagram account profile or DM entry point, useful if many bots are used in the system.
In the Operators section, you can specify system users among whom an automatic search for an available operator will be performed. Then, such a user is added to the channel with the client for further communication. The Priority field allows you to control the selection of available operators. A user with a higher priority will only be selected if all other operators with a lower priority already have more than 5 open channels, or if there are no available operators. The User nickname field should be highlighted separately. The bot settings allow you to sign the author's name in messages that will be sent to the client. In User nickname, you can write the signature that you want your clients to see. If the field is empty, the user's name will be used.
5. Other Useful Parameters
Great, we've filled in all the important fields, now let's take a look at the other bot settings in Parameters page:
When executing script steps, the messenger user's language is taken into account in order to correctly determine the language of the text steps. Sometimes users may have a language that is not activated in our system, in which case the default language from this field will be selected.
If enabled, the author's name will be added at the end of the message, so the messenger client will better understand who they are communicating with.
Template for creating a channel name in Discuss. Consists of the messenger username and bot name.
Determines whether bot operators can assign channels where they are defined by the operator to other operators. If disabled, only the administrator can change the operator.
If enabled, when a messenger user sends a message (without explicit reply) and the last message in the channel was from a document chatter, the message will be duplicated to that document's chatter.
Enable this only after Meta has granted the human_agent permission to your App through App Review. The integration uses HUMAN_AGENT to deliver replies sent more than 24 hours after the user's last inbound message. When this flag is OFF and a message is being sent outside the 24-hour Instagram messaging window, the send is blocked and a warning is posted into the channel — the user simply will not receive that message until they write to the account again.
6. Webhook Configuration in Meta App
Before you click Run Now, the Meta App must know where to deliver events. In the Meta App dashboard:
- Go to Webhooks and select the instagram object.
- Paste the Callback URL generated by Odoo.
- Paste the Verify Token shown on the Odoo bot form.
- Click the Verify and Save button.
- Subscribe to the following webhook fields: messages, message_reactions, comments.
- Instagram Messaging — Webhooks Setup (https://developers.facebook.com/docs/messenger-platform/instagram/features/webhook/)
With the webhook saved on the Meta App side, return to Odoo and click the Run Now button on the bot form. This subscribes the Instagram account to the Meta App, after which Instagram starts delivering events to your Callback URL. If everything was set up correctly, a notification confirming the successful bot launch should appear in the upper corner of the screen.
7. App Review & Production Mode
While the Meta App is in Development mode, the bot can only exchange messages with users who have an explicit role in the App (Admin, Developer, Tester). Profile data of any other Instagram user comes back empty — in that case the integration creates the partner under the placeholder name Instagram User #<IGSID>.
To start serving real customers you must switch the App to Live mode and pass App Review for the following Meta permissions:
Mandatory. Grants read access to the Instagram Business / Creator account profile and user information used for partner creation and channel display.
Mandatory. Without Advanced Access on this permission, the bot can write only to App role users. After approval, the Instagram account can converse with any user that opens a conversation.
Required to receive the comments webhook and to send a Private Reply to a commenter (via recipient.comment_id) within the 7-day window after the comment was created.
Optional but strongly recommended for support workflows. Enables the only currently allowed message tag (HUMAN_AGENT) and extends the response window from 24 hours to 7 days.
8. User Interaction With The Bot
At this stage, Instagram users can already contact our bot via Direct. Here's what interaction with the bot looks like from the client's side in Instagram and the operator's side in Odoo.
As we can see, the client has reached the step of connecting with an operator, so the system searched for an available operator, which turned out to be Mitchell Admin, and added him to the channel. Once the operator has communicated with the client, he can click the End Session button, after which the operator will be removed from the channel, and the client will continue to the next step of the script.
9. 24-hour Session Banner
Above each Instagram channel a coloured banner shows the current state of the Instagram messaging session for that user.
- Grey — no inbound message yet, the session has not been opened.
- Green — session is active; the absolute end time is shown in the operator's timezone.
- Red — the 24-hour window has expired; only HUMAN_AGENT replies are deliverable (and only if the corresponding permission is granted).
The banner refreshes automatically when the user writes again — no manual reload is needed.
10. Channel Statuses
Channel statuses are usually accompanied by a color change or the addition of an icon in the Discuss channel list. The operator can change the status depending on the current state of the channel. Options include waiting for a customer response or seeking help, which is used when the operator has added another system user. In this case, the user will see the channel highlighted in blue. Without Operator highlights the channel in orange and is used when no free operator could be found. This may be the case if the request was made outside of working hours and no users were online. In this case, the system adds all operators to the channel, and the first one to come online can click the Become Operator button to become an operator and exclude other operators from the channel.
11. Instagram Scripts
The Instagram Messaging integration module allows you to build scripts with step-by-step interaction between the bot and the customer. Each step of the script is responsible for one message sent to Instagram Direct. After installing the module, you will have a demo script so that you can better familiarize yourself with the work and capabilities of scripts.
12. Step Types
Each step has its own type and defines the logic of interaction between the bot and the user. Here are the types of steps that will be available in the Instagram script:
Sending a regular text message. Please note that this step does not require a response from the user, so if you have two text steps in a row, they will both be sent at once.
Receiving customer email. With Apply For Partner enabled, Instagram renders a native one-tap quick reply (user_email) that lets the user share the email from their Instagram profile with a single tap; if the profile has no email, the user types it manually. The integration validates the address and stores it on the partner card. If invalid, the step asks again.
Step is waiting for user input.
Step awaits receipt of the phone number. With Apply For Partner enabled, Instagram renders the native user_phone_number quick reply, so the user can submit their phone in a single tap and the value is saved on the partner card. If the customer's Instagram profile has no phone, the button is hidden and the user types the number manually. Numbers shared via the native button are treated as verified — typed numbers skip cross-partner matching to avoid mismatching the channel with someone else's contact card on a typo.
At this step, a search for an available operator is performed, and they are added to the channel. Note that when the client is at this step, the other steps are not performed, since all text or commands go to the channel with the operator.
A special Instagram step that sends text with attached quick reply buttons. When the user taps an option, we can branch to other steps. This step can be used as a poll or to build branches in the script (up to 13 buttons per message).
13. Script Step Example
Let's look at an example of fields in a step with the Question Selection type:
Required field for each step. Contains text that will be sent to the customer.
The step can send a message about the user's successful response, or vice versa, if the user has entered the wrong answer. The message about the successful completion of the step is optional and can be left blank.
The execution of a step can be linked to a command. Note that the first step of the script must be linked to the /start command.
When a user changes the order of steps or creates new steps in a script, the steps are recalculated to automatically determine the next step for each step. If this field is enabled, the next step will not be determined for the current step.
A special field for a step with the Question Selection type. Answer Text will contain the text in the quick reply button.
If the user has selected an option, we can specify the next step to be taken. It is also possible to create a survey without specifying the next steps in all answer options, in which case the next step specified in the step itself will be performed.
14. Private Replies to Comments
Instagram lets a Business or Creator account answer a comment privately — the reply lands in the commenter's Direct inbox, not under the post. The module ingests the comments webhook and routes such conversations into Discuss exactly like regular DMs, with the comment text and a link to the original post surfaced as the first message in the channel.
Meta allows a Private Reply only within 7 days after the comment was created. After that window the API rejects the call and the customer has to be reached through a regular DM (which requires them to write first).
Only one Private Reply is allowed per comment. The integration uses the first operator message in the channel as that reply (sent via recipient.comment_id). Every subsequent message goes through the standard DM path — and is governed by the usual 24-hour Messaging window unless the customer responds first.
instagram_business_manage_comments. Without it the comments webhook is not delivered and the feature stays silent. Request the permission through Meta App Review together with messaging permissions.
Support
We provide free bug fixes and updates for all our modules for 1 year after purchase.
The warranty is for a clean installation of Odoo.
If you need help, please submit a request through our Support Portal at https://unitsoft.com.ua/support. Our support team, which consists of the developers who created the product, is always ready to help you.
We will not provide support (for free) if our modules do not work on your server or conflict with other modules.
We are ready to consider your requests regarding the functionality of our modules, and if they prove useful, we can take them into account when releasing new versions.
We also provide all types of Odoo support services, such as installing Odoo on your server, maintaining your Odoo server, custom development.
We invite you to familiarize yourself with our support packages here: https://unitsoft.com.ua/services-plan
Our Odoo Apps
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module