unpaismejor-notification-whatsapp (8.0.22)
Installation
pip install --index-url https://code.unpaismejor.org.do/api/packages/tryton-do/pypi/simple/ --extra-index-url https://pypi.org/simple unpaismejor-notification-whatsappAbout this package
Reusable WhatsApp notifications for Tryton using Evolution API or OpenWA
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.reportdocuments 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.reportrecords and are executed using the same result contract as notification email attachments; ir.triggeractions and delayed jobs use Tryton's native queue proxy;- the outbox uses
ResourceAccessMixinlike the coreir.emaillog; whatsapp_models,_get_number,get_providerand reportgetare stable extension hooks for optional modules.
Installation
Install the package, update the Tryton module list and activate
Notification WhatsApp. Configure each provider endpoint, instance/session
and API key under WhatsApp > Configurations. Multiple Evolution API and
OpenWA configurations may be active concurrently, but exactly one should be
marked as Default. Existing configurations are treated as Evolution API and
remain the fallback default after upgrading, so their delivery behavior does
not change. Keep API keys restricted to the WhatsApp Administration group.
Select a Provider Configuration on each WhatsApp template. A template left blank uses the default. The chosen configuration is copied to every outbox message before it is queued; changing the template or the default later never reroutes an already queued message through a different provider. A referenced configuration cannot be deleted, preserving the audit history.
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
Use the isolated route containing the provider and Tryton configuration ID::
https://TRYTON_HOST/DATABASE/notification-whatsapp/webhook/PROVIDER/CONFIGURATION_ID
For example::
https://tryton.example.com/demo/notification-whatsapp/webhook/evolution/3
https://tryton.example.com/demo/notification-whatsapp/webhook/openwa/7
The historic route below remains available and resolves only the default configuration. It should be retained solely while migrating an existing Evolution installation::
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/openwa/CONFIGURATION_ID",
"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.
Each isolated route accepts only its configured provider's authentication and updates only messages assigned to that configuration. This prevents equal message IDs or secrets on two platforms from crossing tenant boundaries.
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.