Messaging
Jump to
↵select↑↓navigateescclose

Messaging App

On this page

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 / Newsletter Manager).

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 ensures parity with messaging membership.

  • Validation commits only when necessary; avoids redundant Twilio lookups.

  • 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.