Vou Contigo acompaña a personas mayores a consultas, exámenes, al mercado, al banco, a la farmacia y a paseos, y mantiene a la familia informada de todo. En la v2, el propio WhatsApp agenda, cancela, muestra horarios disponibles y envía recordatorios automáticamente; el cobro por PIX pasa a Asaas y el familiar obtiene un portal web.

El servicio se ofrece a los hijos y familiares que no pueden estar presentes. La plataforma organiza quién recibirá acompañamiento, cuándo, por quién y cuánto costó realmente, y entrega el informe del día listo para copiarlo en el WhatsApp de la familia.
Cada atención tiene cliente, persona acompañada, tipo, dirección de origen y destino, horario y un ciclo claro de estados: solicitada → programada → confirmada → en curso → completada → reportada.
Al finalizar, el sistema exige la hora real, los minutos de espera, los km recorridos, el estacionamiento, el peaje y el nivel de esfuerzo. Después de 10 a 20 atenciones, puedes revisar el precio sin hacer conjeturas.
El informe se genera con la plantilla de la marca. En la v2, es enviado solo al familiar en cuanto la acompañante finaliza, por WhatsApp y, si hay un correo electrónico registrado, también por correo electrónico.
Un bot de menú numérico agenda, cancela, muestra horarios disponibles e informa el saldo mediante Evolution API, con el número habitual de la empresa conectado por QR. Cuando alguien pide hablar con una persona —o escribe algo fuera del menú—, el bot se queda en silencio hasta que la gestión lo habilita.
El paquete se convierte en un cobro por PIX en Asaas, con QR y opción de copiar y pegar. El webhook lo marca como pagado automáticamente y el nuevo paquete solo se crea cuando ingresa el dinero.
Inicio de sesión mediante enlace mágico en el correo electrónico: saldo, próximas visitas, historial de informes en una página imprimible, solicitar y cancelar visitas, y el calendario en .ics.
La persona que recibe atención no necesita app, inicio de sesión ni celular; solo una ficha bien hecha. Quienes usan la plataforma son la familia (por WhatsApp), la acompañante (desde el celular) y la gestora (desde el panel y Telegram).
Hijo, nieta o responsable. Lo solicita desde la landing o por WhatsApp, recibe la confirmación, el recordatorio y el informe de cada acompañamiento. En el MVP, todo se hace por WhatsApp, con una persona del otro lado.
Quién lo realiza. Usa el panel mobile-first en la calle: consulta la agenda del día, presiona Iniciar, presiona Finalizar, completa los datos de espera/km/costos y revisa el informe. O hace lo mismo desde el bot de Telegram.
Organiza la agenda, aprueba solicitudes, vende paquetes, cobra y revisa las métricas. Recibe cada lead y cada cambio de agenda por Telegram en menos de un minuto.
WhatsApp, Telegram y el panel son canales para actuar sobre la atención; no son la atención en sí. Esta distinción evita que el sistema se convierta en «un chat con base de datos».
Sin automatización de WhatsApp: el cliente sigue hablando con una persona. Lo que hace el sistema es evitar que algo se pierda.
Una página mobile-first con la paleta del logo: el problema, los servicios, los 3 pasos, los planes, quiénes somos, qué no hacemos, FAQ y el botón fijo de WhatsApp con mensaje prellenado. El formulario breve crea un lead y avisa a la gestora por Telegram.
Inicio de sesión de Supabase con roles de gestora y acompañante. Agenda por semana/día, registro de clientes y personas acompañadas, paquetes y saldo de horas, gestión financiera manual con PIX, leads, configuraciones y métricas con exportación a CSV.
Pantalla diseñada para usar en la calle: Iniciar registra la hora real; Finalizar requiere espera, km, estacionamiento, peaje y esfuerzo del 1 al 5. De ahí salen los ingresos por hora efectiva, el promedio de espera y el costo extra promedio.
El texto del informe se prepara con la plantilla de la marca a partir de los campos de la atención. Un botón lo copia para WhatsApp y otro lo marca como enviado, junto con las plantillas de confirmación, recordatorio, saldo bajo y cobro.
En el grupo privado de gestión: avisa sobre nuevos leads, atenciones creadas o canceladas, «mañana hay X a las Y», informes pendientes por más de 2 horas y saldo bajo. Incluye comandos para hacer todo desde el celular.
Un job programado consulta la ruta protegida por CRON_SECRET y envía los avisos del día: recordatorio del día anterior, recordatorio de unas horas antes y aviso de informe pendiente. En la VPS se usa el cron del sistema; en Vercel, Vercel Cron.
La automatización no reemplaza a la persona: le quita el trabajo repetitivo de confirmar, recordar, cobrar e informar.
Menú numérico de cinco opciones a través de Evolution API. Agendar ofrece los horarios realmente disponibles en la agenda; cancelar ya aplica la política e informa la tarifa. Todo queda registrado en RPC de Postgres, no en reglas sueltas en la app.
Confirmación al aprobar la solicitud, recordatorio el día anterior, recordatorio dos horas antes y el informe al finalizar: directamente al cliente, por WhatsApp y por correo electrónico cuando corresponda.
Cobro con QR, webhook autenticado que concilia el pago y cron de renovación de los paquetes mensuales, que avisa unos días antes del vencimiento.
Enlace mágico por correo electrónico, saldo, próximas visitas, informes del mes en una página imprimible, solicitud y cancelación, calendario .ics y opción de recibir horarios por correo electrónico o WhatsApp.
El panel ahora tiene una bandeja de entrada unificada (conversaciones de WhatsApp + leads), una fila de solicitudes para aprobar y una línea de tiempo por cliente con todo lo que ocurrió en cualquier canal.
El destino se geocodifica y se compara con la dirección base. El radio es informativo: avisa a la gestora, pero no bloquea. La tarifa de cancelación y la espera después del tiempo de tolerancia se calculan automáticamente.
La persona que recibe atención sigue sin necesitar ninguna app. Quien interactúa es el hijo, la nieta, el responsable, y lo hace como ya usa el celular.
Menú numérico, sin necesidad de escribir ninguna frase:
¡Hola, Ana! Soy el asistente de Vou Contigo. ¿Cómo puedo ayudarte? 1. Agendar acompanhamento 2. Cancelar ou remarcar 3. Ver horários livres 4. Meu saldo e próxima visita 5. Falar com uma pessoa
Tres cosas ponen la conversación en modo humano: elegir 5, escribir texto libre en el menú y ser un número sin registro. Entonces el bot deja de responder por completo — ni escribir “menu” hace que vuelva — hasta que la gestión envíe /liberar por Telegram. Ya dentro de un flujo (al elegir tipo, día u horario), una respuesta inválida no escala: solo vuelve a pedir el número.
/minha-contaInicio de sesión por enlace mágico enviado por correo electrónico (el código por WhatsApp aparece como “próximamente” en la propia pantalla). El correo electrónico debe ser el mismo que figura en la ficha del cliente en el panel; así se vincula la cuenta con el registro.
Ahí dentro: saldo de horas, próximas visitas, historial de informes, datos de la persona acompañada, solicitar y cancelar visitas, y además:
/minha-conta/horarios — horarios disponibles, con los botones recibir por correo electrónico e recibir por WhatsApp;/minha-conta/relatorios/[mes] — los informes del mes en una página diseñada para imprimir (o guardar como PDF desde el navegador);/minha-conta/calendario.ics — descarga las próximas visitas a la agenda del celular.Nada ocurre sin que una persona lo apruebe: el bot recibe la solicitud y la gestora decide. Lo que cambió en la v2 es que decidir ahora es tocar un botón.
Cada solicitud llega al grupo con tres botones inline: ✅ aprobar, ✏️ ajustar e ❌ rechazar. Al aprobar, se envía automáticamente la confirmación al WhatsApp del familiar.
/conversas muestra quién está esperando a personas reales, /responder envía la respuesta por WhatsApp y /liberar devuelve la conversación al bot.
/resumo ofrece la vista operativa del día y /financeiro, el dinero de la última semana. El cron de las 7 h envía automáticamente el resumen del día; los lunes incluye el informe financiero de la semana cerrada.
/painel/inboxBandeja de entrada unificada: conversaciones de WhatsApp y leads de la landing en el mismo lugar, con el historial de cada conversación y el botón para devolverla al bot cuando se resuelve el asunto.
/painel/solicitacoesLa cola de lo que el bot agendó por WhatsApp y aún necesita aprobación, para que la gestora pueda aprobar, ajustar o rechazar sin abrir cada atención.
Cada cliente tiene una línea de tiempo con todo lo que ocurrió en cualquier canal. En finanzas, el cobro PIX de Asaas con QR y opción de copiar y pegar, conciliado mediante el webhook.
Sin infraestructura propia: Node para Next.js, la CLI de Supabase para la base de datos local, un bot de Telegram y (para publicar) una cuenta de Vercel vinculada a GitHub.
El proyecto usa Next.js 15 con App Router, TypeScript y Tailwind 4.
# verifica la versión node -v npm -v
Postgres, Auth, Storage y RLS ejecutándose en Docker mediante la CLI, sin necesitar un proyecto en la nube para desarrollar.
# levanta el stack local npx supabase start
Un bot solo de Vou Contigo, creado en @BotFather, y el ID del grupo privado de administración.
# en Telegram, habla con @BotFather → /newbot
Los pasos 1 a 6 son la instalación, que se hace una sola vez. El paso 7 es la rutina que se repite todos los días.
Descarga el repositorio e instala las dependencias.
git clone https://github.com/inematds/voucontigo.git cd voucontigo npm install
Copia el ejemplo a .env.local. Ya enumera todo lo que lee el proyecto: Supabase, Telegram, cron y sitio web.
cp .env.example .env.local # .env.local — qué completar NEXT_PUBLIC_SUPABASE_URL= # Supabase > Settings > API NEXT_PUBLIC_SUPABASE_ANON_KEY= # ídem SUPABASE_SERVICE_ROLE_KEY= # ídem (nunca al cliente) TELEGRAM_BOT_TOKEN= # @BotFather TELEGRAM_WEBHOOK_SECRET= # inventa una string larga TELEGRAM_CHAT_GESTAO= # id del grupo de gestión CRON_SECRET= # secreto de Vercel Cron NEXT_PUBLIC_SITE_URL=https://voucontigo.inema.club NEXT_PUBLIC_WHATSAPP_EMPRESA=5551999999999 TZ=America/Sao_Paulo # zona horaria del proceso # --- v2 (vacío = desactivado, no rompe nada) --- WHATSAPP_PROVIDER=evolution # o meta EVOLUTION_API_URL=http://evolution:8080 EVOLUTION_API_KEY= # misma clave de Evolution EVOLUTION_INSTANCE=voucontigo WHATSAPP_WEBHOOK_TOKEN= # lo inventas; va en la query del webhook ASAAS_API_KEY= # empieza en el sandbox ASAAS_WEBHOOK_TOKEN= # header asaas-access-token ASAAS_BASE_URL=https://sandbox.asaas.com/api/v3 RESEND_API_KEY= # opcional; vacío = sin correo electrónico EMAIL_FROM=Vou Contigo <contato@voucontigo.com.br> GEOCODER_EMAIL= # exigido por la política de Nominatim
start inicia Postgres local e imprime las claves; db reset recrea la base de datos aplicando las migraciones de supabase/migrations. Copia la URL y la anon key que aparecen para el .env.local.
npx supabase start npx supabase db reset # aplica migraciones + seed
Inicia el servidor de desarrollo y abre el panel. La cuenta se crea en Supabase Auth (Studio local en http://localhost:54323, pestaña Authentication → Add user); un disparador crea el perfil con el rol predeterminado acompanhante, entonces la primera cuenta pasa a ser gestora por SQL.
npm run dev # http://localhost:3000 · panel en /painel # convierte la primera cuenta en gestora (SQL Editor de Studio) update public.perfil set papel = 'gestora' where id = (select id from auth.users where email = 'voce@exemplo.com');
En Supabase Cloud, en Authentication → URL Configuration → Redirect URLs, registra ambos respuestas de enlace mágico, de lo contrario el correo vuelve con este error: ${NEXT_PUBLIC_SITE_URL}/entrar/callback (portal del familiar) y ${NEXT_PUBLIC_SITE_URL}/login/callback (panel del equipo).
En Telegram, llama al @BotFather, envía /newbot, elige un nombre y un usuario, y guarda el token en TELEGRAM_BOT_TOKEN. Añade el bot al grupo privado de administración y coloca el ID del grupo en TELEGRAM_CHAT_GESTAO. Luego configura el webhook para que apunte a la ruta del proyecto.
# registra el webhook en NEXT_PUBLIC_SITE_URL/api/telegram npx tsx scripts/telegram-set-webhook.ts
Durante el desarrollo, Telegram necesita una URL pública: usa un túnel (p. ej.: ngrok http 3000) y ejecuta el script con NEXT_PUBLIC_SITE_URL que apunta a él.
Publicar es git push: lo demás es webhook. Antes, registra las mismas variables de .env.local en el destino (con las claves de Supabase de producción) y vuelve a ejecutar el script del webhook de Telegram con la URL final.
git add -A git commit -m "feat: v2.0.0 do Vou Contigo" git push # deploy automático · no hay que hacer nada en el dashboard # en la VPS (es donde vive Evolution) — Caddy del host hace TLS y proxy docker compose -p voucontigo -f docker-compose.vps.yml --env-file .env up -d --build # y los jobs se convierten en cron del sistema: cp deploy/vps-cron.example /etc/cron.d/voucontigo
Usa siempre -p voucontigo: o deploy/Caddyfile.snippet hace de proxy para los contenedores voucontigo-app-1 e voucontigo-evolution-1, cuyos nombres dependen de ese prefijo. En la Vercel, o vercel.json ya incluye los tres crons en UTC, pero el de cada hora (recordatorio “2 h antes”) requiere un plan Pro; en Hobby solo se ejecuta un cron al día, sin horario garantizado. En la VPS esto no es un problema.
El ciclo completo de una atención, desde el primer contacto hasta el informe en manos de la familia.
# 1. llega el lead (formulario de la landing o WhatsApp) # → el bot avisa en el grupo; la gestora responde por WhatsApp /lead # muestra los leads nuevos # 2. agendar /agendar # asistente paso a paso (o desde el panel) # 3. el día acordado — la acompañante, desde el celular /hoje # agenda del día, con los ids /iniciar 42 # registra la hora real de inicio # 4. al terminar /finalizar 42 # pide espera, km, estacionamiento, peaje, esfuerzo # 5. informe /relatorio 42 # texto listo para copiar y pegar en el WhatsApp de la familia # 6. saldo del paquete /saldo Maria # horas usadas y restantes
Evolution se ejecuta junto a la app, en la misma red Docker, y se comunica con WhatsApp mediante un número común — sin verificación en Meta, sin plantillas aprobadas y sin costo por mensaje. La alternativa oficial (Meta Cloud API) sigue siendo compatible en el código con WHATSAPP_PROVIDER=meta.
La imagen está fijada en atendai/evolution-api:v2.2.3, con su propio Postgres (sin relación con Supabase). Ocupa cerca de 400 MB de memoria junto a la app.
cp .env.evolution.example .env.evolution # edita: EVOLUTION_SERVER_URL, EVOLUTION_API_KEY (string larga), EVOLUTION_DB_PASSWORD docker compose -p voucontigo -f docker-compose.evolution.yml \ --env-file .env.evolution up -d
Abre https://evolution.inema.club/manager y accede con la EVOLUTION_API_KEY. Crea la instancia con el nombre voucontigo — el mismo valor de EVOLUTION_INSTANCE — pide el QR Code y escanéalo con el celular del número de Vou Contigo (WhatsApp → Dispositivos vinculados). La sesión queda en el volumen evolution_instances y se mantiene tras los reinicios.
El webhook global está desactivado a propósito: se registra en la instancia, a través del manager.
| Campo | Valor |
|---|---|
| URL | https://voucontigo.inema.club/api/whatsapp?token=<WHATSAPP_WEBHOOK_TOKEN> |
| Eventos | MESSAGES_UPSERT e MESSAGES_UPDATE |
webhook_by_events | false — todos los eventos en la misma URL |
webhook_base64 | false — nada de medios en base64 |
Evolution no firma el cuerpo de la solicitud, por eso el secreto viaja en la cadena de consulta: el mismo WHATSAPP_WEBHOOK_TOKEN debe estar en el .env de la app, que compara en tiempo constante y devuelve 401 si no coincide. Los mensajes de grupo, enviados por el propio número o sin texto se ignoran con 200, y el id del mensaje garantiza que nada se procese dos veces.
Las dos pilas comparten la red de Docker, así que la app se comunica con Evolution por el nombre del servicio, sin pasar por Internet.
WHATSAPP_PROVIDER=evolution EVOLUTION_API_URL=http://evolution:8080 EVOLUTION_API_KEY=# la MISMA AUTHENTICATION_API_KEY de Evolution EVOLUTION_INSTANCE=voucontigo WHATSAPP_WEBHOOK_TOKEN=# el mismo de la URL del webhook
No es la API oficial: Meta puede bloquear el número si el comportamiento parece spam. Reglas de uso: responder solo a conversaciones iniciadas por el cliente; enviar solo mensajes sobre citas reales (confirmación, recordatorio, informe, cobro de lo contratado); nada de envíos masivos, listas de difusión ni marketing; mantén un número de reserva. Si el volumen crece, migra a WHATSAPP_PROVIDER=meta.
El paquete de horas se convierte en un cobro por PIX con QR Code y opción de copiar y pegar. Cuando el cliente paga, el webhook de Asaas lo marca como pagado y se crea el nuevo paquete; nunca antes.
Crea la cuenta, genera la API key del entorno de pruebas y apunta la base al sandbox. Cambia a producción solo después de que funcione un cobro completo.
ASAAS_API_KEY=# clave del sandbox ASAAS_BASE_URL=https://sandbox.asaas.com/api/v3 ASAAS_WEBHOOK_TOKEN=# string larga que inventas
En Asaas, apunta a la ruta de la app y define el token de autenticación: llega en el header asaas-access-token y se compara con ASAAS_WEBHOOK_TOKEN (401 si no coincide).
https://voucontigo.inema.club/api/asaas/webhook # header: asaas-access-token: <ASAAS_WEBHOOK_TOKEN>
Eventos importantes: PAYMENT_RECEIVED e PAYMENT_CONFIRMED marcan como pagado; PAYMENT_DELETED e PAYMENT_REFUNDED se revierten. La ruta siempre responde 200 cuando la autenticación es válida —Asaas bloquea la cola ante cualquier respuesta que no sea 2xx— e ignora los eventos repetidos.
El cron /api/cron/renovacoes busca paquetes mensuales que vencen en hasta renovacao_aviso_dias (predeterminado 3), genera el cobro de renovación y se lo envía al cliente. Los paquetes vencidos pasan a ser expirado, con aviso a la administración.
Cambiar ASAAS_BASE_URL para https://api.asaas.com/v3, usa la clave de producción y registra el entorno en la configuración asaas_ambiente del panel. El PIX manual de la v1 sigue disponible como alternativa.
Todo lo que hace el bot también se puede hacer en el panel; el bot es el atajo en el celular. Está en el grupo privado de la gestora con la acompañante.
| Comando | Qué hace |
|---|---|
/hoje | Agenda de hoy, con horario, persona acompañada, tipo, destino y estado. |
/amanha | Agenda de mañana — la base del recordatorio del día anterior. |
/semana | Vista de los próximos siete días para ver la ocupación y los espacios libres. |
/agendar | Asistente paso a paso: cliente, persona acompañada, tipo, fecha y hora, origen y destino. |
/cancelar <id> | Cancela la atención y registra el motivo, aplicando la política de cancelación. |
/iniciar <id> | Marca el inicio real: es el check-in de la acompañante. |
/finalizar <id> | Marca el fin real y solicita espera, km, estacionamiento, peaje y esfuerzo del 1 al 5. |
/relatorio <id> | Arma el informe con la plantilla de la marca para copiarlo y enviarlo a la familia. |
/saldo <cliente> | Horas contratadas, usadas y restantes del paquete de ese cliente. |
/lead | Muestra los nuevos leads que llegaron desde la landing, con el enlace de WhatsApp. |
| Novedades de la v2.0.0 | |
/solicitacoes | Solicitudes pendientes que llegan por WhatsApp, cada una con sus botones ✅ aprobar, ✏️ ajustar e ❌ rechazar. Al aprobar, se envía automáticamente la confirmación al familiar. |
/conversas | Quién está esperando atención humana: las conversaciones en las que el bot dejó de responder. |
/responder <whatsapp> <texto> | Envía la respuesta por WhatsApp sin salir de Telegram. |
/liberar <whatsapp> | Devuelve la conversación al bot y la saca del modo humano. |
/resumo | Resumen operativo de hoy: agenda, pendientes y lo que ya se envió. |
/financeiro | Resumen financiero de la última semana cerrada. |
Además de los comandos, el bot avisa por su cuenta: nuevo lead, atención creada o cancelada, nueva solicitud de WhatsApp, solicitud de atención humana, informe pendiente hace más de dos horas y saldo bajo del cliente. El cron de las 7h envía el resumen del día; los lunes, llega junto con el informe financiero de la semana.
Todas están en .env.example. Las de la v2 siguen la regla “vacío = desactivado”: la app se inicia de todos modos, solo que sin esa automatización.
| Variable | De dónde viene · qué hace |
|---|---|
NEXT_PUBLIC_SUPABASE_URLNEXT_PUBLIC_SUPABASE_ANON_KEYSUPABASE_SERVICE_ROLE_KEY | Supabase → Settings → API. Una service role nunca va al cliente. |
TELEGRAM_BOT_TOKENTELEGRAM_WEBHOOK_SECRETTELEGRAM_CHAT_GESTAO | Token de @BotFather, un secreto que inventes y el ID del grupo privado de administración. |
CRON_SECRET | Secreto que el cron envía como Authorization: Bearer …. Sin él, las rutas de job responden 401. |
NEXT_PUBLIC_SITE_URLNEXT_PUBLIC_WHATSAPP_EMPRESA | URL pública del sitio y el número de la empresa en el formato 55DDDNÚMERO. |
TZ | America/Sao_Paulo. Zona horaria del proceso; configúrala también en las variables del proyecto en Vercel. |
WHATSAPP_PROVIDER | evolution (predeterminado) o meta. |
EVOLUTION_API_URLEVOLUTION_API_KEYEVOLUTION_INSTANCE | Dirección interna, la misma clave de Evolution y el nombre de la instancia creada en el manager. |
WHATSAPP_WEBHOOK_TOKEN | Secreto del webhook de entrada; va en la cadena de consulta porque Evolution no firma el cuerpo. |
ASAAS_API_KEYASAAS_WEBHOOK_TOKENASAAS_BASE_URL | Asaas. Vacío = sin cobro automático; el PIX manual de la v1 continúa. |
RESEND_API_KEYEMAIL_FROM | Resend vía REST. Vacío = sin correo electrónico (todo se envía solo por WhatsApp); el dominio del remitente debe estar verificado. |
GEOCODER_PROVIDERGEOCODING_URLGEOCODER_EMAIL | Nominatim de OpenStreetMap, cuya política de uso requiere un correo electrónico de contacto. Vacío = radio nunca verificado. |
Falta todavía lo que no es variable, sino configuración en el panel: raio_km, lat_base/lng_base, tolerancia_espera_min, cancelamento_gratis_horas, cancelamento_taxa_percentual, chave_pix e enviar_horarios_semanal. Sin la latitud y longitud de la base, nunca se llega a verificar el radio.
Esto no es letra pequeña: es una decisión de producto y de riesgo legal, y está registrada en el propio modelo de datos.
No se administran medicamentos ni se realizan tareas de enfermería, procedimientos o cuidados clínicos. El sistema no tiene campos de medicación ni historia clínica — solo un campo de “restricciones declaradas” en texto libre, con lo mínimo necesario. La landing incluye a propósito la sección “lo que no hacemos”.
Los datos de personas mayores, su dirección y movilidad son sensibles. Recopilación mínima, consentimiento registrado al dar de alta, fotos solo con autorización explícita, eliminación a pedido, acceso al panel solo con inicio de sesión y aislamiento mediante RLS en Supabase.
El MVP existe para gestionar a una acompañante con organización y reunir las cifras que validen el precio. Solo después de eso viene la automatización, y solo después de esta, la red.