HighLevel: Create Agent — voice Ai create Agent

← Voice AI operations · Get started

Operation gohighlevel.voice_ai_create_agent

Provider route: POST /voice-ai/agents. 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["voiceAi"]["createAgent"]>[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.voiceAi.createAgent(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.voice_ai.create_agent(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	Model	Required within parent	Expand Create Agent — voice Ai create Agent — request body — body

Referenced models: Create Agent — voice Ai create Agent — 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 Patch Agent — response body

Referenced models: Patch Agent — response body

Schemas

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

Create Agent — voice Ai create Agent — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
agentName	string	Optional	Display name for the voice AI agent, between 1-40 characters. Default: "My Agent {random 3 digit number}" Maximum length: 40 Minimum length: 1
agentPrompt	string	Optional	Custom instructions defining the agent's behavior and personality. Default: Basic prompt generated automatically
agentWorkingHours	array	Optional	Time intervals defining when the agent accepts calls, organized by day of week. Default: [] (available 24/7)
agentWorkingHours[]	Model	Each item	Expand Patch Agent — request body — body agent Working Hours item
businessName	string	Optional	Name of the business this agent represents. Default: Uses location name Minimum length: 1
callEndWorkflowIds	array	Optional	Array of workflow IDs to trigger automatically when calls end. Default: [] Maximum items: 10
callEndWorkflowIds[]	string	Each item
inboundNumber	string	Optional	Phone number for receiving inbound calls to this agent. Default: null
isAgentAsBackupDisabled	boolean	Optional	Prevents this agent from being used as a fallback option. Default: false (Available as backup agent)
language	string	Optional	Language code for the agent's speech and understanding. Default: "en-US" One of: en-US, pt-BR, es, fr, de, it, nl-NL, multi
locationId	string	Required within parent	Unique identifier for the location where this agent will operate
maxCallDuration	number	Optional	Maximum call duration in seconds, between 180-900 (3-15 minutes). Default: 300 seconds (5 minutes) Maximum: 900 Minimum: 180
numberPoolId	string	Optional	Identifier for the number pool managing phone number allocation. Default: null
patienceLevel	string	Optional	Tolerance level for caller response delays. Default: "high" One of: low, medium, high
reminderAfterIdleTimeSeconds	number	Optional	Seconds to wait before sending idle reminders, between 1-20. Default: 8 seconds Maximum: 20 Minimum: 1
sendPostCallNotificationTo	JSON	Optional	Configuration for post-call email notifications to various recipients. Default: []
sendPostCallNotificationTo (allOf 1)	Model	All variants apply	Expand Patch Agent — request body — body send Post Call Notification To admins, all Users, contact Assigned User, custom Emails, specific Users
sendUserIdleReminders	boolean	Optional	Enables automatic reminders when callers are silent. Default: true
timezone	string	Optional	IANA timezone identifier affecting working hours and scheduling. Default: Location timezone Pattern: ^[A-Za-z_]+/[A-Za-z_]+$
translation	JSON	Optional	Language translation settings including enablement flag and target language code. Rules: (1) translation.enabled can only be true if the agent's language is not en-US; (2) when enabled, translation.language must be either the agent's language or en-US; (3) when enabled, translation.language is required.
translation (allOf 1)	Model	All variants apply	Expand Patch Agent — request body — body translation enabled, language
voiceId	string	Optional	Identifier for the speech synthesis voice from available voice options. Default: Auto generated
welcomeMessage	string	Optional	Initial greeting spoken when the agent answers calls. Default: Auto generated Maximum length: 190 Minimum length: 1

Referenced models: Patch Agent — request body — body agent Working Hours item, Patch Agent — request body — body send Post Call Notification To admins, all Users, contact Assigned User, custom Emails, specific Users, Patch Agent — request body — body translation enabled, language

Patch Agent — response body

Field	Type	Presence	Description and constraints
$	object	Root
agentName	string	Required within parent	Display name of the voice AI agent
agentPrompt	string	Required within parent	Custom instructions defining the agent's behavior
agentWorkingHours	array	Optional	Time intervals when the agent accepts calls, organized by day of week
agentWorkingHours[]	Model	Each item	Expand Patch Agent — response body — agent Working Hours item
businessName	string	Required within parent	Name of the business this agent represents
callEndWorkflowIds	array	Optional	Array of workflow IDs triggered automatically when calls end
callEndWorkflowIds[]	string	Each item
id	string	Required within parent	Unique identifier for the created agent
inboundNumber	string	Optional	Phone number for receiving inbound calls
isAgentAsBackupDisabled	boolean	Required within parent	Indicates whether this agent is excluded from backup scenarios
language	string	Required within parent	Language code for the agent's speech and understanding
locationId	string	Required within parent	Unique identifier for the location where this agent operates
maxCallDuration	JSON	Required within parent
maxCallDuration (anyOf 1)	number	Alternative	Maximum call duration in seconds, between 180-900 Maximum: 900 Minimum: 180
maxCallDuration (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
numberPoolId	string	Optional	Identifier for the number pool managing this agent's phone allocation
patienceLevel	string	Required within parent	Current tolerance level for caller response delays
reminderAfterIdleTimeSeconds	JSON	Required within parent
reminderAfterIdleTimeSeconds (anyOf 1)	number	Alternative	Seconds to wait before sending idle reminders, between 1-20 Maximum: 20 Minimum: 1
reminderAfterIdleTimeSeconds (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
sendPostCallNotificationTo	JSON	Optional	Current post-call notification settings including recipient configuration
sendPostCallNotificationTo (allOf 1)	Model	All variants apply	Expand Patch Agent — response body — send Post Call Notification To admins, all Users, contact Assigned User, custom Emails, specific Users
sendUserIdleReminders	boolean	Required within parent	Indicates whether automatic idle reminders are enabled
timezone	string	Required within parent	IANA timezone identifier for working hours and scheduling
translation	JSON	Optional	Current language translation settings including enablement status and target language
translation (allOf 1)	Model	All variants apply	Expand Patch Agent — response body — translation enabled, language
voiceId	string	Required within parent	Identifier for the speech synthesis voice being used
welcomeMessage	string	Required within parent	Greeting message spoken when the agent answers calls

Referenced models: Patch Agent — response body — agent Working Hours item, Patch Agent — response body — send Post Call Notification To admins, all Users, contact Assigned User, custom Emails, specific Users, Patch Agent — response body — translation enabled, language

Patch Agent — request body — body agent Working Hours item

Field	Type	Presence	Description and constraints
$	object	Root
dayOfTheWeek	number	Required within parent	Day of the week for this working hours configuration (Monday=1 to Sunday=7) One of: 1, 2, 3, 4, 5, 6, 7
intervals	array	Required within parent	Array of time intervals when the agent is available on this day
intervals[]	Model	Each item	Expand Patch Agent — request body — body agent Working Hours item intervals item

Referenced models: Patch Agent — request body — body agent Working Hours item intervals item

Patch Agent — request body — body send Post Call Notification To admins, all Users, contact Assigned User, custom Emails, specific Users

Field	Type	Presence	Description and constraints
$	object	Root
admins	boolean	Required within parent	Enables post-call notifications to all admin users in the location. Default: true
allUsers	boolean	Required within parent	Enables post-call notifications to all users in the location. Default: false
contactAssignedUser	boolean	Required within parent	Enables post-call notifications to the user assigned to the contact. Default: false
customEmails	array	Required within parent	Array of custom email addresses to receive post-call notifications. Default: []
customEmails[]	string	Each item
specificUsers	array	Required within parent	Array of specific user IDs to receive post-call notifications. Default: []
specificUsers[]	string	Each item

Patch Agent — request body — body translation enabled, language

Field	Type	Presence	Description and constraints
$	object	Root
enabled	boolean	Required within parent	Enables language translation for agent conversations. Default: false
language	string	Optional	Target language code for translation (e.g., "es" for Spanish, "fr" for French).

Patch Agent — response body — translation enabled, language

Field	Type	Presence	Description and constraints
$	object	Root
enabled	boolean	Optional	Whether translation is enabled
language	string	Optional	Translation language code

Policy, approvals and errors

SDK function policy ID: gohighlevel.voice_ai_create_agent. Catalog operation: voice-ai.create-agent. 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: ["voice-ai-agents.write"]

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

Official provider source