unpaismejor-notification-whatsapp (8.0.21)
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 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.