Skip to main content
Glama
ghl-mcp-server-v2

ghl-mcp-server-v2

by zackscriven

ghl_conversation_ai_update_action

Idempotent

Update an existing Conversation AI action's configuration, including name, description, trigger condition, and behavior settings, while preserving omitted custom API fields.

Instructions

Update Action Updates an existing action's configuration — name, description, trigger condition and behaviour settings. For customApi ("API Call") actions details.apiConfig is optional: omit it to leave the HTTP definition untouched. When sent, it is merged ONE LEVEL DEEP over the stored config — a top-level key you send replaces the stored value outright, keys you omit are kept. Nested values (headers, queryParams, bodyTemplate, parameters, outputFields) are replaced whole, so send the complete object rather than just the entry you changed. authentication is the exception: secret fields omitted, or returned as the redacted placeholder, keep the stored secret. Endpoint: PUT /conversation-ai/agents/{agentId}/actions/{actionId} (Version header: v3; source: v3/conversation-ai-v3.json) OAuth scopes: conversation-ai.write

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "actionId": "<actionId>",
      "agentId": "<agentId>",
      "body": "<body>"
    },
    "name": "ghl_conversation_ai_update_action"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body (schema carried verbatim from the official OpenAPI spec).
agentIdYesThe unique identifier of the AI agent
actionIdYesThe unique identifier of the action ID Attached to the agent

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv2.1.0
    • addedInput schema / properties / actionId / example
      Added value: +"6578278e879ad2646715ba9c"
    • addedInput schema / properties / agentId / description
      Added value: +"The unique identifier of the AI agent"
    • addedInput schema / properties / agentId / example
      Added value: +"ve9EPM428h8vShlRW1KT"
    • changedInput schema / properties / body / properties / details / description
      Previous value: -"Action-specific details. The structure depends on the action type. For TRIGGER_WORKFLOW use triggerWorkflowDto, for UPDATE_CONTACT_FIELD use updateContactFieldDto, for APPOINTMENT_BOOKING use appointmentBookingDto, for STOP_BOT use stopBotDto, for HUMAN_HAND_OVER use humanHandOverDto, for ADVANCED_FOLLOWUP use advancedFollowupDto, and for TRANSFER_BOT use transferBotDto."New value: +"Action-specific details. The structure depends on the action type. For TRIGGER_WORKFLOW use triggerWorkflowDto, for UPDATE_CONTACT_FIELD use updateContactFieldDto, for APPOINTMENT_BOOKING use appointmentBookingDto, for STOP_BOT use stopBotDto, for HUMAN_HAND_OVER use humanHandOverDto, for ADVANCED_FOLLOWUP use advancedFollowupDto, for TRANSFER_BOT use transferBotDto, and for CUSTOM_API use CustomApiDetailsDTO (the API Call config)."
    • addedInput schema / properties / body / properties / details / example
      Added value: +{
      +  "triggerCondition": "When user requests appointment",
      +  "workflowIds": [
      +    "workflow123"
      +  ]
      +}
    • changedInput schema / properties / body / properties / details / oneOf
      Previous value: -[
      -  {
      -    "properties": {
      -      "triggerCondition": {
      -        "description": "Condition that triggers the workflow",
      -        "example": "When user requests appointment",
      -        "type": "string"
      -      },
      -      "triggerMessage": {
      -        "description": "Optional message to send when triggering the workflow",
      -        "example": "Workflow triggered successfully",
      -        "type": "string"
      -      },
      -      "workflowIds": {
      -        "description": "Array of workflow IDs to trigger",
      -        "example": [
      -          "workflow123",
      -          "workflow456"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      }
      -    },
      -    "required": [
      -      "workflowIds",
      -      "triggerCondition"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "contactFieldId": {
      -        "description": "ID of the contact field in Contacts Table",
      -        "example": "123",
      -        "type": "string"
      -      },
      -      "contactUpdateExamples": {
      -        "default": [],
      -        "description": "Contact update examples in Contacts Table. Not required when using standard fields, Monetory or Date Custom fields.",
      -        "example": [
      -          "Example 1"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "description": {
      -        "description": "Description of the contact field in Contacts Table",
      -        "example": "Business Name",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "contactFieldId",
      -      "description"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "actionId": {
      -        "description": "Optional action ID reference",
      -        "example": "action123",
      -        "type": "string"
      -      },
      -      "calendarId": {
      -        "description": "Calendar ID for appointment booking",
      -        "example": "calendar123",
      -        "type": "string"
      -      },
      -      "cancelEnabled": {
      -        "default": false,
      -        "description": "Whether to allow appointment cancellation (cannot be true when onlySendLink is true)",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "onlySendLink": {
      -        "description": "If true, only sends the appointment link without booking",
      -        "example": false,
      -        "type": "boolean"
      -      },
      -      "rescheduleEnabled": {
      -        "default": false,
      -        "description": "Whether to allow appointment rescheduling (cannot be true when onlySendLink is true)",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "sleepAfterBooking": {
      -        "description": "Whether to put the agent to sleep after booking (cannot be true when onlySendLink is true)",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "sleepTime": {
      -        "description": "Sleep duration (required when sleepAfterBooking is true)",
      -        "example": 24,
      -        "type": "number"
      -      },
      -      "sleepTimeUnit": {
      -        "description": "Unit for sleep time (required when sleepAfterBooking is true)",
      -        "enum": [
      -          "days",
      -          "hours",
      -          "minutes"
      -        ],
      -        "example": "hours",
      -        "type": "string"
      -      },
      -      "transferAgent": {
      -        "description": "Agent ID to transfer to (required when transferBot is true)",
      -        "example": "employee456",
      -        "type": "string"
      -      },
      -      "transferBot": {
      -        "description": "Whether to transfer to another agent after booking (cannot be true when onlySendLink is true)",
      -        "example": false,
      -        "type": "boolean"
      -      },
      -      "triggerWorkflow": {
      -        "description": "Whether to trigger a workflow after booking (cannot be true when onlySendLink is true)",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "workflowIds": {
      -        "description": "Workflow IDs to trigger after booking (required when triggerWorkflow is true)",
      -        "example": [
      -          "workflow123"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      }
      -    },
      -    "required": [
      -      "calendarId",
      -      "onlySendLink",
      -      "triggerWorkflow",
      -      "sleepAfterBooking",
      -      "transferBot",
      -      "rescheduleEnabled",
      -      "cancelEnabled"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "enabled": {
      -        "description": "Whether this action is enabled for the agent",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "finalMessage": {
      -        "description": "Final message sent when stopping the bot",
      -        "example": "Thank you for contacting us. Have a great day!",
      -        "type": "string"
      -      },
      -      "reactivateEnabled": {
      -        "description": "Whether the bot can be reactivated after being stopped",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "sleepTime": {
      -        "description": "Time duration before reactivation (required when reactivateEnabled is true)",
      -        "example": 24,
      -        "type": "number"
      -      },
      -      "sleepTimeUnit": {
      -        "description": "Time unit for reactivation delay (required when reactivateEnabled is true)",
      -        "enum": [
      -          "days",
      -          "hours",
      -          "minutes"
      -        ],
      -        "example": "hours",
      -        "type": "string"
      -      },
      -      "stopBotDetectionType": {
      -        "description": "Type of stop bot detection - Goodbye or Custom",
      -        "enum": [
      -          "Goodbye",
      -          "Custom"
      -        ],
      -        "example": "Custom",
      -        "type": "string"
      -      },
      -      "stopBotExamples": {
      -        "description": "Example phrases that trigger stop bot action (minimum 2 required)",
      -        "example": [
      -          "goodbye",
      -          "thank you",
      -          "no more questions"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "stopBotTriggerCondition": {
      -        "description": "Condition that triggers stopping the bot",
      -        "example": "When the user says they no longer need assistance or want to end the conversation",
      -        "type": "string"
      -      },
      -      "tags": {
      -        "description": "Tags to apply when stopping the bot",
      -        "example": [
      -          "resolved",
      -          "no-response"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      }
      -    },
      -    "required": [
      -      "stopBotDetectionType",
      -      "stopBotTriggerCondition",
      -      "reactivateEnabled",
      -      "enabled",
      -      "stopBotExamples",
      -      "finalMessage"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "assignToUserId": {
      -        "description": "ID of the user to assign the conversation to",
      -        "example": "user123",
      -        "type": "string"
      -      },
      -      "createTask": {
      -        "description": "Whether to create a task when handing over",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "enabled": {
      -        "description": "Whether human handover action is enabled",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "examples": {
      -        "description": "Example phrases that trigger human handover (required when handoverType is custom or contactRequest)",
      -        "example": [
      -          "speak to human",
      -          "talk to agent",
      -          "need help from person"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "finalMessage": {
      -        "description": "Final message sent when handing over to human",
      -        "example": "I am transferring you to a human agent who will assist you shortly.",
      -        "type": "string"
      -      },
      -      "handoverType": {
      -        "description": "Type of human handover detection",
      -        "enum": [
      -          "contactRequest",
      -          "lackOfInformation",
      -          "failedToResolveIssue",
      -          "custom"
      -        ],
      -        "example": "contactRequest",
      -        "type": "string"
      -      },
      -      "reactivateEnabled": {
      -        "description": "Whether the agent can be reactivated after handover",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "skipAssignToUser": {
      -        "description": "Whether to skip assigning to a specific user",
      -        "example": false,
      -        "type": "boolean"
      -      },
      -      "sleepTime": {
      -        "description": "Time duration before reactivation (required when reactivateEnabled is true)",
      -        "example": 24,
      -        "type": "number"
      -      },
      -      "sleepTimeUnit": {
      -        "description": "Time unit for reactivation delay (required when reactivateEnabled is true)",
      -        "enum": [
      -          "days",
      -          "hours",
      -          "minutes"
      -        ],
      -        "example": "hours",
      -        "type": "string"
      -      },
      -      "tags": {
      -        "description": "Tags to apply during handover",
      -        "example": [
      -          "escalated",
      -          "human-requested"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "triggerCondition": {
      -        "description": "Condition that triggers human handover",
      -        "example": "When the user requests to speak with a human agent or expresses frustration",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "enabled",
      -      "triggerCondition",
      -      "reactivateEnabled",
      -      "finalMessage",
      -      "handoverType"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "enabled": {
      -        "description": "Whether advanced followup is enabled",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "followupSequence": {
      -        "description": "Sequence of followup actions to perform",
      -        "items": {
      -          "properties": {
      -            "aiEnabledMessage": {
      -              "default": true,
      -              "description": "Whether to use AI to generate the followup message",
      -              "example": true,
      -              "type": "boolean"
      -            },
      -            "contactRequested": {
      -              "description": "Whether contact was requested in this followup",
      -              "example": false,
      -              "type": "boolean"
      -            },
      -            "customMessage": {
      -              "description": "Custom message to send (when aiEnabledMessage is false)",
      -              "example": "Hi! Just following up on our previous conversation. Do you have any questions?",
      -              "type": "string"
      -            },
      -            "followupTime": {
      -              "description": "Time duration before followup (max: 60 minutes, 24 hours, or 180 days depending on unit)",
      -              "example": 2,
      -              "type": "number"
      -            },
      -            "followupTimeUnit": {
      -              "description": "Time unit for followup delay",
      -              "enum": [
      -                "days",
      -                "hours",
      -                "minutes"
      -              ],
      -              "example": "hours",
      -              "type": "string"
      -            },
      -            "id": {
      -              "description": "Unique identifier for this followup step",
      -              "example": 1,
      -              "type": "number"
      -            },
      -            "triggerWorkflow": {
      -              "default": false,
      -              "description": "Whether to trigger a workflow during this followup",
      -              "example": false,
      -              "type": "boolean"
      -            },
      -            "workflowId": {
      -              "description": "Workflow ID to trigger (when triggerWorkflow is true)",
      -              "example": "workflow789",
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "id",
      -            "followupTimeUnit",
      -            "followupTime"
      -          ],
      -          "type": "object"
      -        },
      -        "type": "array"
      -      },
      -      "followupSettings": {
      -        "allOf": [
      -          {
      -            "properties": {
      -              "dynamicChannelSwitching": {
      -                "default": true,
      -                "description": "Whether to dynamically switch channels for followups",
      -                "example": true,
      -                "type": "boolean"
      -              },
      -              "followUpHours": {
      -                "description": "Whether to respect working hours for followups",
      -                "example": true,
      -                "type": "boolean"
      -              },
      -              "timezoneToUse": {
      -                "description": "Timezone to use for followups, contact or location",
      -                "enum": [
      -                  "contact",
      -                  "business"
      -                ],
      -                "type": "string"
      -              },
      -              "workingHours": {
      -                "description": "Working hours configuration for followups",
      -                "items": {
      -                  "properties": {
      -                    "dayOfTheWeek": {
      -                      "description": "Day of the week (0=Sunday, 1=Monday, etc.)",
      -                      "example": 1,
      -                      "type": "number"
      -                    },
      -                    "intervals": {
      -                      "description": "Time intervals for this day",
      -                      "items": {
      -                        "properties": {
      -                          "endHour": {
      -                            "description": "End hour (24-hour format)",
      -                            "example": 17,
      -                            "type": "number"
      -                          },
      -                          "endMinute": {
      -                            "description": "End minute",
      -                            "example": 30,
      -                            "type": "number"
      -                          },
      -                          "startHour": {
      -                            "description": "Start hour (24-hour format)",
      -                            "example": 9,
      -                            "type": "number"
      -                          },
      -                          "startMinute": {
      -                            "description": "Start minute",
      -                            "example": 0,
      -                            "type": "number"
      -                          }
      -                        },
      -                        "required": [
      -                          "startHour",
      -                          "startMinute",
      -                          "endHour",
      -                          "endMinute"
      -                        ],
      -                        "type": "object"
      -                      },
      -                      "type": "array"
      -                    }
      -                  },
      -                  "required": [
      -                    "dayOfTheWeek"
      -                  ],
      -                  "type": "object"
      -                },
      -                "type": "array"
      -              }
      -            },
      -            "required": [
      -              "dynamicChannelSwitching"
      -            ],
      -            "type": "object"
      -          }
      -        ],
      -        "description": "Additional settings for followup behavior"
      -      },
      -      "scenarioId": {
      -        "description": "ID of the followup scenario",
      -        "enum": [
      -          "contactStoppedReplying",
      -          "contactIsBusy",
      -          "contactRequested"
      -        ],
      -        "example": "contactIsBusy",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "enabled",
      -      "scenarioId",
      -      "followupSequence"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "enabled": {
      -        "description": "Whether this transfer action is enabled",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "transferBotExamples": {
      -        "description": "Example phrases that trigger transfer (required for Custom type, minimum 2)",
      -        "example": [
      -          "talk to sales",
      -          "pricing information",
      -          "speak to specialist"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "transferBotTriggerCondition": {
      -        "description": "Condition that triggers the transfer (required for Custom type)",
      -        "example": "When the user asks to speak with sales or needs pricing information",
      -        "type": "string"
      -      },
      -      "transferBotType": {
      -        "description": "Type of transfer - Default or Custom",
      -        "enum": [
      -          "Default",
      -          "Custom"
      -        ],
      -        "example": "Custom",
      -        "type": "string"
      -      },
      -      "transferToBot": {
      -        "description": "ID of the bot/agent to transfer to",
      -        "example": "employee789",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "transferBotType",
      -      "transferToBot",
      -      "enabled"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "properties": {
      +      "triggerCondition": {
      +        "description": "Condition that triggers the workflow",
      +        "example": "When user requests appointment",
      +        "type": "string"
      +      },
      +      "triggerMessage": {
      +        "description": "Optional message to send when triggering the workflow",
      +        "example": "Workflow triggered successfully",
      +        "type": "string"
      +      },
      +      "workflowIds": {
      +        "description": "Array of workflow IDs to trigger",
      +        "example": [
      +          "workflow123",
      +          "workflow456"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "workflowIds",
      +      "triggerCondition"
      +    ],
      +    "title": "triggerWorkflowDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "contactFieldId": {
      +        "description": "ID of the contact field in Contacts Table",
      +        "example": "123",
      +        "type": "string"
      +      },
      +      "contactUpdateExamples": {
      +        "default": [],
      +        "description": "Contact update examples in Contacts Table. Not required when using standard fields, Monetory or Date Custom fields.",
      +        "example": [
      +          "Example 1"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "description": {
      +        "description": "Description of the contact field in Contacts Table",
      +        "example": "Business Name",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "contactFieldId",
      +      "description"
      +    ],
      +    "title": "updateContactFieldDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "actionId": {
      +        "description": "Optional action ID reference",
      +        "example": "action123",
      +        "type": "string"
      +      },
      +      "calendarId": {
      +        "description": "Calendar ID for appointment booking",
      +        "example": "calendar123",
      +        "type": "string"
      +      },
      +      "cancelEnabled": {
      +        "default": false,
      +        "description": "Whether to allow appointment cancellation (cannot be true when onlySendLink is true)",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "onlySendLink": {
      +        "description": "If true, only sends the appointment link without booking",
      +        "example": false,
      +        "type": "boolean"
      +      },
      +      "rescheduleEnabled": {
      +        "default": false,
      +        "description": "Whether to allow appointment rescheduling (cannot be true when onlySendLink is true)",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "sleepAfterBooking": {
      +        "description": "Whether to put the agent to sleep after booking (cannot be true when onlySendLink is true)",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "sleepTime": {
      +        "description": "Sleep duration (required when sleepAfterBooking is true)",
      +        "example": 24,
      +        "type": "number"
      +      },
      +      "sleepTimeUnit": {
      +        "description": "Unit for sleep time (required when sleepAfterBooking is true)",
      +        "enum": [
      +          "days",
      +          "hours",
      +          "minutes"
      +        ],
      +        "example": "hours",
      +        "type": "string"
      +      },
      +      "transferAgent": {
      +        "description": "Agent ID to transfer to (required when transferBot is true)",
      +        "example": "employee456",
      +        "type": "string"
      +      },
      +      "transferBot": {
      +        "description": "Whether to transfer to another agent after booking (cannot be true when onlySendLink is true)",
      +        "example": false,
      +        "type": "boolean"
      +      },
      +      "triggerWorkflow": {
      +        "description": "Whether to trigger a workflow after booking (cannot be true when onlySendLink is true)",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "workflowIds": {
      +        "description": "Workflow IDs to trigger after booking (required when triggerWorkflow is true)",
      +        "example": [
      +          "workflow123"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "calendarId",
      +      "onlySendLink",
      +      "triggerWorkflow",
      +      "sleepAfterBooking",
      +      "transferBot",
      +      "rescheduleEnabled",
      +      "cancelEnabled"
      +    ],
      +    "title": "appointmentBookingDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "enabled": {
      +        "description": "Whether this action is enabled for the agent",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "finalMessage": {
      +        "description": "Final message sent when stopping the bot",
      +        "example": "Thank you for contacting us. Have a great day!",
      +        "type": "string"
      +      },
      +      "reactivateEnabled": {
      +        "description": "Whether the bot can be reactivated after being stopped",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "sleepTime": {
      +        "description": "Time duration before reactivation (required when reactivateEnabled is true)",
      +        "example": 24,
      +        "type": "number"
      +      },
      +      "sleepTimeUnit": {
      +        "description": "Time unit for reactivation delay (required when reactivateEnabled is true)",
      +        "enum": [
      +          "days",
      +          "hours",
      +          "minutes"
      +        ],
      +        "example": "hours",
      +        "type": "string"
      +      },
      +      "stopBotDetectionType": {
      +        "description": "Type of stop bot detection - Goodbye or Custom",
      +        "enum": [
      +          "Goodbye",
      +          "Custom"
      +        ],
      +        "example": "Custom",
      +        "type": "string"
      +      },
      +      "stopBotExamples": {
      +        "description": "Example phrases that trigger stop bot action (minimum 2 required)",
      +        "example": [
      +          "goodbye",
      +          "thank you",
      +          "no more questions"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "stopBotTriggerCondition": {
      +        "description": "Condition that triggers stopping the bot",
      +        "example": "When the user says they no longer need assistance or want to end the conversation",
      +        "type": "string"
      +      },
      +      "tags": {
      +        "description": "Tags to apply when stopping the bot",
      +        "example": [
      +          "resolved",
      +          "no-response"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "stopBotDetectionType",
      +      "stopBotTriggerCondition",
      +      "reactivateEnabled",
      +      "enabled",
      +      "stopBotExamples",
      +      "finalMessage"
      +    ],
      +    "title": "stopBotDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "assignToUserId": {
      +        "description": "ID of the user to assign the conversation to",
      +        "example": "user123",
      +        "type": "string"
      +      },
      +      "createTask": {
      +        "description": "Whether to create a task when handing over",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "enabled": {
      +        "description": "Whether human handover action is enabled",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "examples": {
      +        "description": "Example phrases that trigger human handover (required when handoverType is custom or contactRequest)",
      +        "example": [
      +          "speak to human",
      +          "talk to agent",
      +          "need help from person"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "finalMessage": {
      +        "description": "Final message sent when handing over to human",
      +        "example": "I am transferring you to a human agent who will assist you shortly.",
      +        "type": "string"
      +      },
      +      "handoverType": {
      +        "description": "Type of human handover detection",
      +        "enum": [
      +          "contactRequest",
      +          "lackOfInformation",
      +          "failedToResolveIssue",
      +          "custom"
      +        ],
      +        "example": "contactRequest",
      +        "type": "string"
      +      },
      +      "reactivateEnabled": {
      +        "description": "Whether the agent can be reactivated after handover",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "skipAssignToUser": {
      +        "description": "Whether to skip assigning to a specific user",
      +        "example": false,
      +        "type": "boolean"
      +      },
      +      "sleepTime": {
      +        "description": "Time duration before reactivation (required when reactivateEnabled is true)",
      +        "example": 24,
      +        "type": "number"
      +      },
      +      "sleepTimeUnit": {
      +        "description": "Time unit for reactivation delay (required when reactivateEnabled is true)",
      +        "enum": [
      +          "days",
      +          "hours",
      +          "minutes"
      +        ],
      +        "example": "hours",
      +        "type": "string"
      +      },
      +      "tags": {
      +        "description": "Tags to apply during handover",
      +        "example": [
      +          "escalated",
      +          "human-requested"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "triggerCondition": {
      +        "description": "Condition that triggers human handover",
      +        "example": "When the user requests to speak with a human agent or expresses frustration",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "enabled",
      +      "triggerCondition",
      +      "reactivateEnabled",
      +      "finalMessage",
      +      "handoverType"
      +    ],
      +    "title": "humanHandOverDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "enabled": {
      +        "description": "Whether advanced followup is enabled",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "followupSequence": {
      +        "description": "Sequence of followup actions to perform",
      +        "example": [
      +          {
      +            "aiEnabledMessage": true,
      +            "followupTime": 2,
      +            "followupTimeUnit": "hours",
      +            "id": 1
      +          }
      +        ],
      +        "items": {
      +          "properties": {
      +            "aiEnabledMessage": {
      +              "default": true,
      +              "description": "Whether to use AI to generate the followup message",
      +              "example": true,
      +              "type": "boolean"
      +            },
      +            "contactRequested": {
      +              "description": "Whether contact was requested in this followup",
      +              "example": false,
      +              "type": "boolean"
      +            },
      +            "customMessage": {
      +              "description": "Custom message to send (when aiEnabledMessage is false)",
      +              "example": "Hi! Just following up on our previous conversation. Do you have any questions?",
      +              "type": "string"
      +            },
      +            "followupTime": {
      +              "description": "Time duration before followup (max: 60 minutes, 24 hours, or 180 days depending on unit)",
      +              "example": 2,
      +              "type": "number"
      +            },
      +            "followupTimeUnit": {
      +              "description": "Time unit for followup delay",
      +              "enum": [
      +                "days",
      +                "hours",
      +                "minutes"
      +              ],
      +              "example": "hours",
      +              "type": "string"
      +            },
      +            "id": {
      +              "description": "Unique identifier for this followup step",
      +              "example": 1,
      +              "type": "number"
      +            },
      +            "triggerWorkflow": {
      +              "default": false,
      +              "description": "Whether to trigger a workflow during this followup",
      +              "example": false,
      +              "type": "boolean"
      +            },
      +            "workflowId": {
      +              "description": "Workflow ID to trigger (when triggerWorkflow is true)",
      +              "example": "workflow789",
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "id",
      +            "followupTimeUnit",
      +            "followupTime"
      +          ],
      +          "title": "FollowupSequence",
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "followupSettings": {
      +        "allOf": [
      +          {
      +            "properties": {
      +              "dynamicChannelSwitching": {
      +                "default": true,
      +                "description": "Whether to dynamically switch channels for followups",
      +                "example": true,
      +                "type": "boolean"
      +              },
      +              "followUpHours": {
      +                "description": "Whether to respect working hours for followups",
      +                "example": true,
      +                "type": "boolean"
      +              },
      +              "timezoneToUse": {
      +                "description": "Timezone to use for followups, contact or location",
      +                "enum": [
      +                  "contact",
      +                  "business"
      +                ],
      +                "example": "contact",
      +                "type": "string"
      +              },
      +              "workingHours": {
      +                "description": "Working hours configuration for followups",
      +                "example": [
      +                  {
      +                    "dayOfTheWeek": 1,
      +                    "intervals": [
      +                      {
      +                        "endHour": 17,
      +                        "endMinute": 0,
      +                        "startHour": 9,
      +                        "startMinute": 0
      +                      }
      +                    ]
      +                  }
      +                ],
      +                "items": {
      +                  "properties": {
      +                    "dayOfTheWeek": {
      +                      "description": "Day of the week (0=Sunday, 1=Monday, etc.)",
      +                      "example": 1,
      +                      "type": "number"
      +                    },
      +                    "intervals": {
      +                      "description": "Time intervals for this day",
      +                      "example": [
      +                        {
      +                          "endHour": 17,
      +                          "endMinute": 0,
      +                          "startHour": 9,
      +                          "startMinute": 0
      +                        }
      +                      ],
      +                      "items": {
      +                        "properties": {
      +                          "endHour": {
      +                            "description": "End hour (24-hour format)",
      +                            "example": 17,
      +                            "type": "number"
      +                          },
      +                          "endMinute": {
      +                            "description": "End minute",
      +                            "example": 30,
      +                            "type": "number"
      +                          },
      +                          "startHour": {
      +                            "description": "Start hour (24-hour format)",
      +                            "example": 9,
      +                            "type": "number"
      +                          },
      +                          "startMinute": {
      +                            "description": "Start minute",
      +                            "example": 0,
      +                            "type": "number"
      +                          }
      +                        },
      +                        "required": [
      +                          "startHour",
      +                          "startMinute",
      +                          "endHour",
      +                          "endMinute"
      +                        ],
      +                        "title": "Interval",
      +                        "type": "object"
      +                      },
      +                      "type": "array"
      +                    }
      +                  },
      +                  "required": [
      +                    "dayOfTheWeek"
      +                  ],
      +                  "title": "WorkingHours",
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              }
      +            },
      +            "required": [
      +              "dynamicChannelSwitching"
      +            ],
      +            "title": "FollowupSettings",
      +            "type": "object"
      +          }
      +        ],
      +        "description": "Additional settings for followup behavior",
      +        "example": {
      +          "dynamicChannelSwitching": true,
      +          "followUpHours": false,
      +          "timezoneToUse": "contact"
      +        }
      +      },
      +      "scenarioId": {
      +        "description": "ID of the followup scenario",
      +        "enum": [
      +          "contactStoppedReplying",
      +          "contactIsBusy",
      +          "contactRequested"
      +        ],
      +        "example": "contactIsBusy",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "enabled",
      +      "scenarioId",
      +      "followupSequence"
      +    ],
      +    "title": "advancedFollowupDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "enabled": {
      +        "description": "Whether this transfer action is enabled",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "transferBotExamples": {
      +        "description": "Example phrases that trigger transfer (required for Custom type, minimum 2)",
      +        "example": [
      +          "talk to sales",
      +          "pricing information",
      +          "speak to specialist"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "transferBotTriggerCondition": {
      +        "description": "Condition that triggers the transfer (required for Custom type)",
      +        "example": "When the user asks to speak with sales or needs pricing information",
      +        "type": "string"
      +      },
      +      "transferBotType": {
      +        "description": "Type of transfer - Default or Custom",
      +        "enum": [
      +          "Default",
      +          "Custom"
      +        ],
      +        "example": "Custom",
      +        "type": "string"
      +      },
      +      "transferToBot": {
      +        "description": "ID of the bot/agent to transfer to",
      +        "example": "employee789",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "transferBotType",
      +      "transferToBot",
      +      "enabled"
      +    ],
      +    "title": "transferBotDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "apiConfig": {
      +        "allOf": [
      +          {
      +            "properties": {
      +              "authentication": {
      +                "description": "Auth config; secrets stored per-instance, write-only",
      +                "example": {
      +                  "token": "••••••••",
      +                  "type": "bearer"
      +                },
      +                "type": "object"
      +              },
      +              "bodyTemplate": {
      +                "description": "Request body template — object or raw JSON string. Supports {{variable}} placeholders.",
      +                "example": {
      +                  "email": "{{contact.email}}",
      +                  "orderId": "{{parameters.orderId}}"
      +                },
      +                "type": "object"
      +              },
      +              "headers": {
      +                "additionalProperties": {
      +                  "type": "string"
      +                },
      +                "description": "Static HTTP headers sent with every call. Secrets belong in `authentication`, not here. On update this object REPLACES the stored headers — send them all, not just the changed one.",
      +                "example": {
      +                  "Content-Type": "application/json",
      +                  "X-Source": "conversation-ai"
      +                },
      +                "type": "object"
      +              },
      +              "method": {
      +                "description": "HTTP method used for the call. REQUIRED on create. Optional on update — omit it to keep the stored method.",
      +                "enum": [
      +                  "GET",
      +                  "POST",
      +                  "PUT",
      +                  "PATCH",
      +                  "DELETE"
      +                ],
      +                "example": "GET",
      +                "type": "string"
      +              },
      +              "outputFields": {
      +                "description": "Dot-paths of the response fields handed back to the agent. Omit to return the whole body; use [] notation for arrays, e.g. `result[].id`.",
      +                "example": [
      +                  "data.id",
      +                  "data.status"
      +                ],
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              "parameters": {
      +                "additionalProperties": true,
      +                "description": "JSON Schema of LLM-supplied params",
      +                "example": {
      +                  "properties": {
      +                    "orderId": {
      +                      "description": "The order number the caller gave",
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "orderId"
      +                  ],
      +                  "type": "object"
      +                },
      +                "type": "object"
      +              },
      +              "queryParams": {
      +                "additionalProperties": {
      +                  "type": "string"
      +                },
      +                "description": "Static query-string parameters appended to the URL.",
      +                "example": {
      +                  "limit": "10",
      +                  "status": "active"
      +                },
      +                "type": "object"
      +              },
      +              "retryOnFailure": {
      +                "description": "Retry the call once on a network error or a 5xx. 4xx is never retried.",
      +                "example": false,
      +                "type": "boolean"
      +              },
      +              "sampleResponse": {
      +                "additionalProperties": true,
      +                "description": "Trimmed sample of a real response (editor Test tab). Prompt-only — inlined so the agent knows the response shape; never executed. Secrets are masked on read.",
      +                "type": "object"
      +              },
      +              "timeoutMs": {
      +                "description": "Per-request timeout in milliseconds (max 60000).",
      +                "example": 15000,
      +                "type": "number"
      +              },
      +              "url": {
      +                "description": "HTTPS endpoint; supports {{var}}. REQUIRED on create. Optional on update — omit it to keep the stored url (apiConfig merges by top-level key).",
      +                "example": "https://api.example.com/orders/{{orderId}}",
      +                "type": "string"
      +              },
      +              "useSimpleRequestBody": {
      +                "description": "Send the body template verbatim as raw JSON instead of building it from the parameter schema.",
      +                "example": false,
      +                "type": "boolean"
      +              }
      +            },
      +            "title": "ApiCallConfigDTO",
      +            "type": "object"
      +          }
      +        ],
      +        "description": "The self-contained HTTP definition. Required on CREATE (enforced in the handler). OPTIONAL on UPDATE — omit it to edit just name/description/triggerCondition. When sent on update it is merged ONE LEVEL DEEP over the stored config: top-level keys present replace the stored value, keys absent are kept, and nested objects/arrays (headers, queryParams, bodyTemplate, parameters, outputFields) are replaced whole — send the complete value, not just the entry that changed. Secrets are redacted on read; see `authentication` for how they round-trip."
      +      },
      +      "description": {
      +        "description": "Optional description of the API Call action",
      +        "example": "Looks up an order in the fulfilment system and returns its status and delivery date.",
      +        "maxLength": 2000,
      +        "type": "string"
      +      },
      +      "postActionPrompt": {
      +        "description": "Guidance the agent follows AFTER the call returns (e.g. how to phrase the reply, what not to reveal). REQUIRED on CREATE (enforced in the handler) to match the builder; on UPDATE it may be OMITTED to leave it unchanged (partial merge), but sending it blank is rejected.",
      +        "maxLength": 300,
      +        "type": "string"
      +      },
      +      "triggerCondition": {
      +        "description": "\"use this when…\" rule shown to the agent. REQUIRED on CREATE (enforced in the handler) to match the builder; on UPDATE it may be OMITTED to leave it unchanged, but sending it blank is rejected.",
      +        "example": "When the customer asks where their order is or for a delivery date.",
      +        "maxLength": 500,
      +        "type": "string"
      +      }
      +    },
      +    "title": "CustomApiDetailsDTO",
      +    "type": "object"
      +  }
      +]
    • addedInput schema / properties / body / properties / name / description
      Added value: +"Name of the action (3-50 characters)"
    • addedInput schema / properties / body / properties / type / description
      Added value: +"Type of action to perform"
    • changedInput schema / properties / body / properties / type / enum
      Previous value: -[
      -  "triggerWorkflow",
      -  "updateContactField",
      -  "appointmentBooking",
      -  "stopBot",
      -  "humanHandOver",
      -  "advancedFollowup",
      -  "transferBot"
      -]New value: +[
      +  "triggerWorkflow",
      +  "updateContactField",
      +  "appointmentBooking",
      +  "stopBot",
      +  "humanHandOver",
      +  "advancedFollowup",
      +  "transferBot",
      +  "customApi"
      +]
    • addedInput schema / properties / body / title
      Added value: +"CreateActionDTO"
  2. First observedv2.0.0

TDQS

A4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond annotations: it explains the one-level-deep merge semantics for customApi details, specifies that nested objects and arrays are replaced wholesale, clarifies that authentication secrets are preserved unless explicitly overwritten, and mentions the endpoint and required OAuth scope. This is rich, actionable behavioral context that an agent would otherwise lack.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then proceeds to detailed edge-case behavior. Every sentence is relevant, but the inclusion of endpoint and OAuth scope details, while useful, could be considered slightly beyond the minimal need for tool selection. Overall it is well-organized and dense with necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of nested objects and multiple action types, the description provides complete context about update behavior, merge pitfalls, secret handling, and API endpoint requirements. With annotations covering safety and idempotency, and schema covering all parameters, nothing essential is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter. The description adds some merge behavior detail, but that same information is also present in the schema's own descriptions. It provides no new parameter-specific semantics beyond what the schema already conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Updates an existing action's configuration' and lists the fields that can be changed. It is specific about verb and resource, though it does not explicitly distinguish itself from sibling update tools like ghl_voice_ai_update_action or ghl_conversation_ai_create_action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'Updates an existing action', but there is no explicit guidance on when to choose this tool versus alternatives (e.g., create_action or voice_ai_update_action). The only concrete usage hint is about omitting details.apiConfig on update, which is parameter-level rather than overall tool selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools