Skip to content

README.md

Latest commit

 

History

History
140 lines (99 loc) · 5.45 KB

README.md

File metadata and controls

140 lines (99 loc) · 5.45 KB
Raw

Messaging App

Messaging app for Frappe/ERPNext: Twilio SMS with an inbound webhook and consent handling, group texts, newsletters with merge tags, and a chat-style unified inbox for email and SMS.

Features

  • Chat Interface: Modern, real-time chat view for all Communications (Email & SMS) powered by vue-advanced-chat
  • Twilio SMS inbound webhook (creates Communication records).
  • Group Text Message doctype (broadcast to validated primary mobile numbers with SMS consent).
  • Automatic phone number normalization (E.164), deduplication, and optional Twilio carrier/type validation.
  • Contact consent flag (consent_sms) to control outbound SMS eligibility.
  • Messaging Groups with automatic dynamic linking to Contacts and optional synchronization to an Email Group.
  • Newsletter override supporting merge tags: {{first_name}}, {{last_name}}, {{full_name}}, {{company_name}}, {{designation}}, {{gender}}, {{salutation}}.
  • Workspace shortcuts for rapid access.

Chat Interface

The messaging app includes a modern chat-like interface for viewing and responding to all Communications:

  • Unified inbox for Email and SMS messages
  • Real-time message updates
  • Dark mode support
  • Contact integration
  • File attachments
  • Search and filtering

See docs/chat.md for detailed documentation.

Quick Start

After installation, navigate to Communication in Frappe desk. The default view is now the Chat interface. Use the medium filter to show Email, SMS, or all messages.

Installation

  1. Fetch app into your bench: bench get-app https://github.com/Avunu/messaging
  2. Install: bench --site install-app messaging
  3. Build frontend: bench build --app messaging
  4. Migrate: bench migrate

Configuration

  1. Open Messaging Settings:
    • Set "Messaging Group for All Contacts" (optional auto-enroll on creation).
    • (Optional) Enable Phone Number Validation.
    • Enter Twilio Account SID, Auth Token (Password field), and Twilio Phone Number.
  2. Ensure System Settings country is set (used for number parsing).
  3. Create Messaging Groups (optionally link an Email Group).
  4. Grant appropriate roles: System Manager (or Inbox User, see the chat's access rules) for the chat, Newsletter Manager for newsletters and group texts.

Twilio Inbound Webhook

Endpoint: /api/method/messaging.messaging.api.twilio_webhook.sms

  • Validates X-Twilio-Signature.
  • Creates a Communication (sent_or_received = Received).
  • Returns HTTP 204 on success.
  • Handles SMS consent keywords from known contacts: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END and QUIT clear consent_sms and set unsubscribed; START, YES and UNSTOP restore consent.

Outbound Group SMS

  1. Create Group Text Message.
  2. Select target Messaging Groups; optionally exclude groups.
  3. (Optional) Schedule with future Delivery Date/Time.
  4. Submit:
    • If scheduled: status = Scheduled.
    • Else: message sent immediately via SMS Settings (send_sms).

Sending logic filters:

  • Contact in included groups.
  • Not in excluded groups.
  • consent_sms == 1.
  • Has a primary mobile (is_primary_mobile_no == 1) that is validated (is_valid == 1).

Phone Number Processing

Hook: Contact.validate in messaging.messaging.custom.contact (registered through extend_doctype_class)

  • Deduplicate emails and phones.
  • Convert to E.164 using phonenumbers library (country fallback: Address country → System Settings).
  • Optional Twilio Lookup (line_type_intelligence) sets is_valid + carrier_type.
  • Auto-select primary phone/mobile if missing or invalid.

Newsletter Merge

Override class adds contact-aware rendering:

  • Each recipient resolved through Contact Email → Contact.
  • If no contact, falls back to inferred full_name (local-part of email).
  • Merge tags inserted via Jinja evaluation.

Data Models (Highlights)

  • Messaging Group: members (Table MultiSelect of Messaging Group Member).
  • Group Text Message: target groups + exclude groups.
  • Contact custom fields: consent_sms.
  • Contact Phone custom fields: is_valid, validated_number, carrier_type.

Workflows

Contact creation:

  • Optionally added to “All Contacts” Messaging Group. Inbound SMS:
  • Creates Communication marked Open. Group broadcast:
  • Adds descriptive comment listing recipient count.

Developer Notes

  • Dynamic Link used to associate Messaging Groups to Contacts.
  • Email Group synchronization adds each member's contact to the linked Email Group; it never removes the Email Group's own subscribers.
  • Deleting a Messaging Group (from its form or the list) asks whether to delete its linked Email Group too; by default the Email Group is kept. Deleting it needs delete permission on Email Group.
  • Validation avoids redundant Twilio lookups: a number already validated is not looked up again.
  • Error handling logs Twilio lookup issues without blocking save.

Security

  • Twilio webhook enforces signature validation.
  • Auth Token stored as Password (masked).
  • SMS sending restricted to consented + validated contacts.

Extensibility

  • Add new merge tags by extending Newsletter.get_contact_map or template context.
  • Integrate alternative SMS providers by replacing send_sms in GroupTextMessage.

Troubleshooting

  • No SMS sent: verify consent_sms, primary mobile flag, validation enabled, correct Twilio credentials.
  • Numbers not validated: ensure enable_number_validation is checked and credentials valid.
  • Merge tags blank: recipient not matched to a Contact record.

License

MIT. See license.txt.