Skip to main content

Conversation Ai Update Action

Immutable Catalog Entry

This descriptor comes from the active versioned Portal catalog.

WRITEghl.conversation_ai_update_action
  • Contract tier: agent_ready
  • Risk: write
  • Catalog version: 2026-07-12.2
  • Descriptor hash: 23f24b94223f1a2c52cb5d71cca244368dd44c4ef1c1d8ca3955f1641acda142

Update a GHL Conversation AI agent action. GHL category: AI Agents / Conversation AI. This writes to GHL Conversation AI agent/action configuration. Do not modify production agents during validation unless the user explicitly provides disposable fixtures.

Request Body​

{
  "jsonrpc": "2.0",
  "id": "ghl-conversation-ai-update-action-example",
  "method": "tools/call",
  "params": {
    "name": "ghl.conversation_ai_update_action",
    "arguments": {
      "agentId": "agentId_123",
      "actionId": "actionId_123",
      "body": {},
      "query": {},
      "tenantId": "tenantId_123",
      "locationId": "locationId_123",
      "strictTenant": false,
      "includeFullConfig": false
    }
  }
}

Arguments Schema​

{
  "type": "object",
  "required": [
    "agentId",
    "actionId",
    "body"
  ],
  "properties": {
    "body": {
      "type": "object",
      "required": [
        "name",
        "type",
        "details"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Action name. Use a clear disposable prefix during audit tests."
        },
        "type": {
          "enum": [
            "triggerWorkflow",
            "updateContactField",
            "appointmentBooking",
            "stopBot",
            "humanHandOver",
            "advancedFollowup",
            "transferBot"
          ],
          "type": "string",
          "description": "GHL Conversation AI action type."
        },
        "details": {
          "type": "object",
          "description": "Action-specific details object required by GHL. For stopBot, required fields include enabled, stopBotDetectionType, stopBotTriggerCondition, reactivateEnabled, stopBotExamples, and finalMessage.",
          "additionalProperties": true
        }
      },
      "description": "Request body for a GHL Conversation AI action. GHL requires name, type, and details. Action details are redacted from default MCP output.",
      "additionalProperties": true
    },
    "query": {
      "type": "object",
      "description": "Optional GHL-supported query parameters for this official Conversation AI endpoint, such as pagination, agent, or generation filters from the official docs. Do not include locationId unless you only need local safety validation. For conversation_ai_search_agents, search/q/name are accepted but applied locally because GHL rejects those query fields.",
      "additionalProperties": true
    },
    "agentId": {
      "type": "string",
      "description": "agentId path parameter required by /conversation-ai/agents/:agentId/actions/:actionId."
    },
    "actionId": {
      "type": "string",
      "description": "actionId path parameter required by /conversation-ai/agents/:agentId/actions/:actionId."
    },
    "tenantId": {
      "type": "string",
      "description": "Tenant ID from list_tenants."
    },
    "locationId": {
      "type": "string",
      "description": "Optional GHL location ID for safety validation only. If provided, it must match the authenticated runtime location; Conversation AI endpoints are scoped by the PIT token and this field is not forwarded to GHL."
    },
    "strictTenant": {
      "type": "boolean",
      "default": true,
      "description": "Require tenantId to match locationId routing (default: true)."
    },
    "includeFullConfig": {
      "type": "boolean",
      "description": "Defaults to false. Set true only when the user explicitly needs full Conversation AI configuration such as personality, goal, instructions, prompts, knowledge-base IDs, or action parameters."
    }
  },
  "additionalProperties": false
}

Output Schema​

{
  "type": "object",
  "required": [
    "ok",
    "data",
    "error",
    "meta"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Whether the GHL MCP operation completed successfully."
    },
    "data": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Tool-specific GHL or local navigation result when ok is true."
    },
    "meta": {
      "type": "object",
      "description": "Safe execution, routing, and timing metadata.",
      "additionalProperties": true
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ],
      "description": "Safe error details when ok is false; credential values are never returned."
    }
  },
  "description": "Normalized GHL MCP response envelope.",
  "additionalProperties": false
}

Code Examples​

curl -X POST 'https://portal.madpanda3d.com/api/mcp' \
  -H 'Authorization: Bearer mad_live_***' \
  -H 'Content-Type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": "ghl-conversation-ai-update-action-example",
  "method": "tools/call",
  "params": {
    "name": "ghl.conversation_ai_update_action",
    "arguments": {
      "agentId": "agentId_123",
      "actionId": "actionId_123",
      "body": {},
      "query": {},
      "tenantId": "tenantId_123",
      "locationId": "locationId_123",
      "strictTenant": false,
      "includeFullConfig": false
    }
  }
}'

Example Responses​

{
  "ok": true,
  "message": "Tool ghl.conversation_ai_update_action executed successfully.",
  "note": "Response shape varies by MCP tool. Inspect live responses for exact fields."
}