HighLevel: Create Chat Widget

HighLevel chatWidget.createChatWidget: arguments, response, policy and SDK examples.

Operation gohighlevel.createchatwidget

Provider route: POST /chat-widget/. 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["chatWidget"]["createChatWidget"]>[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.chatWidget.createChatWidget(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.chat_widget.create_chat_widget(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 Chat Widget — request body — body

Referenced models: Create Chat Widget — 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
`$`	JSON	Root

Schemas

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

Create Chat Widget — request body — body

Field	Type	Presence	Description and constraints
`$`	object	Root
`chatType`	string	Required within parent	Chat type One of: liveChat, emailChat
`default`	boolean	Optional	Default
`deleted`	boolean	Optional	Deleted
`locationId`	string	Required within parent	Location ID
`name`	string	Required within parent	Name
`settings`	JSON	Optional	Settings
`settings (allOf 1)`	Model	All variants apply	Expand Patch Chat Widget — request body — body settings acknowledgement Details, advance Settings, agency Name, agency Website, allow Avatar Image, auto Country Code, chat Icon, chat Type, country Code, dimensions, enable Revisit Message, heading, is Prompt Avatar Image Optimize, legal Msg, live Chat Ack Msg, live Chat Ended Msg, live Chat Feedback Msg, live Chat Feedback Note, live Chat Intro Msg, live Chat User Inactive Msg, live Chat User Inactive Time, live Chat Visitor Inactive Msg, live Chat Visitor Inactive Time, locale, location Country Code, prompt Avatar, prompt Avatar Alt Text, prompt Msg, prompt Type, representative Assigned Message, revisit Prompt Msg, send Action Text, show Agency Branding, show Consent Checkbox, show Live Chat Welcome Msg, show Prompt, sub Heading, success Msg, support Contact, thank You Msg, theme, use Email Field, wa Number, widget Id, widget Placement, widget Primary Color
`version`	number	Required within parent	Version

Referenced models: Patch Chat Widget — request body — body settings acknowledgement Details, advance Settings, agency Name, agency Website, allow Avatar Image, auto Country Code, chat Icon, chat Type, country Code, dimensions, enable Revisit Message, heading, is Prompt Avatar Image Optimize, legal Msg, live Chat Ack Msg, live Chat Ended Msg, live Chat Feedback Msg, live Chat Feedback Note, live Chat Intro Msg, live Chat User Inactive Msg, live Chat User Inactive Time, live Chat Visitor Inactive Msg, live Chat Visitor Inactive Time, locale, location Country Code, prompt Avatar, prompt Avatar Alt Text, prompt Msg, prompt Type, representative Assigned Message, revisit Prompt Msg, send Action Text, show Agency Branding, show Consent Checkbox, show Live Chat Welcome Msg, show Prompt, sub Heading, success Msg, support Contact, thank You Msg, theme, use Email Field, wa Number, widget Id, widget Placement, widget Primary Color

Field	Type	Presence	Description and constraints
`$`	object	Root
`icon`	string	Optional	Icon
`liveChatIcon`	string	Optional	Icon for live chat
`liveChatPlaceholderColor`	string	Optional	Placeholder color for live chat
`placeholderColor`	string	Optional	Placeholder color

Field	Type	Presence	Description and constraints
`$`	object	Root
`position`	string	Optional	Position
`sizes`	JSON	Optional	Typography Color Options
`sizes (allOf 1)`	Model	All variants apply	Expand Patch Chat Widget — request body — body settings acknowledgement Details, advance Settings, agency Name, agency Website, allow Avatar Image, auto Country Code, chat Icon, chat Type, country Code, dimensions, enable Revisit Message, heading, is Prompt Avatar Image Optimize, legal Msg, live Chat Ack Msg, live Chat Ended Msg, live Chat Feedback Msg, live Chat Feedback Note, live Chat Intro Msg, live Chat User Inactive Msg, live Chat User Inactive Time, live Chat Visitor Inactive Msg, live Chat Visitor Inactive Time, locale, location Country Code, prompt Avatar, prompt Avatar Alt Text, prompt Msg, prompt Type, representative Assigned Message, revisit Prompt Msg, send Action Text, show Agency Branding, show Consent Checkbox, show Live Chat Welcome Msg, show Prompt, sub Heading, success Msg, support Contact, thank You Msg, theme, use Email Field, wa Number, widget Id, widget Placement, widget Primary Color dimensions position, sizes sizes height, width

Field	Type	Presence	Description and constraints
`$`	object	Root
`colors`	JSON	Optional	Custom Color Options
`colors (allOf 1)`	Model	All variants apply	Expand Patch Chat Widget — request body — body settings acknowledgement Details, advance Settings, agency Name, agency Website, allow Avatar Image, auto Country Code, chat Icon, chat Type, country Code, dimensions, enable Revisit Message, heading, is Prompt Avatar Image Optimize, legal Msg, live Chat Ack Msg, live Chat Ended Msg, live Chat Feedback Msg, live Chat Feedback Note, live Chat Intro Msg, live Chat User Inactive Msg, live Chat User Inactive Time, live Chat Visitor Inactive Msg, live Chat Visitor Inactive Time, locale, location Country Code, prompt Avatar, prompt Avatar Alt Text, prompt Msg, prompt Type, representative Assigned Message, revisit Prompt Msg, send Action Text, show Agency Branding, show Consent Checkbox, show Live Chat Welcome Msg, show Prompt, sub Heading, success Msg, support Contact, thank You Msg, theme, use Email Field, wa Number, widget Id, widget Placement, widget Primary Color theme colors, name colors avatar Background Color, avatar Border Color, background Color, button Color, chat Bubble Color, header Color, received Message Color, sender Message Color
`name`	string	Optional	Theme Name

Patch Chat Widget — request body — body settings acknowledgement Details, advance Settings, agency Name, agency Website, allow Avatar Image, auto Country Code, chat Icon, chat Type, country Code, dimensions, enable Revisit Message, heading, is Prompt Avatar Image Optimize, legal Msg, live Chat Ack Msg, live Chat Ended Msg, live Chat Feedback Msg, live Chat Feedback Note, live Chat Intro Msg, live Chat User Inactive Msg, live Chat User Inactive Time, live Chat Visitor Inactive Msg, live Chat Visitor Inactive Time, locale, location Country Code, prompt Avatar, prompt Avatar Alt Text, prompt Msg, prompt Type, representative Assigned Message, revisit Prompt Msg, send Action Text, show Agency Branding, show Consent Checkbox, show Live Chat Welcome Msg, show Prompt, sub Heading, success Msg, support Contact, thank You Msg, theme, use Email Field, wa Number, widget Id, widget Placement, widget Primary Color advance Settings a Two P Compliance, all In One Chat Types, all In One Initial Msg, branding Title, business Office Hours, contact Form Intro Message, contact Form Options, contact Form System Message, default Consent Check, enable Contact Form, fb Page, instagram Page, play Notification Sound, prefilled Message Text, redirect, voice Ai Agent, voice Ai Send Action Text a Two P Compliance a2p Opt In Form1, a2p Opt In Form1 Pre Checked, a2p Opt In Form1 Show Checkbox, a2p Opt In Form2, a2p Opt In Form2 Pre Checked, a2p Opt In Form2 Show Checkbox, enable A2 P Compliance, is A2 P Opt In Form1, is A2 P Opt In Form2, message Type, privacy Policy Link, terms Of Service Link

Field	Type	Presence	Description and constraints
`$`	object	Root
`a2pOptInForm1`	string	Optional	A2P Opt In Form 1
`a2pOptInForm1PreChecked`	boolean	Optional	Pre-checked state for A2P Opt In Form 1 checkbox
`a2pOptInForm1ShowCheckbox`	boolean	Optional	Show checkbox for A2P Opt In Form 1
`a2pOptInForm2`	string	Optional	A2P Opt In Form 2
`a2pOptInForm2PreChecked`	boolean	Optional	Pre-checked state for A2P Opt In Form 2 checkbox
`a2pOptInForm2ShowCheckbox`	boolean	Optional	Show checkbox for A2P Opt In Form 2
`enableA2PCompliance`	boolean	Optional	Enable A2P Compliance
`isA2POptInForm1`	boolean	Optional	Is A2P Opt In Form 1 enabled
`isA2POptInForm2`	boolean	Optional	Is A2P Opt In Form 2
`messageType`	string	Optional	Message Type
`privacyPolicyLink`	string	Optional	Privacy Policy Link
`termsOfServiceLink`	string	Optional	Terms of Service

Policy, approvals and errors

SDK function policy ID: gohighlevel.createchatwidget. Catalog operation: createChatWidget. 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: ["chat-widget.write"]

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

Official provider source

Report an issue with this page