Lo que ve la persona
El teléfono, con WhatsApp tal cual: burbujas, ticks, la nota de voz, el reenvío, los botones. Nada de lo que aparece en el cristal es un wireframe: es lo que Carlos vería mañana.
Lo que pasa por detrás
Una línea de tiempo numerada. Cada número aparece también pegado a la burbuja que lo provoca. Dice quién hace cada paso: API Mogui · eve Grok Bot Persona.
La regla que lo sostiene
La decisión de producto detrás de cada pantalla, en una línea. Las que todavía son de Carlos están marcadas así en el documento de diseño, sección J.
Cada teléfono trae «Reproducir»: la conversación se escribe sola, mensaje a mensaje, con el «escribiendo…» antes de cada respuesta de Mogui. Sirve para presentarla en una reunión sin leerla en voz alta.
El WhatsApp personal de Carlos. María escribe, deja una nota de voz de 0:32 y manda una foto de referencia.
La petición nace fuera de la plataforma, y ahí se quedaba.
Hoy este mensaje termina en un papel o en la memoria de quien lo recibió. Pedro lo dijo sin rodeos en agosto: me llamaron cinco personas, tú lo anotas en un papel de momento
. La plataforma ya sabe abrir una búsqueda desde un mensaje del inbox, pero este chat no está en el inbox: es el número personal de Carlos, y Mogos no lo ve.
- 1Un texto, una nota de voz y una foto Persona
Tres mensajes distintos. La nota de voz trae lo que el texto no dice: tapa dura, azul marino, logo dorado, «si el mínimo del proveedor es más, dime cuánto».
- 2Carlos responde y promete pasarlo Persona
La promesa es el problema: «lo paso al equipo» hoy significa abrir el admin, buscar a María, copiar el texto y transcribir el audio de oído.
Mantener pulsado el primer mensaje y tocar los otros dos. Texto, audio y foto viajan juntos.
Reenviar a… Mogos. El mismo número de empresa al que escriben los clientes. No hay un número nuevo que guardar.
WhatsApp reenvía el contenido, no al remitente.
Un mensaje reenviado llega marcado como Reenviado, con su texto, su audio y su foto intactos, pero sin decir quién lo escribió. Mogui va a recibir tres mensajes de Carlos, no de María. Por eso el protocolo pide un segundo gesto, también nativo de WhatsApp: compartir el contacto del cliente (o escribir «es para María, +58 412 555 4471»). Con el contacto, Mogui sabe a quién buscar en Mogos.
- 1Tres mensajes llegan al webhook, uno por uno
Meta entrega cada reenvío como un evento aparte, con el audio como
media_idy la marca de reenviado encontext.forwarded. El API ya recibe, verifica la firma y guarda los tres (webhook.processor.ts); hoy no persiste la marca de reenviado, es un campo que se añade. - 2El contacto llega como tarjeta, no como texto
Una tarjeta de contacto es un mensaje de tipo
contactscon nombre y teléfonos. El API ya lo proyecta y lo guarda tal cual (projectInboundContacts): Mogui lee elwa_idsin adivinar nada.
El mismo chat, en tres momentos. Los números de las burbujas son los de la línea de tiempo de abajo: siete pasos entre el reenvío de las 10:09 y la búsqueda con encargado de las 10:16.
10:09 · llega el reenvío. Tres mensajes reenviados, la tarjeta de contacto de María y dos pistas de proveedor que Carlos escribe de su cabeza.
10:13 · acuse, hallazgo, tarjeta. Un acuse de una línea antes de trabajar, a quién reconoció, lo que dijo el audio, y la tarjeta con tres botones. Sin saludo de help-desk.
10:14 · un botón, tres mensajes cortos. Qué quedó, qué salió, qué quedó anclado. Prosa, no memo. A las 10:16, un pedido más en la misma sesión.
Mogui sabe quién le escribe antes de leer qué le escribe.
El número de Carlos está en la plataforma, verificado, con rol de administrador y permiso para crear búsquedas. Eso es todo lo que Mogui necesita para entrar en modo operador: no hay que iniciar sesión, no hay un código, no hay un número nuevo. La prueba de identidad es la misma que usa el registro mágico del bot de clientes: la firma de Meta prueba que el mensaje viene de ese teléfono.
Lo demás es conversación: transcribe, encuentra a María, arma el resumen con los seis campos que Pedro dictó para la tarjeta de «Nueva búsqueda», y pregunta antes de crear. Un botón, y la fila existe en el tablero con su cobro disparado. Si al armar la búsqueda falta un dato que el DTO exige, lo pide antes de la tarjeta (escena 05).
- 1Los tres reenvíos entran por el webhook de siempre API
Firma HMAC verificada, fila en
messagesbajo la conversación de Carlos, audio descargado a S3. Es el camino de cualquier mensaje entrante; nada nuevo hasta aquí. - 2La compuerta de operador decide el camino API
Teléfono en E.164 → usuario con
phoneVerified, activo, rol de equipo, en la lista de operadores y conSERVICE_QUOTES:CREATE. Si pasa, el bot de clientes calla y el API agrupa el lote (8 s sin mensajes nuevos) antes de despachar. La tarjeta de contacto cierra el lote. - 3Mogui recibe el lote con la identidad firmada APIMogui
Una sesión durable por conversación de operador. El principal de la sesión es Carlos (id, rol, permisos, empresa), firmado por el API; nunca sale del cuerpo del mensaje. Mogui transcribe el audio con un paso de voz a texto y guarda el texto en el mensaje, para que el inbox también lo muestre.
- 4Busca al cliente y aparca la pregunta Mogui
find_clientpor teléfono y nombre: una coincidencia. El resumen sale como tarjeta con tres botones (límite de WhatsApp: tres, de 20 caracteres) y el turno queda aparcado hasta 2 h sin consumir nada. - 5El botón vuelve como respuesta a la pregunta aparcada API
Meta entrega el toque como
interactive.button_reply; el API lo traduce a la respuesta de la pregunta pendiente en la sesión de Mogui. Solo el teléfono que inició la sesión puede responderla. - 6Se crea la búsqueda y se dispara el cobro MoguiAPI
POST /service-quotesactuando como Carlos: cliente María, tipo búsqueda de producto, estado Nueva, primer producto con cantidad, MOQ, personalizado y rubro,searchFee: 100, ancla al mensaje. El API resuelve la empresa emisora desdeCompanyUser, escribe la línea «Búsqueda de productos» y corre «Cobrar»: enlace firmado + WhatsApp a María. La respuesta de Mogui vuelve por el callback del API, que la manda porMessagingService. Mogui nunca habla con Meta. - 7Un pedido más, misma sesión MoguiAPI
«Asígnasela a Jesús» es
PATCH /service-quotes/:idconassignedAgentId, validado con el mismo predicado que usa «Tomarla». La búsqueda sigue en Nueva hasta que el pago la mueva, como dicta el ciclo comercial.
Lo que viaja del API a Mogui (el despacho) JSON · un lote por conversación
POST http://mogui:10000/channels/mogos-api/operator· red interna de RenderAuthorization: Bearer <MOGOS_EVE_SERVICE_TOKEN> { "conversationId": "c7f1…",· token de continuación → una sesión por operador"operator": "<JWT HS256 firmado por el API>",· sub: userId · rol · permisos · empresas · exp 10 min"messages": [ { "id": "m1", "type": "text", "forwarded": true, "text": "Hola Carlos, buenas. Quiero 500 libretas…" }, { "id": "m2", "type": "audio", "forwarded": true, "media": { "url": "https://s3…/m2.ogg", "mimeType": "audio/ogg", "expiresAt": "…" } }, { "id": "m3", "type": "image", "forwarded": true, "media": { "url": "https://s3…/m3.jpg", "mimeType": "image/jpeg" }, "caption": "Algo así…" }, { "id": "m4", "type": "contacts", "contacts": [ { "name": "María Ferrer", "phones": ["+584125554471"], "waId": "584125554471" } ] } ], "batchKey": "c7f1…:m4"· idempotencia: el mismo lote nunca se procesa dos veces}
Lo que vuelve de Mogui al API (el callback) JSON · el API decide cómo entregarlo
POST https://api…/messaging/bot/reply· firmado con el mismo secreto{ "conversationId": "c7f1…", "kind": "ask",· reply · ask · escalate · degraded"requestId": "req_01J…",· la pregunta aparcada que espera el botón"messages": [ { "type": "interactive", "header": "Búsqueda lista para crear", "body": "…", "footer": "Vence en 2 h…", "buttons": [ { "id": "approve", "title": "Crear y cobrar 100" }, { "id": "waive", "title": "No cobrar" }, { "id": "edit", "title": "Corregir" } ] } ], "intent": "operator.search.confirm", "toolsUsed": [ "transcribe_audio", "find_client" ] }
Tu número de solicitud es COT-20260906-0031.
Para que nuestro equipo empiece a buscar proveedores, el servicio de búsqueda tiene un costo de USD 100.00. Puedes pagarlo desde el botón de abajo, de forma segura.
Apenas registremos tu pago, comenzamos.
¡Gracias por confiar en Mogos!
Mogos 10:14El WhatsApp de María con el número de Mogos. El aviso llega a las 10:14, un segundo después de que Carlos tocara el botón. Ella paga a las 12:03.
El cliente recibe un solo mensaje, de la plataforma, con el texto que ya está escrito.
Esto no lo diseña Mogui ni lo escribe el modelo: es el aviso que la plataforma manda desde el 4 de septiembre cuando una búsqueda nace con cobro (PR #502). Dice qué pidió, cuánto cuesta empezar y cómo pagar, con el botón «Pagar ahora». Es la promesa que la fase 2 respeta: apenas registremos tu pago, comenzamos
.
- 1La creación dispara el cobro con intención «búsqueda creada» API
create()llama acharge(quoteId, chargedBy, 'SEARCH_CREATED'). El texto esSEARCH_CREATED_TEXTdeservice-quotes-board.service.ts; con la ventana de 24 h abierta sale como mensaje normal con el enlace en el cuerpo, con la ventana cerrada sale la plantillaservice_quote_search_created_prodcon el botón. El cliente no puede notar la diferencia. - 2El botón lleva el enlace de pago firmado
URL dinámica
payments.mogosgroup.com/pay?token=+ el JWT del enlace de pago (vence en 24 h; Stripe, PayPal o Binance). Categoría MARKETING, idioma es, sin cabecera, pie «Mogos». La plantilla está pendiente de aprobación en Meta (META_URLS_TO_UPDATE.md): hasta entonces, con la ventana cerrada el enlace no se entrega y Mogui se lo da a Carlos. - 3El pago mueve la búsqueda y despierta la etapa 2 PersonaAPI
Gaby registra el Zelle; la búsqueda pasa a «En búsqueda» porque tiene encargado (
advanceSearchOnQuotationSettled) y el API publicasearch.sourcing_requesteda Grok Bot. Escena 06.
Ocho situaciones que van a pasar la primera semana. En todas, Mogui dice qué tiene, qué le falta y qué hacer, en su voz. Ninguna termina en una búsqueda a medias: nada se escribe en Mogos hasta el botón, y lo que el DTO exige se pregunta, no se supone.
Faltan datos
El DTO exige cliente y producto; la cantidad caería a 1 en silencio, así que Mogui la exige también. Pide lo que falta en un lote corto, en prosa, y no crea nada hasta tenerlo.
«Corregir»
El botón pregunta qué; el texto libre «cambiar cantidad 300» hace lo mismo sin botón. La tarjeta vuelve como v2 con el dato cambiado marcado y el botón de cobro con el monto nuevo.
El cliente no tiene cuenta
La búsqueda exige un cliente real; crearlo pide un correo y avisa que llegará un acceso. Nunca se inventa una cuenta ni se cuelga la fila de Carlos.
+58 412 555 4471 · 3 envíos · cliente desde 2025
+58 414 200 1188 · sin envíos
Dos clientas iguales
Una lista de WhatsApp (hasta diez filas). El teléfono compartido casi siempre desempata solo; el nombre a secas, no.
El audio no se entiende
Mogui dice qué parte ya tiene y qué le falta. La nota de voz queda anclada igual, para que quien busque la oiga.
Reenvíamela cuando quieras y la retomo desde donde quedó.
12:13Carlos no respondió
La pregunta aparcada tiene fecha de caducidad. Vencer no crea nada y lo dice: un borrador silencioso sería peor que ninguno.
Un número que no es del equipo
Quien no está en la lista de operadores nunca ve el modo operador: recibe al bot de clientes de siempre. La compuerta niega por defecto.
Mogui está caído
Lo dice el API, no Mogui. Nada se pierde: los mensajes ya están en el inbox y el camino manual sigue existiendo.
Grok Bot ya revisó a los proveedores de Mogos con tus dos pistas (Shenzhen Yitai sirve) y sale a Alibaba por tres opciones. Te aviso cuando termine.
12:05- Shenzhen Yitai · proveedor Mogos, tu pista · USD 3,80 · MOQ 300 · 15 días
- Yiwu Jinhao · Alibaba, tu enlace · USD 3,90 · MOQ 500 · 18 días
- Ningbo Bright Paper · Alibaba · USD 3,60 · MOQ 1.000 · 25 días
Jesús ya tiene la tarea «Validar candidatas» en su centro de acciones, y el mensaje para Yitai está redactado: sale cuando él lo apruebe. Nada le llega a María hasta que valide.
Dos avisos de Mogui, horas después, en el mismo chat. Ninguno pide nada: informan y dan un enlace.
El disparo no lo da Mogui: lo da el hecho.
El API despierta a Grok Bot dos veces con el mismo sobre: al crearse la búsqueda (revisa los proveedores de Mogos y las pistas del asesor, sin coste) y al pasar a «En búsqueda», cuando entra el pago o se exonera (sale a Alibaba). Ese cruce ya existe en la plataforma; lo que se añade es el webhook firmado. Así funciona igual si la búsqueda nació de Mogui, del inbox o del formulario del admin. Las pantallas de esa corrida están en Grok Bot busca.
Grok Bot devuelve candidatas, no verdades: proveedor, origen (proveedor Mogos, Alibaba, pista del asesor), precio, MOQ, tiempo, evidencia. Se guardan como opciones marcadas con su origen y no mueven el estado; la tarea de validarlas nace en el centro de acciones del encargado. Ninguna opción pasa a cotizada sin una persona.
- 1Pago registrado → «En búsqueda» → evento API
El paso que ya hace
advanceSearchOnQuotationSettledescribe además una fila en la bandeja de salida (outbox). Un despachador la entrega aGROK_WEBHOOK_URLcon firma HMAC y clave de idempotencia; reintenta si Grok no responde 2xx. Mogui recibe una notificación y avisa a Carlos en su chat (ventana abierta: texto; cerrada: plantilla). - 2Grok devuelve el resultado al API, nunca a WhatsApp Grok BotAPI
POST /integrations/sourcing/resultsfirmado, con el mismorequestId. El API valida, crea las opciones como candidatas (conproposedBy: GROK, sin recomendada, sin cambiar el estado) y notifica: a Jesús en el centro de acciones, a Carlos por Mogui. Un resultado repetido con la misma clave se ignora.
El evento que recibe Grok Bot search.sourcing_requested · v2026-09-06
POST {GROK_WEBHOOK_URL}
X-Mogos-Event: search.sourcing_requested
X-Mogos-Signature: t=1757160300,v1=<hmac-sha256(secret, t + "." + body)>
Idempotency-Key: search:COT-20260906-0031:1
{
"version": "2026-09-06",
"search": { "id": "sq_…", "code": "COT-20260906-0031", "status": "SOURCING", "companyCode": "MOGOS_VE",
"originalRequest": "500 libretas A5 tapa dura, azul marino, logo dorado en portada…", "language": "es" },
"client": { "id": "usr_…", "displayName": "María F.", "country": "VE" }, · sin teléfono ni correo
"encargado": { "id": "usr_…", "name": "Jesús Contreras" },
"requestedProducts": [ { "id": "rp_…", "productName": "Libretas A5 tapa dura con logo", "quantity": 500, "isMoq": false,
"isCustomized": true, "category": "OFFICE_SUPPLIES",
"specifications": "azul marino · logo dorado en portada · 120 hojas · papel 80 g",
"referenceImageUrls": [ "https://s3…/m3.jpg?…" ] } ],
"constraints": { "maxOptionsPerProduct": 3, "origin": "CN", "currencies": ["USD","CNY"], "deadlineAt": "2026-09-07T12:00:00Z" },
"attachments": [ { "kind": "audio", "url": "https://s3…/m2.ogg?…", "transcript": "…que sean tapa dura, azul marino…" } ],
"callbacks": { "resultUrl": "https://api…/integrations/sourcing/results", "statusUrl": "https://api…/integrations/sourcing/status" },
"requestedBy": { "channel": "mogui-whatsapp", "operatorId": "usr_carlos" }
}
Con un cliente, Mogui es el asistente de la guía de voz: se presenta como lo que es, tutea, explica. Con alguien del equipo cambia el registro, no las reglas: habla como crescobot, el agente de ingeniería de crescō. Acuse corto antes de trabajar, conclusión primero, prosa en vez de memos, la longitud la pone el operador, y ninguna de las jugadas de help-desk. Los números, los códigos y la moneda siguen siendo los de la guía.
| Momento | Así no | Así sí |
|---|---|---|
| Arranca el turno | ¡Hola Carlos! 👋 Soy tu asistente inteligente. Voy a analizar los mensajes que me enviaste… | Modo operador, Carlos (Admin). Leyendo los 3 reenvíos. (Y a trabajar; el acuse no es el resultado.) |
| Vuelve con lo que encontró | He procesado el audio exitosamente. A continuación, un resumen: | Es María Ferrer, la encontré por el contacto. La nota de voz dice: «…tapa dura, azul marino…». Con eso tengo todo; te paso la tarjeta. |
| Confirma | ✅ ¡Búsqueda creada con éxito! 🎉 Detalles: • Código… • Estado… • Cobro… | Tres mensajes cortos: «Quedó como COT-20260906-0031 para María Ferrer: 500 libretas A5 tapa dura con logo, en Nuevas, sin encargado.» · «María ya tiene el aviso con el botón de pago de USD 100.» · «Anclé la nota de voz, la transcripción y la foto.» |
| Falta un dato | Error: campo requerido «cantidad». Por favor, indique la cantidad deseada. | Leído. Para armarla me faltan dos cosas: para quién es y cuántas. |
| El operador se equivoca | ¡Claro que sí! Creando la búsqueda a nombre de Carlos Carrasquero… | El cliente tiene que ser María, no tú: bajo tu nombre se pierde del embudo y el cobro te llegaría a ti. ¿La creo para María? |
| Un pedido más | Hecho: he asignado la búsqueda a Jesús Contreras. ¿Hay algo más en lo que pueda ayudarte? | Jesús Contreras queda de encargado. Sigue en Nueva hasta que María pague o la exoneres. |
| Se rinde | Lo siento, no puedo ayudarte con eso. | No pude transcribir la nota de voz: mucho ruido de fondo. ¿Me escribes lo que pidió María? |
| Firma | Atentamente, Mogui, tu asistente de Mogos. | Nada. La sesión se identificó en su primera línea; el inbox etiqueta la conversación como de operador. |
agents/mogui/agent/instructions.mdidentidad y reglas de formato comunes a las dos audiencias · corta y estable · por PRagent/instructions/voz.tsdinámica: al arrancar la sesión mira si el principal es operador o cliente y carga el bloque publicadoagent_skills · mogui · voz-operadorel bloque de voz, versionado · se edita en el admin, en /agentes/instrucciones · publicar exige permisoagent/instructions/voz-operador.mdrespaldo en el repo si no hay versión publicada o Supabase no respondeagent/skills/crear-busqueda/SKILL.mdel procedimiento: acuse, cliente, la lista de obligatorios del DTO, cómo pregunta, la tarjeta, «Corregir»
Una sesión nueva carga la versión publicada. Un borrador no toca ninguna conversación. Los archivos, listos para portar, están en la carpeta instrucciones/ del paquete.
# Voz · modo operador ## Longitud Sigue al operador. A pocas palabras, pocas palabras. Un acuse («Leído», «Voy», «Ok») son una a tres palabras, y ahí paras. Cuando una respuesta tiene dos o tres partes, mándalas como dos o tres mensajes cortos, no como una lista. ## Cómo empieza un turno Tu primera acción visible es una respuesta corta, antes de usar cualquier herramienta. Es un acuse, no un plan ni el resultado: «Leyendo los 3 reenvíos.» En el primer mensaje de la sesión incluye a quién reconociste. Es la única vez que te nombras. ## Jugadas prohibidas - Aperturas de help-desk: «¡Claro que sí!», «Con gusto». - Estado y luego contenido: «Listo:», «Hecho:». El resultado es la frase. - Memos con forma de chat: negritas, viñetas. Prosa. - Cierres de relleno: «¿algo más?», «quedo atento». - Calidez actuada: exclamaciones, emojis, presentarte otra vez. Firmas. ## Autonomía Por defecto actúas. Preguntar se gana por una acción con efectos hacia fuera (crear, cobrar, crear una cuenta), una ambigüedad real, o un dato que solo una persona sabe. Lo que el DTO exige y no tienes se pregunta, no se supone.
No habla con Meta.
Toda respuesta vuelve por el API, donde se validan la ventana de 24 h, las plantillas aprobadas y los límites de formato. Regla de oro del diseño de Mogui, intacta.
No crea nada sin un botón.
Ni búsquedas, ni clientes, ni cobros. La tarjeta muestra lo que va a pasar; la confirmación es un toque y vence a las 2 h.
No le escribe al cliente por su cuenta.
El único mensaje que le llega a María es el del cobro, y lo manda el API con el texto que Pedro apruebe.
No atiende a quien no es del equipo.
La compuerta niega por defecto: un número fuera de la lista recibe al bot de clientes de siempre, con su persona de siempre.
No busca proveedores ni pone precios.
Eso es fase 2 y lo hace Grok Bot, como candidatas que valida una persona. Mogui informa.
No guarda lo que ya guarda Mogos.
Los mensajes, el audio, la transcripción y la búsqueda viven en la plataforma. La sesión de Mogui es memoria de trabajo, no archivo.
Un reenvío. Una fila. Cero papel.
La búsqueda nace donde el cliente la pidió, no donde alguien se acordó de anotarla
Lo que ve Carlos
Reenvía tres mensajes, comparte un contacto, toca un botón. Recibe el código, el estado y el enlace al tablero. Todo en el chat que ya tiene abierto.
Lo que pasa por detrás
La tubería de siempre, una compuerta de operador, una sesión durable en eve, cinco tools que pegan al API como Carlos, y el cobro que ya existía disparado solo.
Lo que decide Carlos
El número (uno o dedicado), el cobro por defecto, el encargado por defecto, qué es Grok Bot y dónde corre. Están en la sección J de DISENO-MOGUI-FLUJO.md.