feat(backend): add whatsapp messaging integration via twilio by saad-gsoft · Pull Request #19 · Global-Software-Consulting/nodejs-boilerplate

saad-gsoft · 2026-03-30T09:19:48Z

Summary

Add complete WhatsApp integration module (services/backend/src/modules/v1/whatsapp/) with text, media, and template message support via Twilio WhatsApp API
7 API routes (1 send, 2 message queries, 2 conversation queries, 2 webhooks) with Joi validation and Swagger docs
WhatsAppMessage Mongoose model with conversation tracking and pagination
Conversation aggregation with last message and message count
Twilio signature validation middleware for webhook security
Smart message dispatch: auto-routes to text/media/template based on request body

New Files

services/backend/src/modules/v1/whatsapp/whatsapp.model.js — WhatsAppMessage Mongoose schema
services/backend/src/modules/v1/whatsapp/whatsapp.service.js — All WhatsApp business logic
services/backend/src/modules/v1/whatsapp/whatsapp.controller.js — HTTP controllers
services/backend/src/modules/v1/whatsapp/whatsapp.validation.js — Joi schemas + E.164 validator
services/backend/src/modules/v1/whatsapp/whatsapp.routes.js — Express routes + Swagger JSDoc
services/backend/src/modules/v1/whatsapp/index.js — Barrel exports
services/backend/src/middlewares/twilioWebhook.js — Twilio signature validation middleware

Modified Files

services/backend/package.json — Added twilio: ^5.0.0
services/backend/src/config/config.js — Added Twilio/WhatsApp env var validation
services/backend/src/config/roles.js — Added sendWhatsapp to user, sendWhatsapp + manageWhatsapp to admin
services/backend/src/modules/v1/index.js — Mounted whatsapp routes
services/backend/src/middlewares/index.js — Export validateTwilioSignature
services/backend/.env.example — Added 4 Twilio/WhatsApp env vars
services/backend/docs/swagger/components.yml — Added WhatsAppMessage, Conversation schemas
README.md — Added WhatsApp endpoints documentation

Env Vars

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_WHATSAPP_NUMBER=+14155238886
TWILIO_WEBHOOK_BASE_URL=https://your-domain.com

Test plan

pnpm install — twilio dependency installs
pnpm lint — no ESLint errors
Start server and verify routes load without errors
Test text message: POST /v1/whatsapp/messages with body
Test media message: POST /v1/whatsapp/messages with mediaUrls
Test template message: POST /v1/whatsapp/messages with templateName
Test message listing and conversation queries
Test webhook with ngrok + Twilio WhatsApp Sandbox
Verify Twilio signature middleware blocks invalid requests

🤖 Generated with Claude Code

add complete whatsapp integration module with text, media, and template message support, conversation tracking, and webhook handling for incoming messages and status callbacks. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…tion # Conflicts: # pnpm-lock.yaml

…tion

github-actions · 2026-03-30T16:32:18Z

⚠️ Missing Test Cases

Source files were changed but test coverage may be incomplete.

Files/modules missing tests:

src/modules/v1/whatsapp/ — no *.test.js found in module
src/middlewares/twilioWebhook.js — no test in tests/unit/middlewares/

Where should tests go?

Module tests: Co-located in src/modules/v{N}/{feature}/*.test.js
Middleware tests: tests/unit/middlewares/*.test.js
Utility tests: tests/unit/utils/*.test.js
Integration tests: tests/integration/*.test.js

github-actions · 2026-03-30T16:54:15Z

⚠️ Missing Test Cases

Source files were changed but test coverage may be incomplete.

Files/modules missing tests:

src/modules/v1/whatsapp/ — no *.test.js found in module
src/middlewares/twilioWebhook.js — no test in tests/unit/middlewares/

Where should tests go?

Module tests: Co-located in src/modules/v{N}/{feature}/*.test.js
Middleware tests: tests/unit/middlewares/*.test.js
Utility tests: tests/unit/utils/*.test.js
Integration tests: tests/integration/*.test.js

Fixes broken lockfile missing scmp@2.1.0 entry. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-03-30T17:01:36Z

⚠️ Missing Test Cases

Source files were changed but test coverage may be incomplete.

Files/modules missing tests:

src/modules/v1/whatsapp/ — no *.test.js found in module
src/middlewares/twilioWebhook.js — no test in tests/unit/middlewares/

Where should tests go?

Module tests: Co-located in src/modules/v{N}/{feature}/*.test.js
Middleware tests: tests/unit/middlewares/*.test.js
Utility tests: tests/unit/utils/*.test.js
Integration tests: tests/integration/*.test.js

…tion

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-03-30T17:49:48Z

⚠️ Missing Test Cases

Source files were changed but test coverage may be incomplete.

Files/modules missing tests:

src/modules/v1/whatsapp/ — no *.test.js found in module
src/middlewares/twilioWebhook.js — no test in tests/unit/middlewares/

Where should tests go?

Module tests: Co-located in src/modules/v{N}/{feature}/*.test.js
Middleware tests: tests/unit/middlewares/*.test.js
Utility tests: tests/unit/utils/*.test.js
Integration tests: tests/integration/*.test.js

github-actions · 2026-03-31T06:48:03Z

⚠️ Missing Test Cases

Source files were changed but test coverage may be incomplete.

Files/modules missing tests:

src/modules/v1/whatsapp/ — no *.test.js found in module
src/middlewares/twilioWebhook.js — no test in tests/unit/middlewares/

Where should tests go?

Module tests: Co-located in src/modules/v{N}/{feature}/*.test.js
Middleware tests: tests/unit/middlewares/*.test.js
Utility tests: tests/unit/utils/*.test.js
Integration tests: tests/integration/*.test.js

github-actions · 2026-03-31T06:59:31Z

⚠️ Missing Test Cases

Source files were changed but test coverage may be incomplete.

Files/modules missing tests:

src/middlewares/twilioWebhook.js — no test in tests/unit/middlewares/

Where should tests go?

Module tests: Co-located in src/modules/v{N}/{feature}/*.test.js
Middleware tests: tests/unit/middlewares/*.test.js
Utility tests: tests/unit/utils/*.test.js
Integration tests: tests/integration/*.test.js

saad-gsoft · 2026-03-31T07:01:37Z

Fixes Applied

1. Orphaned inbound webhook data

handleIncomingMessage now looks up the user by matching the WhatsApp number (To field) via getUserRepository().findOne({ phone: to }) and associates the inbound record with that user.

2. Missing env vars

Added TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_WHATSAPP_NUMBER, and TWILIO_WEBHOOK_BASE_URL to .env.example and the Joi validation schema.

3. Unit tests

Added whatsapp.service.test.js with tests covering: generateConversationId, sendTextMessage, handleIncomingMessage (text, media, with/without user), getMessageById, getConversation, handleStatusCallback.

Known: Mongoose direct usage

Same as #17/#18 — uses Mongoose models directly. Should be migrated to repository pattern when rebasing onto a DB branch.

github-actions · 2026-03-31T07:08:03Z

⚠️ Missing Test Cases

Source files were changed but test coverage may be incomplete.

Files/modules missing tests:

src/middlewares/twilioWebhook.js — no test in tests/unit/middlewares/

Where should tests go?

Module tests: Co-located in src/modules/v{N}/{feature}/*.test.js
Middleware tests: tests/unit/middlewares/*.test.js
Utility tests: tests/unit/utils/*.test.js
Integration tests: tests/integration/*.test.js

…missing env vars - Look up user by phone number in handleIncomingMessage to associate inbound whatsapp records with a user, preventing orphaned data - Add TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_WHATSAPP_NUMBER, and TWILIO_WEBHOOK_BASE_URL to .env.example and Joi schema Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Tests cover: generateConversationId, sendTextMessage, handleIncomingMessage (with/without user association, text and media), getMessageById, getConversation, handleStatusCallback. Twilio client and Mongoose mocked. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Move getUserRepository require to top-level import in whatsapp.service.js and remove unused httpStatus import from test file. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-03-31T07:42:52Z

⚠️ Missing Test Cases

Source files were changed but test coverage may be incomplete.

Files/modules missing tests:

src/middlewares/twilioWebhook.js — no test in tests/unit/middlewares/

Where should tests go?

Module tests: Co-located in src/modules/v{N}/{feature}/*.test.js
Middleware tests: tests/unit/middlewares/*.test.js
Utility tests: tests/unit/utils/*.test.js
Integration tests: tests/integration/*.test.js

github-actions · 2026-05-01T02:51:02Z

This PR has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs.

github-actions Bot added service: backend dependencies area: docs labels Mar 30, 2026

Merge remote-tracking branch 'origin/main' into feat/whatsapp-integra…

a636613

…tion # Conflicts: # pnpm-lock.yaml

github-actions Bot added the size/xl label Mar 30, 2026

saad-gsoft and others added 3 commits March 30, 2026 15:51

Merge remote-tracking branch 'origin/main' into feat/whatsapp-integra…

2a42753

…tion

Merge branch 'main' into feat/whatsapp-integration

aab59ea

Merge branch 'main' into feat/whatsapp-integration

aa8e671

Merge branch 'main' into feat/whatsapp-integration

ba77ee1

fix(deps): regenerate lockfile after merge with main

b7e03aa

Fixes broken lockfile missing scmp@2.1.0 entry. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

saad-gsoft and others added 2 commits March 30, 2026 22:29

Merge remote-tracking branch 'origin/main' into feat/whatsapp-integra…

c2fd9be

…tion

fix(backend): add mongoose dep for whatsapp module

56bb4f5

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions Bot added the area: tests label Mar 31, 2026

saad-gsoft and others added 3 commits March 31, 2026 12:42

fix(backend): resolve eslint global-require and no-unused-vars errors

30e2afa

Move getUserRepository require to top-level import in whatsapp.service.js and remove unused httpStatus import from test file. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

saad-gsoft force-pushed the feat/whatsapp-integration branch from 88b909d to 30e2afa Compare March 31, 2026 07:42

github-actions Bot added the stale label May 1, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(backend): add whatsapp messaging integration via twilio#19

feat(backend): add whatsapp messaging integration via twilio#19
saad-gsoft wants to merge 12 commits into
mainfrom
feat/whatsapp-integration

saad-gsoft commented Mar 30, 2026

Uh oh!

github-actions Bot commented Mar 30, 2026

Uh oh!

github-actions Bot commented Mar 30, 2026

Uh oh!

github-actions Bot commented Mar 30, 2026

Uh oh!

github-actions Bot commented Mar 30, 2026

Uh oh!

github-actions Bot commented Mar 31, 2026

Uh oh!

github-actions Bot commented Mar 31, 2026

Uh oh!

saad-gsoft commented Mar 31, 2026

Uh oh!

github-actions Bot commented Mar 31, 2026

Uh oh!

github-actions Bot commented Mar 31, 2026

Uh oh!

github-actions Bot commented May 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant