Vou Contigo accompanies older adults to appointments, exams, the market, the bank, the pharmacy, and outings—and keeps the family informed about everything. In v2, WhatsApp itself schedules and cancels appointments, shows available times, and sends reminders automatically; PIX payments switch to Asaas, and family members get a web portal.

The service is sold to children and family members who can’t be there in person. The platform organizes who will be accompanied, when, by whom, and what it actually cost, then provides the day’s report, ready to paste into the family’s WhatsApp chat.
Each service includes the client, person accompanied, type, starting address and destination, time, and a clear status flow: requested → scheduled → confirmed → in progress → completed → reported.
When a service is completed, the system requires the actual time, wait time in minutes, distance traveled in km, parking, tolls, and effort level. After 10 to 20 services, you can review the price based on real data.
The report is generated using the brand’s template. In v2, it is sent on its own to the family member as soon as the companion finishes—by WhatsApp and, when an email address is on file, by email too.
A numeric-menu bot schedules and cancels appointments, shows available times, and reports balances through the Evolution API, using the company’s regular number connected by QR code. When someone asks for a person—or writes something outside the menu—the bot goes quiet until management allows it to respond.
A package becomes a PIX charge in Asaas, with a QR code and copy-and-paste code. The webhook automatically marks it as paid, and the new package is created only when the money comes in.
Login via magic link in email: balance, upcoming visits, report history on a printable page, request and cancel a visit, and the .ics calendar.
The person receiving care doesn’t need an app, login, or phone — just a well-maintained record. The family uses the platform through WhatsApp, the caregiver through a phone, and the manager through the dashboard and Telegram.
Child, grandchild, or responsible party. They request through the landing page or WhatsApp, receive confirmation, a reminder, and the report for each visit. In the MVP, everything happens through WhatsApp, with a person on the other end.
The person who carries out the service. Uses the mobile-first dashboard on the go: checks the day’s schedule, taps Start, taps Finish, enters wait time/distance/costs, and reviews the report. Or does the same through the Telegram bot.
Manages the schedule, approves requests, sells packages, collects payments, and checks metrics. Gets every lead and schedule change on Telegram in under a minute.
WhatsApp, Telegram, and the dashboard are channels for managing the service—they are not the service itself. This distinction keeps the system from becoming “a chat with a database.”
No WhatsApp automation: the client still talks to a human. The system makes sure nothing gets lost.
A mobile-first page in the logo’s color palette: the problem, services, 3 steps, plans, who we are, what no we do, FAQ, and the fixed WhatsApp button with a prefilled message. The short form creates a lead and notifies the manager on Telegram.
Supabase login with manager and companion roles. Week/day schedule, client and person-being-accompanied records, packages and hour balances, manual PIX payments, leads, settings, and metrics with CSV export.
Screen designed for use on the go: Start records the actual time, and Finish requires the wait time, mileage, parking, tolls, and effort level from 1 to 5. From that, you get revenue per effective hour, average wait time, and average extra cost.
The report text is prefilled using the brand’s template and the service details. One button copies it to WhatsApp; another marks it as sent—along with templates for confirmations, reminders, low balances, and payment requests.
In the private management group: notifies about a new lead, a service created or canceled, “tomorrow there’s X at Y,” a report pending for more than 2 hours, and a low balance. Includes commands to do everything from your phone.
A scheduled job calls the route protected by CRON_SECRET and sends the day’s notifications: a reminder the day before, another a few hours ahead, and a notice about a pending report. On the VPS, this is handled by the system cron; on Vercel, by Vercel Cron.
Automation doesn’t replace the person: it takes repetitive work off their hands, like confirming, reminding, collecting payment, and reporting.
Five-option numeric menu through Evolution API. Scheduling offers times that are actually available on the calendar; cancellation applies the policy and reports the fee. Everything is recorded in Postgres RPCs, not in scattered app rules.
Confirmation when the request is approved, a reminder the day before, a reminder two hours before, and the report upon completion — sent directly to the client via WhatsApp and email when available.
Billing with a QR code, an authenticated webhook that reconciles the payment, and a monthly package renewal cron that sends a reminder a few days before the due date.
Magic link by email, balance, upcoming visits, monthly reports on a printable page, request and cancellation, .ics calendar, and choice to receive available times by email or WhatsApp.
The dashboard gained a unified inbox (WhatsApp conversations + leads), a request queue for approval, and a customer timeline showing everything that happened across every channel.
The destination is geocoded and compared with the base address. The radius is for information only—it alerts the manager but doesn’t block anything. The cancellation fee and wait time beyond the grace period are calculated automatically.
The person receiving care still doesn’t need an app. The person interacting is their son, granddaughter, or caregiver — using the phone the way they already do.
Numeric menu, no need to type anything:
Hi, Ana! I’m Vou Contigo’s assistant. How can I help? 1. Agendar acompanhamento 2. Cancelar ou remarcar 3. Ver horários livres 4. Meu saldo e próxima visita 5. Falar com uma pessoa
Three things put the conversation in human mode: choosing 5, enter free-form text in the menu, and be an unregistered number. Then the bot stops responding completely — and even typing “menu” won’t bring it back — until management sends /liberar on Telegram. Once you’re inside a flow (choosing a type, day, or time), an invalid response doesn’t escalate: it just asks for the number again.
/minha-contaLogin via magic link sent by email (WhatsApp code is marked “coming soon” on the screen itself). The email must match the one on the client’s record in the dashboard — that’s how the account is linked to the record.
Inside: hour balance, upcoming visits, report history, details about the person being accompanied, request and cancel a visit, and also:
/minha-conta/horarios — available time slots, with the buttons receive via email e receive via WhatsApp;/minha-conta/relatorios/[mes] — the month’s reports on a page designed for printing (or saving as a PDF in your browser);/minha-conta/calendario.ics — downloads upcoming visits to your phone’s calendar.Nothing happens without a person’s approval: the bot receives the request, and the manager decides. What changed in v2 is that deciding became a single tap on a button.
Each request arrives in the group with three inline buttons: ✅ approve, ✏️ edit e ❌ reject. Approving immediately triggers the automatic confirmation in the family member’s WhatsApp.
/conversas shows who is waiting for real people, /responder sends the reply via WhatsApp and /liberar returns the conversation to the bot.
/resumo provides an operational view of the day and /financeiro, last week’s money. The 7 a.m. cron sends the day’s summary automatically; on Mondays, it includes the financial summary for the completed week.
/painel/inboxUnified inbox: WhatsApp conversations and landing page leads in one place, with each conversation’s history and a button to hand it back to the bot when the issue is resolved.
/painel/solicitacoesThe queue of appointments the bot scheduled through WhatsApp that still need approval, so the manager can approve, adjust, or decline them without opening each appointment.
Each client has a timeline of everything that happened across all channels. In the financial section, the Asaas PIX charge includes a QR code and copy-and-paste code, and is reconciled through the webhook.
No custom infrastructure: Node for Next.js, the Supabase CLI for the local database, a Telegram bot, and (for publishing) a Vercel account linked to GitHub.
The project uses Next.js 15 with App Router, TypeScript, and Tailwind 4.
# check the version node -v npm -v
Postgres, Auth, Storage, and RLS running in Docker through the CLI, with no cloud project needed for development.
# starts the local stack npx supabase start
A bot just for Vou Contigo, created in @BotFather, and the ID of management’s private group.
# on Telegram, talk to @BotFather → /newbot
Steps 1 through 6 are the one-time setup. Step 7 is the routine you repeat every day.
Download the repository and install the dependencies.
git clone https://github.com/inematds/voucontigo.git cd voucontigo npm install
Copy the example to .env.local. It already lists everything the project reads: Supabase, Telegram, cron, and site.
cp .env.example .env.local # .env.local — what to fill in NEXT_PUBLIC_SUPABASE_URL= # Supabase > Settings > API NEXT_PUBLIC_SUPABASE_ANON_KEY= # same SUPABASE_SERVICE_ROLE_KEY= # same (never in the client) TELEGRAM_BOT_TOKEN= # @BotFather TELEGRAM_WEBHOOK_SECRET= # make up a long string TELEGRAM_CHAT_GESTAO= # management group ID CRON_SECRET= # Vercel Cron secret NEXT_PUBLIC_SITE_URL=https://voucontigo.inema.club NEXT_PUBLIC_WHATSAPP_EMPRESA=5551999999999 TZ=America/Sao_Paulo # process time zone # --- v2 (empty = disabled, nothing breaks) --- WHATSAPP_PROVIDER=evolution # or Meta EVOLUTION_API_URL=http://evolution:8080 EVOLUTION_API_KEY= # same key as Evolution EVOLUTION_INSTANCE=voucontigo WHATSAPP_WEBHOOK_TOKEN= # you make it up; it goes in the webhook query ASAAS_API_KEY= # start in the sandbox ASAAS_WEBHOOK_TOKEN= # header asaas-access-token ASAAS_BASE_URL=https://sandbox.asaas.com/api/v3 RESEND_API_KEY= # optional; empty = no email EMAIL_FROM=Vou Contigo <contato@voucontigo.com.br> GEOCODER_EMAIL= # required by Nominatim policy
start starts the local Postgres instance and prints the keys; db reset recreates the database by applying the migrations from supabase/migrations. Copy the printed URL and anon key into the .env.local.
npx supabase start npx supabase db reset # applies migrations + seed
Start the development server and open the dashboard. The account is created in Supabase Auth (local Studio at http://localhost:54323, Authentication tab → Add user); a trigger creates the profile with the default role acompanhante, so the first account is promoted to gestora using SQL.
npm run dev # http://localhost:3000 · dashboard at /painel # promote the first account to manager (Studio SQL Editor) update public.perfil set papel = 'gestora' where id = (select id from auth.users where email = 'voce@exemplo.com');
In Supabase Cloud, in Authentication → URL Configuration → Redirect URLs, register both magic link redirects, or the email will return an error: ${NEXT_PUBLIC_SITE_URL}/entrar/callback (family member portal) and ${NEXT_PUBLIC_SITE_URL}/login/callback (team dashboard).
In Telegram, call the @BotFather, send /newbot, choose a name and username, and save the token in TELEGRAM_BOT_TOKEN. Add the bot to management’s private group and put the group ID in TELEGRAM_CHAT_GESTAO. Then point the webhook to the project route.
# registers the webhook at NEXT_PUBLIC_SITE_URL/api/telegram npx tsx scripts/telegram-set-webhook.ts
During development, Telegram needs a public URL—use a tunnel (e.g.: ngrok http 3000) and run the script with NEXT_PUBLIC_SITE_URL pointing to it.
Publishing is git push: everything else is handled by the webhook. First, register the same variables as the .env.local on the destination (with the production Supabase keys) and run the Telegram webhook script again with the final URL.
git add -A git commit -m "feat: v2.0.0 do Vou Contigo" git push # automatic deploy · nothing to do in the dashboard # on the VPS (where Evolution runs) — the host's Caddy handles TLS and proxying docker compose -p voucontigo -f docker-compose.vps.yml --env-file .env up -d --build # and the jobs become system cron jobs: cp deploy/vps-cron.example /etc/cron.d/voucontigo
Always use -p voucontigo: o deploy/Caddyfile.snippet proxies requests to the containers voucontigo-app-1 e voucontigo-evolution-1, whose names depend on this prefix. In the Vercel, o vercel.json already includes the three crons in UTC — but the one for every hour (“2 hours before” reminder) requires a Pro plan; on Hobby, only one cron runs per day, with no guaranteed time. This isn’t a problem on the VPS.
The full service cycle, from the first contact to the report in the family’s hands.
# 1. the lead arrives (landing page form or WhatsApp) # → the bot notifies the group; the manager responds on WhatsApp /lead # lists new leads # 2. schedule /agendar # step-by-step assistant (or through the dashboard) # 3. on the day — the companion, using their phone /hoje # today's schedule, with the IDs /iniciar 42 # records the actual start time # 4. when finished /finalizar 42 # asks for wait time, km, parking, tolls, effort # 5. report /relatorio 42 # text ready to copy and paste into the family's WhatsApp # 6. package balance /saldo Maria # hours used and remaining
Evolution runs alongside the app on the same Docker network and communicates with WhatsApp through a regular number — no Meta verification, no approved templates, and no per-message fees. The official alternative (Meta Cloud API) is still supported in the code with WHATSAPP_PROVIDER=meta.
The image is pinned in atendai/evolution-api:v2.2.3, with its own Postgres (unrelated to Supabase). It fits in about 400 MB of memory alongside the app.
cp .env.evolution.example .env.evolution # edit: EVOLUTION_SERVER_URL, EVOLUTION_API_KEY (long string), EVOLUTION_DB_PASSWORD docker compose -p voucontigo -f docker-compose.evolution.yml \ --env-file .env.evolution up -d
Open https://evolution.inema.club/manager and sign in with the EVOLUTION_API_KEY. Create the instance with the name voucontigo — the same value as EVOLUTION_INSTANCE — request the QR Code and scan it with phone for the Vou Contigo number (WhatsApp → Linked Devices). The session stays in the volume evolution_instances and survives restarts.
The global webhook is deliberately turned off: it’s registered on the instance, through the manager.
| Field | Value |
|---|---|
| URL | https://voucontigo.inema.club/api/whatsapp?token=<WHATSAPP_WEBHOOK_TOKEN> |
| Events | MESSAGES_UPSERT e MESSAGES_UPDATE |
webhook_by_events | false — all events at the same URL |
webhook_base64 | false — no base64 media |
Evolution doesn’t sign the request body, so the secret is sent in the query string: the same WHATSAPP_WEBHOOK_TOKEN needs to be in the .env from the app, which compares it in constant time and returns 401 if there’s no match. Group messages, messages sent by the number itself, and messages without text are ignored with a 200 response, and the message ID ensures nothing is processed twice.
Both stacks share the Docker network, so the app communicates with Evolution by service name without going through the internet.
WHATSAPP_PROVIDER=evolution EVOLUTION_API_URL=http://evolution:8080 EVOLUTION_API_KEY=# the SAME AUTHENTICATION_API_KEY from Evolution EVOLUTION_INSTANCE=voucontigo WHATSAPP_WEBHOOK_TOKEN=# same as the webhook URL
It isn’t the official API: Meta may block the number if the behavior looks like spam. Usage rules—reply only to conversations initiated by the client; send only messages about real appointments (confirmation, reminder, report, billing for what was contracted); no bulk messaging, broadcast lists, or marketing; keep a backup number. If volume grows, migrate to WHATSAPP_PROVIDER=meta.
The hours package becomes a PIX charge with a QR Code and copy-and-paste code. When the client pays, the Asaas webhook marks it as paid and the new package is created—never before.
Create an account, generate an API key for the test environment, and point the base URL to the sandbox. Switch to production only after a complete charge works.
ASAAS_API_KEY=# sandbox key ASAAS_BASE_URL=https://sandbox.asaas.com/api/v3 ASAAS_WEBHOOK_TOKEN=# long string you make up
In Asaas, point to the app route and set the authentication token—it arrives in the header asaas-access-token and is compared with ASAAS_WEBHOOK_TOKEN (401 if they don't match).
https://voucontigo.inema.club/api/asaas/webhook # header: asaas-access-token: <ASAAS_WEBHOOK_TOKEN>
Events that matter: PAYMENT_RECEIVED e PAYMENT_CONFIRMED mark as paid; PAYMENT_DELETED e PAYMENT_REFUNDED are reversed. The route always responds with 200 when authenticated—Asaas blocks the queue for any response that isn’t 2xx—and ignores repeated events.
The cron /api/cron/renovacoes looks for monthly packages that expire within renovacao_aviso_dias (default 3), generates the renewal charge and sends it to the client. Expired packages become expirado, with a notification to management.
Switch ASAAS_BASE_URL to https://api.asaas.com/v3, use the production key and register the environment in the configuration asaas_ambiente from the dashboard. The manual PIX option from v1 remains available as an alternative.
Everything the bot does, the dashboard can do too—the bot is the shortcut on your phone. It runs in the manager’s private group with the companion.
| Command | What it does |
|---|---|
/hoje | Today’s schedule, with time, person accompanied, type, destination, and status. |
/amanha | Tomorrow’s schedule — the basis for the reminder sent the day before. |
/semana | A view of the next seven days to see bookings and gaps. |
/agendar | Step-by-step assistant: client, person accompanied, type, date and time, starting point, and destination. |
/cancelar <id> | Cancels the service and records the reason, applying the cancellation policy. |
/iniciar <id> | Marks the actual start time—it’s the companion’s check-in. |
/finalizar <id> | Marks the actual end time and asks for wait time, km, parking, tolls, and effort from 1 to 5. |
/relatorio <id> | Creates the report using the brand’s template so you can copy and send it to the family. |
/saldo <cliente> | Hours purchased, used, and remaining in that client’s package. |
/lead | Lists new leads who came in through the landing page, with the WhatsApp link. |
| New in v2.0.0 | |
/solicitacoes | Pending requests from WhatsApp, each with buttons ✅ approve, ✏️ edit e ❌ reject. Approving triggers the automatic confirmation to the family member. |
/conversas | Whoever is waiting for human support—the conversations where the bot has gone silent. |
/responder <whatsapp> <texto> | Sends the reply via WhatsApp without leaving Telegram. |
/liberar <whatsapp> | Hands the conversation back to the bot, taking it out of human mode. |
/resumo | Today’s operations summary: schedule, pending items, and what has already gone out. |
/financeiro | Financial summary for the most recent completed week. |
In addition to commands, the bot sends automatic alerts for: a new lead, a service created or canceled, a new WhatsApp request, a request for human assistance, a report pending for more than two hours, and a client’s low balance. The 7 a.m. cron sends the day’s summary; on Mondays, it includes the week’s financial summary.
All of them are in .env.example. The v2 ones follow the “empty = disabled” rule: the app starts up the same way, just without that automation.
| Variable | Where it comes from · what it does |
|---|---|
NEXT_PUBLIC_SUPABASE_URLNEXT_PUBLIC_SUPABASE_ANON_KEYSUPABASE_SERVICE_ROLE_KEY | Supabase → Settings → API. The service role never goes to the customer. |
TELEGRAM_BOT_TOKENTELEGRAM_WEBHOOK_SECRETTELEGRAM_CHAT_GESTAO | Token for @BotFather, a secret you make up, and the ID of management’s private group. |
CRON_SECRET | Secret that the cron sends as Authorization: Bearer …. Without it, job routes respond with 401. |
NEXT_PUBLIC_SITE_URLNEXT_PUBLIC_WHATSAPP_EMPRESA | The public URL of the site and the company’s number in the format 55DDDNÚMERO. |
TZ | America/Sao_Paulo. Process time zone — set it in the project variables in Vercel too. |
WHATSAPP_PROVIDER | evolution (default) or meta. |
EVOLUTION_API_URLEVOLUTION_API_KEYEVOLUTION_INSTANCE | Internal address, the same key as Evolution, and the name of the instance created in the manager. |
WHATSAPP_WEBHOOK_TOKEN | Incoming webhook secret; it goes in the query string because Evolution doesn’t sign the body. |
ASAAS_API_KEYASAAS_WEBHOOK_TOKENASAAS_BASE_URL | Asaas. Leave blank = no automatic billing; the v1 manual PIX flow remains. |
RESEND_API_KEYEMAIL_FROM | Resend via REST. Blank = no email (everything goes out through WhatsApp only); the sender domain must be verified. |
GEOCODER_PROVIDERGEOCODING_URLGEOCODER_EMAIL | Nominatim from OpenStreetMap, whose usage policy requires a contact email. Empty = radius never verified. |
What’s still missing is what isn’t a variable, but configuration in the dashboard: raio_km, lat_base/lng_base, tolerancia_espera_min, cancelamento_gratis_horas, cancelamento_taxa_percentual, chave_pix e enviar_horarios_semanal. Without the base’s latitude and longitude, the radius is never checked.
This isn’t fine print: it’s a product and legal risk decision, and it’s recorded in the data model itself.
There is no medication administration, nursing, procedures, or clinical care. The system there are no medication or medical record fields — just one free-text “declared restrictions” field, with only the minimum necessary information. The landing page intentionally includes a “what we don’t do” section.
Older adults’ personal data, addresses, and mobility information are sensitive. Collect only what is necessary, record consent during registration, take photos only with explicit authorization, delete data on request, require login to access the dashboard, and enforce isolation with RLS in Supabase.
The MVP exists to run one companion service in an organized way and gather the numbers that validate the price. Only after that comes automation, and only after that comes the network.