{"id":4936,"date":"2026-01-26T01:51:04","date_gmt":"2026-01-26T06:51:04","guid":{"rendered":"https:\/\/chubes.net\/?documentation=chat-endpoint"},"modified":"2026-05-01T00:09:33","modified_gmt":"2026-05-01T04:09:33","slug":"chat-endpoint","status":"publish","type":"documentation","link":"https:\/\/chubes.net\/docs\/data-machine\/api\/endpoints\/chat-endpoint\/","title":{"rendered":"Chat Endpoint"},"content":{"rendered":"<p><strong>Implementation<\/strong>: <code>inc\/Api\/Chat\/Chat.php<\/code><\/p><p><strong>Base URL<\/strong>: <code>\/wp-json\/datamachine\/v1\/chat<\/code><\/p><h2 class=\"wp-block-heading\">Overview<\/h2><p>The Chat endpoint provides a conversational AI interface for building and executing Data Machine workflows through natural language interaction with multi-turn conversation support.<\/p><p>In addition to sending messages, it also supports listing, retrieving, and deleting persisted chat sessions.<\/p><h2 class=\"wp-block-heading\">Authentication<\/h2><p>Requires <code>manage_options<\/code> capability. See Authentication Guide.<\/p><h2 class=\"wp-block-heading\">Endpoints<\/h2><h3 class=\"wp-block-heading\">POST \/chat<\/h3><p>Send a message to the AI assistant.<\/p><p><strong>Permission<\/strong>: <code>manage_options<\/code> capability required<\/p><p><strong>Purpose<\/strong>: Natural language workflow building and Data Machine administration via conversational AI<\/p><p><strong>Parameters<\/strong>:<\/p><ul class=\"wp-block-list\"><li><code>message<\/code> (string, required): User message to send to AI<\/li><li><code>session_id<\/code> (string, optional): Session ID for conversation continuity (omit to create new session)<\/li><li><code>selected_pipeline_id<\/code> (int, optional): Active pipeline context for prioritized information awareness (@since v0.8.0)<\/li><li><code>provider<\/code> (string, optional): AI provider (<code>openai<\/code>, <code>anthropic<\/code>, <code>google<\/code>, <code>grok<\/code>, <code>openrouter<\/code>) &#8211; uses default from settings if not provided<\/li><li><code>model<\/code> (string, optional): Model identifier (e.g., <code>gpt-4<\/code>, <code>claude-sonnet-4<\/code>) &#8211; uses default from settings if not provided<\/li><\/ul><p><strong>Example Requests<\/strong>:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">bash<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-bash\"><code class=\"language-bash\"># Start new conversation\ncurl -X POST https:\/\/example.com\/wp-json\/datamachine\/v1\/chat \n  -H &quot;Content-Type: application\/json&quot; \n  -u username:application_password \n  -d &#039;{\n    &quot;message&quot;: &quot;Create a pipeline that fetches from RSS and publishes to Twitter&quot;,\n    &quot;provider&quot;: &quot;anthropic&quot;,\n    &quot;model&quot;: &quot;claude-sonnet-4&quot;\n  }&#039;\n\n# Continue existing conversation\ncurl -X POST https:\/\/example.com\/wp-json\/datamachine\/v1\/chat \n  -H &quot;Content-Type: application\/json&quot; \n  -u username:application_password \n  -d &#039;{\n    &quot;message&quot;: &quot;Now add a flow for that pipeline&quot;,\n    &quot;session_id&quot;: &quot;session_abc123&quot;,\n    &quot;provider&quot;: &quot;anthropic&quot;,\n    &quot;model&quot;: &quot;claude-sonnet-4&quot;\n  }&#039;<\/code><\/pre><\/div><p><strong>Success Response (200 OK)<\/strong>:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">json<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-json\"><code class=\"language-json\">{\n  &quot;success&quot;: true,\n  &quot;session_id&quot;: &quot;session_abc123&quot;,\n  &quot;response&quot;: &quot;I&#039;ll help you create a pipeline with RSS fetch and Twitter publish steps...&quot;,\n  &quot;tool_calls&quot;: [\n    {\n      &quot;id&quot;: &quot;call_abc123&quot;,\n      &quot;type&quot;: &quot;function&quot;,\n      &quot;function&quot;: {\n        &quot;name&quot;: &quot;create_pipeline&quot;,\n        &quot;arguments&quot;: &quot;{&quot;name&quot;:&quot;RSS to Twitter&quot;,&quot;steps&quot;:[{&quot;type&quot;:&quot;fetch&quot;,&quot;handler&quot;:&quot;rss&quot;},{&quot;type&quot;:&quot;ai&quot;},{&quot;type&quot;:&quot;publish&quot;,&quot;handler&quot;:&quot;twitter&quot;}]}&quot;\n      }\n    }\n  ],\n  &quot;conversation&quot;: [\n    {&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Create a pipeline...&quot;},\n    {&quot;role&quot;: &quot;assistant&quot;, &quot;content&quot;: &quot;I&#039;ll help you...&quot;, &quot;tool_calls&quot;: [...]}\n  ],\n  &quot;metadata&quot;: {\n    &quot;last_activity&quot;: &quot;2024-01-02 14:30:00&quot;,\n    &quot;message_count&quot;: 2\n  }\n}<\/code><\/pre><\/div><p><strong>Response Fields<\/strong>:<\/p><ul class=\"wp-block-list\"><li><code>success<\/code> (boolean): Request success status<\/li><li><code>session_id<\/code> (string): Session identifier for conversation continuity<\/li><li><code>response<\/code> (string): AI assistant response message<\/li><li><code>tool_calls<\/code> (array, optional): Array of tool calls made by AI<\/li><li><code>conversation<\/code> (array): Full conversation history<\/li><li><code>metadata<\/code> (object): Session metadata<ul class=\"wp-block-list\"><li><code>last_activity<\/code> (string): Last activity timestamp<\/li><li><code>message_count<\/code> (integer): Number of messages in conversation<\/li><\/ul><\/li><\/ul><h2 class=\"wp-block-heading\">Session Management<\/h2><h3 class=\"wp-block-heading\">Session Creation<\/h3><p>First message automatically creates a new session:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">bash<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-bash\"><code class=\"language-bash\">curl -X POST https:\/\/example.com\/wp-json\/datamachine\/v1\/chat \n  -H &quot;Content-Type: application\/json&quot; \n  -u username:application_password \n  -d &#039;{&quot;message&quot;: &quot;Hello&quot;}&#039;<\/code><\/pre><\/div><p>Returns <code>session_id<\/code> for subsequent messages.<\/p><h3 class=\"wp-block-heading\">Session Continuity<\/h3><p>Use <code>session_id<\/code> to continue existing conversation:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">bash<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-bash\"><code class=\"language-bash\">curl -X POST https:\/\/example.com\/wp-json\/datamachine\/v1\/chat \n  -H &quot;Content-Type: application\/json&quot; \n  -u username:application_password \n  -d &#039;{&quot;message&quot;: &quot;Continue previous task&quot;, &quot;session_id&quot;: &quot;session_abc123&quot;}&#039;<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Session Storage<\/h3><p>Chat sessions are stored in the <code>wp_datamachine_chat_sessions<\/code> table.<\/p><p><strong>Implementation<\/strong>: <code>inc\/Core\/Database\/Chat\/Chat.php<\/code><\/p><p><strong>Database Table<\/strong>: <code>wp_datamachine_chat_sessions<\/code><\/p><p><strong>Features<\/strong>:<\/p><ul class=\"wp-block-list\"><li><code>last_activity<\/code> (string): Last activity timestamp<\/li><li><code>message_count<\/code> (integer): Number of messages in conversation<\/li><\/ul><h3 class=\"wp-block-heading\">Session Security<\/h3><p><strong>User Isolation<\/strong>:<\/p><ul class=\"wp-block-list\"><li><code>last_activity<\/code> (string): Last activity timestamp<\/li><li><code>message_count<\/code> (integer): Number of messages in conversation<\/li><\/ul><p><strong>Error Response (404 Not Found)<\/strong> &#8211; Invalid session:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">json<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-json\"><code class=\"language-json\">{\n  &quot;code&quot;: &quot;session_not_found&quot;,\n  &quot;message&quot;: &quot;Session not found&quot;,\n  &quot;data&quot;: {&quot;status&quot;: 404}\n}<\/code><\/pre><\/div><p><strong>Error Response (403 Forbidden)<\/strong> &#8211; Access denied:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">json<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-json\"><code class=\"language-json\">{\n  &quot;code&quot;: &quot;session_access_denied&quot;,\n  &quot;message&quot;: &quot;Access denied to this session&quot;,\n  &quot;data&quot;: {&quot;status&quot;: 403}\n}<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Available Tools<\/h2><h3 class=\"wp-block-heading\">Global Tools<\/h3><p>Available to all AI agents via <code>datamachine_global_tools<\/code> filter:<\/p><ul class=\"wp-block-list\"><li>Persistent conversation history<\/li><li>User-scoped sessions (users can only access their own)<\/li><li>Message count tracking<\/li><li>Provider and model tracking<\/li><li>Agent type tracking (<code>agent_type<\/code>: <code>chat<\/code>, <code>cli<\/code>)<\/li><\/ul><h3 class=\"wp-block-heading\">Chat-Specific Tools<\/h3><p>Available only to chat AI agents via <code>datamachine_chat_tools<\/code> filter (@since v0.4.3 specialized tools):<\/p><ul class=\"wp-block-list\"><li>Sessions are user-scoped<\/li><li>Users can only access their own sessions<\/li><li>Invalid session returns 404 error<\/li><li>Access to another user&#8217;s session returns 403 error<\/li><\/ul><h2 class=\"wp-block-heading\">Universal Engine Architecture<\/h2><p><strong>Since<\/strong>: v0.2.0<\/p><p>The Chat endpoint uses the Universal Engine architecture at <code>\/inc\/Engine\/AI\/<\/code> for consistent AI request handling across Pipeline and Chat agents.<\/p><h3 class=\"wp-block-heading\">Core Components Used<\/h3><p><strong>AIConversationLoop<\/strong><\/p><ul class=\"wp-block-list\"><li><strong>google_search<\/strong> &#8211; Web search with site restriction<\/li><li><strong>local_search<\/strong> &#8211; WordPress content search<\/li><li><strong>web_fetch<\/strong> &#8211; Web page content retrieval<\/li><li><strong>wordpress_post_reader<\/strong> &#8211; Single post analysis<\/li><\/ul><p><strong>RequestBuilder<\/strong><\/p><ul class=\"wp-block-list\"><li><strong>execute_workflow<\/strong> (@since v0.3.0) &#8211; Execute complete multi-step workflows with automatic defaults injection<\/li><li><strong>get_handler_defaults<\/strong> (@since v0.6.25) &#8211; Retrieve site-wide handler defaults for reference<\/li><li><strong>set_handler_defaults<\/strong> (@since v0.6.25) &#8211; Update site-wide handler defaults<\/li><li><strong>add_pipeline_step<\/strong> (@since v0.4.3) &#8211; Add steps to existing pipelines<\/li><li><strong>api_query<\/strong> (@since v0.4.3) &#8211; REST API query tool for discovery (supports batch requests @since v0.7.0)<\/li><li><strong>configure_flow_step<\/strong> (@since v0.4.2) &#8211; Configure handler and AI messages<\/li><li><strong>configure_pipeline_step<\/strong> (@since v0.4.4) &#8211; Configure pipeline-level AI settings<\/li><li><strong>copy_flow<\/strong> (@since v0.6.25) &#8211; Copy flow to same or different pipeline with optional overrides<\/li><li><strong>create_flow<\/strong> (@since v0.4.2) &#8211; Create flow instances from pipelines<\/li><li><strong>create_pipeline<\/strong> (@since v0.4.3) &#8211; Create pipelines with optional steps<\/li><li><strong>handler_documentation<\/strong> (@since v0.7.0) &#8211; Discover available handlers and their settings schema<\/li><li><strong>run_flow<\/strong> (@since v0.4.4) &#8211; Execute or schedule flows<\/li><li><strong>update_flow<\/strong> (@since v0.4.4) &#8211; Update flow properties<\/li><li><strong>validate_credentials<\/strong> (@since v0.8.0) &#8211; Test authentication provider credentials during configuration<\/li><\/ul><p><strong>ToolExecutor<\/strong><\/p><ul class=\"wp-block-list\"><li>Multi-turn conversation execution<\/li><li>Automatic tool call detection and execution<\/li><li>Completion detection (conversation ends when AI returns no tool calls)<\/li><li>Turn limiting (default: 8 turns)<\/li><li>Duplicate tool call prevention<\/li><\/ul><p><strong>ConversationManager<\/strong><\/p><ul class=\"wp-block-list\"><li>Centralized AI request construction<\/li><li>Hierarchical directive application (global \u2192 agent \u2192 chat-specific)<\/li><li>Tool restructuring for provider compatibility<\/li><li>Integration with the wp-ai-client runtime adapter<\/li><\/ul><p><strong>ToolParameters<\/strong><\/p><ul class=\"wp-block-list\"><li>Universal tool discovery via filters (<code>datamachine_global_tools<\/code>, <code>datamachine_chat_tools<\/code>)<\/li><li>Tool enablement validation<\/li><li>Execution with comprehensive error handling<\/li><\/ul><h3 class=\"wp-block-heading\">Chat Agent Implementation<\/h3><p><strong>File<\/strong>: <code>\/inc\/Api\/Chat\/ChatFilters.php<\/code>\n<strong>Purpose<\/strong>: Registers chat-specific behavior with Universal Engine<\/p><p><strong>Chat Pipelines Inventory<\/strong> (@since v0.7.0):\nThe chat agent receives a lightweight inventory of all pipelines, their configured steps (ID, name, type), and flow summaries (ID, name, handlers) via the <a href=\"https:\/\/chubes.net\/docs\/data-machine\/core-system\/ai-directives-system\/#chatpipelinesdirective-priority-45\">ChatPipelinesDirective<\/a>. When <code>selected_pipeline_id<\/code> is provided (e.g., from the Integrated Chat Sidebar), the agent prioritizes and expands context for that specific pipeline.<\/p><p><strong>Tool Enablement<\/strong> (chat-specific):<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">add_filter(&#039;datamachine_tool_enabled&#039;, function($enabled, $tool_name, $tool_config, $context_id) {\n    \/\/ Chat agent: context_id = null (use global tool enablement)\n    if ($context_id === null) {\n        $tool_configured = apply_filters(&#039;datamachine_tool_configured&#039;, false, $tool_name);\n        $requires_config = !empty($tool_config[&#039;requires_config&#039;]);\n        return !$requires_config || $tool_configured;\n    }\n    return $enabled;\n}, 5, 4);<\/code><\/pre><\/div><p><strong>Directive Registration<\/strong> (@since v0.2.5):<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">\/\/ Current: Unified directive registration with agent type targeting\nadd_filter(&#039;datamachine_directives&#039;, function($directives) {\n    $directives[] = [\n        &#039;class&#039; =&gt; ChatAgentDirective::class,\n        &#039;priority&#039; =&gt; 10,\n        &#039;agent_types&#039; =&gt; [&#039;chat&#039;]\n    ];\n    return $directives;\n});<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Differences from Pipeline Agent<\/h3><p><strong>Chat Agent<\/strong>:<\/p><ul class=\"wp-block-list\"><li>Message formatting utilities<\/li><li>Tool call\/result message generation<\/li><li>Duplicate detection logic<\/li><\/ul><p><strong>Pipeline Agent<\/strong>:<\/p><ul class=\"wp-block-list\"><li>Unified parameter building for tools<\/li><li>Automatic content\/title extraction<\/li><li>Session context integration<\/li><\/ul><h3 class=\"wp-block-heading\">Session Context Structure<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">$context = [\n    &#039;session_id&#039; =&gt; $session_id  \/\/ Chat session identifier\n];<\/code><\/pre><\/div><p>Used by:<\/p><ul class=\"wp-block-list\"><li>Session-based conversation persistence<\/li><li>Global tool enablement (not step-specific)<\/li><li>No data packets from previous steps<\/li><li>Chat-specific specialized tools (create_pipeline, run_flow, etc.)<\/li><li>Session context instead of job context<\/li><\/ul><h3 class=\"wp-block-heading\">Tool Discovery<\/h3><p>Chat agent discovers tools via three sources:<\/p><ol class=\"wp-block-list\"><li><p><strong>Global Tools<\/strong> (<code>datamachine_global_tools<\/code> filter):<\/p><ul class=\"wp-block-list\"><li>google_search<\/li><li>local_search<\/li><li>web_fetch<\/li><li>wordpress_post_reader<\/li><\/ul><\/li><li><p><strong>Chat Tools<\/strong> (<code>datamachine_chat_tools<\/code> filter) (@since v0.4.3 specialized tools):<\/p><ul class=\"wp-block-list\"><li>execute_workflow, add_pipeline_step, api_query, configure_flow_step<\/li><li>configure_pipeline_step, create_flow, create_pipeline, run_flow, update_flow<\/li><\/ul><\/li><li><p><strong>Filtered by Enablement<\/strong> (<code>datamachine_tool_enabled<\/code> filter):<\/p><ul class=\"wp-block-list\"><li>Configuration validation<\/li><li>Global enablement check<\/li><\/ul><\/li><\/ol><h3 class=\"wp-block-heading\">Conversation Flow<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\"><\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code\"><code>1. User sends message via POST \/chat\n   \u2193\n2. Chat endpoint loads or creates session\n   \u2193\n3. AIConversationLoop executes:\n   a. RequestBuilder builds AI request with chat directives\n   b. AI responds with content and\/or tool calls\n   c. ToolExecutor executes each tool call\n   d. ConversationManager formats tool results\n   e. Repeat until AI returns no tool calls (max 8 turns)\n   \u2193\n4. Session updated with conversation history\n   \u2193\n5. Response returned to user<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Filter-Based Architecture<\/h2><h3 class=\"wp-block-heading\">Unified Directive System (@since v0.2.5)<\/h3><p><strong>Global Tools<\/strong> (<code>datamachine_global_tools<\/code> filter):<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">add_filter(&#039;datamachine_directives&#039;, function($directives) {\n    \/\/ Global directive (applies to all agents)\n    $directives[] = [\n        &#039;class&#039; =&gt; MyDirective::class,\n        &#039;priority&#039; =&gt; 25,\n        &#039;agent_types&#039; =&gt; [&#039;all&#039;]  \/\/ Applies to chat and pipeline agents\n    ];\n\n    \/\/ Chat-specific directive\n    $directives[] = [\n        &#039;class&#039; =&gt; MyChatDirective::class,\n        &#039;priority&#039; =&gt; 15,\n        &#039;agent_types&#039; =&gt; [&#039;chat&#039;]  \/\/ Applies only to chat agent\n    ];\n\n    return $directives;\n});<\/code><\/pre><\/div><p><strong>Chat Tools<\/strong> (<code>datamachine_chat_tools<\/code> filter) (@since v0.4.3 specialized tools):<\/p><ul class=\"wp-block-list\"><li>Job-based execution within workflows<\/li><li>Step-specific tool enablement<\/li><li>Data packets flow through steps<\/li><li>Handler tools for specific steps<\/li><li>Job context with engine data<\/li><\/ul><h2 class=\"wp-block-heading\">Integration Examples<\/h2><h3 class=\"wp-block-heading\">Python Chat Integration<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">python<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-python\"><code class=\"language-python\">import requests\nfrom requests.auth import HTTPBasicAuth\n\nurl = &quot;https:\/\/example.com\/wp-json\/datamachine\/v1\/chat&quot;\nauth = HTTPBasicAuth(&quot;username&quot;, &quot;application_password&quot;)\n\n# Start conversation\ninitial_message = {\n    &quot;message&quot;: &quot;Create a pipeline that fetches from RSS&quot;,\n    &quot;provider&quot;: &quot;anthropic&quot;,\n    &quot;model&quot;: &quot;claude-sonnet-4&quot;\n}\n\nresponse = requests.post(url, json=initial_message, auth=auth)\ndata = response.json()\n\nsession_id = data[&#039;session_id&#039;]\nprint(f&quot;AI: {data[&#039;response&#039;]}&quot;)\n\n# Continue conversation\nfollow_up = {\n    &quot;message&quot;: &quot;Add a Twitter publish step&quot;,\n    &quot;session_id&quot;: session_id\n}\n\nresponse2 = requests.post(url, json=follow_up, auth=auth)\ndata2 = response2.json()\n\nprint(f&quot;AI: {data2[&#039;response&#039;]}&quot;)<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">JavaScript Chat Interface<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">javascript<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-javascript\"><code class=\"language-javascript\">const axios = require(&#039;axios&#039;);\n\nclass ChatClient {\n  constructor(baseURL, auth) {\n    this.baseURL = baseURL;\n    this.auth = auth;\n    this.sessionId = null;\n  }\n\n  async sendMessage(message, provider = &#039;anthropic&#039;, model = &#039;claude-sonnet-4&#039;) {\n    const payload = {\n      message,\n      provider,\n      model\n    };\n\n    if (this.sessionId) {\n      payload.session_id = this.sessionId;\n    }\n\n    const response = await axios.post(this.baseURL, payload, {\n      auth: this.auth\n    });\n\n    \/\/ Store session ID from first message\n    if (!this.sessionId) {\n      this.sessionId = response.data.session_id;\n    }\n\n    return response.data;\n  }\n}\n\n\/\/ Usage\nconst chat = new ChatClient(\n  &#039;https:\/\/example.com\/wp-json\/datamachine\/v1\/chat&#039;,\n  { username: &#039;admin&#039;, password: &#039;application_password&#039; }\n);\n\nconst response1 = await chat.sendMessage(&#039;Create an RSS to Twitter pipeline&#039;);\nconsole.log(`AI: ${response1.response}`);\n\nconst response2 = await chat.sendMessage(&#039;Execute the pipeline now&#039;);\nconsole.log(`AI: ${response2.response}`);<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Common Workflows<\/h2><h3 class=\"wp-block-heading\">Create Pipeline via Chat<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">bash<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-bash\"><code class=\"language-bash\"># 1. Start conversation\ncurl -X POST https:\/\/example.com\/wp-json\/datamachine\/v1\/chat \n  -H &quot;Content-Type: application\/json&quot; \n  -u username:application_password \n  -d &#039;{\n    &quot;message&quot;: &quot;Create a pipeline with these steps: fetch from RSS, process with AI, publish to Twitter&quot;\n  }&#039;\n\n# AI will create pipeline using create_pipeline tool<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Monitor Jobs via Chat<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">bash<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-bash\"><code class=\"language-bash\">curl -X POST https:\/\/example.com\/wp-json\/datamachine\/v1\/chat \n  -H &quot;Content-Type: application\/json&quot; \n  -u username:application_password \n  -d &#039;{\n    &quot;message&quot;: &quot;Show me failed jobs from the last hour&quot;,\n    &quot;session_id&quot;: &quot;session_abc123&quot;\n  }&#039;<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Configure Handler via Chat<\/h3><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">bash<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-bash\"><code class=\"language-bash\">curl -X POST https:\/\/example.com\/wp-json\/datamachine\/v1\/chat \n  -H &quot;Content-Type: application\/json&quot; \n  -u username:application_password \n  -d &#039;{\n    &quot;message&quot;: &quot;Configure the Twitter handler for flow 42 with max length 280&quot;,\n    &quot;session_id&quot;: &quot;session_abc123&quot;\n  }&#039;<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Use Cases<\/h2><h3 class=\"wp-block-heading\">Conversational Pipeline Builder<\/h3><p><strong>Filtered by Enablement<\/strong> (<code>datamachine_tool_enabled<\/code> filter):<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\"><\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code\"><code>User: &quot;Create a pipeline that imports recipes from an RSS feed&quot;\nAI: [Creates pipeline with RSS fetch step]\n\nUser: &quot;Add AI processing to extract ingredients&quot;\nAI: [Adds AI step with custom prompt]\n\nUser: &quot;Publish to WordPress&quot;\nAI: [Adds WordPress publish step]<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Natural Language Debugging<\/h3><p><strong>Global Tools<\/strong> (<code>datamachine_global_tools<\/code> filter):<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\"><\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code\"><code>User: &quot;Why did flow 42 fail?&quot;\nAI: [Checks logs, identifies error, suggests fix]\n\nUser: &quot;Clear the failed jobs&quot;\nAI: [Executes DELETE \/jobs with type=failed]<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Interactive Configuration<\/h3><p><strong>Chat Tools<\/strong> (<code>datamachine_chat_tools<\/code> filter) (@since v0.4.3 specialized tools):<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\"><\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code\"><code>User: &quot;Set up Google Search API&quot;\nAI: [Guides through configuration, saves settings]<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Related Documentation<\/h2><ul class=\"wp-block-list\"><li>google_search<\/li><li>local_search<\/li><li>web_fetch<\/li><li>wordpress_post_reader<\/li><\/ul><hr class=\"wp-block-separator\"\/><p><strong>Filtered by Enablement<\/strong> (<code>datamachine_tool_enabled<\/code> filter):<\/p><h2 class=\"wp-block-heading\">Additional Endpoints<\/h2><h3 class=\"wp-block-heading\">POST \/chat\/continue<\/h3><p>Directives are registered via the <code>datamachine_directives<\/code> filter with priority and agent targeting:<\/p><p><strong>Priority Guidelines<\/strong>:<\/p><p>Build complex workflows through natural language conversation:<\/p><ul class=\"wp-block-list\"><li>execute_workflow, add_pipeline_step, api_query, configure_flow_step<\/li><li>configure_pipeline_step, create_flow, create_pipeline, run_flow, update_flow<\/li><\/ul><p>Debug workflows through conversational interface:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">bash<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-bash\"><code class=\"language-bash\">curl -X POST https:\/\/example.com\/wp-json\/datamachine\/v1\/chat\/continue \n  -H &quot;Content-Type: application\/json&quot; \n  -u username:application_password \n  -d &#039;{&quot;session_id&quot;: &quot;abc123&quot;, &quot;message&quot;: &quot;Process new RSS items&quot;}&#039;<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">GET \/chat\/{session_id}<\/h3><p>Configure Data Machine settings through chat:<\/p><p><strong>Base URL<\/strong>: <code>\/wp-json\/datamachine\/v1\/chat<\/code>\n<strong>Permission<\/strong>: <code>manage_options<\/code> capability required\n<strong>Implementation<\/strong>: <code>inc\/Api\/Chat\/Chat.php<\/code>\n<strong>Session Storage<\/strong>: <code>wp_datamachine_chat_sessions<\/code> table\n<strong>Session Expiration<\/strong>: Not enforced by default (table supports an <code>expires_at<\/code> column for optional cleanup)<\/p><p>Continue a chat session with additional context from external triggers (webhooks, scheduled jobs, etc.).<\/p><ul class=\"wp-block-list\"><li>Configuration validation<\/li><li>Global enablement check<\/li><\/ul><p><strong>Permission<\/strong>: <code>manage_options<\/code> capability required<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">json<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-json\"><code class=\"language-json\">{\n  &quot;id&quot;: &quot;abc123&quot;,\n  &quot;user_id&quot;: 1,\n  &quot;session_id&quot;: &quot;abc123&quot;,\n  &quot;provider&quot;: &quot;anthropic&quot;,\n  &quot;model&quot;: &quot;claude-sonnet-4&quot;,\n  &quot;messages&quot;: [\n    {&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Hello&quot;},\n    {&quot;role&quot;: &quot;assistant&quot;, &quot;content&quot;: &quot;Hi! How can I help?&quot;}\n  ],\n  &quot;message_count&quot;: 2,\n  &quot;created_at&quot;: &quot;2024-01-01 12:00:00&quot;,\n  &quot;last_activity&quot;: &quot;2024-01-01 12:05:00&quot;\n}<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">POST \/chat\/ping<\/h3><p><strong>Parameters<\/strong>:<\/p><p><strong>Example<\/strong>:<\/p><p>Retrieve a chat session with its conversation history.<\/p><ul class=\"wp-block-list\"><li>RequestBuilder for directive application<\/li><li>ToolExecutor for tool execution<\/li><li>ToolParameters for parameter building<\/li><\/ul><p><strong>Permission<\/strong>: <code>manage_options<\/code> capability required<\/p><p><strong>Parameters<\/strong>:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">bash<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-bash\"><code class=\"language-bash\">curl -X POST https:\/\/example.com\/wp-json\/datamachine\/v1\/chat\/ping \n  -H &quot;Content-Type: application\/json&quot; \n  -u username:application_password \n  -d &#039;{&quot;session_id&quot;: &quot;abc123&quot;, &quot;message&quot;: &quot;Check for new RSS items and publish&quot;}&#039;<\/code><\/pre><\/div>","protected":false},"excerpt":{"rendered":"<p>Implementation: inc\/Api\/Chat\/Chat.php Base URL: \/wp-json\/datamachine\/v1\/chat Overview The Chat endpoint provides a conversational AI interface for building and executing Data Machine workflows through natural language interaction with multi-turn conversation support. In&#8230;<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"footnotes":""},"tags":[],"project":[505],"project_type":[484],"class_list":["post-4936","documentation","type-documentation","status-publish","hentry","project-endpoints","project_type-wordpress-plugins"],"project_info":{"id":487,"name":"Data Machine","slug":"data-machine"},"project_type_info":{"id":484,"name":"WordPress Plugins","slug":"wordpress-plugins"},"_links":{"self":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/4936","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation"}],"about":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/types\/documentation"}],"version-history":[{"count":6,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/4936\/revisions"}],"predecessor-version":[{"id":11563,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/4936\/revisions\/11563"}],"wp:attachment":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/media?parent=4936"}],"wp:term":[{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/tags?post=4936"},{"taxonomy":"project","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project?post=4936"},{"taxonomy":"project_type","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project_type?post=4936"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}