Management API

Descriçã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 programaticamente com POST /v1/management/bots
• ler um bot específico do qual seja proprietário com GET /v1/management/bots/{bot_id}
• atualizar um bot específico com PATCH /v1/management/bots/{bot_id}
• consultar o consumo 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 do Bot Talk, 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 neste 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 (rate limit) e submeta.
3. Copie a chave completa a partir da janela modal de confirmação. O texto simples é apresentado apenas uma vez.

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

Autenticação

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Enviar uma chave mk_ para /v1/chat (ou para qualquer outro endpoint do Bot Talk) devolve 403 key_type_not_allowed. Enviar 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 (token bucket, capacidade de 10, reposição gradual de ~1 token a cada 6 segundos). Configurável para valores inferiores aquando da criação - defina um rateLimitPerMinute mais baixo e o teto máximo diminui, ajustando a taxa de reposição em conformidade.

Permissões

Cada chave de gestão inclui qualquer subconjunto das três permissões abaixo. Pelo menos uma tem de ser selecionada 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 tenha 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

POST e PATCH aceitam um corpo JSON agrupado em 13 secções. Cada secção corresponde a um subseparador na barra lateral de Bot Settings (Definições do bot) da 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á a mesma opção alterar-se no separador Consent & Privacy (Consentimento e privacidade) na aplicação de administração.

• role - persona do bot, prompt direto, comprimento da resposta, idioma, contexto do website / empresa (separador Role & Behavior [Função e comportamento])
• conversation - mensagem de boas-vindas, refinamento de perguntas, continuidade da conversa, botão de avaliação + descrições de ajuda, conteúdo de perguntas sugeridas + seguimentos dinâmicos (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 - os quatro seletores de consentimento da política de privacidade e o texto do ecrã de consentimento (separador Consent & Privacy [Consentimento e privacidade])
• whiteLabel - ocultar logótipo, hiperligação para logótipo personalizado, alojamento em domínio personalizado (separador Whitelabel)
• security - domínios permitidos, filtro de spam, limites de pedidos de conversação (separador Security [Segurança])
• voice - entrada de 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 da base de conhecimento (separador Languages [Idiomas])
• advanced - modelo LLM, temperatura, tamanho do contexto, limite de mensagens do bot, idioma interno, Offer Cards (separador Model & Advanced [Modelo e avançado])

Apenas name se encontra no nível superior, uma vez que identifica o bot em vez de pertencer a um separador específico.

A barra lateral de Bot Settings tem atualmente 15 subseparadores, e 13 deles correspondem às secções acima. Os dois subseparadores sem secção correspondente são Flow e Actions - ambos abordados na secção "Fora do âmbito da API" abaixo. Os 13 que correspondem 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 inclui dois elementos adicionais:

• meta - só 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 aquando da criação - a chave da Bot Talk API acabada de gerar para o novo bot.

Dois campos dentro da estrutura partilhada são só de leitura - devolvidos na resposta, ignorados se tentar enviá-los em 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 diretamente para descarregar os bytes. Para o alterar, carregue um novo ficheiro através da parte multipart avatar (consulte PATCH).
• whiteLabel.whitelabelLogoUrl - URL público completo do logótipo de cabeçalho em white-label. Segue o mesmo padrão que avatarUrl. Para o alterar, carregue um novo ficheiro através da parte multipart whitelabel_logo (consulte PATCH).

Ambos os URLs utilizam o esquema + anfitrião + caminho de contexto do pedido atual; portanto, num domínio personalizado em white-label, surgem com a raiz desse domínio (por exemplo, https://api.acme.com/aichat/content/...).

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

Construção de funções e de prompts

O prompt de sistema que o LLM recebe é construído de uma de duas formas, consoante role.role. Saber em que fluxo se encontra permite perceber quais os campos relevantes e quais os que são guardados mas ignorados.

Fluxo A - role.role é CUSTOMER_SUPPORT, SALES ou LEAD_COLLECTION_AGENT (baseado em modelos)

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

• role.role - identificador da função (por exemplo, "Apoio ao cliente") e instruções específicas da função adicionadas automaticamente
• name - nome do bot, inserido na frase de abertura
• role.language - "Auto Detect" configura o bot para acompanhar o idioma do utilizador; qualquer outro valor (por exemplo, "English", "Polish") traduz-se em "Responder em {idioma}, exceto se o utilizador usar outro idioma"
• role.responseLength - mapeado para uma contagem de palavras pretendida: Concise ≈ 50 palavras, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - opcional; quando preenchido, é adicionado como "para os utilizadores do website {url}"
• role.companyDescription - opcional; quando preenchido, é adicionado como um parágrafo introdutório antes das instruções da função

Este é o fluxo recomendado para a maioria dos bots - obtém comportamento ajustado à função e salvaguardas de segurança incluídas.

Fluxo B - role.role é CUSTOM (prompt fornecido pelo utilizador)

O backend utiliza role.rawPrompt literalmente como a totalidade do prompt de sistema. responseLength, language, websiteAddress e companyDescription são guardados mas não são inseridos no prompt - se pretender que algum deles seja refletido no comportamento do bot, terá de os incluir manualmente no texto de rawPrompt. As salvaguardas de segurança e as instruções de tom específicas de cada função também não são adicionadas; todo o controlo do prompt fica a seu cargo.

Utilize CUSTOM apenas quando o prompt baseado em modelos não se adequar ao seu caso de utilização (por exemplo, se necessitar de uma persona muito específica para o seu setor, das suas próprias regras de segurança ou de um formato de resposta não padrão).

Campos de enumeração / conjunto fechado

Vários campos aceitam apenas um conjunto fixo de valores de texto. O envio de qualquer valor fora da lista é rejeitado com 400 validation_failed e o caminho do campo em error.param. Os valores diferenciam maiúsculas de minúsculas.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - nome completo do idioma em inglês conforme a lista pendente da 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 é guardado literalmente e inserido no modelo de prompt; por conseguinte, códigos ISO de duas letras (en, pl) e outros valores fora da lista não são rejeitados pela API, mas geram instruções incoerentes como "Output in en, unless...". O valor predefinido é Auto Detect quando omitido na criação.
• advanced.model - consulte "Modelos de texto de IA" abaixo; o conjunto disponível depende dos limites da sua conta e qualquer valor que a sua conta não possa utilizar devolve 400 invalid_parameter
• advanced.chatContextSize - 8000, 16000, 32000. Sujeito aos limites da sua conta; valores mais elevados são ajustados silenciosamente para o limite máximo permitido
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - valor booleano. true obriga o utilizador a preencher o formulário de lead antes de iniciar uma conversa; false permite que a IA decida quando apresentar o formulário (predefinição).

Campos estruturados e intervalos

Campos que aparentam ser textos ou números simples, mas que têm estruturas, intervalos ou particularidades da interface de administração que importa conhecer.

• advanced.temperature - o intervalo aceite é de 0.0 a 1.0, correspondendo ao seletor na interface de administração. Valores fora deste intervalo são rejeitados com 400 validation_failed.

• chatMemory.summariesToKnowledgeRatio - percentagem inteira, de 10 a 90 com incrementos de 10. Controla a quantidade de contexto de chat reservada para os resumos históricos do cliente face ao restante conteúdo (base de conhecimento, conversa atual, instruções). Predefinição: 50. Valores fora de 10-90 são rejeitados com 400 validation_failed. Aplica-se apenas quando chatMemory.enabled=true E chatMemory.summaryConversationsEnabled=true.

• liveChat.schedule - JSON codificado como cadeia de carateres (string), e não como um objeto JSON aninhado no envio. O servidor guarda o texto original sem alterações; a interface de administração processa-o no lado do cliente ao compor o editor de horários. Após o processamento, a estrutura contém uma entrada por dia da semana mais a chave timezone:

  • cada chave de dia da semana (monday-sunday) mapeia para {enabled: boolean, from: "H:MM", to: "H:MM"} em formato de 24 horas
  • timezone é um nome de 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 único campo de texto, 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 dos horários indicados, a mensagem liveChat.outOfHoursMessage é apresentada ao visitante e a transferência para o chat em direto é desativada. A validação da estrutura interna ocorre apenas no lado do cliente na interface de administração - JSON malformado ou chaves desconhecidas são aceites pela API como mero texto e surgirão como erro de renderização quando um utilizador abrir mais tarde o bot na administração. Valide a estrutura do seu lado antes de enviar.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - etiquetas curtas apresentadas nos botões 👍 / 👎 junto a cada resposta da IA quando conversation.conversationRatingEnabled=true. O texto predefinido é "I like the response" / "I don't like the response". 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 é guardado 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 0-200. Pausa entre mensagens consecutivas do bot quando simulateHumanTyping=true. Predefinição: 5.

• appearance.autoOpenChatDelaySeconds - segundos, número inteiro. Atraso antes de 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 cerca de 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, entre muitos outros. O envio de um código de apenas duas letras ("en") ou BCP-47 ("en-US") não consta da lista permitida. Predefinição: en_US. Este é o idioma utilizado para a formatação de datas/números na interface do widget, distinguindo-se de role.language (o idioma de conversação do bot).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - números inteiros (enviar como números JSON, por exemplo, 30, e não "30"). 0 desativa o limite de pedidos por IP. Quando diferente de zero, o widget aplica N mensagens por duração em segundos antes de apresentar security.talkMessagesRateLimitHitMessage ao visitante.

• advanced.botMessagesLimit - número inteiro (número JSON, por exemplo, 1000). 0 significa "sem limite"; caso contrário, deve ser um múltiplo de 1000 (1000, 2000, 10000, ...). Valores como 100 ou 1500 são rejeitados com 400 validation_failed. O valor é depois ajustado silenciosamente para o limite da sua conta, se for superior.

Modelos de texto de IA (advanced.model)

Envie o valor exato da API (coluna da esquerda entre acentos graves). O nome de apresentação na interface de administração encontra-se entre parênteses. Os limites da sua conta determinam qual o subconjunto selecionável; o envio de um modelo que a sua conta não possa utilizar devolve 400 invalid_parameter. A predefinição para novos bots é 5-MINI.

• 4-O-MINI (GPT 4-o mini)
• 4-O (GPT 4-o)
• 4.1-MINI (GPT 4.1-mini)
• 4.1 (GPT 4.1)
• 5-MINI (GPT 5-mini)
• 5 (GPT 5)
• 5.1 (GPT 5.1)
• 5.4-MINI (GPT 5.4-mini)
• 5.4 (GPT 5.4)
• 5.5 (GPT 5.5)
• GEMINI 2.5 PRO (Gemini 2.5 Pro)
• GEMINI 3 Flash (Gemini 3 Flash)
• GEMINI 3.5 Flash (Gemini 3.5 Flash)
• GEMINI 3.7 Flash (Gemini 3.7 Flash)
• GEMINI 3.8 Flash (Gemini 3.8 Flash)
• GEMINI 3.1 Flash-Lite (Gemini 3.1 Flash-Lite)
• GEMINI 3 PRO (Gemini 3 Pro)

Referência de campos (esquema completo do pedido)

Todos os campos transmitidos, com o respetivo tipo, restrição e descrição de uma linha. Semântica de PATCH: qualquer campo omitido (ou enviado como null) mantém o valor persistido inalterado. A mesma estrutura é utilizada para a resposta (menos o conteúdo binário multipart; mais o bloco meta de apenas leitura em todas as respostas e apiKey apenas na resposta de criação).

Nível superior

Campo	Tipo	Restrição	Descrição
name	string	máx. 150, obrigatório na criação	Nome de apresentaçã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 do Bot Talk recém-gerada para o novo bot, devolvida exatamente uma vez.

§ role

Campo	Tipo	Restrição	Descrição
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 inserido 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

Campo	Tipo	Restrição	Descrição
welcomeMessage	string		Primeira mensagem apresentada ao visitante ao abrir
queryRefinementEnabled	boolean		Se for true, refina a pergunta do visitante antes da obtenção via RAG
conversationContinuityEnabled	boolean		Se for true, os visitantes que regressam retomam a sua última conversa
conversationRatingEnabled	boolean		Se for true, apresenta a avaliação com polegar para cima/baixo nas mensagens do bot
positiveRatingTooltip	string		Descrição contextual no botão de avaliação positiva
negativeRatingTooltip	string		Descrição contextual no botão de avaliação negativa
suggestedQuestions	string		Perguntas sugeridas / iniciadores de conversa separados por quebra de linha
dynamicSuggestedFollowups	boolean		Se for true, a IA sugere perguntas de seguimento após cada resposta
dynamicFollowupsAutoIcons	boolean		Se for true, a IA escolhe automaticamente ícones de emoji para as perguntas de seguimento dinâmicas

§ chatMemory

Campo	Tipo	Restrição	Descrição
enabled	boolean		Interruptor geral para a funcionalidade de memória de chat
summaryConversationsEnabled	boolean		Persistir resumos por conversa
conversationSummaryPrompt	string		Prompt personalizado utilizado para resumir cada conversa
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	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 predefinido vs. personalizado para o perfil do cliente
summariesToKnowledgeRatio	int	10-90, incremento de 10	% da janela de contexto do chat atribuída a resumos vs. conhecimento RAG

§ appearance

Campo	Tipo	Restrição	Descrição
launcherColor	string (hex)		Cor de fundo do iniciador (ícone do 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		Linha de destaque apresentada por baixo do título do chat
senderPlaceholder	string		Texto de placeholder no campo de introdução da mensagem
resetConversationTooltip	string		Descrição contextual no botão "repor conversa"
chatAlignment	string (enum)	∈ {left, right}	Lado do ecrã ao qual o chat se fixa
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 processado injetado no iframe do widget
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Como as hiperligações dentro das mensagens do bot abrem
minimizedDisplayMode	string (enum)	∈ {icon, minified}	Estado minimizado: ícone de iniciador ou barra compacta de envio
chatDesktopWidthPx	int		Largura do widget em computadores
chatDesktopHeightPx	int		Altura do widget em computadores
chatMobileSizePercent	int		Tamanho do widget em dispositivos móveis em % da área 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 em computadores
showChatbotBubblesMobile	boolean		Apresentar os balões flutuantes de chamada de atenção em telemóveis
chatbotBubblesDelaySeconds	int		Atraso antes de os balões de chamada de atenção surgirem (segundos)
launcherIconFullSize	boolean		Apresentar o ícone personalizado de iniciador de ponta a ponta em vez de encaixado
welcomeScreenEnabled	boolean		Apresentar o ecrã de boas-vindas em vez de ir diretamente para o chat
welcomeScreenQuestionsLabel	string		Rótulo 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 ecrã de boas-vindas estiver visível. Reaparece 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 Live Chat no cabeçalho enquanto o ecrã de boas-vindas estiver visível. Reaparece após a primeira mensagem do visitante. Nos bots criados antes de 2026-09-02 a predefinição é true
headerActionsLayout	string	DROPDOWN	Como o Live Chat e o formulário de contacto humano são disponibilizados no cabeçalho do chat: ICONS (um ícone individual para cada) 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 dos chips de perguntas sugeridas (px)
suggestedQuestionsTextColor	string (hex)		Cor do texto dos chips de perguntas sugeridas
suggestedQuestionsBackgroundColor	string (hex)		Cor de fundo dos chips de perguntas sugeridas
autoOpenChat	boolean		Abrir automaticamente o chat em computadores
autoOpenChatOnMobiles	boolean		Abrir automaticamente o chat em telemóveis
autoOpenChatDelay	boolean		Utilizar um atraso antes de abrir automaticamente
autoOpenChatDelaySeconds	int		Atraso da 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	máx. 255	Markdown de rodapé personalizado apresentado por baixo do chat
avatarUrl	string	apenas leitura	URL público totalmente qualificado do avatar; para o alterar, carregue através da parte multipart avatar

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

§ humanSupport

Campo	Tipo	Restrição	Descrição
enabled	boolean		Interruptor do fluxo de Human Support (Apoio Humano)
email	string	obrigatório (create-strict) quando enabled=true	Endereço que recebe os e-mails de apoio 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 agente
emailMessageContentTemplate	string		Modelo de corpo para o e-mail enviado ao agente
emailPlaceholder	string		Placeholder no campo de e-mail
messagePlaceholder	string		Placeholder na área 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. null mantém o formulário integrado
customFormMapping	string	string com codificação JSON	Mapeia os campos do formulário personalizado nos campos de e-mail de apoio humano

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

§ leadCollection

Campo	Tipo	Restrição	Descrição
enabled	boolean		Interruptor do formulário de recolha de leads
nameEnabled	boolean		Recolher nome
nameLabel	string		Rótulo no campo de introdução do nome
emailEnabled	boolean		Recolher e-mail
emailLabel	string	obrigatório (create-strict) quando enabled=true E emailEnabled=true	Rótulo no campo de introdução do e-mail
phoneEnabled	boolean		Recolher telefone
phoneLabel	string	obrigatório (create-strict) quando enabled=true E phoneEnabled=true	Rótulo no campo de introdução do telefone
leaveDetailsMessage	string	obrigatório (create-strict) quando enabled=true	Mensagem a incentivar o visitante a deixar os seus dados
thankYouMessage	string	obrigatório (create-strict) 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 iniciar; se for false, a IA decide quando exibir o formulário
emailNotificationEnabled	boolean		Enviar um e-mail ao proprietário sempre que uma lead for recolhida
emailNotificationAddress	string		Destinatário da notificação (o padrão é o e-mail da conta)
emailWithConversationContent	boolean		Se for true, inclui a transcrição da conversa na notificação

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

| customFormId | long | id de um formulário personalizado existente | Substitui o formulário de leads integrado por um formulário personalizado. null mantém o formulário integrado | | customFormMapping | string | string com codificação JSON | Mapeia os campos do formulário personalizado em nome / e-mail / telefone |

§ liveChat

Campo	Tipo	Restrição	Descrição
enabled	boolean		Interruptor da funcionalidade Live Chat
infoMessage	string		Mensagem explicativa antes da transferência
startMessage	string		Mensagem apresentada quando a sessão de chat em direto tem início
endMessage	string		Mensagem apresentada quando a sessão de chat em direto termina
nameLabel	string		Rótulo no campo de nome no pré-formulário de Live Chat
emailLabel	string		Rótulo no campo de e-mail no pré-formulário de Live Chat
schedule	string	string com codificação JSON (seletores de dias de semana + from/to + timezone)	Horário de funcionamento do Live Chat - 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 "fechar live chat?"
closeModalConfirmLabel	string		Rótulo do botão de confirmação na janela modal de encerramento
closeModalCancelLabel	string		Rótulo do botão de cancelamento na janela modal de encerramento
closeModalTooltipText	string		Descrição contextual no elemento de encerramento do chat
operatorHasJoinedLabel	string		Rótulo apresentado quando um operador entra
operatorDidNotJoinInTimeLabel	string		Rótulo apresentado quando nenhum operador entra dentro do limite de tempo
waitingForOperatorToJoinLabel	string		Rótulo apresentado enquanto se aguarda por um operador
waitingForOperatorSeconds	int		Tempo limite para um operador atender (segundos)
redirectToHumanSupportForm	boolean		Se for true, reencaminha para o formulário de Human Support quando nenhum operador atender
missedEmailEnabled	boolean	predefinição true	Enviar um e-mail ao proprietário do bot quando um pedido de Live Chat não for atendido. Não definido em bots antigos, o que é interpretado como ativado

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

§ consent

Campo	Tipo	Restrição	Descrição
newConversationRequirePolicyAccept	boolean		Exigir consentimento da política de privacidade antes de iniciar uma nova conversa
humanSupportRequirePolicyAccept	boolean		Exigir consentimento da política de privacidade antes de enviar o formulário de apoio humano
leadCollectionRequirePolicyAccept	boolean		Exigir consentimento da política de privacidade antes de enviar o formulário de recolha de leads
liveChatRequirePolicyAccept	boolean		Exigir consentimento da política de privacidade antes de iniciar uma sessão de Live Chat
newConversationConsentDescription	string		Texto introdutório para o ecrã de consentimento no início da conversa
privacyPolicyConsentCheckboxLabel	string		Rótulo junto à caixa de seleção de consentimento (normalmente contém uma hiperligação para a política de privacidade)

§ whiteLabel

Campo	Tipo	Restrição	Descrição
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 no rodapé encaminha
assignToCustomDomain	boolean	restrito pela funcionalidade CUSTOM_DOMAIN	Alojar o chat no domínio personalizado configurado
whitelabelLogoUrl	string	apenas leitura	URL público totalmente qualificado do logótipo white label; para o alterar, carregue através da parte multipart whitelabel_logo

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

§ security

Campo	Tipo	Restrição	Descrição
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 nas mensagens recebidas
countryFilterMode	string	BLACKLIST ou WHITELIST	Forma como as listas de países são interpretadas. As listas em si permanecem restritas 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 de limite de taxa (segundos)
talkMessagesRateLimitHitMessage	string		Mensagem apresentada ao visitante quando o limite de taxa é atingido

§ voice

Campo	Tipo	Restrição	Descrição
inputEnabled	boolean		Permitir que o visitante dite mensagens (voz para texto)
conversationEnabled	boolean	requer a funcionalidade de voz no plano	Ativar conversas de voz completas
voiceId	string	id de voz específico do fornecedor (ex.: alloy)	Qual a voz sintética utilizada
model	string	ex.: GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Modelo de voz. Faturado ao minuto, os preços diferem consoante o modelo
turnDetection	string	específico do fornecedor	Modo de alternância de turnos na fala
audioPrompt	string		Prompt de sistema adicional utilizado apenas para os turnos de voz
welcomeMessage	string		Frase de abertura falada
language	string	código de idioma	Idioma principal da voz
additionalLanguages	string	códigos de idioma separados por vírgulas	Idiomas adicionais que o agente de voz aceita
maxDurationSeconds	int		Limite máximo rígido para uma única conversa de voz
maxDurationMessage	string		Mensagem apresentada quando o limite máximo é atingido

§ multilingual

Campo	Tipo	Restrição	Descrição
enabled	boolean		Interruptor do modo multilingue
mode	string	AUTODETECT ou um modo de lista fixa	Como o bot seleciona o idioma de resposta
baseLanguage	string	código de idioma	Idioma no qual os textos do próprio bot foram criados
languages	string	códigos de idioma separados por vírgulas	Idiomas disponibilizados ao visitante
knowledgeLanguageMode	string		Como o conhecimento noutros idiomas é processado
knowledgeLanguageFallback	string	código de idioma	Idioma utilizado quando não for encontrada correspondência

§ advanced

Campo	Tipo	Restrição	Descrição
model	string	sujeito aos limites da conta; consulte "AI text models" acima	Identificador do LLM (ex.: 5-MINI)
temperature	decimal	0.0-1.0	Temperatura de amostragem (corresponde ao cursor da interface)
chatContextSize	int	∈ {8000, 16000, 32000}; ajustado automaticamente ao limite da sua conta	Janela de tokens para o histórico do chat
botMessagesLimit	long	0 ou múltiplo de 1000 (ex.: 1000, 2000, 10000)	Máximo de respostas do bot por conversa (0 = sem limite)
internalLocale	string	código de locale no formato ll_CC	Região (locale) para os rótulos de interface do widget (distinto de role.language)
productsViewEnabled	boolean		Se for true, apresenta os Offer Cards (Cartões de Oferta) 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:

• Separador Flow (Fluxo) - o editor visual de Conversation Flow (etapas e transições). Não exposto através da Management API.
• Separador Actions (Ações) - 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. No entanto, é possível associar um formulário existente a um bot através de leadCollection.customFormId e humanSupport.customFormId.
• Ícones personalizados de abertura / fecho do chat - customLauncherIconVisible, openChatIcon, closeChatIcon. A API expõe apenas as partes multipart principais avatar e whitelabel_logo.
• Listas de IP e de países - as entradas em si são exclusivas para 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 o 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 do avatar do bot
• Parte de ficheiro whitelabel_logo (opcional) - logótipo de white-label (aplica-se apenas se a sua conta incluir white-label)

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

Corpo do pedido completo

Este é o JSON data máximo - com todas as secções preenchidas. Envie apenas as secções relevantes; tudo o resto assume os 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-MINI",
    "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áx. 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áx. 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 verdadeiro; o canal ativo também exige a respetiva etiqueta, além de leaveDetailsMessage e thankYouMessage
• Os campos com limite (advanced.chatContextSize, advanced.botMessagesLimit, etc.) são ajustados silenciosamente aos limites da sua conta

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

Corpo da resposta completo (201)

A mesma estrutura do pedido, acrescida do bloco apenas de leitura meta e da apiKey de utilização única no nível raiz. Os URLs de ficheiros apenas de leitura (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) são preenchidos pelo servidor quando as partes multipart correspondentes foram 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-MINI",
    "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 na criação - é a chave recém-gerada da Bot Talk API 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 (o mais direto):

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_..."

Corpo da resposta completo (200)

A mesma estrutura da resposta do POST, com exceção da apiKey de utilização única. O bloco meta está incluído. Devolve o erro 404 not_found_error se o bot não existir ou não pertencer à sua conta.

O avatar e o logótipo de white-label atuais são apresentados como URLs totalmente qualificados apenas de leitura (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - com origem 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 do 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-MINI",
    "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 o mesmo formato; deste modo, clonar é um processo em três passos: executar o GET do bot de origem, remover os campos de identidade geridos pelo servidor e enviar o resultado via POST.

1. Executar o GET do bot de origem.

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 seja distinguível da origem.

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

3. Enviar o corpo limpo via POST para criar o clone. Consulte a referência de POST /v1/management/bots acima para conhecer 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-gerada (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 poderá ser recuperado mais tarde.

Duas advertências:

• Os ficheiros não são clonados. Os campos appearance.avatarUrl e whiteLabel.whitelabelLogoUrl são apenas de leitura e apontam para os ficheiros do bot de origem. Se necessitar do mesmo avatar ou logótipo white-label no clone, descarregue os bytes a partir dos URL 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 apiKey individual devolvida pelo POST de criação é a única gerada automaticamente; crie chaves adicionais a partir do separador API do bot, se necessário.

PATCH /v1/management/bots/{bot_id}

Atualize um ou mais campos num bot que lhe pertença. Apenas as secções / campos presentes no JSON são modificados; tudo o que for omitido (ou enviado como null) permanece inalterado. Aplicam-se regras 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 quando se atualizam apenas definições):

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

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

• parte JSON data (opcional) - o patch. Envie apenas se pretender alterar campos. Omita completamente se pretender apenas carregar um avatar ou logótipo.
• parte de ficheiro avatar (opcional) - substitui o avatar
• parte de ficheiro whitelabel_logo (opcional) - substitui o logótipo white-label (aplica-se apenas se a sua conta incluir white-label)

As três partes são opcionais no PATCH, mas pelo menos uma tem de estar presente para a chamada ser válida.

Corpo do pedido completo (superfície máxima)

Qualquer campo aceite por POST /v1/management/bots também pode ser enviado aqui. O exemplo abaixo representa a superfície completa; 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) mantém o valor guardado 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

Aplique o PATCH a um único campo 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 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 de 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)

Mesmo formato 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 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 de Corpo do pedido completo (superfície máxima) acima ao bot do exemplo de GET - os campos alterados refletem os novos valores, os campos intactos são preservados e meta.updatedAt avança.

{
  "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": "standard",
  "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 (por exemplo, standard no exemplo). 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 cadeia de carateres opaca e não como um enum fixo.
• messages.used / limit / remaining são os créditos de mensagens do período de faturação atual.
• bots.used / limit / remaining contabilizam os bots ativos em relação ao limite de bots da sua conta.

Cabeçalhos de rate limit

As respostas que alcançam a fase de rate limit (ou seja, quando a autenticação e a lista de permissões de IP são validadas com sucesso) 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 logo após esta chamada.
• X-RateLimit-Reset - segundos do epoch Unix em que o próximo token fica disponível (não representa uma reposição total do balde; o balde volta a encher continuamente). Quando o balde estiver cheio, corresponde à hora atual.

Em 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.

Erros 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 terem sido concluídas com sucesso.

Formato de erro

O mesmo envelope da 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 acrescentam o caminho do campo em falha no início da mensagem, para que a secção em causa seja fácil de identificar:

{
  "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 enum / conjuntos fechados (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 a Bot Talk API.