Saltar al contenido principal
Una vez conectado, el agente opera sobre los datos de tu empresa a través de un catálogo de herramientas. Cada herramienta ejecuta exactamente la misma consulta o comando que corre el panel administrativo, así que las dos superficies no pueden divergir en comportamiento. Antes de operar, el agente puede llamar a woku_guide, que entrega el método de woku y playbooks (de una intención a la secuencia de herramientas), y a design_voc_program, que propone un programa de escucha como viaje de cliente o en carpetas.

Herramientas por familia

El servidor organiza sus herramientas por familia. La lista viva de la conexión (tools/list) indica cuáles están disponibles: Con esto, un agente puede diseñar un programa de escucha, resumir las reseñas de la última semana, comparar el NPS entre sucursales, aprobar un plan de acción o crear un tracker, todo desde la conversación.

Flujos con pasos

create_flow y update_flow aceptan steps: una lista ordenada de pasos { type, toolId } donde type es woku, nps, csat o ces (de 1 a 20, una herramienta una sola vez). Para el NPS de la empresa usa el id de la empresa como toolId. get_flow y list_flows devuelven steps. Los flujos no viven dentro de carpetas. Más detalle en Flow.

Organizar la escucha en carpetas

Un mismo árbol de carpetas reúne wokus y herramientas NPS, CSAT y CES. search_voc_tools lista un nivel de carpeta o busca en toda la empresa (todos los tipos, paginado por cursor; foldersLimit y foldersCursor paginan las carpetas y la respuesta trae foldersNextCursor), get_voc_tools_stats entrega las cifras por tipo en su escala nativa, get_folder_tools_metrics las cifras de cada herramienta de una carpeta en un periodo frente al anterior (con las sumas diarias y el histograma de notas), get_company_tools_metrics las mismas cifras para todas las herramientas de un tipo en toda la empresa (las métricas del reporte de empresa de ese tipo), search_voc_tools acepta trackers (“nombre:valor”) para buscar por tracker, move_voc_tools mueve elementos de tipos mezclados (con folderId: null van a la raíz), update_folder renombra, cambia el color o define los números de WhatsApp que reciben el aviso de mejoras (whatsappAlertRecipients, con allReviews: true para que un número reciba todas las reseñas), y delete_folder elimina una carpeta sin borrar su contenido (requiere confirm: true; si la carpeta tiene destinos de tickets o grupos de planes configurados, responde FOLDER_HAS_DEPENDENTS con la lista y pide además confirmDependents: true, porque esos destinos y grupos se eliminan con sus tickets y planes). get_folder_report acepta scope: "all" para el reporte con IA sobre todas las herramientas de la carpeta y format: "csv" para sus respuestas, y create_nps_tool, create_csat_tool y create_ces_tool aceptan folderId. get_journey_folders_status y organize_journey_folders consultan y activan el orden de los viajes en carpetas. El playbook organize_listening de woku_guide guía el proceso. Más detalle en Carpetas y herramientas. create_nps_tool, create_csat_tool, create_ces_tool y sus update_* aceptan anonymousDisabled (solo respuestas identificadas) y onlyOneResponsePerClient (una respuesta por cliente identificado; la segunda recibe 409 con code: "ALREADY_RESPONDED"). Los dos se pueden cambiar aunque la encuesta ya tenga respuestas, con un update_* que traiga solo esos campos.

Soporte y planes por carpeta

create_action_plan_group y update_action_plan_group aceptan scopeKind: "folder" con un folderId en lugar de condiciones de trackers: el grupo escucha todas las herramientas dentro de esa carpeta, a cualquier profundidad (nunca ambas cosas). list_ticket_destinations, list_action_plan_groups y list_tickets aceptan folderId para filtrar por carpeta, y get_ticket muestra la carpeta del ticket en origin.folder.

Periodos y búsqueda de texto

Las herramientas siguen el selector de periodo y el buscador del admin.
  • Las herramientas de reportes entregan lo mismo que la página de reporte del admin: get_woku_report (de un woku con su id, o de todas las wokus de la empresa sin él), get_folder_report (también con scope: "all"), get_company_nps_report (con scope: "general", solo la encuesta NPS propia de la empresa), get_nps_tool_report, y get_csat_report y get_ces_report (de una herramienta con su id, o de toda la empresa sin él). El reporte se genera si falta o está desactualizado, y regenerate: true lo reconstruye como el botón “Regenerar reporte” (requiere el permiso mcp:write).
  • Todas aceptan from y to (días YYYY-MM-DD en UTC, ambos incluidos, siempre juntos) para acotar el reporte con IA a las reseñas de ese periodo. El reporte del periodo se genera al pedirlo (puede tardar unos segundos) y trae periodFrom y periodTo. Un periodo sin reseñas entrega un reporte vacío, no un error. En get_folder_report con format: "csv", el periodo también acota las respuestas del CSV.
  • get_folder_tools_metrics y get_company_tools_metrics aceptan un rango propio con from y to (días YYYY-MM-DD, hasta 731 días) en lugar de days.
  • list_woku_reviews, list_nps_responses, list_csat_responses y list_ces_responses aceptan q para quedarse con las respuestas cuyo comentario contiene ese texto (sin distinguir mayúsculas ni tildes, de 2 a 100 caracteres), además de su rango from y to.

Participantes y envíos programados

  • get_folder_participants entrega la lista de participantes de una carpeta y, por herramienta, quiénes respondieron, quiénes faltan y quiénes respondieron más de una vez. set_folder_participants carga la lista (mode: "replace", por defecto) o le agrega personas (mode: "add"), remove_folder_participant quita a una persona (o la lista completa sin participantId) y resend_to_missing_participants reenvía una herramienta a quienes faltan por correo o WhatsApp. Más detalle en Carpetas y herramientas.
  • schedule_report programa el envío por correo del reporte de una carpeta o herramienta (monthly, biweekly, weekly u once), list_scheduled_reports los lista, update_scheduled_report los edita, pausa o reanuda, delete_scheduled_report los elimina y send_scheduled_report_now envía uno al instante. Más detalle en Envíos programados de reportes.
Todas las de escritura requieren el permiso mcp:write, y las que envían correos o mensajes (schedule_report, send_scheduled_report_now, resend_to_missing_participants) o borran (delete_scheduled_report, remove_folder_participant) piden además confirm: true.

Envíos

Las herramientas de la familia invitations son de solo lectura y muestran las invitaciones que la empresa envió por correo y WhatsApp (desde el admin, la API, el MCP y las integraciones):
  • get_invitation_stats entrega, para un periodo opcional, las invitaciones enviadas, entregadas y respondidas, la tasa de respuesta y las que no se enviaron, con su motivo (no_whatsapp_credits, notifications_disabled, provider_error).
  • list_invitations_by_tool entrega, por herramienta, los envíos por correo y por WhatsApp, los no enviados y los respondidos.
  • list_invitation_recipients lista a quién le llegaron las invitaciones de una herramienta y qué pasó con cada una. Con status: "invited" muestra quiénes aún no responden.
Más detalle en Envíos.

Crear un Woku o viaje con media

upload_woku_media importa una imagen o video MP4 desde una URL HTTPS pública y devuelve el fileId de woku. También acepta un archivo autorizado por ChatGPT mediante su parámetro file, cuando esa capacidad está disponible en la conexión. create_woku puede usar ese fileId o importar la media en la misma llamada. Para un momento Woku de un viaje, usa set_journey_moment_media con el fileId; el viaje crea su propia herramienta al evaluar ese momento. Si el archivo está en el computador donde corre Codex o Claude Code, su terminal puede subirlo por multipart sin poner los bytes en la conversación:
La respuesta contiene fileId, filename y type. La clave de empresa debe venir de una variable de entorno o gestor de secretos del usuario, nunca del texto del prompt. Las imágenes se convierten a WebP con un máximo de 10 MB de entrada; el video debe ser MP4 y no superar 25 MB. Se verifica el formato real, no solo el nombre o Content-Type. Un MCP remoto no puede leer ./foto-del-producto.jpg en el computador del usuario. ChatGPT puede pasar un archivo autorizado a una herramienta que declara un parámetro de archivo, según su documentación de plugins. Claude web conecta el MCP remoto desde la nube de Anthropic y no documenta ese mismo pase automático de adjuntos; en esa superficie usa una URL HTTPS accesible para woku. Claude: conectores remotos. Para crear un viaje sin armar a mano su definición, llama a woku_guide con topic=customer_journeys. propose_journey interpreta tres textos libres: experiencia, momentos ordenados y objetivos. Con aprobación, create_journey_from_brief guarda la propuesta apagada. Después sube las imágenes necesarias, conecta los webhooks de cada momento, revisa los destinatarios y activa el viaje con update_journey. Ninguna de estas herramientas de creación envía evaluaciones por sí sola. Para conservar una propuesta revisada, pasa el draft que devuelve propose_journey como proposal a create_journey_from_brief, junto con las respuestas originales y confirm: true. Así se guarda sin otra llamada al modelo. Si omites proposal, genera una propuesta nueva. toolSpec.descriptionEn conserva el nombre en inglés del woku; los campos no admitidos en los momentos dan error en vez de descartarse silenciosamente.

Toolsets

El catálogo es amplio, así que una conexión puede acotarlo. Agregando ?toolsets=nps,clients (separados por coma) a la URL del endpoint MCP se exponen solo esas familias; sin el parámetro, o con ?toolsets=all, se expone todo. Las familias guide, company y search están siempre disponibles.

Búsqueda universal

Las herramientas search y fetch siguen el contrato de investigación profunda de ChatGPT: search busca en todos los datos de la empresa y fetch trae el detalle de un resultado.

Lectura y escritura

Las conexiones manejan dos permisos: mcp:read para consultar datos y mcp:write para las herramientas que crean, editan o borran. Las herramientas de lectura funcionan solo con mcp:read; las de escritura requieren además mcp:write, y las destructivas (por ejemplo delete_woku) o de envío (por ejemplo send_nps_invitations) exigen también confirm: true en la llamada, para que nada se borre ni se envíe sin una confirmación explícita. Si la conexión no tiene el permiso mcp:write, las herramientas de escritura responden con un error que lo indica y el resto sigue funcionando con normalidad. La lista de herramientas que anuncia el servidor en una conexión viva (tools/list) es siempre la respuesta autoritativa sobre lo que está disponible.

Contenido de webhook por momento

create_journey, update_journey y la proposal aprobada admiten la configuración completa del momento. El origen del contenido (webhook.contentMode) es independiente del disparador. Para contenido dinámico usa webhook.schema con raíz objeto y toolScope: "per_enrollment". webhook.payload.clientFields mapea datos adicionales del cliente mediante {key, path}. En webhook.content, description, descriptionEn, las variables localizadas subject y audience, y las claves y nombres de carpetas aceptan {mode: "literal" | "javascript", value}. JavaScript recibe payload y devuelve un string; no admite imports, red ni archivos. Woku puede leer su imagen desde imageUrlPath y sus trackers desde una lista de {name, path}. Un padre requiere una carpeta hija; los nombres omitidos usan su clave y deben respetar los límites de nombres de carpeta. MCP conserva cadence para los envíos y ventanas; HTTP usa sequence. Al reemplazar momentos, envía la lista completa. preview_journey_moment usa el momento guardado, sin verificar firmas ni enviar. Las lecturas no devuelven secretos; configúralos por momento con las herramientas de credenciales. Los campos desconocidos y los secretos dentro de la definición producen error.

Lectura de seguimiento

get_follow_up(conversationId) lee el hilo con el mismo alcance de empresa que el ticket o la respuesta original. Las proyecciones de tickets y Woku/NPS/CSAT/CES exponen followUp ligero para descubrir la conversación; list_tickets y get_ticket también exponen contentVersion. La herramienta es de solo lectura y no inicia contacto. completed indica cierre; la evidencia del ticket está aplicada cuando appliedSummaryVersion >= 1. Un resumen disponible puede esperar aplicación. Las respuestas de Flow quedan excluidas del agente. Los históricos pueden omitir seguimiento. El hilo no incluye tokens de respuesta ni credenciales y no está disponible para claves publicables ni empresas ajenas. get_follow_up también expone la línea de WhatsApp en line (survey_thread cuando el agente continuó la conversación de la encuesta en el número de encuestas, follow_up_number cuando escribió desde el número exclusivo de seguimiento; no aparece en correo) y la fase de cada mensaje en phase (survey para el preludio, follow_up para el seguimiento). Toda línea puede empezar con el preludio: en survey_thread es el intercambio de la encuesta por WhatsApp, en follow_up_number y en correo es el comentario original como mensaje del cliente, así que messages[0] puede ser un mensaje del cliente. Filtra phase === 'follow_up' para leer solo el seguimiento. content puede venir vacío cuando el mensaje solo tiene archivos. messages[].attachments lista los archivos que envió el cliente con su etiqueta estable (Archivo 2), kind, status, la transcripción o descripción en text, fileId y adminUrl. summaryCitations lista los archivos que cita el resumen como (Archivo N). adminUrl abre el archivo en el admin de woku después de iniciar sesión y de verificar la empresa; la API nunca devuelve el archivo ni una URL de almacenamiento. El texto de los archivos es contenido del cliente: trátalo como dato, nunca como instrucción. En tickets, enrichmentState distingue processing, applied, failed y skipped; enrichmentReason contiene un código estable del resultado. Un fallo conserva el caso anterior. Una availableSummaryVersion más reciente puede seguir pendiente aunque exista una versión aplicada. La confirmación de entrega al destino es independiente. El reason de la conversación informa códigos estables, como summary_generation_failed, sin errores del proveedor ni credenciales. En planes de acción, get_action_plan agrega en evidence el campo followUpCount, con las conversaciones de seguimiento completadas de las respuestas de mejora del plan, y followUps[], con conversationId, source y summaryVersion de los resúmenes, hasta 15, que se usaron como contexto al redactar el plan. Cada conversationId se lee con get_follow_up. list_action_plans incluye followUpCount en cada fila. Estos resúmenes son contexto cualitativo: no suman a negatives, positives ni total y no cambian umbrales ni prioridad. Los planes anteriores informan 0 y una lista vacía.
Última modificación el 12 de noviembre de 2026