# Create a new chat widget POST https://services.leadconnectorhq.com/chat-widget/ Creates a new chat widget for a specific location ## Authentication Send `Authorization: Bearer ` using: - **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `chat-widget.write` ## Parameters ### Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Version` | string | Yes | API Version | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "LeadConnector API", "version": "v3" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/chat-widget/": { "post": { "summary": "Create a new chat widget", "operationId": "createANewChatWidget", "description": "Creates a new chat widget for a specific location", "parameters": [ { "name": "Version", "in": "header", "description": "API Version", "required": true, "schema": { "type": "string", "enum": [ "v3" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWidgetDTO" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWidgetDTO" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestDTO-2" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedDTO-2" } } } }, "403": { "description": "The token does not have access to this location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidLocationDTO" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableDTO-2" } } } } }, "security": [ { "Location-Access": [ "chat-widget.write" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access": { "scheme": "bearer", "bearerFormat": "JWT", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "description": "Use the Access Token generated with user type as Sub-Account.", "type": "http" }, "Agency-Access": { "scheme": "bearer", "bearerFormat": "JWT", "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.", "type": "http" }, "Agency-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "description": "Use the Access Token generated with user type as Agency.", "type": "http" } }, "schemas": { "CreateWidgetDTO": { "type": "object", "properties": { "version": { "type": "number", "description": "Version", "example": 2 }, "chatType": { "type": "string", "description": "Chat Type. The public API supports only liveChat and emailChat; any other value is rejected with a 422.", "example": "emailChat", "enum": [ "liveChat", "emailChat" ] }, "name": { "type": "string", "description": "Name", "example": "Chat Widget 1" }, "locationId": { "type": "string", "description": "Location ID", "example": "oHJiAh0wDG3BzmzACVD6" }, "deleted": { "type": "boolean", "description": "Deleted", "example": false }, "default": { "type": "boolean", "description": "Default", "example": false }, "settings": { "description": "Settings", "example": { "promptType": "avatar", "locale": "en-us", "heading": "Welcome to Acme", "widgetPrimaryColor": "#4285F4", "theme": { "name": "blue" } }, "allOf": [ { "type": "object", "properties": { "acknowledgementDetails": { "description": "Acknowledgement Details", "example": {}, "allOf": [ { "type": "object", "properties": { "icon": { "description": "Acknowledgement icon. Either a preset name (`Check`, `CheckCircle`, `MessageDotsCircle`, `MessageSmileSquare`) or an absolute URL to a custom uploaded image.", "example": "Check", "oneOf": [ { "type": "string", "enum": [ "Check", "CheckCircle", "MessageDotsCircle", "MessageSmileSquare" ] }, { "type": "string", "format": "uri" } ] }, "placeholderColor": { "type": "string", "example": "#000", "description": "Placeholder color" }, "liveChatIcon": { "description": "Live-chat acknowledgement icon. Either a preset name (`Check`, `CheckCircle`, `MessageDotsCircle`, `MessageSmileSquare`) or an absolute URL to a custom uploaded image.", "example": "Check", "oneOf": [ { "type": "string", "enum": [ "Check", "CheckCircle", "MessageDotsCircle", "MessageSmileSquare" ] }, { "type": "string", "format": "uri" } ] }, "liveChatPlaceholderColor": { "type": "string", "example": "#000", "description": "Placeholder color for live chat" } }, "title": "AcknowledgementDetailsDTO" } ] }, "agencyName": { "type": "string", "description": "Name of the agency", "example": "Example Agency" }, "agencyWebsite": { "type": "string", "description": "Website URL of the agency", "example": "https://example.com" }, "allowAvatarImage": { "type": "boolean", "description": "Allow avatar image", "example": true }, "autoCountryCode": { "type": "boolean", "description": "Boolean indicating whether to automatically detect country code", "example": true }, "countryCode": { "type": "string", "description": "Country code", "example": "US" }, "chatType": { "type": "string", "description": "Chat Type. The public API supports only liveChat and emailChat; any other value is rejected with a 422.", "example": "emailChat", "enum": [ "liveChat", "emailChat" ] }, "promptType": { "type": "string", "description": "Chat bubble style — \"avatar\" shows the agent avatar, \"normal\" shows a plain bubble.", "example": "avatar", "enum": [ "avatar", "normal" ] }, "chatIcon": { "description": "Icon shown on the closed chat bubble. Either a preset name (`messageChatCircle`, `messageChatSquare`, `messageSquare`, `messageDotsCircle`, `messageWhatsApp`, `phoneCall01`, `phone`, `phoneOutgoing02`, `fbMessenger`, `instagram`) or an absolute URL to a custom uploaded image.", "example": "messageChatCircle", "oneOf": [ { "type": "string", "enum": [ "messageChatCircle", "messageChatSquare", "messageSquare", "messageDotsCircle", "messageWhatsApp", "phoneCall01", "phone", "phoneOutgoing02", "fbMessenger", "instagram" ] }, { "type": "string", "format": "uri" } ] }, "enableRevisitMessage": { "type": "boolean", "description": "Boolean indicating whether to enable a revisit message", "example": true }, "heading": { "type": "string", "description": "Heading text", "example": "Welcome to Our Website" }, "legalMsg": { "type": "string", "description": "Legal message", "example": "By using this website, you agree to our terms and conditions." }, "liveChatAckMsg": { "type": "string", "description": "Message acknowledging a live chat", "example": "Thank you for reaching out. How may I assist you today?" }, "liveChatEndedMsg": { "type": "string", "description": "Message indicating the end of a live chat", "example": "Thank you for chatting with us. Have a great day!" }, "liveChatFeedbackMsg": { "type": "string", "description": "Message asking for feedback after a live chat", "example": "We would appreciate your feedback. Please rate your experience." }, "liveChatFeedbackNote": { "type": "string", "description": "Note regarding live chat feedback", "example": "Your feedback helps us improve our services." }, "liveChatIntroMsg": { "type": "string", "description": "Introduction message for a live chat", "example": "Hello! Welcome to our live chat support. How can I assist you today?" }, "liveChatUserInactiveMsg": { "type": "string", "description": "Message for inactive users during a live chat", "example": "Are you still there? Please let us know if you need assistance." }, "liveChatUserInactiveTime": { "type": "string", "description": "Time for considering a user inactive during a live chat", "example": "5 minutes" }, "liveChatVisitorInactiveMsg": { "type": "string", "description": "Message for inactive visitors during a live chat", "example": "Looks like you stepped away. Feel free to return whenever you need help." }, "liveChatVisitorInactiveTime": { "type": "string", "description": "Time for considering a visitor inactive during a live chat", "example": "10 minutes" }, "locale": { "type": "string", "description": "Locale setting. Use \"location\" to inherit from the location's locale, or \"auto\" to detect from the visitor's browser. Otherwise pick a BCP 47 tag in hyphen-lowercase form.", "example": "en-us", "enum": [ "location", "auto", "en-us", "en-gb", "de", "fr-fr", "nl", "hu", "pt-pt", "pt-br", "es", "fr-ca", "hr", "it", "sv-se", "da-dk", "fi", "no" ] }, "promptAvatar": { "type": "string", "description": "Avatar for prompts", "example": "avatar.jpg" }, "promptAvatarAltText": { "type": "string", "description": "Prompt Avatar Alt Text", "example": "company logo" }, "isPromptAvatarImageOptimize": { "type": "boolean", "description": "Avatar Image Optimization", "example": false }, "promptMsg": { "type": "string", "description": "Prompt message", "example": "Need assistance? Feel free to ask us anything!" }, "revisitPromptMsg": { "type": "string", "description": "Message for revisiting prompts", "example": "Welcome back! How can we help you today?" }, "sendActionText": { "type": "string", "description": "Text for send action", "example": "Send" }, "showAgencyBranding": { "type": "boolean", "description": "Boolean indicating whether to show agency branding", "example": true }, "showConsentCheckbox": { "type": "boolean", "description": "Boolean indicating whether to show a consent checkbox", "example": true }, "showLiveChatWelcomeMsg": { "type": "boolean", "description": "Boolean indicating whether to show a welcome message for live chat", "example": true }, "showPrompt": { "type": "boolean", "description": "Boolean indicating whether to show prompts", "example": true }, "subHeading": { "type": "string", "description": "Subheading text", "example": "We are here to help you!" }, "successMsg": { "type": "string", "description": "Success message", "example": "Your message has been sent successfully." }, "supportContact": { "type": "string", "description": "Contact information for support", "example": "support@example.com" }, "thankYouMsg": { "type": "string", "description": "Thank you message", "example": "Thank you for visiting our website!" }, "theme": { "description": "Theme", "example": {}, "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "example": "blue", "description": "Theme preset name. Use \"custom\" together with a colors/typography object to override.", "enum": [ "blue", "teal", "tan", "lavender", "golden", "instagram", "facebook", "custom" ] }, "value": { "type": "string", "description": "Resolved theme value / preset identifier persisted alongside the preset name.", "example": "blue" }, "colors": { "description": "Custom Color Options", "example": {}, "allOf": [ { "type": "object", "properties": { "chatBubbleColor": { "type": "string", "example": "#fffff", "description": "Chat Bubble Color" }, "backgroundColor": { "type": "string", "example": "#fffff", "description": "Background Color" }, "headerColor": { "type": "string", "example": "#fffff", "description": "Header Color" }, "buttonColor": { "type": "string", "example": "#fffff", "description": "Button Color" }, "avatarBackgroundColor": { "type": "string", "example": "#fffff", "description": "Avatar Background Color" }, "avatarBorderColor": { "type": "string", "example": "#fffff", "description": "Avatar Border Color" }, "senderMessageColor": { "type": "string", "example": "#fffff", "description": "Sender Message Color" }, "receivedMessageColor": { "type": "string", "example": "#fffff", "description": "Received Message Color" } }, "title": "WidgetSettingsThemeCustomColorDTO" } ] }, "typography": { "description": "Typography Options", "example": {}, "allOf": [ { "type": "object", "properties": { "fontFamily": { "type": "string", "example": "inter", "description": "Font Family" }, "colors": { "description": "Typography Color Options", "example": {}, "allOf": [ { "type": "object", "properties": { "senderMessageTextColor": { "type": "string", "example": "#fffff", "description": "Sender Message Text Color" }, "receivedMessageTextColor": { "type": "string", "example": "#fffff", "description": "Received Message Text Color" }, "headerMessageTextColor": { "type": "string", "example": "#fffff", "description": "Header Message Text Color" }, "welcomeMessageTextColor": { "type": "string", "example": "#fffff", "description": "Welcome Message Text Color" }, "systemMessageTextColor": { "type": "string", "example": "#fffff", "description": "System Message Text Color" } }, "title": "WidgetSettingsTypographyColorDTO" } ] } }, "title": "WidgetSettingsTypographyDTO" } ] } }, "title": "WidgetSettingsThemeDTO" } ] }, "waNumber": { "type": "string", "description": "WhatsApp number", "example": "+1234567890" }, "widgetPrimaryColor": { "type": "string", "description": "Primary color for the widget", "example": "#4285F4" }, "representativeAssignedMessage": { "type": "string", "description": "Representative Assigned Message", "example": "#4285F4" }, "dimensions": { "description": "Customizations", "example": {}, "allOf": [ { "type": "object", "properties": { "position": { "type": "string", "example": "bottom-right", "description": "Widget anchor position on the host page (kebab-case).", "enum": [ "top-left", "top-right", "middle-left", "middle-right", "bottom-left", "bottom-right" ] }, "sizes": { "description": "Widget dimensions (width/height)", "example": {}, "allOf": [ { "type": "object", "properties": { "width": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": 360, "description": "Width in pixels. Accepts a number (360), a CSS length (\"600px\"), or \"\" for auto." }, "height": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": 640, "description": "Height in pixels. Accepts a number (640), a CSS length (\"600px\"), or \"\" for auto." } }, "title": "WidgetSettingsCustomizationSizeDTO" } ] } }, "title": "WidgetSettingsCustomizationDTO" } ] }, "advanceSettings": { "description": "Advance Settings", "example": {}, "allOf": [ { "type": "object", "properties": { "brandingTitle": { "type": "string", "description": "Branding Title", "example": "Agency" }, "redirect": { "description": "Redirect Object", "example": {}, "allOf": [ { "type": "object", "properties": { "redirectAction": { "type": "boolean", "description": "Redirect Action", "example": false }, "redirectWebsite": { "type": "string", "description": "Redirect Website", "example": "www.example.com" }, "redirectText": { "type": "string", "description": "Redirect Text", "example": "Click here" } }, "title": "RedirectDTO" } ] }, "enableContactForm": { "type": "boolean", "description": "Boolean for showing contact form at start", "example": true }, "defaultConsentCheck": { "type": "boolean", "description": "By default consent check for contact form", "example": true }, "businessOfficeHours": { "description": "Business Office Hours", "example": {}, "allOf": [ { "type": "object", "properties": { "enableBusinessHours": { "type": "boolean", "description": "Enable Business Hours", "example": false }, "openHours": { "description": "Open Hours", "example": [ { "daysOfTheWeek": [ 1, 2, 3, 4, 5 ], "hours": [ { "openHour": "09", "openMinute": "00", "closeHour": "16", "closeMinute": "30" } ] } ], "type": "array", "items": { "type": "object", "properties": { "daysOfTheWeek": { "description": "Day of week", "example": [ 1 ], "type": "array", "items": { "type": "string" } }, "hours": { "description": "Hours", "example": [ { "openHour": "09", "openMinute": "00", "closeHour": "16", "closeMinute": "30" } ], "type": "array", "items": { "type": "string" } } }, "title": "OpenHoursDTO" } }, "timezone": { "type": "string", "description": "Time Zone", "example": "UTC" }, "outsideOfficeHoursWelcomeMsg": { "type": "string", "description": "Time Zone", "example": "Asia/Calcutta" } }, "title": "BusinessOfficeHoursDTO" } ] }, "contactFormOptions": { "description": "Ordered list of fields shown on the chat-widget contact form. Standard fields are identified by `value` = `name | phone | email | message`; custom fields use the contact custom-field id.", "example": [ { "label": "Name", "value": "name", "dataType": "TEXT", "fieldKey": "contact.name", "required": true }, { "label": "Email", "value": "email", "dataType": "EMAIL", "fieldKey": "contact.email", "required": true }, { "label": "Phone", "value": "phone", "dataType": "PHONE", "fieldKey": "contact.phone", "required": false } ], "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label shown next to the field in the form.", "example": "Email" }, "value": { "type": "string", "description": "Field identifier. For standard fields use one of: `name`, `phone`, `email`, `message`. For custom fields use the contact custom-field id.", "example": "email" }, "dataType": { "type": "string", "description": "Data type of the field, used to pick the input control and validation.", "example": "EMAIL", "enum": [ "TEXT", "LARGE_TEXT", "TEXTAREA", "EMAIL", "PHONE", "DATE", "NUMERICAL", "MONETORY", "SINGLE_OPTIONS" ] }, "placeholder": { "type": "string", "example": "Email", "description": "Placeholder text rendered inside the input." }, "fieldKey": { "type": "string", "description": "Dotted field key used to write the value onto the contact (e.g. `contact.email`).", "example": "contact.email" }, "required": { "type": "boolean", "description": "Whether the field must be filled in to submit the form.", "example": true }, "id": { "type": "string", "description": "Client-assigned field identifier; the chat-widget UI round-trips this on save.", "example": "1" }, "disabled": { "type": "boolean", "description": "Whether the field is shown but disabled in the form editor.", "example": false }, "picklistOptions": { "description": "Choices for option-type custom fields (SINGLE_OPTIONS, MULTIPLE_OPTIONS, RADIO, CHECKBOX).", "example": [ "Option 1", "Option 2" ], "type": "array", "items": { "type": "string" } } }, "title": "ContactFormOptionsDTO" } }, "allInOneChatTypes": { "description": "All In One Chat Type", "example": [], "type": "array", "items": { "type": "string" } }, "allInOneInitialMsg": { "type": "string", "description": "All In One Initial Msg", "example": "Choose a chat option to get started." }, "contactFormIntroMessage": { "type": "string", "description": "Contact Form Intro Message", "example": "Please share contact details" }, "contactFormSystemMessage": { "type": "string", "description": "Contact Form System Message", "example": "Please share contact details" }, "prefilledMessageText": { "type": "string", "description": "Prefilled Message Text", "example": "I want to know more" }, "voiceAiAgent": { "type": "object", "description": "Voice AI Agent", "example": {} }, "fbPage": { "description": "Facebook Page", "example": {}, "allOf": [ { "type": "object", "properties": { "facebookPageId": { "type": "string", "description": "Facebook Page ID", "example": "1234567890" }, "facebookPageName": { "type": "string", "description": "Facebook Page Name", "example": "Facebook Page Name" } }, "title": "FBPageDTO" } ] }, "instagramPage": { "description": "Instagram Page", "example": {}, "allOf": [ { "type": "object", "properties": { "facebookPageId": { "type": "string", "description": "Facebook Page ID", "example": "1234567890" }, "facebookPageName": { "type": "string", "description": "Facebook Page Name", "example": "Facebook Page Name" }, "instagramPageId": { "type": "string", "description": "Instagram Page ID", "example": "1234567890" }, "instagramUsername": { "type": "string", "description": "Instagram UserName", "example": "Instagram UserName" } }, "title": "InstagramPageDTO" } ] }, "playNotificationSound": { "type": "boolean", "description": "Play Notification Sound", "example": false }, "allowVoiceNotes": { "type": "boolean", "description": "Allow visitors to record and send voice notes from the chat window", "example": true }, "allowAttachments": { "type": "boolean", "description": "Allow visitors to send attachments (images, PDFs, files) alongside their messages", "example": true }, "voiceAiSendActionText": { "type": "string", "description": "Voice Ai Send Action Text", "example": "Call Now" }, "voiceAiDisplayMode": { "type": "string", "description": "Voice AI display mode", "example": "avatar", "enum": [ "avatar", "visualiser" ] }, "voiceAiAnimation": { "type": "string", "description": "Voice AI Animation ID. Only \"1\" is supported for now.", "example": "1", "enum": [ "1" ] }, "voiceAiAnimationColor": { "type": "string", "description": "Voice AI animation visualiser color", "example": "#155EEF" }, "voiceAiAnimationSize": { "type": "string", "description": "Voice AI animation size for the embedded visualiser orb", "example": "md", "enum": [ "sm", "md", "lg" ] }, "addSupportingText": { "type": "boolean", "description": "Add Supporting Text", "example": true }, "supportingText": { "type": "string", "description": "Supporting Text", "example": "We are here to help you" } }, "title": "AdvanceSettingsDTO" } ] }, "locationCountryCode": { "type": "string", "description": "Location Country Code", "example": "US" }, "widgetPlacement": { "type": "string", "description": "Widget Placement. \"sticky\" keeps the widget pinned to a page corner; \"embedded\" renders inline within the host page.", "example": "embedded", "enum": [ "sticky", "embedded" ] }, "loadStrategy": { "type": "string", "description": "Load strategy for the embed script: \"immediate\" loads on page load (default), \"interaction\" defers until user interacts.", "example": "interaction", "enum": [ "immediate", "interaction" ] } }, "title": "WidgetSettingsDTO" } ] } }, "required": [ "version", "chatType", "name", "locationId" ], "title": "CreateWidgetDTO" }, "ChatWidgetDTO": { "type": "object", "properties": { "_id": { "type": "string", "description": "Chat widget ID", "example": "ve9EPM428h8vShlRWsss" }, "version": { "type": "number", "description": "Schema version of the widget", "example": 2 }, "chatType": { "type": "string", "description": "Chat Type. Reads are not restricted to the public-API write allow-list, so any stored chat type can be returned here.", "example": "emailChat", "enum": [ "liveChat", "waChat", "emailChat", "allInOneChat", "voiceAiChat", "facebookChat", "instagramChat" ] }, "name": { "type": "string", "description": "Widget name", "example": "Chat Widget 1" }, "locationId": { "type": "string", "description": "The location ID that owns this widget", "example": "ve9EPM428h8vShlRWsss" }, "deleted": { "type": "boolean", "description": "Whether the widget is soft-deleted", "example": false }, "default": { "type": "boolean", "description": "Whether this is the default widget for the location", "example": false }, "settings": { "description": "Widget settings", "allOf": [ { "type": "object", "properties": { "acknowledgementDetails": { "description": "Acknowledgement Details", "example": {}, "allOf": [ { "type": "object", "properties": { "icon": { "description": "Acknowledgement icon. Either a preset name (`Check`, `CheckCircle`, `MessageDotsCircle`, `MessageSmileSquare`) or an absolute URL to a custom uploaded image.", "example": "Check", "oneOf": [ { "type": "string", "enum": [ "Check", "CheckCircle", "MessageDotsCircle", "MessageSmileSquare" ] }, { "type": "string", "format": "uri" } ] }, "placeholderColor": { "type": "string", "example": "#000", "description": "Placeholder color" }, "liveChatIcon": { "description": "Live-chat acknowledgement icon. Either a preset name (`Check`, `CheckCircle`, `MessageDotsCircle`, `MessageSmileSquare`) or an absolute URL to a custom uploaded image.", "example": "Check", "oneOf": [ { "type": "string", "enum": [ "Check", "CheckCircle", "MessageDotsCircle", "MessageSmileSquare" ] }, { "type": "string", "format": "uri" } ] }, "liveChatPlaceholderColor": { "type": "string", "example": "#000", "description": "Placeholder color for live chat" } }, "title": "AcknowledgementDetailsDTO" } ] }, "agencyName": { "type": "string", "description": "Name of the agency", "example": "Example Agency" }, "agencyWebsite": { "type": "string", "description": "Website URL of the agency", "example": "https://example.com" }, "allowAvatarImage": { "type": "boolean", "description": "Allow avatar image", "example": true }, "autoCountryCode": { "type": "boolean", "description": "Boolean indicating whether to automatically detect country code", "example": true }, "countryCode": { "type": "string", "description": "Country code", "example": "US" }, "chatType": { "type": "string", "description": "Chat Type. The public API supports only liveChat and emailChat; any other value is rejected with a 422.", "example": "emailChat", "enum": [ "liveChat", "emailChat" ] }, "promptType": { "type": "string", "description": "Chat bubble style — \"avatar\" shows the agent avatar, \"normal\" shows a plain bubble.", "example": "avatar", "enum": [ "avatar", "normal" ] }, "chatIcon": { "description": "Icon shown on the closed chat bubble. Either a preset name (`messageChatCircle`, `messageChatSquare`, `messageSquare`, `messageDotsCircle`, `messageWhatsApp`, `phoneCall01`, `phone`, `phoneOutgoing02`, `fbMessenger`, `instagram`) or an absolute URL to a custom uploaded image.", "example": "messageChatCircle", "oneOf": [ { "type": "string", "enum": [ "messageChatCircle", "messageChatSquare", "messageSquare", "messageDotsCircle", "messageWhatsApp", "phoneCall01", "phone", "phoneOutgoing02", "fbMessenger", "instagram" ] }, { "type": "string", "format": "uri" } ] }, "enableRevisitMessage": { "type": "boolean", "description": "Boolean indicating whether to enable a revisit message", "example": true }, "heading": { "type": "string", "description": "Heading text", "example": "Welcome to Our Website" }, "legalMsg": { "type": "string", "description": "Legal message", "example": "By using this website, you agree to our terms and conditions." }, "liveChatAckMsg": { "type": "string", "description": "Message acknowledging a live chat", "example": "Thank you for reaching out. How may I assist you today?" }, "liveChatEndedMsg": { "type": "string", "description": "Message indicating the end of a live chat", "example": "Thank you for chatting with us. Have a great day!" }, "liveChatFeedbackMsg": { "type": "string", "description": "Message asking for feedback after a live chat", "example": "We would appreciate your feedback. Please rate your experience." }, "liveChatFeedbackNote": { "type": "string", "description": "Note regarding live chat feedback", "example": "Your feedback helps us improve our services." }, "liveChatIntroMsg": { "type": "string", "description": "Introduction message for a live chat", "example": "Hello! Welcome to our live chat support. How can I assist you today?" }, "liveChatUserInactiveMsg": { "type": "string", "description": "Message for inactive users during a live chat", "example": "Are you still there? Please let us know if you need assistance." }, "liveChatUserInactiveTime": { "type": "string", "description": "Time for considering a user inactive during a live chat", "example": "5 minutes" }, "liveChatVisitorInactiveMsg": { "type": "string", "description": "Message for inactive visitors during a live chat", "example": "Looks like you stepped away. Feel free to return whenever you need help." }, "liveChatVisitorInactiveTime": { "type": "string", "description": "Time for considering a visitor inactive during a live chat", "example": "10 minutes" }, "locale": { "type": "string", "description": "Locale setting. Use \"location\" to inherit from the location's locale, or \"auto\" to detect from the visitor's browser. Otherwise pick a BCP 47 tag in hyphen-lowercase form.", "example": "en-us", "enum": [ "location", "auto", "en-us", "en-gb", "de", "fr-fr", "nl", "hu", "pt-pt", "pt-br", "es", "fr-ca", "hr", "it", "sv-se", "da-dk", "fi", "no" ] }, "promptAvatar": { "type": "string", "description": "Avatar for prompts", "example": "avatar.jpg" }, "promptAvatarAltText": { "type": "string", "description": "Prompt Avatar Alt Text", "example": "company logo" }, "isPromptAvatarImageOptimize": { "type": "boolean", "description": "Avatar Image Optimization", "example": false }, "promptMsg": { "type": "string", "description": "Prompt message", "example": "Need assistance? Feel free to ask us anything!" }, "revisitPromptMsg": { "type": "string", "description": "Message for revisiting prompts", "example": "Welcome back! How can we help you today?" }, "sendActionText": { "type": "string", "description": "Text for send action", "example": "Send" }, "showAgencyBranding": { "type": "boolean", "description": "Boolean indicating whether to show agency branding", "example": true }, "showConsentCheckbox": { "type": "boolean", "description": "Boolean indicating whether to show a consent checkbox", "example": true }, "showLiveChatWelcomeMsg": { "type": "boolean", "description": "Boolean indicating whether to show a welcome message for live chat", "example": true }, "showPrompt": { "type": "boolean", "description": "Boolean indicating whether to show prompts", "example": true }, "subHeading": { "type": "string", "description": "Subheading text", "example": "We are here to help you!" }, "successMsg": { "type": "string", "description": "Success message", "example": "Your message has been sent successfully." }, "supportContact": { "type": "string", "description": "Contact information for support", "example": "support@example.com" }, "thankYouMsg": { "type": "string", "description": "Thank you message", "example": "Thank you for visiting our website!" }, "theme": { "description": "Theme", "example": {}, "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "example": "blue", "description": "Theme preset name. Use \"custom\" together with a colors/typography object to override.", "enum": [ "blue", "teal", "tan", "lavender", "golden", "instagram", "facebook", "custom" ] }, "value": { "type": "string", "description": "Resolved theme value / preset identifier persisted alongside the preset name.", "example": "blue" }, "colors": { "description": "Custom Color Options", "example": {}, "allOf": [ { "type": "object", "properties": { "chatBubbleColor": { "type": "string", "example": "#fffff", "description": "Chat Bubble Color" }, "backgroundColor": { "type": "string", "example": "#fffff", "description": "Background Color" }, "headerColor": { "type": "string", "example": "#fffff", "description": "Header Color" }, "buttonColor": { "type": "string", "example": "#fffff", "description": "Button Color" }, "avatarBackgroundColor": { "type": "string", "example": "#fffff", "description": "Avatar Background Color" }, "avatarBorderColor": { "type": "string", "example": "#fffff", "description": "Avatar Border Color" }, "senderMessageColor": { "type": "string", "example": "#fffff", "description": "Sender Message Color" }, "receivedMessageColor": { "type": "string", "example": "#fffff", "description": "Received Message Color" } }, "title": "WidgetSettingsThemeCustomColorDTO" } ] }, "typography": { "description": "Typography Options", "example": {}, "allOf": [ { "type": "object", "properties": { "fontFamily": { "type": "string", "example": "inter", "description": "Font Family" }, "colors": { "description": "Typography Color Options", "example": {}, "allOf": [ { "type": "object", "properties": { "senderMessageTextColor": { "type": "string", "example": "#fffff", "description": "Sender Message Text Color" }, "receivedMessageTextColor": { "type": "string", "example": "#fffff", "description": "Received Message Text Color" }, "headerMessageTextColor": { "type": "string", "example": "#fffff", "description": "Header Message Text Color" }, "welcomeMessageTextColor": { "type": "string", "example": "#fffff", "description": "Welcome Message Text Color" }, "systemMessageTextColor": { "type": "string", "example": "#fffff", "description": "System Message Text Color" } }, "title": "WidgetSettingsTypographyColorDTO" } ] } }, "title": "WidgetSettingsTypographyDTO" } ] } }, "title": "WidgetSettingsThemeDTO" } ] }, "waNumber": { "type": "string", "description": "WhatsApp number", "example": "+1234567890" }, "widgetPrimaryColor": { "type": "string", "description": "Primary color for the widget", "example": "#4285F4" }, "representativeAssignedMessage": { "type": "string", "description": "Representative Assigned Message", "example": "#4285F4" }, "dimensions": { "description": "Customizations", "example": {}, "allOf": [ { "type": "object", "properties": { "position": { "type": "string", "example": "bottom-right", "description": "Widget anchor position on the host page (kebab-case).", "enum": [ "top-left", "top-right", "middle-left", "middle-right", "bottom-left", "bottom-right" ] }, "sizes": { "description": "Widget dimensions (width/height)", "example": {}, "allOf": [ { "type": "object", "properties": { "width": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": 360, "description": "Width in pixels. Accepts a number (360), a CSS length (\"600px\"), or \"\" for auto." }, "height": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": 640, "description": "Height in pixels. Accepts a number (640), a CSS length (\"600px\"), or \"\" for auto." } }, "title": "WidgetSettingsCustomizationSizeDTO" } ] } }, "title": "WidgetSettingsCustomizationDTO" } ] }, "advanceSettings": { "description": "Advance Settings", "example": {}, "allOf": [ { "type": "object", "properties": { "brandingTitle": { "type": "string", "description": "Branding Title", "example": "Agency" }, "redirect": { "description": "Redirect Object", "example": {}, "allOf": [ { "type": "object", "properties": { "redirectAction": { "type": "boolean", "description": "Redirect Action", "example": false }, "redirectWebsite": { "type": "string", "description": "Redirect Website", "example": "www.example.com" }, "redirectText": { "type": "string", "description": "Redirect Text", "example": "Click here" } }, "title": "RedirectDTO" } ] }, "enableContactForm": { "type": "boolean", "description": "Boolean for showing contact form at start", "example": true }, "defaultConsentCheck": { "type": "boolean", "description": "By default consent check for contact form", "example": true }, "businessOfficeHours": { "description": "Business Office Hours", "example": {}, "allOf": [ { "type": "object", "properties": { "enableBusinessHours": { "type": "boolean", "description": "Enable Business Hours", "example": false }, "openHours": { "description": "Open Hours", "example": [ { "daysOfTheWeek": [ 1, 2, 3, 4, 5 ], "hours": [ { "openHour": "09", "openMinute": "00", "closeHour": "16", "closeMinute": "30" } ] } ], "type": "array", "items": { "type": "object", "properties": { "daysOfTheWeek": { "description": "Day of week", "example": [ 1 ], "type": "array", "items": { "type": "string" } }, "hours": { "description": "Hours", "example": [ { "openHour": "09", "openMinute": "00", "closeHour": "16", "closeMinute": "30" } ], "type": "array", "items": { "type": "string" } } }, "title": "OpenHoursDTO" } }, "timezone": { "type": "string", "description": "Time Zone", "example": "UTC" }, "outsideOfficeHoursWelcomeMsg": { "type": "string", "description": "Time Zone", "example": "Asia/Calcutta" } }, "title": "BusinessOfficeHoursDTO" } ] }, "contactFormOptions": { "description": "Ordered list of fields shown on the chat-widget contact form. Standard fields are identified by `value` = `name | phone | email | message`; custom fields use the contact custom-field id.", "example": [ { "label": "Name", "value": "name", "dataType": "TEXT", "fieldKey": "contact.name", "required": true }, { "label": "Email", "value": "email", "dataType": "EMAIL", "fieldKey": "contact.email", "required": true }, { "label": "Phone", "value": "phone", "dataType": "PHONE", "fieldKey": "contact.phone", "required": false } ], "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label shown next to the field in the form.", "example": "Email" }, "value": { "type": "string", "description": "Field identifier. For standard fields use one of: `name`, `phone`, `email`, `message`. For custom fields use the contact custom-field id.", "example": "email" }, "dataType": { "type": "string", "description": "Data type of the field, used to pick the input control and validation.", "example": "EMAIL", "enum": [ "TEXT", "LARGE_TEXT", "TEXTAREA", "EMAIL", "PHONE", "DATE", "NUMERICAL", "MONETORY", "SINGLE_OPTIONS" ] }, "placeholder": { "type": "string", "example": "Email", "description": "Placeholder text rendered inside the input." }, "fieldKey": { "type": "string", "description": "Dotted field key used to write the value onto the contact (e.g. `contact.email`).", "example": "contact.email" }, "required": { "type": "boolean", "description": "Whether the field must be filled in to submit the form.", "example": true }, "id": { "type": "string", "description": "Client-assigned field identifier; the chat-widget UI round-trips this on save.", "example": "1" }, "disabled": { "type": "boolean", "description": "Whether the field is shown but disabled in the form editor.", "example": false }, "picklistOptions": { "description": "Choices for option-type custom fields (SINGLE_OPTIONS, MULTIPLE_OPTIONS, RADIO, CHECKBOX).", "example": [ "Option 1", "Option 2" ], "type": "array", "items": { "type": "string" } } }, "title": "ContactFormOptionsDTO" } }, "allInOneChatTypes": { "description": "All In One Chat Type", "example": [], "type": "array", "items": { "type": "string" } }, "allInOneInitialMsg": { "type": "string", "description": "All In One Initial Msg", "example": "Choose a chat option to get started." }, "contactFormIntroMessage": { "type": "string", "description": "Contact Form Intro Message", "example": "Please share contact details" }, "contactFormSystemMessage": { "type": "string", "description": "Contact Form System Message", "example": "Please share contact details" }, "prefilledMessageText": { "type": "string", "description": "Prefilled Message Text", "example": "I want to know more" }, "voiceAiAgent": { "type": "object", "description": "Voice AI Agent", "example": {} }, "fbPage": { "description": "Facebook Page", "example": {}, "allOf": [ { "type": "object", "properties": { "facebookPageId": { "type": "string", "description": "Facebook Page ID", "example": "1234567890" }, "facebookPageName": { "type": "string", "description": "Facebook Page Name", "example": "Facebook Page Name" } }, "title": "FBPageDTO" } ] }, "instagramPage": { "description": "Instagram Page", "example": {}, "allOf": [ { "type": "object", "properties": { "facebookPageId": { "type": "string", "description": "Facebook Page ID", "example": "1234567890" }, "facebookPageName": { "type": "string", "description": "Facebook Page Name", "example": "Facebook Page Name" }, "instagramPageId": { "type": "string", "description": "Instagram Page ID", "example": "1234567890" }, "instagramUsername": { "type": "string", "description": "Instagram UserName", "example": "Instagram UserName" } }, "title": "InstagramPageDTO" } ] }, "playNotificationSound": { "type": "boolean", "description": "Play Notification Sound", "example": false }, "allowVoiceNotes": { "type": "boolean", "description": "Allow visitors to record and send voice notes from the chat window", "example": true }, "allowAttachments": { "type": "boolean", "description": "Allow visitors to send attachments (images, PDFs, files) alongside their messages", "example": true }, "voiceAiSendActionText": { "type": "string", "description": "Voice Ai Send Action Text", "example": "Call Now" }, "voiceAiDisplayMode": { "type": "string", "description": "Voice AI display mode", "example": "avatar", "enum": [ "avatar", "visualiser" ] }, "voiceAiAnimation": { "type": "string", "description": "Voice AI Animation ID. Only \"1\" is supported for now.", "example": "1", "enum": [ "1" ] }, "voiceAiAnimationColor": { "type": "string", "description": "Voice AI animation visualiser color", "example": "#155EEF" }, "voiceAiAnimationSize": { "type": "string", "description": "Voice AI animation size for the embedded visualiser orb", "example": "md", "enum": [ "sm", "md", "lg" ] }, "addSupportingText": { "type": "boolean", "description": "Add Supporting Text", "example": true }, "supportingText": { "type": "string", "description": "Supporting Text", "example": "We are here to help you" } }, "title": "AdvanceSettingsDTO" } ] }, "locationCountryCode": { "type": "string", "description": "Location Country Code", "example": "US" }, "widgetPlacement": { "type": "string", "description": "Widget Placement. \"sticky\" keeps the widget pinned to a page corner; \"embedded\" renders inline within the host page.", "example": "embedded", "enum": [ "sticky", "embedded" ] }, "loadStrategy": { "type": "string", "description": "Load strategy for the embed script: \"immediate\" loads on page load (default), \"interaction\" defers until user interacts.", "example": "interaction", "enum": [ "immediate", "interaction" ] } }, "title": "WidgetSettingsDTO" } ] }, "creationSource": { "type": "string", "description": "How the widget was created", "example": "chat-widget", "enum": [ "chat-widget", "a2pCompliance", "public-api", "snapshot" ] }, "updatedBy": { "type": "string", "description": "ID of the user who last updated the widget", "example": "oHJiAh0wDG3BzmzACVD6" }, "originId": { "type": "string", "description": "ID of the widget this one was cloned or imported from", "example": "ve9EPM428h8vShlRWsss" }, "createdAt": { "type": "string", "description": "Creation timestamp (ISO 8601)", "example": "2026-08-17T09:24:11.123Z" }, "updatedAt": { "type": "string", "description": "Last update timestamp (ISO 8601)", "example": "2026-08-17T09:24:11.123Z" } }, "required": [ "_id", "version", "chatType", "name", "locationId", "deleted", "default", "createdAt", "updatedAt" ], "title": "ChatWidgetDTO" }, "BadRequestDTO-2": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Bad Request" } }, "title": "BadRequestDTO-2" }, "UnauthorizedDTO-2": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid token: access token is invalid" }, "error": { "type": "string", "example": "Unauthorized" } }, "title": "UnauthorizedDTO-2" }, "InvalidLocationDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "HTTP status code for invalid location access", "example": 403 }, "message": { "type": "string", "description": "Error message describing the location access failure", "example": "The token does not have access to this location" } }, "title": "InvalidLocationDTO" }, "UnprocessableDTO-2": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 422 }, "message": { "example": [ "Unprocessable Entity" ], "type": "array", "items": { "type": "string" } }, "error": { "type": "string", "example": "Unprocessable Entity" } }, "title": "UnprocessableDTO-2" } } } } ``` ## Code Examples **cURL** ```bash curl -L -X POST 'https://services.leadconnectorhq.com/chat-widget/' \ -H 'Authorization: Bearer ' \ -H 'Version: v3' \ -H 'Content-Type: application/json' \ --data-raw '{ "version": 2, "chatType": "emailChat", "name": "Chat Widget 1", "locationId": "oHJiAh0wDG3BzmzACVD6", "deleted": false, "default": false, "settings": { "promptType": "avatar", "locale": "en-us", "heading": "Welcome to Acme", "widgetPrimaryColor": "#4285F4", "theme": { "name": "blue" } } }' ``` **Node.js** ```javascript const options = { method: 'POST', headers: { Authorization: 'Bearer ', Version: 'v3', 'Content-Type': 'application/json' }, body: JSON.stringify({ "version": 2, "chatType": "emailChat", "name": "Chat Widget 1", "locationId": "oHJiAh0wDG3BzmzACVD6", "deleted": false, "default": false, "settings": { "promptType": "avatar", "locale": "en-us", "heading": "Welcome to Acme", "widgetPrimaryColor": "#4285F4", "theme": { "name": "blue" } } }) }; try { const response = await fetch('https://services.leadconnectorhq.com/chat-widget/', options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **Python** ```python import requests url = "https://services.leadconnectorhq.com/chat-widget/" headers = { "Authorization": "Bearer ", "Version": "v3" } payload = { "version": 2, "chatType": "emailChat", "name": "Chat Widget 1", "locationId": "oHJiAh0wDG3BzmzACVD6", "deleted": false, "default": false, "settings": { "promptType": "avatar", "locale": "en-us", "heading": "Welcome to Acme", "widgetPrimaryColor": "#4285F4", "theme": { "name": "blue" } } } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/chat-widget/', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: v3', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => '{ "version": 2, "chatType": "emailChat", "name": "Chat Widget 1", "locationId": "oHJiAh0wDG3BzmzACVD6", "deleted": false, "default": false, "settings": { "promptType": "avatar", "locale": "en-us", "heading": "Welcome to Acme", "widgetPrimaryColor": "#4285F4", "theme": { "name": "blue" } } }', ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .post("https://services.leadconnectorhq.com/chat-widget/") .header("Authorization", "Bearer ") .header("Version", "v3") .header("Content-Type", "application/json") .body("{\"version\":2,\"chatType\":\"emailChat\",\"name\":\"Chat Widget 1\",\"locationId\":\"oHJiAh0wDG3BzmzACVD6\",\"deleted\":false,\"default\":false,\"settings\":{\"promptType\":\"avatar\",\"locale\":\"en-us\",\"heading\":\"Welcome to Acme\",\"widgetPrimaryColor\":\"#4285F4\",\"theme\":{\"name\":\"blue\"}}}") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" "strings" ) func main() { url := "https://services.leadconnectorhq.com/chat-widget/" payload := strings.NewReader(`{ "version": 2, "chatType": "emailChat", "name": "Chat Widget 1", "locationId": "oHJiAh0wDG3BzmzACVD6", "deleted": false, "default": false, "settings": { "promptType": "avatar", "locale": "en-us", "heading": "Welcome to Acme", "widgetPrimaryColor": "#4285F4", "theme": { "name": "blue" } } }`) req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "v3") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` **Ruby** ```ruby require 'uri' require 'net/http' url = URI("https://services.leadconnectorhq.com/chat-widget/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = "Bearer " request["Version"] = "v3" request["Content-Type"] = "application/json" request.body = '{ "version": 2, "chatType": "emailChat", "name": "Chat Widget 1", "locationId": "oHJiAh0wDG3BzmzACVD6", "deleted": false, "default": false, "settings": { "promptType": "avatar", "locale": "en-us", "heading": "Welcome to Acme", "widgetPrimaryColor": "#4285F4", "theme": { "name": "blue" } } }' response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "v3" } $body = '{ "version": 2, "chatType": "emailChat", "name": "Chat Widget 1", "locationId": "oHJiAh0wDG3BzmzACVD6", "deleted": false, "default": false, "settings": { "promptType": "avatar", "locale": "en-us", "heading": "Welcome to Acme", "widgetPrimaryColor": "#4285F4", "theme": { "name": "blue" } } }' $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/chat-widget/' -Method 'POST' -Headers $headers -Body $body -ContentType 'application/json' $response | ConvertTo-Json ```