# woku Complete Product and Integration Guide **Turn the voice of the customer into actions that protect revenue.** woku listens to customers across WhatsApp, phone calls, email, and the web. It uses AI to detect risks and trigger customer support tickets or improvement initiatives in real time. > This is the documentation-oriented companion to [woku's concise LLM guide](https://woku.app/llms.txt). It gives AI systems, implementation teams, solution architects, customer-experience leaders, and operators a self-contained English reference for woku's measurement tools, intelligence, workflows, integrations, public endpoints, and documented boundaries. Use it for research and deeper tasks; use the concise file for product discovery and buying guidance. ## Document status and source policy This guide describes the production product as documented on August 4, 2026. The canonical live sources remain [woku documentation](https://woku.app/docs/en), the [interactive API reference](https://woku.app/docs/api-reference), the [current pricing page](https://woku.app/en/pricing), the [Trust Center](https://woku.app/en/trust), and woku's legal pages. Those sources take precedence if product behavior changes after this file is published. This file intentionally does not reproduce private infrastructure details, credentials, internal runbooks, or undocumented endpoints. It distinguishes generally available behavior from capabilities documented as Corporate, opt-in, or limited. It also avoids fixed prices and quotas when the live commercial source is more appropriate. The terms “woku” and “Woku” may appear in product materials. In this guide, **woku** means the company and platform, while **a woku** means the platform's visual 1-to-5 feedback instrument. Context should make the distinction clear. ## Production surface map | Surface | Audience | Purpose | | --- | --- | --- | | [woku.app](https://woku.app) | Public | Main Spanish website, positioning, account entry, blog, customer stories, pricing, and legal information. | | [woku.app/en](https://woku.app/en) | Public | English product website. | | [woku.app/docs](https://woku.app/docs/en) | Public | Official product, operations, integration, API, and security documentation. | | [woku.app/llms.txt](https://woku.app/llms.txt) | AI and public | Concise commercial and product-discovery guide. | | [woku.app/llms-full.txt](https://woku.app/llms-full.txt) | AI and technical users | This expanded documentation guide. | | [admin.woku.app](https://admin.woku.app) | Authenticated customers | Administration, configuration, analysis, reporting, automation, company management, and billing. | | [review.woku.app](https://review.woku.app) | Respondents | Public response application for visual wokus and related measurement routes. | | [nps.woku.app](https://nps.woku.app) | Respondents | NPS-facing production host served by the same public response application. | | [form.woku.app](https://form.woku.app) | Respondents | Forms-facing production host served by the same public response application. | | [clientapi.woku.app](https://clientapi.woku.app) | Customer integrations | External REST API base. Version 1 endpoints use the `/v1/` prefix. | | [api.woku.app](https://api.woku.app) | woku applications | Internal product API. It is not the general customer REST base. | | [api.woku.app/mcp](https://api.woku.app/mcp) | Approved AI clients | Documented remote Model Context Protocol server with OAuth authorization. | The three response hosts route to the same deployed response frontend but provide recognizable entry points for different instrument types. A valid public response link normally includes identifiers or tokens; opening only a host root is not a substitute for sharing an actual measurement. ## Product model: distributed, contextual listening Traditional feedback programs often ask many questions after the full experience has ended. That creates delay, recall bias, questionnaire design work, and response fatigue. woku's operating model is different: measure a small number of things close to the moment where they happened, use the instrument that matches the decision, and retain an open explanation whenever the customer wants to provide one. A common customer journey might use: | Journey moment | Operational question | Recommended instrument | | --- | --- | --- | | Purchase | Was the customer satisfied with the transaction? | CSAT | | Delivery | What happened and why did it matter? | woku | | Support | How easy was it to resolve the need? | CES | | Post-sale use | What is working or failing in the real experience? | woku | | Relationship review | Would the customer recommend the organization? | NPS | | Multi-part event or program | How did each important component perform? | Flow | | Registration or structured intake | What concrete information is required? | Forms | This is a design pattern, not a rigid prescription. Teams should choose moments that can lead to action, define frequency rules to avoid over-contact, and decide who will respond to evidence before launching another measurement. ## Shared concepts ### Company and tenancy Customer data and configuration are scoped to a company. Administrative users belong to companies with roles such as owner, administrator, or member. Public API company keys resolve the company for each request. MCP authorization binds one approved connection to one company. Reporting, clients, trackers, alerts, and automation operate inside that company scope. ### Instrument versus response An instrument defines what a respondent sees and what is being measured. A response records the score, structured fields, explanation, respondent identity when supplied, channel, timestamps, and relevant business context. A Flow references underlying instruments; its individual responses remain attached to those instruments. ### Production versus sandbox Production data affects real reports and workflows. The sandbox is an isolated environment for test instruments, disposable responses, keys, integrations, and ingestion pipelines. Ticket generation and other production actions may deliberately exclude sandbox responses. Never validate a customer-facing automation by sending arbitrary test records into production when the sandbox or a dry run is available. ### Channel The response channel records how a signal entered woku, such as the public review app, WhatsApp, email invitation, web widget, mobile SDK, API, or Shopify-related flow. Channel data can be used as a reporting dimension. Historical records may not always have the same channel metadata as newer responses. ### Client A client is the company-scoped profile of a person who interacts with the organization. It can contain encrypted contact details, configurable attributes, and linked response history. Email is the primary deduplication key documented for automatic unification inside a company. Clients can be created through responses, manually, through imports, or through data flows. ### External tracker A tracker is a business-defined identifier that links feedback to the organization's existing context. Typical trackers include country, branch, store, order, campaign, account, property, program, instructor, product line, or support case. A tracker definition belongs to a company; tracker values can be attached to wokus and other VoC instruments. Reporting, searches, action-plan groups, and ticket destinations can use them for segmentation and routing. ## Measurement instruments ### 1. Visual woku A woku represents a product, service, process, activity, or moment through an image or video and a short description. The respondent recognizes the subject, gives a 1-to-5-star rating, and can explain the experience in writing or through a voice note. The explanation is central because it connects a score to a cause. Appropriate uses include store service, delivery, property visits, restaurant experiences, workshops, classes, events, products, internal services, onboarding stages, and post-sale interactions. A visual woku is especially useful when open feedback is more valuable than a predetermined list of questions. Administrators can create, edit, close, organize, share, and report on wokus. Hierarchical folders can reflect regions, locations, programs, products, or any other operating structure. External trackers provide a second, system-oriented structure for joining feedback with CRM, ERP, order, or case identifiers. Response content can include: - A star rating from 1 to 5. - A written explanation, up to the documented limit for that channel. - A recorded voice note and server-generated transcription. - Optional respondent identity such as email or phone, or an anonymous choice when allowed. - Response-channel and tracker context. Reports can show counts, average rating, recognition versus improvement, words and summaries, actions suggested by AI, source evidence, and trends. The visual report builder can use creation date, rating, feedback type, opinion type, channel, comment, and woku as fields. See [the visual woku concept](https://woku.app/docs/en/core-concepts/woku) and [the tools overview](https://woku.app/docs/en/fundamentals/tools). ### 2. NPS Net Promoter Score measures recommendation and relationship health. Respondents answer on a 0-to-10 scale: - 0 through 6: detractors. - 7 through 8: passives. - 9 through 10: promoters. The score is the percentage of promoters minus the percentage of detractors, producing a value from -100 to 100. A response may be tied to a specific NPS tool or recorded at company level. woku supports identified or anonymous responses and an optional text or audio explanation. Use NPS for relationship-level questions, program health, brand recommendation, or a clean first signal in a multi-step Flow. Avoid treating NPS as a complete diagnosis: its open explanation, segmentation, and supporting metrics are what help a team decide what to do. NPS reporting can include response volume, NPS, promoter/passive/detractor shares, text and audio evidence, AI summaries, and tracker-based segmentation. Company-level and tool-specific reports are available through documented surfaces. See [NPS documentation](https://woku.app/docs/en/core-concepts/nps). ### 3. CSAT Customer Satisfaction Score asks how satisfied a respondent is with a defined subject after a concrete experience. The scale is 1 to 5. The score is required; the explanatory text or audio comment is optional. Documented reporting includes: - Average score. - Top-two-box share, the percentage of 4 and 5 responses. - Satisfied, neutral, and dissatisfied distribution. - Response count and comments. CSAT is appropriate immediately after purchases, onboarding steps, completed service, appointments, activities, or other moments where satisfaction is the operative question. It should be scoped to a recognizable subject rather than a vague overall relationship. See [CSAT documentation](https://woku.app/docs/en/core-concepts/csat). ### 4. CES Customer Effort Score asks how easy it was to complete a defined action. The scale is 1 to 5, where 5 means very easy. The score is required; a text or audio comment is optional. Reporting uses the same average, top-two-box, distribution, and count logic as CSAT. CES is most useful for support, returns, troubleshooting, onboarding, post-sale requests, and administrative processes. A low effort score points toward friction, but the comment and tracker context are needed to locate the cause. See [CES documentation](https://woku.app/docs/en/core-concepts/ces). ### 5. Flow A Flow combines several visual wokus into one guided session and can optionally begin with NPS. The respondent uses one link, sees progress, and provides identity once for reuse across the session. If NPS is included, it comes first so the relationship signal is not influenced by detailed prompts that follow. Each answer is stored in its underlying instrument. This preserves the individual woku and NPS reports while adding the context that the same person completed them in one journey. Use Flow for events, courses, programs, multi-stage purchases, or service experiences with several components that deserve separate feedback. A Flow is not a generic branching survey engine and does not imply that every instrument type can be inserted as a step. The documented model is multiple wokus with optional NPS at the beginning. See [Flow documentation](https://woku.app/docs/en/core-concepts/flow). ### 6. Forms Forms collect structured data rather than a rating. Configurable field types include text, number, date, email, phone, single selection, and multiple selection. Administrators choose field order, required fields, anonymous behavior, identification rules, and response limits. Use Forms for registrations, respondent attributes, service details, event intake, research variables, follow-up information, or operational facts that should be stored in defined fields. Forms can be shared through links, QR, bulk invitations, the API, and data flows. Responses can be inspected, exported, and used in reports. Forms do not replace woku, CSAT, CES, or NPS when the goal is to measure an experience. Conversely, a rating instrument should not be forced to collect a large structured record when Forms is the appropriate tool. See [Forms documentation](https://woku.app/docs/en/core-concepts/forms). ## Multilingual measurements Corporate multilingual surveys can keep one instrument and one consolidated result set while presenting translated content. The documented selection order is an explicit user preference when available, then browser `Accept-Language`, then the instrument's primary language. Respondents can manually change language when several are enabled. Missing translations fall back to the primary language. Spanish (`es`) and English (`en`) are currently documented as supported. Forms can use AI-assisted translation with human review. Additional languages require product enablement and should not be represented as already available until confirmed. See [multilingual survey documentation](https://woku.app/docs/en/guides/multilanguage-surveys). ## Public response experience Respondents do not need to install an application. They open a link, scan a QR code, receive an invitation, interact with a widget, or respond through an integrated channel. The public frontend is mobile-first and supports the relevant flow for visual reviews, NPS, CSAT, CES, Flow, and Forms. Identification rules depend on the instrument and company configuration. A response may be identified by email, phone, or linked invitation context, or may be anonymous when allowed. Integrators should not assume that every response contains contact information. Webhook payloads deliberately avoid including customer contact data. The response application handles states such as loading, invalid or expired links, successful completion, and quarantine blocks. Public errors should not expose internal rule names or security details. ## Clients and respondent identity When a respondent supplies an email, woku can find or create the company-scoped client and associate responses from different tools with that profile. The client page can expose contact data, configurable attributes, response statistics, and response history. Companies can import clients by CSV, search them, edit them, export them, and define a client-capture form. Identity choices affect downstream behavior: - Anonymous feedback can inform aggregate analysis but cannot support direct service recovery in the same way as identified feedback. - The support-ticket engine requires an identified, non-anonymous client. - Quarantine rules currently use email or phone as respondent identifiers. - External systems should pass stable business identifiers through trackers or documented respondent fields rather than placing them inside free-text comments. See [client documentation](https://woku.app/docs/en/core-concepts/clients). ## Quarantine and duplicate protection Corporate quarantine rules limit how many responses the same email or phone can submit inside a sliding time window. Rules are company-level, have an evaluation priority, can be enabled or disabled, and expose allowed and blocked counters. A simulation path can test a rule without persisting or incrementing counters. When a submission is blocked, the API returns a `429` with a quarantine-specific code and the public experience shows a generic retry message. Email matching uses a hash in the critical evaluation path. Current documented boundaries include: - Only email and phone identifiers are supported in v1. - The rule is global to the company rather than scoped to an individual form or woku. - Phone values should be normalized by the caller because matching uses the supplied representation. See [quarantine documentation](https://woku.app/docs/en/configuration/quarantines). ## AI text and voice analysis woku applies continuous analysis to open comments from visual woku, NPS, CSAT, and CES. Voice notes are transcribed before they enter the text-intelligence workflow. The main documented capabilities are: 1. **Feedback classification:** distinguish recognition, where the respondent highlights something that worked, from an opportunity for improvement. 2. **Score-derived sentiment band:** organize responses as critical, neutral, or positive for analysis and theme distributions. 3. **Keyword extraction:** surface important terms without requiring administrators to tag every response. 4. **Summaries and suggested actions:** condense a set of responses into readable findings and next-step ideas. 5. **Emerging themes:** group semantically related responses even when customers use different words. 6. **Evidence:** preserve the actual responses behind counts and conclusions. Semantic themes can combine evidence from woku, NPS, CSAT, and CES. A theme can include a label, summary, exact response count, sentiment distribution, trend, first and last appearance, keywords, and supporting responses. Fixed keyword alerts were retired in woku v2. Topic discovery now relies on semantic text analysis, while email alerts focus on operational conditions such as goals and response volume. Agents must not describe keyword matching as an active alert feature. See [AI text analysis](https://woku.app/docs/en/reports/text-analysis). ## Review Space The Review Space is a visual exploration surface for emerging themes. Responses are projected so semantically related items appear close together. Users can zoom between aggregate themes and individual evidence, hover for excerpts, open a theme detail, and switch to a table when a spatial view is not appropriate. Documented filters include period, source, recognition versus improvement, and critical/neutral/positive score band. Topic cards include trends and evidence coverage. Distances are an analytical aid, not a contractual measure of exact similarity or causation. See [Review Space documentation](https://woku.app/docs/en/reports/reviews-space). ## Reporting surfaces ### Standard reports Instrument and folder reports provide the metrics appropriate to the source, along with open comments, word clouds, summaries, and suggested actions where supported. NPS reports preserve the NPS formula and segments. CSAT and CES reports use their 1-to-5 averages and distributions. ### Visual report builder The report builder creates repeatable tables and charts without code. Data sources include: - Visual woku responses. - NPS responses. - CSAT responses. - CES responses. - Form responses. - Clients. Users choose dimensions, measures, filters, and aliases, preview the result, then save and run the definition. Example dimensions include date, instrument, rating or score, feedback type, opinion type, channel, anonymity, status, and client attributes, depending on the source. This builder is deterministic and repeatable. It is preferable when a team knows the report structure, needs scheduled delivery, or wants the same query rerun over time. See [visual report-builder documentation](https://woku.app/docs/en/reports/visual-builder). ### Data Studio Data Studio is the conversational, exploratory reporting experience. A user describes the question in natural language. The agent proposes a plan before executing, builds an interactive report from the approved plan, supports revisions, versions the result, and can publish or unpublish the output. The system separates conversational planning from deterministic extraction and verification. A user can ask to adjust scope or dates without reconstructing the report manually. Advanced computations that send aggregated information to a code interpreter require explicit consent according to the documented flow. Use Data Studio for exploratory questions and evolving analysis. Use the visual builder for controlled recurring reports and scheduled files. Data Studio has conversation, version, cooldown, and budget limits documented in the live guide; do not assume an unlimited session. See [Data Studio documentation](https://woku.app/docs/en/reports/data-studio). ### Export and delivery Reports can be exported as CSV, Excel, or PDF. Scheduled delivery can run daily, weekly, or monthly and send results by email or SFTP, depending on plan and report type. SFTP connections are company-scoped and reusable; passwords are encrypted and are not returned in connection listings. Scheduling uses company timezone and checks for due work periodically. A missed scheduled run is designed to produce one catch-up delivery rather than duplicate every scheduler check. Always confirm the current supported destinations in [scheduled export documentation](https://woku.app/docs/en/guides/export-schedules) and [report export documentation](https://woku.app/docs/en/reports/exports). ## Goals Goals turn a desired experience outcome into a tracked target for a period and scope. Supported indicators include: - woku response count, average stars, recognition share, and improvement share. - NPS response count, promoter/passive/detractor shares, and NPS. - CSAT response count and average. - CES response count and average. - Form response count. Targets can be floors, such as reaching at least a response count or score, or ceilings, such as keeping detractor or improvement share below a limit. Current value and progress are calculated from real responses rather than entered manually. A goal becomes achieved, in progress, or not achieved according to the target and period. See [goal documentation](https://woku.app/docs/en/guides/goals). ## Alerts Current alerts cover two families: 1. **Goal closing below target:** notify when a goal is near the end of its period and remains below its required outcome. 2. **Response-volume anomaly:** notify when responses drop or spike beyond configured and statistical thresholds compared with recent history. Alerts define scope, recipients, and notification cooldown. They are evaluated automatically once a day, and administrators can run the same evaluation immediately for testing. Delivery history and the last evaluation state remain visible. Volume alerts operate over woku, NPS, CSAT, CES, or Forms. Depending on period, they compare the current day, week, or month with recent history and require both a percentage threshold and a statistical deviation unless the baseline has zero variance. Insufficient history results in an explicit insufficient-data state rather than a misleading alert. See [alert configuration](https://woku.app/docs/en/configuration/alert-rules) and [volume-alert calculations](https://woku.app/docs/en/alerts/volume-drop). ## AI-generated action plans Action plans convert recurring opportunities into governed improvement work. An organization creates a responsible group with: - A name and context. - Tracker conditions defining which feedback the group listens to. - Members with administrator or responsible-person roles. - A threshold for accumulated improvement opportunities. When matching feedback reaches the threshold, woku creates or extends a draft. The draft freezes its evidence window, tracker conditions, counts, and representative customer excerpts. Deterministic processes calculate metrics and priority inputs; AI drafts the title, summary, objective, expected impact, tasks, and pattern names. Group members can inspect the source responses, edit tasks, and collaborate with the AI agent. Group administrators control approval, cancellation, reopening, and delivery. States include review, approved, sent, cancelled, and delivery error. The history records generation, evidence changes, manual edits, approval, reopening, delivery, and failures. Plans are not created by the alert module. Alerts cover goals and volume; action-plan groups independently accumulate matching improvement feedback. This distinction prevents an AI assistant from inventing a direct alert-to-plan dependency. See [action-plan group setup](https://woku.app/docs/en/action-plans/create-plan), [review and approval](https://woku.app/docs/en/action-plans/kanban), and [evidence behavior](https://woku.app/docs/en/action-plans/link-alerts). ## Support tickets The Corporate support module evaluates identified, non-anonymous negative feedback from woku, NPS, CSAT, and CES. Form answers do not directly generate tickets, but can contribute to a client's history. Sandbox responses do not generate production tickets. Tracker conditions select the first enabled destination that matches. There is no implicit default destination: if no destination matches, no ticket is created. For a matching destination, AI triage reviews the feedback and relevant customer history to decide whether escalation is warranted and can draft title, severity, summary, description, milestones, customer request, suggested action, churn risk, and language. Customer identity is attached deterministically rather than sent to the language model according to the documented design. Delivery runs asynchronously with retries. Destinations include Zendesk and a configurable custom HTTP service. Operators can inspect and edit ticket fields and follow delivery history. See [support-ticket documentation](https://woku.app/docs/en/guides/support-tickets) and [Zendesk integration](https://woku.app/docs/en/integrations/zendesk). ## External REST API v1 ### Base and authentication The customer-facing base is [clientapi.woku.app](https://clientapi.woku.app). Version 1 resources use `/v1/`. Requests authenticate with the company key as a Bearer value in the `Authorization` header. The company owner obtains the key from the company information section in [the admin application](https://admin.woku.app). Do not direct customers to use [api.woku.app](https://api.woku.app) as the general REST base. That host serves woku's internal applications. The documented MCP endpoint on that host is a separate, intentional external surface. ### API use cases The documented v1 API supports: - Validate the company associated with a key. - Create a visual woku using a public media URL or multipart upload. - List wokus and retrieve details, statistics, or reviews. - Submit woku ratings with text or audio. - Share a woku by email. - Capture normalized mobile events for woku, NPS, CSAT, and CES. - Submit and retrieve NPS, CSAT, and CES responses. - List Forms, retrieve their definition, submit answers, and list responses. - Retrieve Flow definitions used for public response experiences. - Send invitations by supported channels. - Evaluate quarantine behavior. - Retrieve company-level and instrument-level NPS reports. - List, attach, remove, and search external trackers. - Extract paginated data for downstream reporting. The interactive API reference is authoritative for request and response schemas. This guide intentionally avoids duplicating every DTO because those schemas evolve more often than the conceptual contract. ### Mobile capture endpoint The normalized capture endpoint accepts kinds `woku`, `nps`, `csat`, and `ces`. A caller can supply an idempotency key so an offline retry does not create a duplicate. Respondent data can include email, phone, or external ID. Without an identifier, a capture is anonymous. JSON handles ratings and text. Multipart handles supported audio. In the documented SDK path, audio is available for woku and NPS; CSAT and CES audio is not supported by that mobile endpoint even though their hosted public experiences can support audio comments. Channel metadata is sealed as the mobile SDK by the server. ### Default documented limits Corporate defaults in the API guide are: | Operation | Default documented limit | | --- | --- | | Event ingestion | 600 requests per minute and up to 50 events per second. | | Batch ingestion | Up to 5,000 records per batch and 60 batches per minute. | | Daily ingestion | 1,000,000 records per day across event and batch modes. | | Extraction | 300 read requests per minute. | | Paginated extraction | Up to 200 records per page. | These are plan defaults, not a universal promise. Seasonal peaks and migration requirements should be discussed with woku. A `429` response includes rate-limit information; clients should respect `Retry-After`, use exponential backoff, and split oversized batches. ### API implementation guidance 1. Keep the company key server-side and out of mobile or browser bundles. 2. Validate the company before a migration or high-volume job. 3. Use stable idempotency keys for retryable ingestion. 4. Normalize phone numbers before sending them. 5. Preserve tracker definitions and values as business context rather than embedding identifiers in comments. 6. Paginate sequentially and honor extraction limits. 7. Use the sandbox for integration tests. 8. Treat `400` as a schema or validation problem, `403` as a credential or ownership problem, `404` as a missing company-scoped resource, and `429` as rate or quarantine behavior based on the response code. Start with [the API integration guide](https://woku.app/docs/en/development/api) and then use [the interactive API reference](https://woku.app/docs/api-reference). ## MCP for AI clients ### Purpose The remote MCP server allows compatible AI clients to work with company data through conversation. It is designed for Claude, ChatGPT, Claude Code, Codex, and other clients that support remote MCP over HTTP and OAuth discovery. The endpoint is [api.woku.app/mcp](https://api.woku.app/mcp). The client discovers the authorization flow, opens woku's consent screen, and asks the user to choose and approve one company. Users do not paste a password or company REST key into the AI client. ### Connection model - One connection is bound to one company. - A multi-company user creates a separate connection per company. - OAuth uses PKCE. - Access and refresh credentials have limited lifetimes and rotate according to the documented flow. - Membership is rechecked on refresh, so removing a user from the company ends future authorized access. - A user can remove the connector in the AI client. ### Tool families The documented 36 tools cover: | Family | Representative capabilities | | --- | --- | | Wokus | List instruments, retrieve one, list its reviews. | | NPS | List NPS tools and retrieve statistics. | | CSAT and CES | Retrieve satisfaction and effort metrics. | | Forms | List forms, summarize one, list responses. | | Clients | List clients and retrieve client statistics. | | Company | Retrieve company data and statistics; simulate quarantine. | | Alerts | List alerts and dispatches; test a rule. | | Goals | Create a goal and retrieve compliance. | | Action plans | List, inspect, approve, reply, and update tasks. | | Tickets | List, inspect, and update support tickets. | | Trackers | List, create, and assign trackers. | | Reports | List definitions and run a report. | | Review intelligence | Query themes and evidence. | | Universal research | Search company data and fetch a selected result. | Read access uses `mcp:read`. Tools that create or modify supported resources require `mcp:write`. The catalog deliberately excludes destructive and high-risk administration such as arbitrary deletes, billing changes, member or security management, and customer-facing bulk sends. ### ChatGPT note ChatGPT can use `search` and `fetch` for deep research without the full developer tool catalog. Developer mode is required for the complete set of MCP tools according to the current connection guide. ### Appropriate agent tasks - Find improvement themes for a period and return evidence. - Compare NPS, CSAT, or CES across tracker-defined scopes. - Summarize recent visual woku reviews. - Check goal compliance and active alerts. - Inspect or approve an action plan with write permission. - Review and update a support ticket. - Run a saved report definition. An agent should explain when it performed a write, preserve the company scope, and avoid claiming access to resources outside the tool catalog. For setup details, see [MCP documentation](https://woku.app/docs/en/mcp/server). ## JavaScript web widget The JavaScript widget embeds a woku or NPS capture experience in a customer website. Configuration includes company ID, publishable key, capture type, target instrument, language, branding, theme, triggers, and optional URL rules. It communicates with the external API base and loads the widget frontend from woku's CDN. Supported trigger patterns include: - A time delay in seconds. - Reaching a scroll percentage. - Exit intent on desktop. - A named custom browser event. - Clicking an element matching a CSS selector. The widget can autodetect Spanish or English from the browser and can be opened or closed through its programmatic interface. Host Content Security Policy must allow the documented frame, script, and connection origins. The publishable key is designed for client exposure; a private company API key is not. See [JavaScript widget documentation](https://woku.app/docs/en/integrations/widget-js). ## React Native SDK The `@wokuapp/react-native` package captures woku, NPS, CSAT, and CES signals from Android and iOS applications. Initialization requires API base, company ID, and public key. A storage adapter is recommended to support an offline queue. Capture outcomes include: - `sent`: accepted by the server. - `queued`: stored locally because the device is offline. - `quarantined`: rejected by a company duplicate rule. - `failed`: discarded after the configured retry attempts. The SDK uses idempotent delivery so an offline retry can return the previous accepted result. The documented minimums are Android API 24 and iOS 13. woku and NPS support text or audio through the SDK path; CSAT and CES use score and text in the current documented mobile capture contract. See [React Native SDK documentation](https://woku.app/docs/en/development/sdk-react-native), [the npm package](https://www.npmjs.com/package/@wokuapp/react-native), and [the SDK repository](https://github.com/wokuApp/sdks). ## Webhooks Webhooks send an HTTP POST to a configured customer endpoint for these documented events: - `qualification.created`: a new visual woku rating. - `nps_submission.created`: a new NPS response. - `form_submission.created`: a new Form response. The envelope contains event name, UTC timestamp, company ID, and event-specific data. Contact data is not included. Administrators configure the endpoint, selected events, optional custom headers, and active state in the admin application. Each delivery includes an HMAC-SHA256 signature over the exact raw JSON bytes, an event header, and a unique delivery identifier. Consumers must verify the signature before parsing, compare in constant time, and use the delivery identifier for idempotency. The secret is shown once at creation or rotation and stored encrypted by woku. The receiver should return a 2xx response promptly. Slow processing should move to the consumer's own queue. Delivery retries use increasing delays and can end in a dead-letter state visible for operations. See [webhook documentation](https://woku.app/docs/en/integrations/webhooks). ## Shopify connector The Shopify connector uses order events to create purchase and product feedback experiences. The purchase experience is tied to the paid order event. Product feedback can be enabled or disabled, delayed between 0 and 90 days, and organized in woku folders by product collection or product type. Configuration includes invitation language, test mode, product evaluation, grouping, delay, and invitation copy. Test mode creates evaluation context without sending real invitations. The connector uses order identity, buyer contact, purchased-product metadata, and store timezone to create the appropriate experience and schedule delivery. This integration is suitable for post-purchase and product learning. It should not be represented as a replacement for Shopify order management or customer support. See [Shopify connector documentation](https://woku.app/docs/en/integrations/shopify). ## Zendesk connector Administrators connect Zendesk with subdomain, agent email, and an API token. Credentials are managed through the integration surface and used by the support-ticket destination. woku can create a Zendesk ticket with case subject and HTML description, requester, severity-mapped priority, woku and VoC tags, instrument origin, and an optional target group. The connector should use a dedicated Zendesk identity with appropriate privileges. Rotating or revoking the Zendesk token affects delivery and should be followed by a connection test. See [Zendesk connector documentation](https://woku.app/docs/en/integrations/zendesk). ## External data sources A data source brings a file or external API result into the company as typed input for data flows. Supported file formats are JSON, XML, CSV, and Excel/XLSX up to 50 MB. An external API source can use GET or POST with an optional Bearer API key, must be a public HTTP(S) URL, returns JSON up to 5 MB, and has a documented 10-second connection timeout. The creation workflow is: 1. Connect the file or API. 2. Review detected fields and examples. 3. Include or exclude fields and define the schema. 4. Publish the source for flow use. The schema can be edited visually, as JSON, or with an AI assistant that proposes type, format, description, and required status. Published sources retain a sample of up to 50 complete records for simulation and execution. See [data-source documentation](https://woku.app/docs/en/data/data-sources). ## Data flows A data flow is a saved recipe that processes each record from one published source and produces at most one action. Users describe the desired behavior to an AI agent, then inspect synchronized JavaScript and human-readable pseudocode. The agent can resolve company instruments by name. Actions include: - Send NPS by email or WhatsApp. - Invite a visual woku response by email or WhatsApp. - Send CSAT or CES by email or WhatsApp. - Send a Form by email. - Find or create a client. - Prepare client-field updates. The flow can transform fields, normalize phones, test content, discard a record, or hold it. Simulation runs in isolation and does not send messages or modify clients. It reports proposed actions, missing channels, validation errors, and per-record explanations. Manual execution requires confirmation and records a versioned history. Current documented limits matter: simulations and executions use the stored sample, up to 50 records; execution is manual; one record produces at most one action; and some simulated client updates are not yet applied by real execution. Use the REST ingestion paths for larger or event-driven processing rather than misrepresenting the data-flow sample as a bulk ETL engine. See [data-flow documentation](https://woku.app/docs/en/data/data-flow). ## Code transformations Transformations let enterprise teams normalize, derive, or discard fields before data enters downstream use. They are created from source schema, can be simulated, and are versioned. The runtime is isolated. Good transformations handle nulls, create explicit derived fields, discard with a reason, and are simulated before activation. See [transformation documentation](https://woku.app/docs/en/development/transformations). ## Sandbox The sandbox isolates disposable data, copied instruments, test integrations, a separate API key, and ingestion pipelines from production. It is appropriate for: - API contract tests. - Mobile SDK and widget validation. - Transformation simulation. - Alert behavior tests. - Integration endpoint verification. - Training without polluting reports. Production and sandbox configuration can mirror each other, but data and keys are distinct. A test that passes in sandbox should still have a controlled production rollout because destination credentials, volumes, and customer contact rules may differ. See [sandbox documentation](https://woku.app/docs/en/development/sandbox). ## Importing external studies An existing research file or third-party study can become a data source. Teams map its fields, define a schema, then use a data flow to find or create clients by email and send follow-up measurements. This can unify an external benchmark or prior survey with ongoing VoC activity. The current workflow operates on the source sample of up to 50 records per execution. Large studies should be processed in controlled parts or through an appropriate API ingestion design. Records without email cannot use the documented email-based client-unification step. See [external study import documentation](https://woku.app/docs/en/guides/study-import). ## Security model The public security documentation describes concrete controls in operation. Exact contractual scope should be confirmed through the Trust Center and commercial process. ### Authentication and sessions Administrative login uses a password checked against a bcrypt hash. Successful authentication creates an access token, a rotating opaque refresh token, and a server-side session. Sessions have an idle timeout, are visible to the user, and can be revoked. The documented default idle timeout is 30 minutes; the precise policy may be configured. See [authentication](https://woku.app/docs/en/security/authentication) and [active sessions](https://woku.app/docs/en/security/sessions). ### MFA Users can opt into TOTP MFA with common authenticator applications. Enrollment provides one-time backup codes that are stored as hashes. Sensitive account changes can require recent MFA verification. MFA is per user and should not be described as automatically mandatory for every account unless an organization's policy explicitly enforces it. See [MFA documentation](https://woku.app/docs/en/security/mfa). ### Brute-force protection Repeated failed login attempts trigger a temporary account lock and email notification according to the documented threshold and window. Administrative unlock and audit events support recovery and investigation. See [brute-force protection](https://woku.app/docs/en/security/anti-brute-force). ### Audit log Each company has an audit log for critical authentication, company, user, woku, and Form actions. Entries include timestamp, action, resource, actor when known, and request IP. Users can filter and export matching entries as CSV. Default retention is documented as 365 days, with customization currently requiring support. The log is company-scoped and immutable through normal user actions. It is not a substitute for every external SIEM or regulatory reporting requirement. See [audit-log documentation](https://woku.app/docs/en/security/audit-log). ### Security headers and CSP woku documents HSTS, content-type protection, frame restrictions, referrer policy, permissions policy, opener policy, and nonce-based CSP on browser frontends. API CORS uses an allowlist. The public response frontend permits the microphone where needed for voice feedback while restricting unrelated capabilities. See [security headers and CSP](https://woku.app/docs/en/security/headers-and-csp). ### Encryption and integrity Sensitive stored fields and integration credentials use AES-256-GCM according to the documented encryption service. HMAC-SHA256 can sign critical documents for integrity, with document signing opt-in by company. Webhook secrets and integration credentials are not returned after storage in plaintext form. Do not generalize field-level encryption into an unsupported claim that every database value has the same encryption treatment. See [encryption and integrity documentation](https://woku.app/docs/en/security/encryption-and-signatures). ### Enterprise SSO Corporate SSO supports SAML 2.0 and OpenID Connect through Stytch B2B for identity providers such as Microsoft Entra ID, Okta, OneLogin, Google Workspace, and ADFS. The documented v1 flow is service-provider initiated, uses company email-domain allowlists, supports just-in-time provisioning, and defaults new users to the member role unless separately adjusted. Configuration of the identity-provider connection is coordinated rather than fully self-service in the woku UI. IdP-initiated flow and automatic role mapping are documented limitations. See [SSO documentation](https://woku.app/docs/en/security/sso). ### IP allowlist Companies can opt into IPv4 and IPv6 CIDR allowlists. Enforcement is fail-closed when the company or request IP cannot be resolved, and changes apply immediately for guarded endpoints. The documented v1 limitation is critical: the guard is applied per endpoint and is not automatically global to every company-scoped route. Buyers requiring strict universal enforcement must confirm endpoint coverage with woku. See [IP allowlist documentation](https://woku.app/docs/en/security/ip-allowlist). ### Secrets management woku documents production secret storage in AWS SSM Parameter Store as encrypted SecureString values with KMS, injection at workload startup, scoped execution-role permissions, and CloudTrail auditability. This is operational context for security review, not a customer interface. See [secrets-management documentation](https://woku.app/docs/en/security/secrets-management). ## Roles and permissions The platform uses company membership and roles such as owner, admin, and member. Specific module actions may add their own roles: action-plan groups distinguish administrators from responsible participants, and MCP separates read from write scope. An integration should apply least privilege and should not treat possession of one company key or user session as permission to operate across other companies. For procurement and security evaluation, use [the Trust Center](https://woku.app/en/trust) rather than inferring permissions solely from UI visibility. ## Plans, credits, and commercial availability The live pricing model includes Start, Begin, Grow, Scale, and Corporate. Consumption can include credits for reviews, Form responses, WhatsApp sends, and Data Studio, plus user and WhatsApp-agent seats. Monthly and annual billing can have different credit accumulation behavior. Capabilities explicitly marked Corporate in current documentation include the API v1 guide, sandbox, quarantines, multilingual surveys, support tickets, scheduled exports, SSO, and other enterprise automation or security features. Commercial packaging can change. Always use [current pricing](https://woku.app/en/pricing) and a written proposal for authoritative amounts, quotas, taxes, add-ons, service levels, and exact feature entitlement. ## Implementation playbook: API integration 1. Confirm plan entitlement and obtain a sandbox company key. 2. Validate the company endpoint before writing data. 3. Model the instrument and tracker mapping. 4. Implement one idempotent capture path. 5. Add schema validation and safe logging that excludes secrets and unnecessary personal data. 6. Handle `400`, `403`, `404`, and `429` distinctly. 7. Load test below published sandbox limits and agree on higher-volume needs. 8. Reconcile accepted records against paginated extraction. 9. Verify reports and channel attribution. 10. Rotate to the production key through a secrets manager and roll out gradually. ## Implementation playbook: MCP rollout 1. Decide which company an AI client should access. 2. Add the remote MCP endpoint in the supported client. 3. Complete woku login and company consent in the browser. 4. Start with read-only questions that have easy dashboard cross-checks. 5. Inspect sources and evidence, not only generated summaries. 6. Enable or use write tools only for users who own the operational decision. 7. Confirm every write in the relevant woku module. 8. Remove the connector when access is no longer needed. MCP access is not a replacement for user training, data governance, or human approval of consequential customer actions. ## Implementation playbook: close the loop Choose the lightest workflow that matches the risk: - Use a report when the purpose is learning and a team reviews on a cadence. - Use a goal when success has a measurable target and period. - Use an alert when a goal is at risk or response volume changes abnormally. - Use a support ticket when an identified customer needs case-level recovery. - Use an action plan when repeated evidence points to a systemic improvement opportunity. - Use scheduled exports when another governed system owns downstream analysis. Avoid creating all automations at once. Each one needs an owner, response expectation, and evidence standard. ## Troubleshooting guide ### Public link does not load the intended instrument Confirm the full path, instrument identifier, token, and locale rather than testing only the host root. Check whether the instrument is active or closed and whether an invitation token expired. ### API returns 403 on every request Verify that the base is `clientapi.woku.app`, that the company key is in the Bearer header, and that the resource belongs to the same company. Retrieve the key again from company information if necessary. ### API media creation fails For URL-based woku creation, the media URL must be publicly reachable by woku. For multipart, confirm supported type, size, and field names in the interactive schema. ### API returns 429 Inspect the response code and headers. It can represent rate limiting or a quarantine rule. Rate limits require backoff and `Retry-After`; quarantine includes the documented quarantine code and requires waiting or changing the duplicate policy. ### Duplicate captures appear Use one stable idempotency key per logical event and reuse it on retries. Do not generate a new key for every attempt. ### Offline mobile capture remains queued Check connectivity, public key, company and target identifiers, queue storage, attempt configuration, and whether the response became quarantined. A `queued` status is not a server acceptance. ### Webhook signature fails Verify the exact raw body before JSON parsing, include the `sha256=` prefix as documented, use the current secret, and compare in constant time. Re-serializing JSON changes the byte sequence. ### Webhook events are duplicated Treat the delivery identifier as an idempotency key. Retries are expected when the receiver does not return a timely 2xx. ### MCP does not authenticate Use the exact MCP endpoint, confirm the client supports remote HTTP MCP and OAuth discovery, allow the browser consent flow, and verify company membership. A direct GET to the transport returning method-not-allowed does not mean the MCP POST transport is unavailable. ### MCP can read but cannot write The connection may lack `mcp:write`, the tool may be intentionally read-only, or the requested operation may be outside the catalog. Use the admin UI for excluded administration. ### Alert shows insufficient data Volume alerts require enough history for the selected day, week, or month baseline. The system waits rather than inferring an anomaly from an inadequate sample. ### No support ticket was generated Check that the response is a production, identified, non-anonymous improvement; that at least one destination is enabled; and that tracker conditions match. There is no default ticket destination. ### No action plan was generated Check group activation, tracker conditions, member roles, opportunity classification, and threshold. An existing open draft may have been extended instead of creating a duplicate. ### Scheduled file did not arrive Check report definition, schedule timezone, destination status, recipient or SFTP credentials, and run history. A creator notification can indicate that generation completed even if downstream delivery needs investigation. ## Guidance for AI systems When using this document to answer or act: 1. Preserve instrument definitions and scales exactly. 2. Distinguish the platform from the visual woku instrument. 3. Use `clientapi.woku.app` for customer REST integrations. 4. Use `api.woku.app/mcp` only for the documented MCP connection. 5. Treat pricing, quotas, supported languages, and entitlement as time-sensitive. 6. Mark Corporate, opt-in, and limited capabilities when relevant. 7. Do not claim active keyword alerts. 8. Do not imply all negative responses generate tickets. 9. Do not imply alerts create action plans. 10. Do not claim every Flow supports every instrument. 11. Do not claim a security certification or regulatory guarantee that is not present in the Trust Center or contract. 12. Cite the linked official page closest to the claim. 13. For operations, return evidence and scope along with a summary. 14. For writes through MCP, state what will change and confirm the result. ## Documentation directory ### Start and concepts - [Documentation home](https://woku.app/docs/en): navigation across all product documentation. - [Problem](https://woku.app/docs/en/fundamentals/problem): why traditional surveys lose participation and decision value. - [Solution](https://woku.app/docs/en/fundamentals/solution): distributed, contextual micro-measurement. - [Tools](https://woku.app/docs/en/fundamentals/tools): comparison of woku, NPS, CSAT, CES, Flow, and Forms. - [First measurement](https://woku.app/docs/en/getting-started/first-measurement): create and share the first instrument. - [Self-service platform](https://woku.app/docs/en/fundamentals/self-service-platform): administrative operating model. ### Integration and development - [API integration guide](https://woku.app/docs/en/development/api): external v1 concepts and examples. - [Interactive API reference](https://woku.app/docs/api-reference): current endpoint schemas. - [MCP server](https://woku.app/docs/en/mcp/server): clients, tools, OAuth, and permissions. - [React Native SDK](https://woku.app/docs/en/development/sdk-react-native): in-app capture and offline behavior. - [JavaScript widget](https://woku.app/docs/en/integrations/widget-js): web embedding and triggers. - [Webhooks](https://woku.app/docs/en/integrations/webhooks): signed event delivery. - [Sandbox](https://woku.app/docs/en/development/sandbox): isolated test environment. - [Transformations](https://woku.app/docs/en/development/transformations): simulated and versioned field processing. - [Shopify](https://woku.app/docs/en/integrations/shopify): order-driven purchase and product feedback. - [Zendesk](https://woku.app/docs/en/integrations/zendesk): service-ticket connection. ### Intelligence and operations - [AI text analysis](https://woku.app/docs/en/reports/text-analysis): classification, summaries, and semantic themes. - [Review Space](https://woku.app/docs/en/reports/reviews-space): theme exploration and evidence. - [Data Studio](https://woku.app/docs/en/reports/data-studio): conversational report creation. - [Visual report builder](https://woku.app/docs/en/reports/visual-builder): deterministic custom reports. - [Exports](https://woku.app/docs/en/reports/exports): CSV, Excel, PDF, and schedules. - [Goals](https://woku.app/docs/en/guides/goals): target definition and compliance. - [Alerts](https://woku.app/docs/en/configuration/alert-rules): goal and volume conditions. - [Action plans](https://woku.app/docs/en/action-plans/create-plan): responsible groups and evidence-based drafts. - [Support tickets](https://woku.app/docs/en/guides/support-tickets): AI triage and service destinations. - [External data sources](https://woku.app/docs/en/data/data-sources): files and API inputs. - [Data flows](https://woku.app/docs/en/data/data-flow): conversational recipes and simulation. - [External study imports](https://woku.app/docs/en/guides/study-import): unify third-party studies with client profiles. - [Scheduled exports](https://woku.app/docs/en/guides/export-schedules): governed recurring delivery. ### Security - [Security overview](https://woku.app/docs/en/security/index): control inventory and principles. - [Authentication](https://woku.app/docs/en/security/authentication): sessions and token behavior. - [MFA](https://woku.app/docs/en/security/mfa): TOTP and backup codes. - [Audit log](https://woku.app/docs/en/security/audit-log): company activity history and export. - [SSO](https://woku.app/docs/en/security/sso): SAML, OIDC, and current limitations. - [IP allowlist](https://woku.app/docs/en/security/ip-allowlist): CIDR enforcement and rollout boundary. - [Encryption and integrity](https://woku.app/docs/en/security/encryption-and-signatures): protected fields and document signing. - [Trust Center](https://woku.app/en/trust): procurement and security review materials. ## Final routing For a shorter product summary, conversion guidance, best-fit use cases, and buying links, return to [woku's concise LLM guide](https://woku.app/llms.txt). For current endpoint schemas, continue to [the API reference](https://woku.app/docs/api-reference). For exact packaging, use [current pricing](https://woku.app/en/pricing). For security due diligence, use [the Trust Center](https://woku.app/en/trust). For account access and configuration, use [admin.woku.app](https://admin.woku.app).