HighLevel: Attach Action to Agent

← Conversation AI operations · Get started

Operation gohighlevel.conversation_ai_create_action

Provider route: POST /conversation-ai/agents/{agentId}/actions. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/gohighlevel with npm, or alter-sdk-gohighlevel with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HighLevelIntegration } from "@alter-ai/gohighlevel";

async function execute(input: Parameters<HighLevelIntegration["conversationAi"]["createAction"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HighLevelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.conversationAi.createAction(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_gohighlevel import HighLevelIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HighLevelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.conversation_ai.create_action(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.agentId	string	Required within parent
body	Model	Required within parent	Expand Update Action — request body — body

Referenced models: Update Action — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Attach Action to Agent — response body

Referenced models: Attach Action to Agent — response body

Schemas

15 more schemas are linked from the tables above, on the schema pages.

Update Action — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
details	JSON	Required within parent	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.
details (oneOf 1)	Model	Alternative	Expand Update Action — request body — body details trigger Condition, trigger Message, workflow Ids
details (oneOf 2)	Model	Alternative	Expand Update Action — request body — body details contact Field Id, contact Update Examples, description
details (oneOf 3)	Model	Alternative	Expand Update Action — request body — body / details / sleepTimeUnit: days, hours, minutes
details (oneOf 4)	Model	Alternative	Expand Update Action — request body — body / details / sleepTimeUnit: days, hours, minutes, stop Bot Detection Type: Goodbye, Custom
details (oneOf 5)	Model	Alternative	Expand Update Action — request body — body / details / handoverType: contact Request, lack Of Information, failed To Resolve Issue, custom, sleep Time Unit: days, hours, minutes
details (oneOf 6)	Model	Alternative	Expand Update Action — request body — body / details / scenarioId: contact Stopped Replying, contact Is Busy, contact Requested
details (oneOf 7)	Model	Alternative	Expand Update Action — request body — body / details / transferBotType: Default, Custom
name	string	Required within parent
type	string	Required within parent	One of: triggerWorkflow, updateContactField, appointmentBooking, stopBot, humanHandOver, advancedFollowup, transferBot

Referenced models: Update Action — request body — body details trigger Condition, trigger Message, workflow Ids, Update Action — request body — body details contact Field Id, contact Update Examples, description, Update Action — request body — body / details / scenarioId: contact Stopped Replying, contact Is Busy, contact Requested, Update Action — request body — body / details / sleepTimeUnit: days, hours, minutes, Update Action — request body — body / details / handoverType: contact Request, lack Of Information, failed To Resolve Issue, custom, sleep Time Unit: days, hours, minutes, Update Action — request body — body / details / sleepTimeUnit: days, hours, minutes, stop Bot Detection Type: Goodbye, Custom, Update Action — request body — body / details / transferBotType: Default, Custom

Attach Action to Agent — response body

Field	Type	Presence	Description and constraints
$	object	Root
data	JSON	Required within parent	Created action details
data (allOf 1)	Model	All variants apply	Expand List Actions for an Agent — response body — data item
success	boolean	Required within parent	Success status of the request

Referenced models: List Actions for an Agent — response body — data item

Update Action — request body — body details trigger Condition, trigger Message, workflow Ids

Field	Type	Presence	Description and constraints
$	object	Root
triggerCondition	string	Required within parent	Condition that triggers the workflow
triggerMessage	string	Optional	Optional message to send when triggering the workflow
workflowIds	array	Required within parent	Array of workflow IDs to trigger
workflowIds[]	string	Each item

Update Action — request body — body details contact Field Id, contact Update Examples, description

Field	Type	Presence	Description and constraints
$	object	Root
contactFieldId	string	Required within parent	ID of the contact field in Contacts Table
contactUpdateExamples	array	Optional	Contact update examples in Contacts Table. Not required when using standard fields, Monetory or Date Custom fields. Default: []
contactUpdateExamples[]	string	Each item
description	string	Required within parent	Description of the contact field in Contacts Table

Update Action — request body — body / details / scenarioId: contact Stopped Replying, contact Is Busy, contact Requested

Field	Type	Presence	Description and constraints
$	object	Root
enabled	boolean	Required within parent	Whether advanced followup is enabled
followupSequence	array	Required within parent	Sequence of followup actions to perform
followupSequence[]	Model	Each item	Expand Update Action — request body — body / details / scenarioId: contact Stopped Replying, contact Is Busy, contact Requested followup Sequence item
followupSettings	JSON	Optional	Additional settings for followup behavior
followupSettings (allOf 1)	Model	All variants apply	Expand Update Followup Settings — request body — body followup Settings
scenarioId	string	Required within parent	ID of the followup scenario One of: contactStoppedReplying, contactIsBusy, contactRequested

Referenced models: Update Action — request body — body / details / scenarioId: contact Stopped Replying, contact Is Busy, contact Requested followup Sequence item, Update Followup Settings — request body — body followup Settings

Update Action — request body — body / details / sleepTimeUnit: days, hours, minutes

Field	Type	Presence	Description and constraints
$	object	Root
actionId	string	Optional	Optional action ID reference
calendarId	string	Required within parent	Calendar ID for appointment booking
cancelEnabled	boolean	Required within parent	Whether to allow appointment cancellation (cannot be true when onlySendLink is true) Default: false
onlySendLink	boolean	Required within parent	If true, only sends the appointment link without booking
rescheduleEnabled	boolean	Required within parent	Whether to allow appointment rescheduling (cannot be true when onlySendLink is true) Default: false
sleepAfterBooking	boolean	Required within parent	Whether to put the agent to sleep after booking (cannot be true when onlySendLink is true)
sleepTime	number	Optional	Sleep duration (required when sleepAfterBooking is true)
sleepTimeUnit	string	Optional	Unit for sleep time (required when sleepAfterBooking is true) One of: days, hours, minutes
transferAgent	string	Optional	Agent ID to transfer to (required when transferBot is true)
transferBot	boolean	Required within parent	Whether to transfer to another agent after booking (cannot be true when onlySendLink is true)
triggerWorkflow	boolean	Required within parent	Whether to trigger a workflow after booking (cannot be true when onlySendLink is true)
workflowIds	array	Optional	Workflow IDs to trigger after booking (required when triggerWorkflow is true)
workflowIds[]	string	Each item

Update Action — request body — body / details / handoverType: contact Request, lack Of Information, failed To Resolve Issue, custom, sleep Time Unit: days, hours, minutes

Field	Type	Presence	Description and constraints
$	object	Root
assignToUserId	string	Optional	ID of the user to assign the conversation to
createTask	boolean	Optional	Whether to create a task when handing over
enabled	boolean	Required within parent	Whether human handover action is enabled
examples	array	Optional	Example phrases that trigger human handover (required when handoverType is custom or contactRequest)
examples[]	string	Each item
finalMessage	string	Required within parent	Final message sent when handing over to human
handoverType	string	Required within parent	Type of human handover detection One of: contactRequest, lackOfInformation, failedToResolveIssue, custom
reactivateEnabled	boolean	Required within parent	Whether the agent can be reactivated after handover
skipAssignToUser	boolean	Optional	Whether to skip assigning to a specific user
sleepTime	number	Optional	Time duration before reactivation (required when reactivateEnabled is true)
sleepTimeUnit	string	Optional	Time unit for reactivation delay (required when reactivateEnabled is true) One of: days, hours, minutes
tags	array	Optional	Tags to apply during handover
tags[]	string	Each item
triggerCondition	string	Required within parent	Condition that triggers human handover

Update Followup Settings — request body — body followup Settings working Hours item intervals item

Field	Type	Presence	Description and constraints
$	object	Root
endHour	number	Required within parent	End hour (24-hour format)
endMinute	number	Required within parent	End minute
startHour	number	Required within parent	Start hour (24-hour format)
startMinute	number	Required within parent	Start minute

Policy, approvals and errors

SDK function policy ID: gohighlevel.conversation_ai_create_action. Catalog operation: conversation-ai.create-action. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["conversation-ai.write"]

Pinned headers: {"Version": "v3"}

Official provider source