Metadata-Version: 2.5
Name: unpaismejor_notification_whatsapp
Version: 8.0.21
Summary: Reusable WhatsApp notifications for Tryton using Evolution API or OpenWA
Project-URL: repository, https://code.unpaismejor.org.do/tryton-do/notification_whatsapp
Author: SOLUTEMA SRL, Fundación Un País Mejor
Maintainer: Fundación Un País Mejor
License-Expression: GPL-3.0-or-later
License-File: COPYRIGHT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Framework :: Tryton
Classifier: Topic :: Office/Business
Requires-Python: >=3.10
Requires-Dist: trytond-account-invoice<8.1,>=8.0
Requires-Dist: trytond<8.1,>=8.0
Provides-Extra: test
Requires-Dist: proteus<8.1,>=8.0; extra == 'test'
Requires-Dist: trytond-company<8.1,>=8.0; extra == 'test'
Requires-Dist: trytond-party<8.1,>=8.0; extra == 'test'
Description-Content-Type: text/x-rst

Notification WhatsApp
=====================

Tryton 8.0 module for reusable WhatsApp templates with selectable Evolution
API v2 and OpenWA providers.

Features
--------

* Genshi templates bound to any Tryton model.
* Recipient fields or PYSON expressions with phone normalization.
* Any number of ``ir.action.report`` documents attached to a template.
* Trigger and Tryton worker queue integration.
* Auditable text/document outbox and Evolution message identifiers.
* Manual sending from its menu and from the invoice form action.
* Independent attachment retries and idempotency keys.
* Authenticated delivery/read status webhook.
* Evolution API v2 and OpenWA 0.23 integrations; n8n is optional.

Core compatibility
------------------

The module does not inherit the ``ir.email.template`` SQL model because doing
so would mix email-specific recipients, subject and SMTP fields with WhatsApp
records. Instead it follows the same composition used by
``notification_email``:

* template context, PYSON evaluation, recipient models and languages are
  delegated dynamically to ``ir.email.template``;
* documents are standard ``ir.action.report`` records and are executed using
  the same result contract as notification email attachments;
* ``ir.trigger`` actions and delayed jobs use Tryton's native queue proxy;
* the outbox uses ``ResourceAccessMixin`` like the core ``ir.email`` log;
* ``whatsapp_models``, ``_get_number``, ``get_provider`` and report ``get``
  are stable extension hooks for optional modules.

Installation
------------

Install the package, update the Tryton module list and activate
``Notification WhatsApp``. Configure the provider, endpoint, instance/session
and API key under ``WhatsApp > Configurations``. Existing configurations are
treated as Evolution API configurations, so upgrading does not change their
delivery behavior. Keep the API key restricted to the WhatsApp Administration
group.

Providers
---------

Evolution API v2 is the backward-compatible default. It uses::

    POST /message/sendText/{instance}
    POST /message/sendMedia/{instance}
    apikey: API_KEY

OpenWA 0.23 uses::

    POST /api/sessions/{sessionId}/messages/send-text
    POST /api/sessions/{sessionId}/messages/send-document
    X-API-Key: API_KEY

For OpenWA, enter the OpenWA session ID in *Instance / Session*. The session
must already exist, be paired and have state ``ready``. The module appends
``@c.us`` to normalized individual phone numbers and sends documents as base64.
It does not create, start or pair OpenWA sessions.

Webhooks
--------

Both providers send status events to the same Tryton route::

    https://TRYTON_HOST/DATABASE/notification-whatsapp/webhook

For Evolution API enable ``MESSAGES_UPDATE`` and add the configuration secret
as a custom ``X-Webhook-Secret`` header. Accepted statuses are ``PENDING``,
``SERVER_ACK``, ``SENT``, ``DELIVERY_ACK``, ``DELIVERED``, ``READ``, ``PLAYED``,
``ERROR`` and ``FAILED``.

For OpenWA register a webhook on the configured session with the events
``message.sent``, ``message.ack`` and ``message.failed``. Set its ``secret`` to
the same *Webhook Secret* stored in Tryton. OpenWA signs the exact JSON bytes as
``X-OpenWA-Signature: sha256=<hex>``; Tryton rejects unsigned, altered or
incorrectly signed requests. Do not configure OpenWA without a webhook secret.
For example::

    POST /api/sessions/{sessionId}/webhooks
    X-API-Key: API_KEY
    Content-Type: application/json

    {
      "url": "https://TRYTON_HOST/DATABASE/notification-whatsapp/webhook",
      "events": ["message.sent", "message.ack", "message.failed"],
      "secret": "THE_SAME_TRYTON_WEBHOOK_SECRET",
      "retryCount": 5
    }

The Tryton endpoint returns ``200 {"updated": true}`` for a matched message,
``200 {"updated": false}`` for a valid event whose message is unknown, ``400``
for an unsupported payload and ``403`` for failed authentication. Delivery
events may be retried or arrive out of order; updates are idempotent and never
regress a message from read/delivered to an earlier state. ``DELIVERY_ACK`` or
OpenWA ``delivered`` fills *Delivered At*. ``READ``/``PLAYED`` or OpenWA
``read`` fills both *Delivered At* and *Read At* when necessary.

Only outbound delivery receipts are consumed. Incoming messages, QR codes,
session status, reactions and group events are intentionally ignored.

Administrators are automatically assigned to both the
WhatsApp Administration and WhatsApp Sender groups. Regular operators must be
assigned to WhatsApp Sender explicitly.

Security notes
--------------

Use HTTPS and keep certificate verification enabled. Use separate, restricted
API keys for Tryton, random webhook secrets of at least 32 bytes and rotate
them when access changes. Evolution and OpenWA use different webhook
authentication schemes and they are never accepted interchangeably. OpenWA's
unofficial WhatsApp engines carry a non-zero account restriction risk; use a
dedicated opted-in number and an official Cloud API path for regulated or
business-critical messaging.
