ReadMe

Alerta Gar - Twilio SMS App

This project is a Next.js application that connects to the Twilio API to receive SMS messages, saves the message content into a Supabase database, and displays the messages on the frontend in real-time.

Features

Receive SMS Messages: Uses a Twilio virtual phone number to receive incoming SMS messages.
Store SMS Data: Saves SMS details (sender, message, timestamp) into a Supabase database.
Display Messages: Fetches and displays the stored SMS messages on the frontend.
Secure Webhooks: Validates requests using Twilio's x-twilio-signature.
Real-time Updates (Optional): Supports real-time message updates using Supabase subscriptions.

Technologies Used

Next.js: React-based framework for building web applications.
Twilio: Cloud communication platform for handling SMS messages.
Supabase: Backend-as-a-service for database and authentication.
TypeScript: Strongly-typed JavaScript for better developer experience.
ngrok: Tool to expose your local server for webhook testing.
Tailwind CSS (Optional): For frontend styling.

Getting Started

Prerequisites

Node.js (v16+ recommended)
npm
Twilio account and virtual phone number
Supabase account

Installation

Clone the Repository:

gh repo clone Min11Benja/alertagas-twilio-sms
cd alertagas-twilio-sms

Install Dependencies:
```
npm install
```

Set Up Environment Variables: Create a .env.local file in the root of your project and add the following:

# Twilio
TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

Set Up Supabase: Create a Supabase project. Add a table named sms_messages (and optional sensors table) with columns matching your SMS data. For example:

create table public.sensors (
  id serial not null,
  sensor_name text null,
  phone_number text null,
  level integer null,
  updated_at timestamp with time zone not null default now(),
  constraint sensors_pkey primary key (id),
  constraint sensors_phone_number_key unique (phone_number)
);

create table public.sms_messages (
  id serial not null,
  from_number text null,
  body text null,
  received_at timestamp with time zone null default now(),
  sensor_id integer null,
  status text null default 'received'::text,
  constraint sms_messages_pkey primary key (id),
  constraint sms_messages_sensor_id_fkey foreign key (sensor_id) references sensors (id)
);

create index if not exists idx_from_number on public.sms_messages using btree (from_number);
create index if not exists idx_received_at on public.sms_messages using btree (received_at);

Set Up Twilio: Purchase a Twilio phone number that supports SMS. Configure the webhook URL to point to your endpoint (e.g., /api/receive-sms). Use ngrok for local testing if needed.
Start the Development Server:
```
npm run dev
```

Usage

Sending an SMS: Send an SMS to your Twilio phone number. The backend /api/receive-sms endpoint will handle the incoming request, validate it, and store the data in Supabase.
Viewing Messages: Open the application in your browser (http://localhost:3000). View the list of received SMS messages on the homepage or relevant dashboard pages.

Project Structure

src
├── app
│   ├── api
│   │   ├── receive-sms
│   │   │   └── route.js
│   │   └── sensors
│   │       └── route.ts
│   ├── auth
│   │   ├── layout.tsx
│   │   ├── login
│   │   │   └── page.tsx
│   │   ├── register
│   │   │   └── page.tsx
│   │   └── reset-password
│   │       └── page.tsx
│   ├── components
│   │   ├── HOC
│   │   │   └── ProtectedPage.tsx
│   │   ├── data-tables
│   │   │   ├── SensorForm.tsx
│   │   │   └── SensoresTable.tsx
│   │   ├── landing
│   │   │   ├── Contact.tsx
│   │   │   ├── CtaBanner.tsx
│   │   │   ├── Faq.tsx
│   │   │   ├── Features.tsx
│   │   │   ├── Footer.tsx
│   │   │   ├── Header.tsx
│   │   │   ├── HeroSection.tsx
│   │   │   ├── StepArrows.tsx
│   │   │   └── Testimonials.tsx
│   │   └── layout-components
│   │       ├── SideBar.tsx
│   │       └── TopBar.tsx
│   ├── dashboard
│   │   ├── PlatformLayout.tsx
│   │   ├── citas
│   │   │   ├── page.tsx
│   │   │   ├── programar
│   │   │   │   └── page.tsx
│   │   │   └── tabla
│   │   │       └── page.tsx
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── rutas
│   │   │   ├── page.tsx
│   │   │   ├── programar
│   │   │   │   └── page.tsx
│   │   │   └── tabla
│   │   │       └── page.tsx
│   │   ├── sensores
│   │   │   ├── crear
│   │   │   │   └── page.tsx
│   │   │   ├── editar
│   │   │   │   └── [id]
│   │   │   │       └── page.tsx
│   │   │   ├── page.tsx
│   │   │   └── tabla
│   │   │       └── page.tsx
│   │   ├── settings
│   │   │   ├── globales
│   │   │   │   └── page.tsx
│   │   │   └── usuario
│   │   │       └── page.tsx
│   │   ├── sms
│   │   │   ├── page.tsx
│   │   │   └── tabla
│   │   │       └── page.tsx
│   │   ├── ticket
│   │   │   └── page.tsx
│   │   └── usuarios
│   │       ├── clientes
│   │       │   └── page.tsx
│   │       ├── operadores
│   │       │   └── page.tsx
│   │       ├── page.tsx
│   │       └── vendedores
│   │           └── page.tsx
│   ├── hooks
│   │   ├── useAuth.tsx
│   │   ├── useFetchData.tsx
│   │   └── useFetchUnlinkedPhoneNumbers.tsx
│   ├── landing
│   │   ├── LandingLayout.tsx
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── layout.tsx
│   └── page.tsx
├── lib
│   ├── helpers
│   │   └── formatDate.ts
│   └── supabase
│       └── supabaseClient.ts
└── styles
    └── globals.css

API Endpoints

Method

Endpoint

Description

POST

/api/receive-sms

Handles incoming SMS messages from Twilio.

GET

/api/sensors

Retrieves sensor data.

Enforce Branch Naming Convention

To maintain consistency and traceability between Jira issues and Git branches, follow this naming convention:

feature/ → Used for new features or improvements.
bugfix/ → Used to fix identified bugs.
hotfix/ → Used for critical fixes that need immediate deployment.

Each branch should be linked to a Jira issue ID (AGT-XXX), ensuring better integration with project tracking and automation tools.

Commit Types

feat: Commits that add or remove a new feature to the API or UI
fix: Commits that fix a API or UI bug of a preceded feat commit
refactor: Commits that rewrite/restructure your code, however do not change any API or UI behaviour
perf: Commits that improve performance
style: Commits that do not affect the meaning (white-space, formatting, missing semi-colons, etc)
test: Commits that add missing tests or correcting existing tests
docs: Commits that affect documentation only
build: Commits that affect build components like build tool, ci pipeline, dependencies, project version, etc
ops: Commits that affect operational components like infrastructure, deployment, backup, recovery, etc
chore: Miscellaneous commits that dont fit anyhwere else

Jira & Git Integration

1. Link Jira with Your Git Repository

To track branches, commits, and PRs in Jira, integrate with GitHub (or GitLab/Bitbucket):

Go to Jira Settings → Click Apps → Search for GitHub for Jira.
Install the app and authorize Jira to access your GitHub repository.
Ensure your repository (alertagas-twilio-sms) is linked to Jira.
Enable Smart Commits to recognize AGT-XXX in commits and branches.

2. Automate Issue Tracking with Smart Commits

Use Smart Commit messages to automatically update Jira issues based on commits:

git commit -m "AGT-004: Implement sensor logging #done"
git commit -m "Fix AGT-005: Handle Twilio webhook errors #in-progress"

#done → Moves issue to "Done" #in-progress → Moves issue to "In Progress" #review → Moves issue to "Code Review"

Deployment

To deploy the project to Google Cloud Run:

gcloud run deploy nextjs-cloud-run \
  --image gcr.io/alertagas-nextjs-project/alertagas-twilio-sms:latest \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated

Contributing

Fork the repository.
Clone your fork: git clone https://github.com/your-user/alertagas-twilio-sms.git
Create a feature branch: git checkout -b feature/AGT-XXX-new-feature
Make changes and commit: git commit -m "AGT-XXX: Description"
Push to GitHub: git push origin feature/AGT-XXX-new-feature
Create a Pull Request and request a review.

Contact

Developer: Benjamin Martinez Juarez
Email: [email protected]
GitHub: @min11benja

License

This project is licensed under the MIT License.

PreviousGITHUB REPO NextTemplates

Last updated 7 months ago