Metadata-Version: 2.1
Name: odoo-addon-mail_gateway_instagram
Version: 18.0.1.0.0.2
Requires-Python: >=3.10
Requires-Dist: odoo-addon-mail_gateway==18.0.*
Requires-Dist: odoo==18.0.*
Summary: Set a gateway for Instagram Direct Messages
Home-page: https://github.com/OCA/social
License: AGPL-3
Author: Cetmix, Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 18.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Description-Content-Type: text/x-rst

.. image:: https://odoo-community.org/readme-banner-image
   :target: https://odoo-community.org/get-involved?utm_source=readme
   :alt: Odoo Community Association

======================
Mail Instagram Gateway
======================

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:1907f6d226e01f0331f46f14712f67da339fd501ec9650a7652f066e5dca9f6e
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fsocial-lightgray.png?logo=github
    :target: https://github.com/OCA/social/tree/18.0/mail_gateway_instagram
    :alt: OCA/social
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/social-18-0/social-18-0-mail_gateway_instagram
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
    :target: https://runboat.odoo-community.org/builds?repo=OCA/social&target_branch=18.0
    :alt: Try me on Runboat

|badge1| |badge2| |badge3| |badge4| |badge5|

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.

**Table of contents**

.. contents::
   :local:

Configuration
=============

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.

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

Odoo gateway
------------

1. Enable developer mode, then go to Settings > Technical > Email >
   Gateway. (Technical is visible only in the developer mode.)
2. Create a gateway of type **Instagram**.
3. 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.

4. Save. **Webhook Key** and **Webhook User** must be set or the
   **Integrate Webhook** button stays hidden.
5. Press **Integrate Webhook** on the gateway form (header). The state
   becomes ``pending``. Meta's verification GET is only accepted in this
   state.
6. 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
------------

1. In the Meta app, open the Instagram Login product's webhook /
   callback settings.
2. Callback URL: paste the **Webhook URL** copied from Odoo.
3. Verify token: paste the same string as **Instagram Security Key**.
4. Subscribe the **``messages``** field only.
5. 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
=====

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.

Known issues / Roadmap
======================

- Outbound attachments / media upload.
- Quick replies, icebreakers and the persistent menu.
- HUMAN_AGENT tagging to reply after the 24-hour window: send
  ``messaging_type=MESSAGE_TAG`` with ``tag=HUMAN_AGENT``. Meta
  documents this on the Page Messages API; only ``HUMAN_AGENT`` is
  available for Instagram Messaging, and the message may be sent within
  7 days of the customer's last message. Not implemented in 1.0.
- Message reactions, read receipts, and the standby / handover protocol.
- Facebook-Login Instagram (``graph.facebook.com``).

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/social/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/social/issues/new?body=module:%20mail_gateway_instagram%0Aversion:%2018.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
-------

* Cetmix

Contributors
------------

- Cetmix OÜ https://cetmix.com

Maintainers
-----------

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

This module is part of the `OCA/social <https://github.com/OCA/social/tree/18.0/mail_gateway_instagram>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
