Management API

Visão geral da Management API

A Management API destina-se a operações de back-office que não envolvam o envio de mensagens de chat:

• criar um bot por via programática com POST /v1/management/bots
• ler um bot específico que lhe pertença com GET /v1/management/bots/{bot_id}
• atualizar um bot específico com PATCH /v1/management/bots/{bot_id}
• ler a utilização da subscrição com GET /v1/usage

As chaves de gestão estão associadas à sua conta e não a um bot em particular. São mantidas deliberadamente separadas das chaves da Bot Talk API para que uma chave de chat comprometida não possa alterar os seus bots nem ler os seus dados de faturação.

URL base

https://api.chatlab.com/aichat

Todos os endpoints deste artigo são relativos a este URL base.

Primeiros passos

1. Abra a aplicação de administração e aceda a Account Settings > Management API (Definições da conta > Management API).
2. Clique em Create Management Key (Criar chave de gestão), atribua-lhe um nome, configure opcionalmente a lista de permissões de IP e o limite de pedidos, e submeta.
3. Selecione apenas as permissões de que a sua integração necessita e copie a chave completa a partir da janela modal de sucesso. O texto simples é apresentado apenas uma vez.
4. Guarde-a no seu servidor, nunca em código do navegador nem num repositório público. Efetue um pedido de apenas leitura, como GET /v1/usage com a permissão usage, para verificar o acesso.
5. Revogue as chaves não utilizadas ou comprometidas na página da Management API.

Uma chave tem o formato mk_abcdefghijklmnopqrstuvwxyz012345. O prefixo mk_ distingue-a das chaves da Bot Talk API (ck_).

Autenticação

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

O envio de uma chave mk_ para /v1/chat (ou qualquer outro endpoint da Bot Talk API) devolve 403 key_type_not_allowed. O envio de uma chave ck_ para /v1/management/* devolve o mesmo erro.

Limites

• Máximo de 5 chaves da Management API ativas por utilizador
• Máximo de 10 pedidos por minuto por chave (balde de tokens, capacidade de 10, reposição gradual a ~1 token a cada 6 segundos). Configurável para valores inferiores no momento da criação - defina um rateLimitPerMinute menor para reduzir o teto máximo, ajustando a taxa de reposição proporcionalmente.

Permissões

Cada chave de gestão contém qualquer subconjunto das três permissões abaixo. Deve selecionar pelo menos uma no momento da criação; caso contrário, o pedido é rejeitado com 400 invalid_request_error. Chamar um endpoint com uma chave que não possua a permissão necessária devolve 403 insufficient_permissions.

• bot_read - necessária para GET /v1/management/bots/{bot_id}
• bot_management - necessária para POST /v1/management/bots e PATCH /v1/management/bots/{bot_id}
• usage - necessária para GET /v1/usage

Estrutura do corpo: secções aninhadas que refletem os separadores da interface de administração

Os métodos POST e PATCH aceitam um corpo JSON agrupado em 13 secções. Cada secção corresponde a um subseparador na barra lateral de definições do bot na aplicação de administração, pelo que as chaves JSON e os separadores visíveis coincidem: se alterar consent.humanSupportRequirePolicyAccept através da API, verá essa mesma opção alternar no separador Consent & Privacy (Consentimento e privacidade) na aplicação de administração.

• role - persona do bot, prompt em bruto, comprimento da resposta, idioma, contexto do website / empresa (separador Role & Behavior [Função e comportamento])
• conversation - mensagem de boas-vindas, refinamento de consultas, continuidade da conversa, botão de avaliação + descrições de ajuda, conteúdo de perguntas sugeridas + perguntas complementares dinâmicas (separador Chat Conversation [Conversa de chat])
• chatMemory - botão de memória de chat, prompts de resumo, alocação de contexto (separador Summaries & Memory [Resumos e memória])
• appearance - cores, textos, dimensões, CSS personalizado, ecrã de boas-vindas, estilo das perguntas sugeridas, comportamento de abertura automática, simulação de digitação humana, markdown do rodapé (separador Appearance [Aparência])
• humanSupport - formulário de contacto humano (separador Human Contact Form [Formulário de contacto humano])
• leadCollection - formulário de recolha de leads (separador Lead Collection [Recolha de leads])
• liveChat - transferência para Live Chat (separador Live Chat)
• consent - todas as quatro opções de consentimento da política de privacidade e o texto do ecrã de consentimento (separador Consent & Privacy [Consentimento e privacidade])
• whiteLabel - ocultar logótipo, ligação do logótipo personalizado, alojamento em domínio personalizado (separador Whitelabel [White Label])
• security - domínios autorizados, filtro de spam, limites de pedidos de conversação (separador Security [Segurança])
• voice - introdução por voz e conversas de voz: modelo, voz, idiomas, prompt, limite de duração (separador Voice Conversation [Conversa de voz])
• multilingual - modo multilingue, idioma base, idiomas disponibilizados, gestão do idioma do conhecimento (separador Languages [Idiomas])
• advanced - modelo de LLM, temperatura, tamanho do contexto, limite de mensagens do bot, idioma interno, Offer Cards (separador Model & Advanced [Modelo e avançado])

Das definições editáveis, apenas name reside no nível superior, uma vez que identifica o bot em vez de pertencer a um separador específico.

A barra lateral de definições do bot tem atualmente 16 subseparadores, e 13 deles mapeiam para as secções acima. Os três subseparadores sem secção correspondente são Flow, Actions e Forms - todos os três abordados na secção "Fora do âmbito da API" abaixo. Os 13 que mapeiam são Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation e Languages.

O corpo do pedido e o corpo da resposta partilham a mesma estrutura. A resposta acrescenta dois elementos adicionais:

• meta - apenas de leitura: ID do bot e carimbos de data/hora. Remova-o para transformar uma resposta GET num corpo POST válido.
• apiKey - presente apenas no momento da criação - a nova chave da Bot Talk API gerada para o novo bot.

Dois campos dentro da estrutura partilhada são apenas de leitura - devolvidos na resposta, mas ignorados se tentar enviá-los no POST/PATCH:

• appearance.avatarUrl - URL público completo da imagem de avatar do bot (por exemplo, https://api.chatlab.com/aichat/content/avatar_xyz.png). Efetue um GET direto para descarregar os bytes. Para alterá-lo, carregue um novo ficheiro através do campo multipart avatar (consulte PATCH).
• whiteLabel.whitelabelLogoUrl - URL público completo do logótipo de cabeçalho White Label. Segue o mesmo padrão de avatarUrl. Para alterá-lo, carregue um novo ficheiro através do campo multipart whitelabel_logo (consulte PATCH).

Ambos os URLs utilizam o esquema + anfitrião + caminho de contexto do pedido atual, pelo que num domínio personalizado White Label são devolvidos com a raiz desse domínio (por exemplo, https://api.acme.com/aichat/content/...).

Envie null numa secção para ignorá-la no PATCH; envie null num campo dentro de uma secção para ignorar esse campo individual. O valor null ao nível do campo nunca limpa um valor armazenado - significa apenas "não alterar".

Construção de função e prompt

O prompt de sistema que o LLM recebe efetivamente é construído de uma de duas formas, consoante o valor de role.role. Saber em que ramo se encontra indica quais os campos relevantes e quais são armazenados mas ignorados.

Ramo A - role.role é CUSTOMER_SUPPORT, SALES ou LEAD_COLLECTION_AGENT (baseado em modelo)

O backend compõe o prompt a partir de um modelo integrado e ignora role.rawPrompt por completo (o valor continua armazenado no bot, apenas não é utilizado). O modelo incorpora:

• role.role - etiqueta da função (por exemplo, "Customer Support") e instruções específicas da função anexadas automaticamente
• name - nome do bot, inserido na frase de abertura
• role.language - "Auto Detect" faz com que o bot siga o idioma do utilizador; qualquer outro valor (por exemplo, "English", "Polish") é convertido em "Output in {language}, unless user uses another language"
• role.responseLength - mapeado para uma meta de contagem de palavras: Concise ≈ 50 palavras, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - opcional; quando preenchido, é anexado como "for the users of the website {url}"
• role.companyDescription - opcional; quando preenchido, é incluído como um parágrafo adicional antes das instruções da função

Este é o ramo recomendado para a maioria dos bots - obtém um comportamento otimizado para a função e proteções de segurança de forma imediata.

Ramo B - role.role é CUSTOM (prompt fornecido pelo autor da chamada)

O backend utiliza role.rawPrompt como prompt de função e anexa a orientação fixa da plataforma para o comprimento da resposta. Isto funciona de forma independente de role.responseLength: a configuração opcional Concise/Normal/Detailed não é inserida para uma função CUSTOM. Do mesmo modo, language, websiteAddress e companyDescription são armazenados, mas não são injetados neste prompt de função. Deve incluir qualquer idioma pretendido, meta de comprimento de resposta ou contexto da empresa no próprio rawPrompt. Podem também ser fornecidas instruções adicionais de tempo de execução e contexto recuperado, pelo que rawPrompt não constitui a totalidade das entradas do modelo. As instruções de tom da função predefinida não são adicionadas, mas escolher CUSTOM não remove todas as instruções da plataforma.

Utilize CUSTOM apenas quando o prompt baseado em modelo não se adequar ao seu caso de utilização (por exemplo, se necessitar de uma persona muito específica de um determinado domínio, das suas próprias restrições de segurança ou de um formato de saída não padronizado).

Campos de tipo enum / conjunto fechado

Os campos enumerados e restritos rejeitam valores inválidos com 400 invalid_parameter. Os restantes campos são strings simples, mesmo onde a interface oferece uma lista fixa. Utilize a grafia documentada e valide o seu payload em vez de presumir que qualquer string não suportada é rejeitada.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - nome completo em inglês do idioma constante no menu pendente de administração, por exemplo, Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi e cerca de 80 outros. O valor é armazenado exatamente como enviado e substituído no modelo de prompt, pelo que códigos ISO de duas letras (en, pl) e outros valores fora da lista não são rejeitados pela API, mas geram uma instrução incoerente como "Output in en, unless...". Assume o valor predefinido Auto Detect se omitido na criação.
• advanced.model - consulte a secção "Modelos de texto de IA" abaixo. Trata-se de uma string e não de um enum validado no esquema do pedido; utilize um valor suportado e não um nome arbitrário de modelo.
• advanced.chatContextSize - utilize 8000, 16000 ou 32000, de acordo com a interface. Os valores acima do máximo da conta são limitados silenciosamente; o DTO não valida este conjunto de três valores.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - opção booleana. true obriga o utilizador a preencher o formulário de recolha de leads antes de iniciar uma conversa; false permite que a IA decida quando apresentar o formulário (predefinição).

Campos estruturados e intervalos

Campos que parecem strings simples ou números, mas que possuem formatos específicos, intervalos ou particularidades da interface de administração que importa conhecer.

• advanced.temperature - o intervalo aceite varia entre 0.0 e 1.0, correspondendo ao controlo deslizante na interface de administração. Os valores fora deste intervalo são rejeitados com 400 invalid_parameter.

• chatMemory.summariesToKnowledgeRatio - percentagem em número inteiro, 10-90; a interface utiliza passos de 10, mas a API aceita números inteiros em todo o intervalo. Predefinição: 50. Com a memória ativada e um contexto superior a 8k, divide o orçamento de conhecimento e memória após a reserva para o prompt/conversa recente, e não todo o contexto do modelo. A 8k, esta configuração não aloca qualquer orçamento para resumos.

• liveChat.schedule - JSON codificado como uma string, e não como um objeto JSON aninhado no envio. O servidor armazena a string original sem alterações; a interface de administração processa-a do lado do cliente ao processar o editor de horários. Após o processamento, a string organiza-se como uma entrada por dia da semana mais uma chave timezone:

  • cada chave de dia da semana (monday-sunday) mapeia para {enabled: boolean, from: "H:MM", to: "H:MM"} no formato de 24 horas
  • timezone é o nome de uma zona IANA (por exemplo, "Europe/Warsaw", "America/New_York")

  Exemplo de valor (note as aspas externas e as aspas internas com escape - trata-se de um campo de string única, não de um objeto aninhado):

  "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}"
  

  Fora do horário definido, liveChat.outOfHoursMessage é apresentada ao visitante e a transferência para live chat é desativada. A validação da estrutura interna decorre apenas do lado do cliente na interface de administração - JSONs malformados ou chaves não reconhecidas são aceites pela API simplesmente como uma string e resultarão num erro de renderização quando um operador abrir o bot na administração mais tarde. Valide a estrutura do seu lado antes do envio.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - descrições curtas apresentadas nos controlos de avaliação de conversa 👍 / 👎 quando conversation.conversationRatingEnabled=true. O texto predefinido é "Gosto da resposta" / "Não gosto da resposta". Visível para os utilizadores finais.

• whiteLabel.hideRoboAssistLogo - funcionalidade de White Label, sujeita aos limites da sua conta. Oculta a linha de rodapé "Powered by ChatLab". Se a sua conta não incluir White Label, o valor é armazenado mas ignorado e o rodapé é sempre apresentado.

• whiteLabel.whitelabelLogoLink - funcionalidade de White Label, sujeita aos limites da sua conta. URL de destino de clique para o logótipo personalizado quando hideRoboAssistLogo=true e um ficheiro de logótipo personalizado é carregado através da parte multipart whitelabel_logo.

• appearance.simulateHumanTypingDelay - segundos (não milissegundos), número inteiro de 0-200. Pausa entre balões de mensagem sucessivos do bot quando simulateHumanTyping=true. Predefinição: 5.

• appearance.autoOpenChatDelaySeconds - segundos, número inteiro. Atraso até o widget abrir automaticamente quando autoOpenChat=true e autoOpenChatDelay=true.

• advanced.internalLocale - código de idioma-região IETF no formato ll_CC (com sublinhado, e NÃO ll-CC com hífen). Os valores aceites provêm de uma lista fixa de aproximadamente 95 idiomas: en_US, pl_PL, de_DE, fr_FR, es_ES, it_IT, pt_PT, nl_NL, ru_RU, zh_CN, zh_TW, ja_JP, ko_KR, ar_SA, hi_IN, tr_TR, cs_CZ, da_DK, fi_FI, sv_SE, no_NO, el_GR, he_IL e muitos outros. O envio de apenas um código de duas letras ("en") ou formato BCP-47 ("en-US") não consta da lista de valores permitidos. Predefinição: en_US. Este é o idioma utilizado para a formatação de datas e números na moldura do widget, sendo distinto de role.language (o idioma das respostas conversacionais do bot).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - números inteiros (enviar como números JSON, por exemplo, 30, e não "30"). Defina o limite de mensagens para 0 para desativar este limite baseado em sessões. Ao ativá-lo, indique uma duração positiva. O backend aplica N mensagens por sessão pelo período de duração em segundos antes de apresentar security.talkMessagesRateLimitHitMessage ao visitante.

• advanced.botMessagesLimit - número inteiro (número JSON, por exemplo, 1000). 0 significa ausência de teto adicional por bot, mantendo-se a aplicação do limite de créditos da conta; caso contrário, tem de ser um múltiplo de 1000 (1000, 2000, 10000, ...). Valores como 100 ou 1500 são rejeitados com 400 invalid_parameter. Trata-se de um teto mensal de créditos do bot e não de uma contagem de mensagens por conversa. O mapeador não ajusta este valor ao teto da conta; o limite da conta continua a restringir a utilização real.

Modelos de texto de IA (advanced.model)

Utilize o identificador exato de modelo devolvido em advanced.model ao consultar um bot configurado com o modelo pretendido em Settings > Model & Advanced (Definições > Modelo e avançado). O valor predefinido atual aquando da criação é 5.6-LUNA. Os identificadores diferenciam maiúsculas de minúsculas e diferem dos nomes de apresentação; por exemplo, 5.6-LUNA é apresentado como GPT 5.6-luna.

O catálogo de modelos evolui ao longo do tempo. Não presuma que uma string arbitrária ou o ID público de modelo de um fornecedor seja suportado apenas porque o esquema do pedido aceita uma string. Consulte a configuração guardada e teste o chatbot resultante antes de o colocar em produção.

Field reference (full request schema)

As secções e campos suportados, com os respetivos tipos e restrições importantes. Semântica de PATCH: qualquer campo omitido (ou enviado como null) mantém o valor persistido inalterado. O mesmo formato é utilizado para a resposta (exceto o conteúdo binário multipart; com a adição do bloco de apenas leitura meta em todas as respostas e de apiKey apenas na resposta de criação).

Top level

Field	Type	Constraint	Description
name	string	max 150, obrigatório na criação	Nome de exibição do bot
role	object		Consulte § role
conversation	object		Consulte § conversation
chatMemory	object		Consulte § chatMemory
appearance	object		Consulte § appearance
humanSupport	object		Consulte § humanSupport
leadCollection	object		Consulte § leadCollection
liveChat	object		Consulte § liveChat
consent	object		Consulte § consent
whiteLabel	object		Consulte § whiteLabel
security	object		Consulte § security
advanced	object		Consulte § advanced

Adições exclusivas da resposta:

• meta: { id, createdAt, updatedAt } - apenas leitura.
• apiKey - string, presente apenas na resposta a POST /v1/management/bots - a chave Bot Talk recém-gerada para o novo bot, devolvida exatamente uma vez.

§ role

Field	Type	Constraint	Description
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Predefinição de persona; seleciona o modelo de prompt (consulte "Role and prompt construction")
language	string	nome completo do idioma em inglês (English, Polish, ...) ou Auto Detect	Idioma principal introduzido no modelo de prompt
responseLength	string	∈ {Concise, Normal, Detailed}	Nível de detalhe pretendido para as respostas da IA
websiteAddress	string		Website utilizado para o contexto do prompt
companyDescription	string		Descrição da empresa utilizada para o contexto do prompt
rawPrompt	string		Prompt de sistema personalizado - utilizado textualmente apenas quando role=CUSTOM

§ conversation

Field	Type	Constraint	Description
welcomeMessage	string		Primeira mensagem apresentada ao visitante ao abrir
queryRefinementEnabled	boolean		Se for true, refina a pergunta do visitante antes da recuperação RAG
conversationContinuityEnabled	boolean		Se for true, os visitantes que regressam retomam a sua última conversa
conversationRatingEnabled	boolean		Se for true, apresenta os controlos de avaliação da conversa com polegar para cima/baixo
positiveRatingTooltip	string		Dica de contexto no botão de avaliação positiva
negativeRatingTooltip	string		Dica de contexto no botão de avaliação negativa
suggestedQuestions	string		Perguntas sugeridas / abridores de conversa separados por quebra de linha
dynamicSuggestedFollowups	boolean		Se for true, a IA propõe sugestões de seguimento após cada resposta
positiveRatingMessage	string		Mensagem apresentada após feedback positivo
negativeRatingMessage	string		Mensagem apresentada após feedback negativo
hideSuggestedQuestionsAfterFirstUse	boolean		Ocultar sugestões estáticas após a utilização
dynamicFollowupsAutoIcons	boolean		Se for true, a IA escolhe automaticamente ícones emoji para as sugestões de seguimento dinâmicas

§ chatMemory

Field	Type	Constraint	Description
enabled	boolean		Interruptor principal da funcionalidade de memória de chat
summaryConversationsEnabled	boolean		Guardar resumos individuais por conversa
conversationSummaryPrompt	string		Prompt personalizado utilizado para resumir cada conversa
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Define se deve ser utilizado o prompt de resumo predefinido ou personalizado
clientSummaryPrompt	string		Prompt personalizado utilizado para resumir o cliente ao longo de várias conversas
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Prompt de perfil de cliente predefinido vs personalizado
summariesToKnowledgeRatio	int	10-90 (passo na interface: 10)	% do orçamento disponível de conhecimento/memória alocado a resumos em contextos superiores a 8k

§ appearance

Field	Type	Constraint	Description
launcherLabelLine1	string	max 60	Primeira linha de texto do iniciador
launcherLabelLine2	string	max 60	Segunda linha de texto do iniciador
launcherTextColor	string		Cor do texto do iniciador
launcherDismissEnabled	boolean		Permitir dispensar o iniciador
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Família de tipos de letra do widget
chatDrawerEnabled	boolean		Ativar apresentação em gaveta (drawer)
launcherColor	string (hex)		Cor de fundo do iniciador (ícone de chat)
headerColor	string (hex)		Cor de fundo do cabeçalho do chat
titleColor	string (hex)		Cor do título do cabeçalho do chat
subtitleColor	string (hex)		Cor do subtítulo do cabeçalho do chat
clientMessageBubbleColor	string (hex)		Cor do balão de mensagem do visitante
clientMessageTextColor	string (hex)		Cor do texto da mensagem do visitante
responseMessageBubbleColor	string (hex)		Cor do balão de resposta do bot
responseMessageTextColor	string (hex)		Cor do texto da resposta do bot
chatSubheader	string		Frase de destaque apresentada abaixo do título do chat
senderPlaceholder	string		Texto de espaço reservado no campo de introdução de mensagem
resetConversationTooltip	string		Dica de contexto no botão de "repor conversa"
chatAlignment	string (enum)	∈ {left, right}	Lado do ecrã ao qual o chat fica fixado
launcherBottomMargin	int	0-500	Distância do iniciador à margem inferior (px)
launcherSideMargin	int	0-500	Distância do iniciador à margem lateral (px)
displayShadow	boolean		Sombra projetada sob o widget
customCss	string		CSS não tratado injetado no iframe do widget
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Modo de abertura das ligações dentro das mensagens do bot
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Estado minimizado: ícone de iniciador, barra de envio compacta ou formato de pílula
chatDesktopWidthPx	int		Largura do widget no computador
chatDesktopHeightPx	int		Altura do widget no computador
chatMobileSizePercent	int		Dimensão do widget em dispositivos móveis em % da janela de visualização
messageFontSize	int		Tamanho do tipo de letra do texto da mensagem (px)
showChatbotBubblesDesktop	boolean		Apresentar os balões flutuantes de chamada de atenção no computador
showChatbotBubblesMobile	boolean		Apresentar os balões flutuantes de chamada de atenção em dispositivos móveis
chatbotBubblesDelaySeconds	int		Atraso antes do aparecimento dos balões de chamada de atenção (segundos)
launcherIconFullSize	boolean		Apresentar o ícone personalizado do iniciador de ponta a ponta em vez de inserido com margem
welcomeScreenEnabled	boolean		Apresentar o Welcome Screen (ecrã de boas-vindas) em vez de ir diretamente para o chat
welcomeScreenQuestionsLabel	string		Legenda acima das perguntas sugeridas no ecrã de boas-vindas
welcomeScreenHideHumanContactForm	boolean		Ocultar a ação do formulário de contacto humano no cabeçalho enquanto o Welcome Screen estiver visível. Volta a surgir após a primeira mensagem do visitante. Nos bots criados antes de 2026-09-02, a predefinição é true
welcomeScreenHideLiveChat	boolean		Ocultar a ação de chat ao vivo no cabeçalho enquanto o Welcome Screen estiver visível. Volta a surgir após a primeira mensagem do visitante. Nos bots criados antes de 2026-09-02, a predefinição é true
headerActionsLayout	string	ICONS or DROPDOWN	Como o chat ao vivo e o formulário de contacto humano são disponibilizados no cabeçalho do chat: ICONS (um ícone individual para cada um) ou DROPDOWN (agrupados no menu do cabeçalho). Nos bots criados antes de 2026-09-02, a predefinição é ICONS
stackSuggestedQuestions	boolean		Empilhar as perguntas sugeridas verticalmente (em vez de lado a lado)
suggestedQuestionsFontSize	int		Tamanho do tipo de letra das etiquetas de perguntas sugeridas (px)
suggestedQuestionsTextColor	string (hex)		Cor do texto das etiquetas de perguntas sugeridas
suggestedQuestionsBackgroundColor	string (hex)		Cor de fundo das etiquetas de perguntas sugeridas
autoOpenChat	boolean		Abrir automaticamente o chat no computador
autoOpenChatOnMobiles	boolean		Abrir automaticamente o chat em dispositivos móveis
autoOpenChatDelay	boolean		Utilizar um atraso antes da abertura automática
autoOpenChatDelaySeconds	int		Atraso na abertura automática (segundos)
simulateHumanTyping	boolean		Dividir a resposta do bot em balões com animação de escrita
simulateHumanTypingDelay	int	0-200	Atraso entre mensagens em balão (segundos)
footerMarkdown	string	max 255	Markdown personalizado de rodapé apresentado por baixo do chat
avatarUrl	string	apenas leitura	URL público completo do avatar; para o alterar, carregue através da parte multipart avatar

Multipart em POST/PATCH: avatar (parte do ficheiro). Os corpos de resposta e de pedidos GET omitem o conteúdo do ficheiro - apenas o URL é transmitido.

§ humanSupport

Field	Type	Constraint	Description
enabled	boolean		Interruptor do fluxo de Human Support
email	string	obrigatório (strict na criação) quando enabled=true	Endereço que recebe os e-mails de suporte humano
dialogMessage	string		Mensagem de incentivo apresentada acima do formulário
thankYouMessage	string		Confirmação apresentada após o envio
emailMessageSubjectTemplate	string		Modelo de assunto para o e-mail enviado ao operador
emailMessageContentTemplate	string		Modelo de corpo para o e-mail enviado ao operador
emailPlaceholder	string		Espaço reservado no campo de introdução de e-mail
messagePlaceholder	string		Espaço reservado na área de introdução de texto da mensagem
emailWithConversationContent	boolean		Se for true, inclui a transcrição da conversa no corpo do e-mail
customFormId	long	id de um formulário personalizado existente	Substitui o formulário de contacto integrado por um formulário personalizado. Na criação, a omissão utiliza o formulário integrado; em PATCH, null mantém a seleção atual inalterada
customFormMapping	string	string codificada em JSON	Mapeia os campos do formulário personalizado para os campos do e-mail de suporte humano

requirePolicyAccept encontra-se em consent.humanSupportRequirePolicyAccept, e não aqui.

§ leadCollection

Field	Type	Constraint	Description
enabled	boolean		Interruptor do formulário de leads
nameEnabled	boolean		Recolher o nome
nameLabel	string		Legenda no campo de introdução do nome
emailEnabled	boolean		Recolher o e-mail
emailLabel	string	obrigatório (strict na criação) quando enabled=true E emailEnabled=true	Legenda no campo de introdução do e-mail
phoneEnabled	boolean		Recolher o telefone
phoneLabel	string	obrigatório (strict na criação) quando enabled=true E phoneEnabled=true	Legenda no campo de introdução do telefone
leaveDetailsMessage	string	obrigatório (strict na criação) quando enabled=true	Mensagem que incentiva o visitante a deixar os seus dados de contacto
thankYouMessage	string	obrigatório (strict na criação) quando enabled=true	Confirmação apresentada após o envio
requireBeforeNewConversation	boolean		Se for true, o formulário tem de ser enviado antes de o chat começar; se for false, a IA decide quando apresentar o formulário
emailNotificationEnabled	boolean		Enviar um e-mail ao proprietário sempre que um lead for recolhido
emailNotificationAddress	string		Destinatário da notificação (assume por predefinição o e-mail da conta)
emailWithConversationContent	boolean		Se for true, inclui a transcrição da conversa na notificação

| customFormId | long | id de um formulário personalizado existente | Substitui o formulário de leads integrado por um formulário personalizado. Na criação, a omissão utiliza o formulário integrado; em PATCH, null mantém a seleção atual inalterada | | customFormMapping | string | string codificada em JSON | Mapeia os campos do formulário personalizado para nome / e-mail / telefone |

Regra cross-field strict na criação: enabled=true exige pelo menos um entre emailEnabled ou phoneEnabled. requirePolicyAccept encontra-se em consent.leadCollectionRequirePolicyAccept, e não aqui.

§ liveChat

Field	Type	Constraint	Description
enabled	boolean		Interruptor da funcionalidade Live Chat
infoMessage	string		Mensagem explicativa antes da transferência para atendimento humano
startMessage	string		Mensagem apresentada quando a sessão ao vivo tem início
endMessage	string		Mensagem apresentada quando a sessão ao vivo termina
nameLabel	string		Legenda no campo de introdução do nome no pré-formulário de chat ao vivo
emailLabel	string		Legenda no campo de introdução do e-mail no pré-formulário de chat ao vivo
schedule	string	string codificada em JSON (seleções de dias da semana + from/to + timezone)	Horário de funcionamento do chat ao vivo - consulte "Structured fields and ranges" para a estrutura exata
outOfHoursMessage	string		Mensagem apresentada quando o horário indica que o serviço está encerrado
closeModalMessage	string		Título da janela modal "terminar chat ao vivo?"
closeModalConfirmLabel	string		Legenda do botão de confirmação na janela modal de encerramento
closeModalCancelLabel	string		Legenda do botão de cancelamento na janela modal de encerramento
closeModalTooltipText	string		Dica de contexto no elemento de encerramento do chat
operatorHasJoinedLabel	string		Legenda apresentada quando um operador entra na conversa
operatorDidNotJoinInTimeLabel	string		Legenda apresentada quando nenhum operador entra dentro do limite de tempo
waitingForOperatorToJoinLabel	string		Legenda apresentada durante a espera por um operador
waitingForOperatorSeconds	int		Tempo limite para um operador aceitar a conversa (segundos)
redirectToHumanSupportForm	boolean		Se for true, reencaminha para o formulário de Human Support quando nenhum operador aceitar o contacto
requireAdminOnline	boolean		Exigir um operador disponível de acordo com as definições de presença
presenceMode	string		Modo de presença; utilize o valor de um bot configurado na interface
hideHumanSupportWhenLiveChatAvailable	boolean		Ocultar o formulário de contacto quando o chat ao vivo estiver disponível
missedEmailEnabled	boolean	predefinição true	Enviar um e-mail ao proprietário do bot quando um pedido de chat ao vivo não obtiver resposta. Não definido em bots antigos, o que é interpretado como ativado

requirePolicyAccept encontra-se em consent.liveChatRequirePolicyAccept, e não aqui.

§ consent

Field	Type	Constraint	Description
newConversationRequirePolicyAccept	boolean		Exigir consentimento com a política de privacidade antes de iniciar uma nova conversa
humanSupportRequirePolicyAccept	boolean		Exigir consentimento com a política de privacidade antes de enviar o formulário de suporte humano
leadCollectionRequirePolicyAccept	boolean		Exigir consentimento com a política de privacidade antes de enviar o formulário de recolha de leads
liveChatRequirePolicyAccept	boolean		Exigir consentimento com a política de privacidade antes de iniciar uma sessão de chat ao vivo
newConversationConsentDescription	string		Texto de introdução do ecrã de consentimento no início da conversa
privacyPolicyConsentCheckboxLabel	string		Legenda junto à caixa de seleção de consentimento (normalmente contém uma ligação para a política de privacidade)

§ whiteLabel

Field	Type	Constraint	Description
hideRoboAssistLogo	boolean	funcionalidade White Label; sujeita aos limites da conta	Ocultar o logótipo predefinido do ChatLab no rodapé
whitelabelLogoLink	string	funcionalidade White Label; sujeita aos limites da conta	URL para o qual o logótipo personalizado de rodapé direciona
assignToCustomDomain	boolean	condicionado pela funcionalidade CUSTOM_DOMAIN	Alojar o chat no domínio personalizado configurado
whitelabelLogoUrl	string	apenas leitura	URL público completo do logótipo de white label; para o alterar, carregue através da parte multipart whitelabel_logo

Multipart em POST/PATCH: whitelabel_logo (parte do ficheiro). Os corpos de resposta e de pedidos GET omitem o conteúdo do ficheiro - apenas o URL é transmitido.

§ security

Field	Type	Constraint	Description
allowedDomains	string		Lista separada por vírgulas de domínios autorizados a incorporar o widget (vazio = sem lista de permissões)
spamFilterEnabled	boolean		Ativar o filtro de spam por bot para as mensagens recebidas
countryFilterMode	string	BLACKLIST ou WHITELIST	Modo como as listas de países são interpretadas. As listas em si permanecem acessíveis apenas a administradores
talkMessagesRateLimit	int	>= 0; 0 desativa	Número máximo de mensagens de utilizador permitidas na janela de limite de taxa
talkMessagesRateLimitDurationSeconds	int	>= 0	Duração da janela do limite de taxa (segundos)
talkMessagesRateLimitHitMessage	string		Mensagem apresentada ao visitante quando o limite de taxa for atingido

§ voice

Field	Type	Constraint	Description
inputEnabled	boolean		Permitir que o visitante dite mensagens (voz para texto)
conversationEnabled	boolean	exige a funcionalidade de voz no plano	Ativar conversas completas por voz
voiceId	string	id de voz específico do fornecedor (ex.: alloy)	Voz sintética utilizada
model	string	ex.: GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Modelo de voz. Faturado ao minuto, com tarifas variáveis consoante o modelo
turnDetection	string	específico do fornecedor	Modo de alternância de turnos de fala
audioPrompt	string		Prompt de sistema adicional utilizado apenas para interações por voz
welcomeMessage	string		Frase inicial falada
language	string	código do idioma	Idioma principal de voz
additionalLanguages	string	códigos de idioma separados por vírgulas	Idiomas adicionais que o agente de voz aceita
maxDurationSeconds	int		Limite máximo estrito para uma única conversa por voz
maxDurationMessage	string		Mensagem apresentada quando o limite de duração for atingido

§ multilingual

Field	Type	Constraint	Description
enabled	boolean		Interruptor do modo multilingue
mode	string	AUTODETECT ou FIXED_LIST	Como o bot escolhe o idioma de resposta
baseLanguage	string	código do idioma	Idioma no qual os textos do próprio bot estão redigidos
languages	string	códigos de idioma separados por vírgulas	Idiomas disponibilizados ao visitante
knowledgeLanguageMode	string	NONE, MAIN, ou DYNAMIC	Como o conhecimento noutros idiomas é tratado
knowledgeLanguageFallback	string	código do idioma	Idioma utilizado quando não for encontrada nenhuma correspondência

§ advanced

Field	Type	Constraint	Description
model	string	sujeito aos limites da conta; consulte "AI text models" acima	Identificador do LLM (ex.: 5.6-LUNA)
temperature	decimal	0.0-1.0	Temperatura de amostragem (corresponde ao controlo deslizante da interface)
chatContextSize	int	∈ {8000, 16000, 32000}; ajustado silenciosamente ao limite da sua conta	Orçamento de contexto configurado, incluindo instruções, histórico e conhecimento
botMessagesLimit	long	0 ou múltiplo de 1000 (ex.: 1000, 2000, 10000)	Limite mensal de créditos de mensagens do bot (0 = sem limite adicional para o bot; o orçamento da conta continua a aplicar-se)
internalLocale	string	código de locale no formato ll_CC	Região/idioma para as etiquetas de interface do widget (distinto de role.language)
productsViewEnabled	boolean		Se for true, apresenta os Offer Cards de e-commerce dentro do chat
includeProductsInKnowledgeBase	boolean		Se for true, indexa o catálogo de produtos como parte da base de conhecimento

Fora do âmbito da API

A interface de administração apresenta algumas áreas que não estão intencionalmente expostas nesta versão da Management API:

• Treino e eliminação - estes endpoints não listam todos os bots, não gerem conjuntos de dados de treino nem eliminam bots. Utilize a aplicação para estes fluxos de trabalho.
• Separador Flow - o editor visual de Conversation Flow (fluxo de conversa: fases e transições). Não exposto através da Management API.
• Separador Actions - integrações geridas de e-commerce / reservas, AI Search e funções personalizadas da API. A invocação de ferramentas (tool calling) nunca fez parte da Management API.
• O próprio construtor de formulários personalizados - a criação e edição de formulários personalizados não está exposta. Pode, no entanto, associar um formulário existente a um bot através de leadCollection.customFormId e humanSupport.customFormId.
• Ícones personalizados de abrir / fechar o chat - customLauncherIconVisible, openChatIcon, closeChatIcon. A API expõe apenas as partes multipart principais avatar e whitelabel_logo.
• Listas de IP e países - as entradas individuais são acessíveis apenas a administradores. Apenas o modo de interpretação está exposto, através de security.countryFilterMode.

Endpoints

POST /v1/management/bots

Crie um novo bot. São aceites dois Content-Types equivalentes; escolha o que for mais conveniente.

Modo A - JSON simples (recomendado quando não precisa de carregar um avatar / logótipo no mesmo pedido):

• Content-Type: application/json
• O corpo do pedido é o JSON de configuração do bot (sem wrapper data)
• Os ficheiros (avatar / logótipo) podem ser carregados mais tarde através de um segundo PATCH usando o modo B

Modo B - multipart/form-data (utilize ao carregar ficheiros no mesmo pedido):

• Content-Type: multipart/form-data; boundary=...
• Parte JSON data (obrigatória, Content-Type: application/json) - configuração do bot na estrutura aninhada descrita acima
• Parte de ficheiro avatar (opcional) - imagem de avatar do bot
• Parte de ficheiro whitelabel_logo (opcional) - logótipo White Label (aplica-se apenas se a sua conta incluir White Label)

Apenas o campo name é obrigatório no JSON; todos os restantes campos assumem a mesma predefinição que o assistente da interface de administração definiria.

Exemplo de corpo do pedido

Este é o JSON data maximal - com todas as secções preenchidas. Envie apenas as secções relevantes para si; tudo o resto assume valores predefinidos.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Regras de validação com mensagens de erro próprias:

• name - obrigatório, máximo de 150 carateres
• advanced.temperature - entre 0.0 e 1.0
• chatMemory.summariesToKnowledgeRatio - número inteiro entre 10 e 90 (percentagem, incremento de 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - entre 0 e 500
• appearance.footerMarkdown - máximo de 255 carateres
• humanSupport.enabled=true exige que humanSupport.email esteja definido
• leadCollection.enabled=true exige que pelo menos um dos campos leadCollection.emailEnabled ou leadCollection.phoneEnabled seja true; qualquer canal ativo exige também o respetivo rótulo, além de leaveDetailsMessage e thankYouMessage
• advanced.chatContextSize é limitado ao tamanho máximo de contexto suportado pela conta. Não assuma que outros campos numéricos sejam limitados automaticamente.

Os campos cujo valor seja null no servidor são omitidos do corpo JSON - a comunicação transmite apenas campos com valores não nulos.

Exemplo de corpo da resposta (201)

Mesma estrutura do pedido, acrescida do bloco só de leitura meta e do campo de utilização única apiKey no nível superior. Os URLs de ficheiros só de leitura (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) são preenchidos pelo servidor quando as partes multipart correspondentes tiverem sido carregadas.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T10:11:02Z"
  },
  "apiKey": "ck_freshly_minted_bot_talk_key_here"
}

O campo apiKey surge apenas no momento da criação - é a chave Bot Talk recém-gerada e associada ao novo bot. O texto simples é apresentado uma única vez e não pode ser recuperado posteriormente através da API; guarde-o de imediato do seu lado.

O cabeçalho de resposta Location contém o URL do novo bot (/v1/management/bots/{id}).

Exemplos de Curl

Modo A - JSON simples (mais simples):

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Helpdesk Bot","conversation":{"welcomeMessage":"Hi!"}}'

Modo B - multipart com avatar:

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -F 'data={"name":"Helpdesk Bot","conversation":{"welcomeMessage":"Hi!"}};type=application/json' \
  -F 'avatar=@./avatar.png'

GET /v1/management/bots/{bot_id}

Devolve a configuração atual de um bot que lhe pertença.

Exemplo de Curl

curl https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..."

Exemplo de corpo da resposta (200)

Mesma estrutura da resposta a POST, excluindo o campo de utilização única apiKey. O bloco meta está incluído. Devolve 404 not_found_error se o bot não existir ou não pertencer à sua conta.

O avatar e o logótipo White Label atuais são disponibilizados como URLs completos só de leitura (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - com base no mesmo esquema + anfitrião + caminho de contexto que processou este pedido. Obtenha os bytes fazendo um GET diretamente a esses URLs; para substituir qualquer um dos ficheiros, carregue um novo através da parte multipart avatar / whitelabel_logo no PATCH. Estes campos de URL são ignorados se forem enviados no corpo de um pedido.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T11:02:19Z"
  }
}

Clonar um bot

O corpo do pedido de POST /v1/management/bots e o corpo da resposta de GET /v1/management/bots/{bot_id} partilham a mesma estrutura, pelo que a clonagem é um processo em três passos: obter o bot de origem com GET, remover os campos de identidade geridos pelo servidor e enviar o resultado com POST.

1. Obter o bot de origem com GET.

curl https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -o source-bot.json

2. Remover o bloco meta de nível superior. O objeto meta (id, createdAt, updatedAt) é gerido pelo servidor e apenas de leitura - deixá-lo no corpo do POST não causa problemas (o servidor ignora-o), mas removê-lo torna a intenção explícita e mantém o payload limpo. Opcionalmente, edite name para que o clone se distinga da origem.

jq 'del(.meta) | .name = "Helpdesk Bot (clone)"' source-bot.json > clone-body.json

3. Enviar o corpo limpo com POST para criar o clone. Consulte a referência de POST /v1/management/bots acima para a estrutura completa do corpo e as regras de validação.

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d @clone-body.json

A resposta contém o meta.id do novo bot e uma apiKey recém-criada (a chave Bot Talk para o clone). O texto simples da apiKey é devolvido apenas nesta resposta de criação - copie-o antes de descartar o corpo da resposta; não pode ser recuperado mais tarde.

Isto copia as definições suportadas, não um chatbot totalmente treinado. O conteúdo de treino, o histórico de conversas, as integrações/ações, o Flow e as definições de formulários não são clonados por estes endpoints. Configure esses elementos separadamente na aplicação.

Ressalvas adicionais:

• Os ficheiros não são clonados. appearance.avatarUrl e whiteLabel.whitelabelLogoUrl são apenas de leitura e apontam para os ficheiros do bot de origem. Se precisar do mesmo avatar ou logótipo White Label no clone, descarregue os bytes dos URLs de origem e envie-os como partes multipart avatar / whitelabel_logo - quer no POST de criação (Modo B), quer num PATCH subsequente.
• As chaves Bot Talk não são clonadas. Cada bot tem o seu próprio conjunto de chaves Bot Talk. A única apiKey devolvida pelo POST de criação é a única gerada automaticamente; crie chaves adicionais no separador de API do bot, se necessário.

PATCH /v1/management/bots/{bot_id}

Atualize um ou mais campos num bot que lhe pertence. Apenas as secções / campos presentes no JSON são modificados; tudo o que for omitido (ou enviado como null) permanece inalterado. Aplicam-se semânticas de atualização parcial por campo dentro de uma secção enviada.

São aceites dois Content-Types equivalentes (o mesmo que no POST):

Modo A - JSON simples (recomendado ao atualizar apenas definições):

• Content-Type: application/json
• O corpo do pedido é o JSON do patch (sem wrapper data)

Modo B - multipart/form-data (utilize ao carregar ficheiros):

• Parte JSON data (opcional) - o patch. Envie apenas se pretender alterar campos. Omita totalmente se apenas pretender carregar um avatar ou logótipo.
• Parte de ficheiro avatar (opcional) - substituir o avatar
• Parte de ficheiro whitelabel_logo (opcional) - substituir o logótipo White Label (aplica-se apenas se a sua conta incluir White Label)

Todas as três partes são opcionais no PATCH, mas pelo menos uma tem de estar presente para que a chamada tenha efeito.

Exemplo de corpo do pedido (múltiplas secções)

Qualquer campo aceite por POST /v1/management/bots também pode ser enviado aqui. O exemplo abaixo ilustra várias secções, não todos os campos suportados; na prática, envia apenas as chaves que pretende alterar (consulte "Atualização parcial mínima" mais abaixo) - cada chave omitida (ou enviada como null) deixa o valor persistido inalterado.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc. Be concise.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Concise",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hello there!",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "Pricing\nShipping times\nReturns policy",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize the conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about the customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#abcdef",
    "headerColor": "#abcdef",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI assistant",
    "senderPlaceholder": "Type a message",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we'll get back to you.",
    "thankYouMessage": "Thanks!",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details.",
    "thankYouMessage": "Thanks!",
    "requireBeforeNewConversation": true,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5",
    "temperature": 0.2,
    "chatContextSize": 32000,
    "botMessagesLimit": 2000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Atualização parcial mínima

Atualize um único campo através de PATCH enviando exatamente as chaves que pretende alterar - tudo o resto é preservado.

{
  "appearance": {
    "launcherColor": "#abcdef"
  }
}

Exemplos com Curl

Modo A - JSON simples (mais simples):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"appearance":{"launcherColor":"#abcdef"}}'

Modo B - multipart (ao substituir o avatar / logótipo):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -F 'data={"appearance":{"launcherColor":"#abcdef"}};type=application/json' \
  -F 'avatar=@./new-avatar.png'

Modo B - substituir apenas o avatar (sem alterações nos campos):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -F 'avatar=@./new-avatar.png'

Corpo da resposta (200)

Tem a mesma estrutura que GET /v1/management/bots/{bot_id} - a configuração completa do bot após a aplicação do patch, incluindo o bloco meta. Sem o campo apiKey. Devolve 404 not_found_error se o bot não existir ou não pertencer à sua conta.

O exemplo abaixo mostra a resposta após aplicar o patch do Exemplo de corpo do pedido (múltiplas secções) acima ao bot do exemplo de GET - os campos alterados refletem os novos valores, os campos intocados são preservados e meta.updatedAt é atualizado.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc. Be concise.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Concise",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hello there!",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "Pricing\nShipping times\nReturns policy",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize the conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about the customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#abcdef",
    "headerColor": "#abcdef",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI assistant",
    "senderPlaceholder": "Type a message",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we'll get back to you.",
    "thankYouMessage": "Thanks!",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details.",
    "thankYouMessage": "Thanks!",
    "requireBeforeNewConversation": true,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5",
    "temperature": 0.2,
    "chatContextSize": 32000,
    "botMessagesLimit": 2000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T12:45:08Z"
  }
}

GET /v1/usage

Consulte a utilização atual da subscrição para a conta proprietária da chave Management.

Corpo da resposta (200)

{
  "subscriptionType": "your-plan-id",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}

• subscriptionType é um identificador em minúsculas do plano atual da conta (your-plan-id é um placeholder ilustrativo). Os planos provêm de um catálogo dinâmico, pelo que o conjunto exato de identificadores pode mudar ao longo do tempo à medida que os planos são renomeados ou adicionados - trate isto como uma string opaca e não como um enum fixo.
• messages.used / limit / remaining correspondem aos créditos de mensagens do mês civil atual, sendo repostos no primeiro dia do mês e não no dia de renovação da subscrição. São ponderados por créditos e não representam contagens brutas de respostas.
• bots.used / limit / remaining contabilizam os bots pertencentes à conta, incluindo bots em pausa, em relação ao limite total de bots da sua conta.

Cabeçalhos de limite de taxa

As respostas que atingem a fase de limite de taxa (ou seja, autenticação e lista de permissões de IP aprovadas) incluem:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1715430000

• X-RateLimit-Limit - o limite por chave efetivamente aplicado a esta chamada (10 por predefinição, ou o seu rateLimitPerMinute configurado, se for inferior).
• X-RateLimit-Remaining - tokens restantes no balde imediatamente após esta chamada.
• X-RateLimit-Reset - segundos no formato Unix epoch em que o próximo token fica disponível (não representa uma reposição total do balde; o balde enche-se continuamente). Quando o balde está cheio, corresponde à hora atual.

Nas respostas 429 rate_limit_exceeded, o cabeçalho Retry-After também é definido, expresso em segundos inteiros até que pelo menos um token seja libertado.

Os erros de pré-autenticação (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) e 403 ip_not_whitelisted não contêm os cabeçalhos X-RateLimit-* - o limitador só é consultado após a autenticação e as verificações de IP serem concluídas com êxito.

Formato de erro

Mesmo formato de envelope que a Bot Talk API:

{
  "error": {
    "type": "permission_error",
    "code": "key_type_not_allowed",
    "message": "This endpoint requires a MANAGEMENT API key.",
    "param": null
  }
}

Os erros de validação utilizam code: "invalid_parameter" e prefixam o caminho do campo em falha na mensagem para facilitar a identificação da secção com problemas:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "humanSupport.email Human support email is required when humanSupport.enabled=true"
  }
}

Valores incorretos para campos de tipo enum / conjunto fechado (por exemplo, chatMemory.clientSummaryPromptType = "BOGUS") incluem o caminho do campo, o valor rejeitado e a lista de valores permitidos:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "chatMemory.clientSummaryPromptType 'BOGUS' is not a valid value. Allowed: CUSTOM, DEFAULT"
  }
}

Relacionado

Para endpoints de conversação e streaming SSE, consulte Bot Talk API.