What it is for#
This page lists the 20 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.
How to read them#
- Permission. Each tool belongs to one of the four permissions you choose when authorising. The AI only sees the tools for the permissions you ticked.
winchange_proyectosis always available. proyecto_id. Every tool exceptwinchange_proyectosneeds it: it is the project number returned bywinchange_proyectos. If a project outside the connection is requested, the tool refuses and says which ones are available.- Format. Dates go as
YYYY-MM-DDand 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-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_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_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_personas for the list of those people. Parameters: proyecto_id only.
winchange_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_personas and winchange_notificar need.
| Field | What it does | Values |
|---|---|---|
estado | Which actions are returned. | activas (published and not archived) or todas (includes drafts and archived ones). Default: activas. |
pagina | Page of the list. | Number from 1. Default: 1. |
por_pagina | Rows 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_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_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_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.
| Field | What it does | Values |
|---|---|---|
desde | First day included. | Date YYYY-MM-DD. Default: 27 days before hasta. |
hasta | Last day included. | Date YYYY-MM-DD. Default: today. |
At most 92 days per query.
winchange_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_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_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_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_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_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.
| Field | What it does | Values |
|---|---|---|
dias | It does not change which months are published. | Number from 30 to 180. Default: 90. |
winchange_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.
| Field | What it does | Values |
|---|---|---|
encuesta_id | Which questionnaire to open. | Number from the catalogue. Default: the last one launched. |
oleada_id | Which 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_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).
| Field | What it does | Values |
|---|---|---|
tipo | Which 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). Required. |
ref_id | The location, action or group. | Number. Required with location, action, action_status and action_group. |
pagina | Page of the list. | Number from 1. Default: 1. |
por_pagina | Rows per page. | Number. Default: 50; maximum 100. |
winchange_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.
| Field | What it does | Values |
|---|---|---|
persona_id | Which person. | The person number returned by winchange_personas. Required (or persona_uuid). |
persona_uuid | Alternative to persona_id. | The person's public identifier, if the list includes it. |
Tools that write#
None of them can edit or delete what already exists. What they create 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_personas groups, in two steps:
- 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. - 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.
| Field | What it does | Values |
|---|---|---|
tipo | Which group is notified. | The same as winchange_personas. 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_id | The location, action or group. | Number. Required with location, action, action_status and action_group. Optional with pending_validation: the action whose validations you want to chase. |
titulo | Notification title: what is read on the lock screen. | Text, up to 120 characters. Required. |
mensaje | Notification body. | Text, up to 500 characters. Required. |
personas_ids | Notify only some people in the group. | List of person numbers. It is intersected with the group: it never widens it. |
confirmacion | The 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_crear_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.
| Field | What it does | Values |
|---|---|---|
nombre | Journey name, the one people read. | Text. Required. |
descripcion | One or two sentences about the journey. | Text. Optional. |
orden | Position among journeys in the panel, lowest first. | Number from 0 to 999. Default: 0. |
winchange_crear_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.
| Field | What it does | Values |
|---|---|---|
nombre | Group name, the heading people see above their actions. | Text. Required. |
descripcion | Context under the name. | Text. Optional. |
itinerario | Journey 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. |
orden | Position within the journey, lowest first. | Number from 0 to 999. Default: 0. |
winchange_crear_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.
| Field | What it does | Values |
|---|---|---|
nombre | Action name. | Text. Required. |
descripcion | Context sentences under the name. | Text. Optional. |
puntos | Points paid on completion (for a protocol, for each period completed). | Number from 0 to 1,000. Default: 0. |
umbral | Pass mark for the test. | Number from 0 to 100. Default: 0. Requires at least one question; not allowed in a protocol. |
grupo | Action 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. |
categoria | Category, by its exact name. | Text. Optional. |
plazo_dias | Days to complete it after assignment. | Number from 0 to 365; 0 = no deadline. Not allowed in a protocol. |
inicio_dias | Days after assignment before it can be started. | Number from 0 to 365, not greater than plazo_dias. Not allowed in a protocol. |
bloques | The 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. |
checklist | The 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. |
recurrencia | How often a new protocol period opens. | dia (day) or semana (week, Monday to Sunday). Only with checklist. |
dias_semana | Which days a daily protocol applies. | Numbers from 1 (Monday) to 7 (Sunday) separated by commas. Empty: every day. |
completa_accion | In 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_horaria | Time 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. Withcompleta_accion, the first completed period also marks the action as completed.
For the draft to reach anyone, in Actions you narrow the audience in the Asignación (assignment) step, click Publicar acción (publish action) and apply the assignments with Ver cambios de asignación (preview assignment changes), which first tells you how many people it will reach.
Things to know#
- What is created cannot be corrected through the connector. Review the content in the conversation before asking it to create anything. To correct, publish, archive or delete, use Actions, Action Groups and Journeys.
- 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.
Related#
- Connect your AI to WinChange: connection, permissions and disconnecting.
- The admin panel: the same figures in the panel.
- Send Push Notifications: push notifications from the panel.