PHPackages                             opencoreemr/oce-module-sinch-conversations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. opencoreemr/oce-module-sinch-conversations

ActiveOpenemr-module[Utility & Helpers](/categories/utility)

opencoreemr/oce-module-sinch-conversations
==========================================

OpenEMR Sinch Conversations integration module for HIPAA-compliant patient messaging, by OpenCoreEMR Inc

1.3.2(3w ago)06.6k↓31.4%[15 issues](https://github.com/openCoreEMR/oce-module-sinch-conversations/issues)[1 PRs](https://github.com/openCoreEMR/oce-module-sinch-conversations/pulls)GPL-3.0-or-laterPHPPHP >=8.4CI passing

Since Mar 2Pushed 1w agoCompare

[ Source](https://github.com/openCoreEMR/oce-module-sinch-conversations)[ Packagist](https://packagist.org/packages/opencoreemr/oce-module-sinch-conversations)[ Docs](https://opencoreemr.com)[ RSS](/packages/opencoreemr-oce-module-sinch-conversations/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (52)Versions (18)Used By (0)

OpenEMR Sinch Conversations Module
==================================

[](#openemr-sinch-conversations-module)

A HIPAA-compliant, omnichannel patient communication module for OpenEMR using the Sinch Conversations API.

Features
--------

[](#features)

- **📱 Multi-Channel Messaging**: SMS, WhatsApp, RCS, MMS, Viber - all through a unified API
- **🔐 HIPAA-Compliant**: Approved message templates with no PHI in SMS
- **✅ Consent Management**: Track patient opt-ins and honor opt-out requests
- **🤖 Keyword Handling**: Automatic HELP/STOP/START response system
- **📅 Appointment Features**:
    - High-compliance appointment reminders (portal links only)
    - Telehealth appointment links
    - Missed appointment follow-up
    - Pre-visit instructions
- **💬 Portal Notifications**:
    - New secure message alerts
    - Test results available notifications
- **💰 Billing Communications**:
    - Statement ready notifications
    - Balance due reminders (no amounts in SMS)
- **🏥 Wellness & Prevention**:
    - Annual wellness visit reminders
    - Public health campaigns (flu shots, screenings)
- **📢 Operational Messages**:
    - Office closure alerts
    - Emergency updates
- **📊 Post-Visit Surveys**: Patient feedback collection
- **🔄 Polling Architecture**: No webhooks needed - simple local development

Requirements
------------

[](#requirements)

- OpenEMR 8.0.0 or later
- PHP 8.2 or later
- MariaDB 10.6 or later
- **Sinch Conversations API account with BAA** (see Legal Requirements below)

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

[](#installation)

### Important Note About Uninstall/Reinstall

[](#important-note-about-uninstallreinstall)

**OpenEMR does not automatically drop module tables on uninstall.** If you need to reinstall the module cleanly:

```
# Option 1: Via Docker (if using Docker environment)
docker compose exec -T mysql mariadb -uroot -proot openemr  I consent to receive text message notifications from \[Clinic Name\] at the phone number provided above. I understand that these messages may include appointment reminders, test result notifications, billing reminders, and other healthcare-related communications. I understand that message and data rates may apply, and message frequency varies. I can opt out at any time by replying STOP.

#### 2. Document Consent

[](#2-document-consent)

You must maintain records of:

- ✅ Patient signature or electronic agreement
- ✅ Date of consent
- ✅ Phone number provided
- ✅ Types of messages agreed to
- ✅ Method of consent (web form, in-person, etc.)

#### 3. Never Include PHI in SMS

[](#3-never-include-phi-in-sms)

**Standard SMS is not encrypted.** You must **NEVER** include Protected Health Information such as:

- ❌ Diagnoses
- ❌ Treatment details
- ❌ Specific test results
- ❌ Medication names
- ❌ Account balances (amounts)
- ❌ Specific appointment reasons

**Instead:** Use the approved templates that direct patients to the secure patient portal.

✅ **Good:** "Your test results are available. Log in to view: \[portal link\]" ❌ **Bad:** "Your cholesterol test came back at 245 mg/dL"

#### 4. Honor Opt-Out Requests Immediately

[](#4-honor-opt-out-requests-immediately)

- ✅ Process STOP keywords within seconds
- ✅ Confirm opt-out with confirmation message
- ✅ Never send marketing messages to opted-out patients
- ✅ May still send critical transactional messages (e.g., appointment cancellations)

#### 5. Identify Yourself in Every Message

[](#5-identify-yourself-in-every-message)

Every message must start with your clinic name:

✅ **Good:** "Example Clinic: Your appointment is tomorrow..." ❌ **Bad:** "Your appointment is tomorrow..."

#### 6. Include Opt-Out Instructions

[](#6-include-opt-out-instructions)

Every message must include opt-out instructions:

✅ **Required:** "Reply STOP to opt-out"

### Required Initial Opt-In Confirmation

[](#required-initial-opt-in-confirmation)

When a patient first opts in, you **MUST** send this confirmation message:

```
{{ clinic_name }}: You have successfully opted-in to receive alerts from
{{ clinic_name }}. Msg&Data rates may apply. Msg freq varies. Reply HELP
for help. Reply STOP to unsubscribe at any time.

```

This message is **required by carriers (CTIA) and the TCPA**. The system sends it automatically when a patient opts in.

### Approved Message Templates

[](#approved-message-templates)

All message templates included in this module have been reviewed and approved by Sinch for use by OpenCoreEMR under our BAA. These templates are:

- ✅ HIPAA-compliant (when used with proper consent)
- ✅ TCPA-compliant
- ✅ Carrier-compliant (CTIA guidelines)

**Template Categories:**

1. Initial Opt-In Confirmation (required)
2. Appointment Reminders (high-compliance version)
3. Telehealth Appointment Links
4. Missed Appointment Follow-Up
5. Pre-Visit Instructions
6. Portal Notifications (new messages, test results)
7. Billing Reminders (statement ready, balance due)
8. Preventive Care / Wellness Reminders
9. Public Health Announcements (flu shots, etc.)
10. Office Closure / Emergency Updates
11. Post-Visit Feedback Surveys

**If you create custom templates**, you **MUST** submit them to Sinch for compliance review before using them in production.

See [`TEMPLATE-IMPLEMENTATION-PLAN.md`](./TEMPLATE-IMPLEMENTATION-PLAN.md) for complete template details.

### Message Timing Restrictions

[](#message-timing-restrictions)

**Best practices for send times:**

- ✅ 8 AM - 9 PM local time (patient's timezone)
- ❌ Avoid late night or early morning messages
- ✅ Exception: Emergency/urgent notifications (office closures, safety alerts)

### No Warranty / Use at Your Own Risk

[](#no-warranty--use-at-your-own-risk)

This open-source software is provided **"AS IS"** without warranty of any kind, express or implied. You are **solely responsible** for ensuring your use of this module complies with:

- HIPAA Privacy and Security Rules
- TCPA (Telephone Consumer Protection Act)
- State-specific privacy laws (e.g., California CMIA, Texas HB300)
- Carrier regulations (CTIA Best Practices)
- Any other applicable laws and regulations

**STRONGLY RECOMMENDED:** Consult with legal counsel experienced in healthcare compliance before deploying this module in a production environment.

Security
--------

[](#security)

- 🔐 **Encrypted Credentials**: API keys encrypted using OpenEMR's CryptoGen
- 🔒 **TLS/SSL**: All API communications use TLS 1.2+
- 📝 **Audit Logging**: All messages logged for compliance
- ✅ **Access Control**: OpenEMR ACL integration
- 🛡️ **CSRF Protection**: All forms protected against CSRF attacks
- 🔑 **Patient Consent**: Verified before every message send

Architecture
------------

[](#architecture)

### Polling-Based (No Webhooks)

[](#polling-based-no-webhooks)

This module uses a **polling architecture** instead of webhooks:

**Benefits:**

- ✅ Simple local development (no ngrok needed)
- ✅ Works identically locally and in production
- ✅ User-controlled refresh (click "Refresh" button)
- ✅ Easier testing and debugging
- ✅ No external dependencies

**How it works:**

1. Provider clicks "Refresh" or loads inbox
2. Module polls Sinch API for new messages
3. Stores new messages in local database
4. Displays updated inbox

See [`POLLING-ARCHITECTURE.md`](./POLLING-ARCHITECTURE.md) for detailed implementation.

Development
-----------

[](#development)

### Development Taskfile

[](#development-taskfile)

This module includes a **Taskfile** for common development tasks:

```
# Install Task (if not already installed)
# macOS
brew install go-task

# Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

# Show all available tasks
task --list

# Quick start
task setup                    # Complete setup (install, prebuild, start)
task dev:start                # Start Docker environment
task dev:port                 # Get OpenEMR URL
task module:cleanup           # Clean database for reinstall
task check                    # Run all code quality checks
```

**Common tasks:**

- `task dev:start` - Start Docker environment
- `task dev:logs` - View live logs
- `task dev:port` - Get OpenEMR access URL
- `task module:cleanup` - Drop tables for clean reinstall
- `task db:shell` - Access database
- `task check` - Run pre-commit checks
- `task --list` - See all available tasks

### Docker Development Environment

[](#docker-development-environment)

Quick setup for local module development (or just run `task setup`):

```
# 1. Clone and install module dependencies
git clone https://github.com/opencoreemr/oce-module-sinch-conversations.git
cd oce-module-sinch-conversations
composer install

# 2. Install OpenEMR source under tools/openemr (used by PHPStan + Docker bind mount).
#    OpenEMR source is intentionally NOT a runtime dep of this module — see
#    tools/openemr/README.md and issue #118.
composer install --working-dir=tools/openemr

# 3. Pre-build OpenEMR (optional but recommended - saves 5-10 min)
cd tools/openemr/vendor/openemr/openemr
composer install --no-dev
npm install --legacy-peer-deps && npm run build
cd -

# 4. Start Docker environment
docker compose up -d --wait

# 5. Get the port and open in browser
docker compose port openemr 80
# Visit http://localhost:PORT and login with admin/pass
```

**All local changes are immediately reflected** - no rebuild needed! See [`docker/README.md`](./docker/README.md) for details.

#### Common Docker Commands

[](#common-docker-commands)

```
# View live logs from OpenEMR container
docker compose logs -f openemr

# View MySQL logs
docker compose logs -f mysql

# Check container status
docker compose ps

# Execute commands in running OpenEMR container
docker compose exec openemr bash
docker compose exec openemr php -v

# Access MariaDB database
docker compose exec mysql mariadb -h mysql -uroot -proot openemr

# Stop environment (keeps data)
docker compose down

# Stop and remove all data (fresh start)
docker compose down -v

# Restart a specific service
docker compose restart openemr

# View phpMyAdmin (get port first)
docker compose port phpmyadmin 80
# Visit http://localhost:PORT
```

**Note:** We use `docker compose exec` to run commands in already-running containers:

- Fast execution (no container startup overhead)
- No entrypoint conflicts
- Works with running services

#### Troubleshooting Docker Issues

[](#troubleshooting-docker-issues)

**Container won't start:**

```
# Check logs for errors
docker compose logs openemr

# Remove everything and start fresh
docker compose down -v
docker compose up -d --wait
```

**OpenEMR installer keeps running:**

```
# The installer creates a sites/default/sqlconf.php file
# If this file exists, installer is complete
docker compose exec openemr ls -la /var/www/localhost/htdocs/openemr/sites/default/sqlconf.php
```

**Changes not showing up:**

```
# PHP changes should be instant (OPCACHE_OFF=1)
# If not, restart Apache:
docker compose restart openemr
```

**Database issues:**

```
# Access database directly
docker compose exec mysql mariadb -uroot -proot openemr

# View module tables
docker compose exec mysql mariadb -uroot -proot -e "SHOW TABLES LIKE 'oce_sinch%'" openemr

# Export database
docker compose exec mysql mariadb-dump -uroot -proot openemr > backup.sql

# Import database
docker compose exec -T mysql mariadb -uroot -proot openemr