Connector tools

Reference for the tools the WinChange connector offers your AI assistant: what each one does, which parameters it takes and what it returns.

What it is for#

This page explains the tools your AI assistant sees when you connect WinChange (how to connect it is in Connect your AI to WinChange). You don't need to use them by hand: you ask the AI in plain language and it picks the tool and fills in the parameters. This page helps you know what it can answer, why it sometimes asks you for something, and what the names in your assistant's activity log mean.

The tool names (winchange_…) and their parameter names are the ones you see in your AI client. Answers come back in Spanish and as data, with notes telling the AI how to read them.

Since 21/10/2026 the connector announces 9 tools: winchange_proyectos, winchange_editar, winchange_crear, winchange_publicar, winchange_consultar, winchange_notificar, winchange_subir_imagen, winchange_exportar_informe and winchange_resultado. The four main working tools group operations by what they do: tipo (or que, in winchange_consultar) picks what to edit, create, publish or query, and the other fields are those of each operation. With ayuda: true they return the full description and fields of an operation without running anything. Below, each operation appears as tool · tipo=…. If your assistant had the previous list saved, refresh the connector in its settings (in ChatGPT: Settings > Apps > WinChange > Refresh) and open a new conversation.

How to read them#

  • Permission. Each tool belongs to one of the permissions you choose when authorising (read data, read people, create and edit the programme, notifications, store and content). The AI only sees the tools for the permissions you ticked. winchange_proyectos is always available. If you connected before a tool existed, connect again so your assistant can see it.
  • proyecto_id. Every tool except winchange_proyectos needs it: it is the project number returned by winchange_proyectos. If a project outside the connection is requested, the tool refuses and says which ones are available.
  • Format. Dates go as YYYY-MM-DD and numbers as whole numbers. If the AI sends something else ("last month", "the next one"), the tool rejects it and explains what it expected, instead of silently ignoring it.
  • Pagination. Long lists arrive in pages, with a count of the total rows and whether there are more.
  • Read before editing. winchange_consultar with que=accion, grupo, itinerario, noticia or cuestionario (and id or part of the nombre) returns the full current values of that item, with the same field names winchange_editar accepts: the AI reads them before changing a text and does not need you to paste it. To add something at the start or end of an action description without rewriting it: anadir_al_principio / anadir_al_final.
  • Long queries. If a tool takes more than about 20 seconds (in large projects, the first time participation is calculated), it answers "in progress" with a job number and keeps calculating. The AI picks up the result with winchange_resultado a few seconds later; you do not need to ask again. Panel figures are kept for ten minutes, so the following queries are immediate.

Read-only tools#

Permission Consultar datos agregados del programa (view aggregate programme data). None of them return people's names.

winchange_proyectos#

The projects you administer that this connection covers, with their number and name. The AI calls it first. No parameters.

winchange_consultar · que=participacion#

The programme snapshot: registered and active people (today, over 7 and 14 days and over the month), actions completed last week against the week before and over 28 days, submissions pending approval and peer validation, overdue actions, points awarded, recent news and comments, store redemptions and a list of recommendations. Parameters: proyecto_id only.

winchange_consultar · que=ubicaciones#

Participation by site or location: people, how many have signed in over the last 28 days, the percentage and the actions completed at each one. It is sorted from best to worst and flags those lagging behind. Each row carries the location number the AI can then use to ask winchange_consultar · que=personas for the list of those people. Parameters: proyecto_id only.

winchange_consultar · que=acciones#

The project's catalogue of actions: name, points, completion method, group, journey, badge, deadline and who it is aimed at. It is the tool that gives each action's number, which winchange_consultar · que=personas and winchange_notificar need.

FieldWhat it doesValues
estadoWhich actions are returned.activas (published and not archived) or todas (includes drafts and archived ones). Default: activas.
paginaPage of the list.Number from 1. Default: 1.
por_paginaRows per page.Number. Default: 50; maximum 100.

Two readings the answer explains: an action aimed at the whole project is normal, not an action without recipients; and with relative dates the deadline counts from each person's assignment, so there is no common date.

winchange_consultar · que=acciones_atascadas#

Which actions are not being completed and where they get stuck: no activity, by completion method and by group, plus the ones that do work. Parameters: proyecto_id only.

winchange_consultar · que=evolucion#

Whether the project is getting better or worse: the last four weeks, the last week against the previous one, reach (distinct people) and the activity that feeds the programme (news, comments, points). Parameters: proyecto_id only.

winchange_consultar · que=serie#

Completed actions and active people, day by day, over the period you ask for, together with the immediately preceding period of the same length for comparison.

FieldWhat it doesValues
desdeFirst day included.Date YYYY-MM-DD. Default: 27 days before hasta.
hastaLast day included.Date YYYY-MM-DD. Default: today.

At most 92 days per query.

winchange_consultar · que=comentarios#

The project's conversation: comment volume, unanswered threads, moderation queue, reactions, which content people comment on and which locations take part. Note: unanswered threads look back 90 days and the rest 28. Parameters: proyecto_id only.

winchange_consultar · que=puntos#

What the programme costs: points issued, redeemed and outstanding since the start, their value in euros using your company's conversion factor, the pace over the last 30 days, what is pending delivery, where points come from, the monthly trend and the store catalogue seen by price. Parameters: proyecto_id only.

winchange_consultar · que=tienda#

The rewards catalogue item by item: price in points and euros, units available, redemptions, delivered and pending delivery, limit per person, and which actions unlock it (all of them must be approved before it can be redeemed) or give it away (when approved, the person gets an automatic order at 0 points). It does not say who redeemed what, or whether a given person can see the item. Parameters: proyecto_id only.

winchange_consultar · que=contenido#

What content the actions have and which are misconfigured: breakdown by content type and completion method, library pieces and alarms (published actions missing what they need to be completed). Parameters: proyecto_id only.

winchange_consultar · que=logros#

Recognition: how many people are on each level of the ladder, action badges, certificates issued and alarms such as a project without a level ladder. It is calculated on the spot: there is no history. Parameters: proyecto_id only.

winchange_consultar · que=pulso#

Team mood: the index for the last closed month (0 to 100, from the average on the 1–5 scale) and the twelve-month trend. Only closed calendar months with at least five distinct people; a month without enough sample comes back empty, not as zero. It does not include comments, questions, answer breakdowns or breakdowns by site or area.

FieldWhat it doesValues
diasIt does not change which months are published.Number from 30 to 180. Default: 90.

winchange_consultar · que=encuestas#

The catalogue of questionnaires with their waves and, for a closed wave, the result of each question. Results are only given for closed waves with at least five people; a whole question is hidden if any of its options has fewer than five distinct people. Free text is never returned.

FieldWhat it doesValues
encuesta_idWhich questionnaire to open.Number from the catalogue. Default: the last one launched.
oleada_idWhich wave to open.Number from the list of waves. Default: the last one launched.

People tools#

Permission Consultar nombres y fichas de personas (view people's names and profiles). None of them return email addresses, and nobody can be looked up by name.

winchange_consultar · que=personas#

Who is behind a number in the panel: the list with first and last names, location and two values that depend on the list (for example, last sign-in and days without signing in).

FieldWhat it doesValues
tipoWhich list.at_risk (have not signed in for a while), registered (everyone signed up), pending_approval (submissions awaiting approval; includes who has to approve), overdue (overdue actions), location (people at a location), action (who has done an action), action_status (each person's status in an action), action_group (progress in an action group), eligibility_group (members of an eligibility group). Required.
ref_idThe location, action, action group or eligibility group.Number. Required with location, action, action_status, action_group and eligibility_group.
paginaPage of the list.Number from 1. Default: 1.
por_paginaRows per page.Number. Default: 50; maximum 100.

winchange_consultar · que=persona#

A person's profile: job title, location and unit, whether they are an administrator or manager, app activity (last sign-in, days without signing in, number of sign-ins), actions assigned and completed, the breakdown by status, pending actions with their deadline (up to 20) and recently completed ones. It does not include email, points balance or transactions, or anything about surveys.

FieldWhat it doesValues
persona_idWhich person.The person number returned by winchange_consultar · que=personas. Required (or persona_uuid).
persona_uuidAlternative to persona_id.The person's public identifier, if the list includes it.

Tools that write#

None of them deletes anything. Everything people already see (publishing, withdrawing, editing something published, removing people from a group, changing job titles, sending a notification) takes two steps: a dry run that changes nothing and says who is affected, and a ten-minute confirmation code the AI can only use after you say yes. What they do is recorded in the audit log under the user who authorised the connection.

winchange_notificar#

Permission Preparar y enviar notificaciones tras confirmar destinatarios y texto (prepare and send notifications after confirming recipients and text). Sends a push notification to one of the winchange_consultar · que=personas groups, in two steps:

  1. Dry run (without confirmacion): nothing is sent. It returns the text, how many people it would reach, how many have the app installed and a confirmation code.
  2. Send (with that code): it sends. The code expires after ten minutes and only works for the same text, group, selection and recipients as the dry run, on the same connection. Sending again with the same code returns the same result without resending.
FieldWhat it doesValues
tipoWhich group is notified.The same as winchange_consultar · que=personas (including eligibility_group). With pending_approval, the notification goes to whoever has to approve, not to whoever submitted. Plus one more, only in this tool: pending_validation, a reminder to the people who still have to validate a colleague's action (not to whoever asked for the validation). Required.
ref_idThe location, action or group.Number. Required with location, action, action_status, action_group and eligibility_group. Optional with pending_validation: the action whose validations you want to chase.
tituloNotification title: what is read on the lock screen.Text, up to 120 characters. Required.
mensajeNotification body.Text, up to 500 characters. Required.
personas_idsNotify only some people in the group.List of person numbers. It is intersected with the group: it never widens it.
programar_paraSchedule the notification instead of sending it now.Date and time with a time zone, for example 2026-11-03T09:00:00+01:00, between one minute and one year ahead. Only with registered, at_risk, overdue, location, action_status, action_group and eligibility_group, and without personas_ids. Recipients are worked out when it is sent.
confirmacionThe dry-run code.Empty for a dry run.

The answer distinguishes recipients (people) from segment rows (one person can appear in several rows), and says whether it has been sent. Sent means the notification service accepted it, not that it reached every phone.

winchange_consultar · que=notificaciones_programadas#

Same permission. Lists the project's scheduled notifications (pending ones first, with the send time and, for those already sent, how many people they reached) and cancels one that has not gone out yet.

FieldWhat it doesValues
cancelarCancel a pending notification.The notification number from the list. Optional.

winchange_crear · tipo=itinerario#

Permission Crear borradores de acciones, grupos e itinerarios (create draft actions, groups and journeys). Creates an empty journey. Nobody sees it until it contains published, assigned actions. It is rejected if the project already has one with the same name.

FieldWhat it doesValues
nombreJourney name, the one people read.Text. Required.
descripcionOne or two sentences about the journey.Text. Optional.
ordenPosition among journeys in the panel, lowest first.Number from 0 to 999. Default: 0.

winchange_crear · tipo=grupo#

Same permission. Creates an empty action group, inside a journey or standalone. It is rejected if the project already has one with the same name.

FieldWhat it doesValues
nombreGroup name, the heading people see above their actions.Text. Required.
descripcionContext under the name.Text. Optional.
itinerarioJourney it belongs to, by its exact name.Text. Optional: empty leaves the group standalone. If it doesn't exist, it is rejected and the answer lists the existing ones.
ordenPosition within the journey, lowest first.Number from 0 to 999. Default: 0.

winchange_crear · tipo=accion#

Same permission. Creates an action as a draft, unpublished and without automatic assignment, with its content in a single call. The audience is left unrestricted, which in WinChange means the whole project once published. It accepts two kinds of content, never both: a lesson (bloques) or a recurring protocol (checklist). If anything is invalid, the answer lists every problem and nothing is created.

FieldWhat it doesValues
nombreAction name.Text. Required.
descripcionContext sentences under the name.Text. Optional.
puntosPoints paid on completion (for a protocol, for each period completed).Number from 0 to 1,000. Default: 0.
umbralPass mark for the test.Number from 0 to 100. Default: 0. Requires at least one question; not allowed in a protocol.
grupoAction group, by its exact name. The action inherits the group's journey.Text. Optional. If it doesn't exist or is inactive, it is rejected and lists the existing ones.
categoriaCategory, by its exact name.Text. Optional.
plazo_diasDays to complete it after assignment.Number from 0 to 365; 0 = no deadline. Not allowed in a protocol.
inicio_diasDays after assignment before it can be started.Number from 0 to 365, not greater than plazo_dias. Not allowed in a protocol.
bloquesThe lesson, in order.List of blocks: text (text, with optional title and kicker), quote (quote, with author) and question (quiz: question, at least two options, the correct one by its position starting at 0, and an optional explanation). No images.
checklistThe checks of a recurring protocol.List of 1 to 20 checks, each with text, optional detail and whether it is mandatory (default: yes). At least one must be mandatory.
recurrenciaHow often a new protocol period opens.dia (day) or semana (week, Monday to Sunday). Only with checklist.
dias_semanaWhich days a daily protocol applies.Numbers from 1 (Monday) to 7 (Sunday) separated by commas. Empty: every day.
completa_accionIn a protocol, whether completing the first period also marks the action as completed. Useful when the protocol is a prerequisite for something else.Yes or no. Default: no (the protocol never completes the action). Only with checklist.
zona_horariaTime zone in which the day or week changes.Europe/Madrid (default), Atlantic/Canary, Europe/Lisbon, Europe/London, Europe/Paris and some American ones.

The answer says which group, journey and category it ended up in, and how it is completed:

  • With bloques: it is approved automatically when the test is passed and pays its points at that moment.
  • Without content: it becomes an action approved by a manager.
  • With checklist: the person ticks the checklist each period and earns the points every time, without review. A period left to lapse closes as not completed. With completa_accion, the first completed period also marks the action as completed.

What is not set when creating (formatted description, fixed dates, how people take part and the cover) is added afterwards with winchange_editar · tipo=accion and winchange_subir_imagen. For the draft to reach anyone: winchange_editar · tipo=audiencia and winchange_publicar · tipo=accion, or from Actions.

winchange_editar · tipo=accion#

Same permission. Changes an action only in the fields sent. A draft nobody has is saved straight away; an action that is published or that someone already has goes through a dry run and confirmation. Once people have it, the content type and the group cannot change, and what is already done (points paid, scores, submissions) is not recalculated. It accepts the fields of winchange_crear · tipo=accion plus:

FieldWhat it doesValues
descripcion_htmlFormatted description.HTML with paragraphs, line breaks, bold, italics, lists, subheadings and https links. Other tags are removed and the answer says so. Replaces descripcion.
fecha_inicio, fecha_limiteFixed dates, the same for everyone.Date YYYY-MM-DD; empty removes it. They replace plazo_dias and inicio_dias. The deadline also applies to people who already have the action.
mostrar_desdeDo not show the action before that day.Date YYYY-MM-DD. Optional.
metodoHow an action without content is completed.aprobacion_responsable (the person writes a comment and their manager approves it), aprobacion_ia (the same, but the AI approves what meets the criteria and leaves doubtful cases to the manager) or confirmacion_persona (the person marks it as done).
criterios_iaWhat the answer must meet for the AI to approve it.Text, up to 2,000 characters. Only with aprobacion_ia.
imagen_urlCover from a public address.An https address of a jpg, png or webp image of up to 5 MB.

Tests, SCORM packages and interactive activities are not edited through the connector.

winchange_editar · tipo=audiencia, winchange_publicar · tipo=accion and winchange_publicar · tipo=retirar_accion#

Same permission. They decide who an action reaches (by units, sites, eligibility groups and tribes; an empty audience means the whole project), publish and assign it, or withdraw it (back to draft, without deleting records or points). Anything already published always goes through a dry run and confirmation; publishing assigns the action but sends no notifications.

winchange_editar · tipo=grupo and winchange_editar · tipo=itinerario#

Same permission. They change the name, description and order of an action group or a journey; a group can also move to another journey if nobody has it yet.

winchange_editar · tipo=noticia and tipo=cuestionario#

The same works for news and surveys, also once they are published or launched: anything people already see goes through a dry run and confirmation, and an edited news item sends no new notifications or emails. On a launched survey you can change the name, description and points and add questions (only people who answer afterwards will see them), but questions that already have answers and the anonymity setting are not touched.

winchange_subir_imagen#

Puts an image on an action, a news item, a reward or an action group. If your assistant works with access to your files and a terminal (for example Claude Code or Codex), it uploads the image itself with the direct upload the tool gives it. Otherwise it gives you a WinChange link: you open it in your browser without signing in again, drop the image (jpg, png or webp, up to 5 MB) and it is set straight away. The code works once and expires after ten minutes. If the image is published online, the AI can pass its address (imagen_url) and WinChange downloads it; if people already see the item, it is confirmed first.

FieldWhat it doesValues
destinoWhat gets the image.accion, noticia, recompensa or grupo. Required.
idThat item's number.Number. Required.
huecoWhere it goes.On an action, portada (cover, default) or imagen (inside image); on a group, portada (default) or icono.
imagen_urlPublic address of the image.Optional: without it, the tool returns the upload link.

Permission: create the programme for actions and groups, content for news, store for rewards.

winchange_consultar · que=grupos_elegibilidad, winchange_crear · tipo=grupo_elegibilidad and winchange_editar · tipo=grupo_elegibilidad#

The list with the read permission; create and edit with the create permission. They show eligibility groups with their member count, whether they are manual or by job title, and where they are used (actions, survey waves, challenges). With the people permission, a group's list also brings its members by name, without email. When creating or editing you add or remove people by number or email (up to 500 at a time) or set a job-title rule, and WinChange then keeps people in or out according to their job title. Removing people, deactivating a group, changing the rule or touching a group in use goes through a dry run and confirmation. Changing members does not assign or withdraw actions at that moment.

winchange_editar · tipo=puestos#

Same permission as create. Updates the job title of many people at once (up to 500 rows with email or person number and job title). Always in two steps: the dry run says, row by row, what changes and what cannot be applied (people outside the project or job titles outside the catalogue); it can only be confirmed with no errors. Applying it recalculates the job-title eligibility groups.

winchange_exportar_informe#

Read permission. Prepares a complete report (without the row limit of the panel download) and gives you a link straight away, valid for thirty minutes. While it is being generated the page says "Preparando el informe" (preparing the report); then it offers Descargar Excel (.xlsx), with dates and numbers as such, and Descargar CSV. You can download it as many times as you like while the link is valid. The content does not go through your assistant. For small tables, such as the action catalogue, the AI can build the Excel itself from what the other tools return.

FieldWhat it doesValues
tipoWhich report.equipo (one row per person), acciones (one row per action assigned to each person) or segmento (the people in a panel segment). Required.
filtrosNarrow the report.Period in days (0 = all history), sites, units, actions or action groups, and the segment with its number. Optional.
incluir_personasName, employee number and email.Only if the connection has the people permission; without it, the report has the WinChange identifier and no personal data.

Things to know#

  • Check before confirming. The dry run says what changes and how many people are affected; the AI cannot make up the confirmation code. Archiving and deleting are done in Actions, Action Groups and Journeys.
  • Upload and download links are personal. They work once and expire within minutes; do not forward them.
  • A push notification cannot be withdrawn. The dry run is there for you to read: check the text and the number of people before saying yes.
  • Personal data stays in your assistant. What the people tools return goes into your AI assistant's conversation.