Folders and tools

​

How it works

• A folder has a name, an optional color and, when nested, a parent folder. The root is the level with no folder.
• Each tool (woku, NPS, CSAT or CES) lives in one folder or at the root. Existing tools stay at the root until you move them.
• Deleting a folder deletes nothing inside it: its subfolders, wokus and tools move up to the parent folder (or the root).
• Moving is always reversible and does not change a tool’s responses or public links.

​

In the app

• Text analytics (the main one): the AI analysis of every comment of the folder and its subfolders, shaped like the report of a woku (recognitions, improvement opportunities, word cloud and summary). While it is generated, a progress bar shows that the report is on its way.
• Metrics by tool: four cards (one per type, each on its own scale) with the change against the previous period, how the result evolves over time, the distribution of scores, where the responses come from and the tools worth looking at first. You can see the whole history or the last 7, 30 or 90 days.

​

Folders

curl --request POST https://clientapi.woku.app/v1/folders \
  --header "Authorization: Bearer $WOKU_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Post-sale", "color": "#3498db" }'

​

Create a tool inside a folder

curl --request POST https://clientapi.woku.app/v1/csat-tools \
  --header "Authorization: Bearer $WOKU_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Delivery", "question": "How satisfied are you with your delivery?", "folderId": "<folder id>" }'

​

Search and list tools

​

Figures per type

​

Metrics per tool of a folder

• tools: one row per tool with type, id, name, totalResponses, lastResponseAt and two windows, current and previous, each with count, headline (the figure on its native scale), positive and negative (share of positive and negative responses: 4 and 5 or 1 and 2, or promoters and detractors for NPS) and the raw counts positiveCount, negativeCount and scoreSum, to combine tools without rounding drift.
• daily: the daily sums (in UTC) of both periods per type (count, scoreSum and the positive and negative counts), to draw a trend with any grouping. The windows are UTC calendar days ending today, so summing daily over the period gives current.count.
• distribution: how many responses each score got in the period. For NPS position 0 is score 0 (11 positions); for the rest position 0 is score 1 (5 positions).

curl "https://clientapi.woku.app/v1/folders/FOLDER_ID/metrics?days=30" \
  --header "Authorization: Bearer $WOKU_API_KEY"

​

Move in bulk

{
  "items": [
    { "type": "csat", "id": "<tool id>" },
    { "type": "woku", "id": "<woku id>" },
    { "type": "folder", "id": "<folder id>" }
  ],
  "folderId": null
}

​

A folder’s report, PDF and CSV

• GET /v1/folders/:id/report generates (and stores) an AI report over all the tools of the folder and its subfolders: recognitions, improvement opportunities, word cloud and summary. Each quote keeps the context of its tool. Because the scales differ, the report does not include a score distribution. A report that was already generated is reused while the number of reviews does not change; use regenerate=true to force a new one and lang=es or lang=en for the language. A folder with no tools, or with fewer than two commented responses, returns an empty report, not an error.
• GET /v1/folders/:id/pdf downloads the report as a PDF file (lang=es or lang=en), with a breakdown per tool type (count, responses and headline figure on its native scale). It has no rating distribution. It is a binary file: it is on the API and the SDKs, not on the MCP server.
• GET /v1/folders/:id/csv downloads a CSV file with one row per response of every tool in the folder and its subfolders: folder and path, tool type and name, score with its scale, comment, comment type (text or audio), classification (recognition or improvement), customer email, channel and date. A customer that no longer exists leaves the cell empty, and an anonymous response shows as Anónimo.

​

WhatsApp alerts per folder

curl --request PATCH https://clientapi.woku.app/v1/folders/FOLDER_ID \
  --header "Authorization: Bearer $WOKU_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "whatsappAlertRecipients": [{ "whatsappId": "56912345678", "name": "Ana" }] }'

• whatsappAlertRecipients replaces the previous list (up to 10); send [] to remove every number. Numbers use E.164 format without the +.
• Each number can carry sources (woku, nps, csat, ces): the kinds of comment that alert it. If you omit it, the number is alerted for all four. Numbers that existed before this feature keep receiving woku alerts only.
• A folder’s number also receives the alerts of the tools in its subfolders, once even if it is in several.
• Every folder returns the list as whatsappAlertRecipients.
• So that a journey creating a tool per order cannot flood anyone, each number receives at most 5 tool alerts per hour; later ones are dropped.
• The alert is sent once per response and counts as one WhatsApp notification of your plan. It includes the company, the tool with its folder, the customer, the comment and the score on its scale.
• In the MCP, update_folder accepts the same field.

​

Journeys in folders

• The organization is optional per company. You switch it on once and from then on the new tools of each moment are placed in their moment’s folder.
• When you switch it on, a one-off pass in the background moves the tools of existing journeys that still have no folder. It is safe to repeat: it never touches what already has a folder and a second run changes nothing.
• If you move a tool to another folder, it does not go back on its own. Moving or renaming the folders of the tree never breaks a journey: the next case keeps creating its tool in its moment’s folder, wherever that folder is now.
• Integrations sort their own folders the same way (for example Shopify and Pancake).

curl --request POST https://clientapi.woku.app/v1/journey-folders/organize \
  --header "Authorization: Bearer $WOKU_API_KEY"

const status = await woku.journeyFolders.status();
if (!status.enabled) await woku.journeyFolders.organize();
const journey = await woku.journeys.get(journeyId);
console.log(journey.folderId, journey.momentFolders);

​

SDKs and MCP

const folder = await woku.folders.create({ name: 'Post-sale' });
await woku.csatTools.create({ name: 'Delivery', question: 'How satisfied are you?', folderId: folder.id });

for await (const tool of await woku.tools.list({ folderId: folder.id, types: ['csat', 'nps'] })) {
  console.log(tool.type, tool.name, tool.headline.value);
}
const stats = await woku.tools.stats({ folderId: folder.id });
await woku.tools.move({ items: [{ type: 'csat', id: toolId }], folderId: null });
const csv = await woku.folders.csv(folder.id);
const pdf = await woku.folders.pdf(folder.id, { lang: 'en' }); // Uint8Array
const metrics = await woku.folders.metrics(folder.id, { days: 30 }); // per tool, against the previous period
const tagged = await woku.tools.list({ trackers: ['TRR:00482'] });

folder = woku.folders.create({"name": "Post-sale"})
woku.csat_tools.create({"name": "Delivery", "question": "How satisfied are you?", "folderId": folder["id"]})

for tool in woku.tools.list({"folderId": folder["id"], "types": ["csat", "nps"]}):
    print(tool["type"], tool["name"], tool["headline"]["value"])
stats = woku.tools.stats({"folderId": folder["id"]})
woku.tools.move({"items": [{"type": "csat", "id": tool_id}], "folderId": None})
csv_text = woku.folders.csv(folder["id"])
pdf_bytes = woku.folders.pdf(folder["id"], {"lang": "en"})
metrics = woku.folders.metrics(folder["id"], {"days": 30})  # per tool, against the previous period
tagged = woku.tools.list({"trackers": ["TRR:00482"]})