Documentación de woku - Guía para desarrolladores

Once connected, the agent operates on your company data through a catalog of tools. Every tool runs the exact same query or command the admin panel runs, so the two surfaces cannot diverge in behaviour. Before operating, the agent can call woku_guide, which returns woku’s method and playbooks (from an intent to the sequence of tools), and design_voc_program, which proposes a listening program for your customer journey.

Tools by family

The server organizes tools by family. The live connection’s tools/list response tells you which are available:

Family	Tools
Guide	`woku_guide`, `design_voc_program`
Company	`get_company`, `get_company_statistics`, `list_company_members`
Wokus and media	`upload_woku_media`, `create_woku`, `list_wokus`, `get_woku`, `list_woku_reviews`, `update_woku`, `move_woku`, `update_woku_settings`, `delete_woku`, `send_woku_invitations`
Customer journeys	`propose_journey`, `create_journey_from_brief`, `create_journey`, `list_journeys`, `get_journey`, `set_journey_moment_media`, `update_journey`, `delete_journey`, `enroll_in_journey`, `emit_journey_event`, `list_journey_evaluations`, `get_journey_evaluation`, `stop_journey_evaluation`, `get_journey_connections`, `mint_journey_moment_url`, `set_journey_sender_secret`, `preview_journey_moment`
NPS	`list_nps_tools`, `get_nps_statistics`, `list_nps_responses`, `send_nps_invitations`, `create_nps_tool`, `update_nps_tool`, `delete_nps_tool`
CSAT and CES	`get_csat_metrics`, `get_ces_metrics`, `list_csat_responses`, `list_ces_responses`, `send_csat_survey`, `send_ces_survey`, `create_csat_tool`, `update_csat_tool`, `delete_csat_tool`, `create_ces_tool`, `update_ces_tool`, `delete_ces_tool`
Forms	`list_forms`, `get_form`, `get_form_summary`, `list_form_responses`, `send_form_invitations`, `create_form`, `update_form`, `delete_form`
Survey flows	`list_flows`, `get_flow`, `create_flow`, `update_flow`, `delete_flow`
Folders	`list_folders`, `get_folder`, `create_folder`, `move_folder`
Clients	`list_clients`, `get_client_stats`, `list_client_feedback`, `get_client_form_config`, `create_client`, `update_client`, `import_clients`, `delete_client`
Trackers	`list_trackers`, `create_tracker`, `assign_tracker_to_woku`, `assign_tracker_to_entity`, `update_tracker`, `set_tracker_active`, `remove_tracker_value`, `list_entity_trackers`, `search_entities_by_trackers`
Tickets	`list_tickets`, `get_ticket`, `update_ticket`, `list_ticket_destinations`, `get_ticket_destination`, `create_ticket_destination`, `update_ticket_destination`, `delete_ticket_destination`, `test_ticket_destination`
Action plans	`list_action_plans`, `get_action_plan`, `approve_action_plan`, `change_action_plan_status`, `create_action_plan_task`, `update_action_plan_task`, `delete_action_plan_task`, `reorder_action_plan_tasks`, `get_action_plan_events`, `get_action_plan_conversation`, `reply_to_action_plan`, `list_action_plan_groups`, `get_action_plan_group`, `create_action_plan_group`, `update_action_plan_group`, `set_action_plan_group_enabled`, `delete_action_plan_group`
Response controls	`list_alert_rules`, `create_alert_rule`, `update_alert_rule`, `delete_alert_rule`, `test_alert_rule`, `list_quarantines`, `create_quarantine`, `update_quarantine`, `delete_quarantine`, `simulate_quarantine`
Instrument reports	`list_generated_reports`, `get_woku_report`, `get_folder_report`, `get_company_nps_report`
Review intelligence	`query_review_intelligence`
Billing	`get_subscription`, `list_billing_plans`, `list_invoices`, `get_billing_profile`, `get_usage_balance`
Integrations	`list_integration_connections`
Audit	`list_audit_log_entries`
Data apps	`list_data_apps`, `get_data_app`
Universal search	`search`, `fetch`

With this, an agent can design a listening program, summarize last week’s reviews, compare NPS across locations, approve an action plan, or create a tracker, all from the conversation.

Create a Woku or journey with media

upload_woku_media imports an image or MP4 video from a public HTTPS URL and returns a woku fileId. It also accepts a ChatGPT-authorized file through its file parameter when that capability is available on the connection. create_woku can use the fileId or import media in the same call. For a Woku moment within a journey, use set_journey_moment_media with the fileId; the journey creates its own instrument when that moment is evaluated. When the file is on the computer running Codex or Claude Code, its terminal can upload it by multipart without putting the bytes in the conversation:

curl --fail-with-body --request POST \
  --url https://clientapi.woku.app/v1/woku-media \
  --header "Authorization: Bearer $WOKU_API_KEY" \
  --form "file=@./product-photo.jpg"

The response contains fileId, filename, and type. Supply the company key through the user’s environment or secret manager, never in prompt text. Images are converted to WebP with a 10 MB input limit; videos must be MP4 and at most 25 MB. The actual file format is checked, not just its name or Content-Type. A remote MCP server cannot read ./product-photo.jpg on the user’s computer. ChatGPT can pass an authorized file to a tool that declares a file parameter, as described in its plugin documentation. Claude web connects to remote MCP servers from Anthropic’s cloud and does not document the same automatic attachment handoff; use an HTTPS URL that woku can reach there. Claude remote connectors. To create a journey without authoring the full definition by hand, call woku_guide with topic=customer_journeys. propose_journey interprets three free-text answers: experience, ordered moments, and objectives. With approval, create_journey_from_brief saves a disabled journey. Then upload any needed images, connect each moment’s webhook, review recipients, and activate with update_journey. None of these creation tools sends evaluations on its own. To preserve a reviewed proposal, pass the draft returned by propose_journey as proposal to create_journey_from_brief, together with the original answers and confirm: true. This saves it without another model call. Omitting proposal generates a fresh proposal. toolSpec.descriptionEn preserves the Woku’s English title; unsupported moment fields return an error instead of being silently discarded.

Toolsets

The catalog is large, so a connection can narrow it. Adding ?toolsets=nps,clients (comma-separated) to the MCP endpoint URL exposes only those families; without the parameter, or with ?toolsets=all, everything is exposed. The guide, company, and search families are always available.

Universal search

The search and fetch tools follow ChatGPT’s deep research contract: search searches across all company data and fetch brings the detail of a result.

Read and write

Connections handle two permissions: mcp:read to query data and mcp:write for the tools that create, edit, or delete. Read tools work with mcp:read alone; write tools also require mcp:write, and destructive ones (for example delete_woku) or sends (for example send_nps_invitations) additionally require confirm: true in the call, so nothing is deleted or sent without an explicit confirmation. If the connection does not have the mcp:write permission, the write tools respond with an error indicating so and the rest keep working normally. The list of tools the server advertises on a live connection (tools/list) is always the authoritative answer about what is available.

Per-moment webhook content

create_journey, update_journey, and an approved proposal accept the complete moment configuration. Content source (webhook.contentMode) is independent of the trigger. For dynamic content, use an object-root webhook.schema and toolScope: "per_enrollment". webhook.payload.clientFields maps extra customer data with {key, path}. Under webhook.content, description, descriptionEn, localized subject and audience variables, and folder keys and names accept {mode: "literal" | "javascript", value}. JavaScript receives payload and returns a string; imports, network and filesystem access are unavailable. Woku can read its image from imageUrlPath and trackers from a list of {name, path}. A parent requires a child folder; omitted names use their keys and must fit folder-name limits. MCP keeps cadence for sends and windows; HTTP uses sequence. Send the complete list when replacing moments. preview_journey_moment uses the saved moment without verifying signatures or sending. Reads never return secrets; configure them separately with per-moment credential tools. Unknown fields and secrets inside the definition return an error.

​Tools by family

​Create a Woku or journey with media

​Toolsets

​Universal search

​Read and write

​Per-moment webhook content