OdooWiki OCA HUB

Mail Instagram Gateway

mail_gateway_instagram folder_open OCA/social open_in_new
Uncategorised License: AGPL-3

This module connects Odoo Discuss to Instagram Direct Messages through OCA mail_gateway. Incoming DMs become gateway channels; replies from Discuss are sent back as Instagram text messages.

auto_awesome What this module does

AI-generated from the code · Odoo 18.0

Connects Odoo Discuss to Instagram Direct Messages: incoming Instagram messages appear as chat channels, and replies typed in Odoo are sent back to the Instagram user as text messages.

This module adds Instagram as a new gateway type on the gateway configuration screen. When you choose Instagram, extra fields appear: a security key (verify token), the Instagram professional account ID, and the Graph API version (default 26.0). A dedicated "Instagram configuration" tab shows the webhook URL and step-by-step setup instructions.

Once configured and the webhook is integrated, incoming Instagram Direct Messages are turned into Discuss channels. Each sender is identified by their Instagram ID; Odoo tries to fetch the person's profile name and username, and falls back to the ID if that fails. The channel is named after the sender and gets an Instagram-style avatar.

  • Text messages become chat messages in the channel.
  • Images, videos, audio and files are downloaded and attached to the message, with a 25 MB size limit.
  • Links to posts, reels and stories are added as clickable links.
  • Echoes of your own messages and deleted messages are ignored.
  • Messages are timestamped with the original Instagram send time.

When you reply in Discuss, the plain text is sent back to the Instagram user through the Instagram messaging API. If sending fails, the message is marked with an exception and the failure reason is recorded. The webhook handshake is verified with the security key, and incoming calls are checked with a signature based on the webhook secret.

Depends on

mail_gateway
Models and fields (2)
  • mail.gateway · extends an existing modelgateway_type, instagram_version, instagram_account_id, instagram_security_key
  • mail.gateway.instagram · new model

Text generated by AI (DeepSeek) from reading the Odoo 18.0 code on GitHub; it may contain mistakes, so check the code before deciding. View the code on GitHub

Availability by version

Reviewed: 2026-11-03
Confirmed (verified in repository and branch) Estimated (unverified) No information

Confirmation status: 1 confirmed, 8 with no information of 9 versions.

terminal Installation and usage

OCA documentation · Odoo 18.0

Configuration

Source · Odoo 18.0

The connector uses the Instagram API with Instagram Login (graph.instagram.com). Facebook-Login / Page-scoped Instagram is not supported.

Meta app

IMPORTANT — publish the Meta app (Live mode). Webhook verification can succeed while the app is still in Development, but Instagram Direct Messages are not delivered to Odoo until the app is published (switched to Live). Without Live mode you will see an integrated webhook and no inbound POSTs, and no Discuss channels. Do this before expecting real DMs to work. App Review / Advanced Access is also required for permissions that serve Instagram accounts the app does not own.

  • Use an Instagram professional account (Business or Creator).
  • Create a Meta app at developers.facebook.com/apps and add the Instagram Login product.
  • Request instagram_business_basic and instagram_business_manage_messages. Advanced Access is required to serve Instagram accounts the app does not own.
  • Publish the app (Development → Live). This step is mandatory for messaging delivery; skip it and inbound DMs will never arrive.

Odoo gateway

  • Enable developer mode, then go to Settings > Technical > Email > Gateway. (Technical is visible only in the developer mode.)
  • Create a gateway of type Instagram.
  • Fill in:
  • Token: Instagram user access token (sent as Authorization: Bearer).
  • Webhook Secret: Meta app secret (HMAC key for X-Hub-Signature-256). Copy it from the Meta app Settings > Basic > App Secret.
  • Instagram Security Key: a string you choose. You will enter the same value in Meta as the webhook verify token (hub.verify_token).
  • Instagram Account: professional account IGID used in the send URL.
  • Instagram Version: Graph API version without the v prefix (default 26.0).
  • Webhook Key: URL path segment of your choice. It becomes part of the webhook URL.
  • Webhook User: user that creates inbound messages.
  • Members: Discuss users who join new conversations.
  • Save. Webhook Key and Webhook User must be set or the Integrate Webhook button stays hidden.
  • Press Integrate Webhook on the gateway form (header). The state becomes pending. Meta's verification GET is only accepted in this state.
  • Open the Instagram configuration tab on the same form. Copy Webhook URL. Odoo builds it as https://<your-odoo-host>/gateway/instagram/<webhook_key>/update. You do not get this URL from Meta.

The same Webhook URL field on the main form group is visible only in the developer mode. Use the tab; that copy is for operators.

Meta webhook

  • In the Meta app, open the Instagram Login product's webhook / callback settings.
  • Callback URL: paste the Webhook URL copied from Odoo.
  • Verify token: paste the same string as Instagram Security Key.
  • Subscribe the messages field only.
  • Meta sends a GET to Odoo. On success the gateway state becomes integrated.

The webhook endpoint must be publicly reachable over HTTPS. Self-signed certificates are not accepted by Meta.

24-hour messaging window

Instagram only allows the professional account to message a user after that user has messaged it, and only for 24 hours after the user's last message. Replies from Discuss outside that window are rejected by Meta. Anything that must be sent later has to go through another channel. A human-agent tag that extends the window is listed on the module roadmap and is not implemented here.

Usage

Source · Odoo 18.0

Incoming Instagram Direct Messages appear as Discuss channels of type gateway. The sender is a mail.guest until a user promotes them to a partner from the followers menu.

Replies typed in that Discuss channel are delivered as Instagram DMs (text only). Messages the professional account sends from the Instagram app are not duplicated into the channel.

Shares, story mentions and reels arrive as links in the message body, not as downloaded files. Images, videos, audio and files are downloaded and attached to the Discuss message.

No verified information in OCA: Installation.

info

Data imported from GitHub: this sheet reflects the latest catalog review, not a live lookup. Always check the module documentation and staging before installing in production.