Temas e personalização no ChatKit

Depois de seguir o guia de início rápido do ChatKit, veja como alterar o tema e personalizar o chat incorporado ao seu aplicativo. Para combinar o chat com o visual do aplicativo, escolha um tema claro ou escuro, defina uma cor de destaque, ajuste a densidade e arredonde os cantos.

Visão geral

Para personalizar o tema, passe um objeto de opções. Se você seguiu o guia de início rápido do ChatKit para incorporar o ChatKit ao frontend, use a sintaxe do React indicada a seguir.

• React — passe as opções para useChatKit({...}).
• Integrações avançadas — defina as opções com chatkit.setOptions({...}).

O objeto de opções tem a mesma estrutura nos dois tipos de integração.

Explore as opções de personalização

Acesse o ChatKit Studio para ver implementações do ChatKit em funcionamento e explorar ferramentas interativas de criação. Se você prefere aprender experimentando, esses recursos são um bom ponto de partida.

Explore a interface do ChatKit

Veja exemplos em funcionamento

Altere o tema

Defina as cores, a tipografia e outros elementos para que o chat combine com o visual do seu produto. No exemplo a seguir, ativamos o modo escuro, alteramos as cores, arredondamos os cantos, ajustamos a densidade das informações e definimos a fonte.

Para ver todas as opções de tema, consulte a referência da API.

1
2
3
4
5
6
7
8
9
10
11
12
13
14const options = {
  theme: {
    colorScheme: "dark",
    color: {
      accent: {
        primary: "#2D8CFF",
        level: 2,
      },
    },
    radius: "round",
    density: "compact",
    typography: { fontFamily: "'Inter', sans-serif" },
  },
};

Personalize o texto da tela inicial

Altere o texto que aparece no campo de mensagem vazio para sugerir perguntas ou orientar o usuário ao escrever a primeira mensagem.

1
2
3
4
5
6
7
8const options = {
  composer: {
    placeholder: "Ask anything about your data…",
  },
  startScreen: {
    greeting: "Welcome to FeedbackBot!",
  },
};

Exiba prompts iniciais em novas conversas

Sugira prompts no início de cada conversa para orientar os usuários sobre o que perguntar ou fazer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17const options = {
  startScreen: {
    greeting: "What can I help you build today?",
    prompts: [
      {
        name: "Check on the status of a ticket",
        prompt: "Can you help me check on the status of a ticket?",
        icon: "search",
      },
      {
        name: "Create Ticket",
        prompt: "Can you help me create a new support ticket?",
        icon: "write",
      },
    ],
  },
};

Adicione botões personalizados ao cabeçalho

Use botões personalizados no cabeçalho para oferecer opções de navegação, fornecer contexto ou disponibilizar ações relevantes para a sua integração.

1
2
3
4
5
6
7
8
9
10
11
12const options = {
  header: {
    customButtonLeft: {
      icon: "settings-cog",
      onClick: () => openProfileSettings(),
    },
    customButtonRight: {
      icon: "home",
      onClick: () => openHomePage(),
    },
  },
};

Habilite os anexos de arquivos

Por padrão, os anexos estão desabilitados. Para habilitá-los, adicione a configuração de anexos. Se você não estiver usando um backend personalizado, deverá usar a estratégia de upload hosted. Consulte a documentação do SDK para Python para saber como as outras estratégias de upload funcionam com um backend personalizado.

Você também pode controlar a quantidade, o tamanho e os tipos de arquivo que os usuários podem anexar às mensagens.

1
2
3
4
5
6
7
8
9
10const options = {
  composer: {
    attachments: {
      uploadStrategy: { type: "hosted" },
      maxSize: 20 * 1024 * 1024, // 20 MB per file
      maxCount: 3,
      accept: { "application/pdf": [".pdf"], "image/*": [".png", ".jpg"] },
    },
  },
};

Habilite menções com @ no campo de mensagem usando tags de entidade

Permita que os usuários marquem “entidades” personalizadas com menções usando @. Isso dá mais contexto à conversa e amplia as possibilidades de interação.

• Use onTagSearch para retornar uma lista de entidades com base na consulta digitada.
• Use onClick para tratar o evento de clique em uma entidade.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24const options = {
  entities: {
    async onTagSearch(query) {
      void query;
      return [
        {
          id: "user_123",
          title: "Jane Doe",
          group: "People",
          interactive: true,
        },
        {
          id: "document_123",
          title: "Quarterly Plan",
          group: "Documents",
          interactive: true,
        },
      ];
    },
    onClick: (entity) => {
      navigateToEntity(entity.id);
    },
  },
};

Personalize a exibição das tags de entidade

Use widgets para personalizar o que aparece quando o usuário passa o cursor sobre uma tag de entidade. Você pode exibir prévias detalhadas, como um cartão de visita, o resumo de um documento ou uma imagem.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16const options = {
  entities: {
    async onTagSearch() {
      return [];
    },
    onRequestPreview: async (entity) => ({
      preview: {
        type: "Card",
        children: [
          { type: "Text", value: `Profile: ${entity.title}` },
          { type: "Text", value: "Role: Developer" },
        ],
      },
    }),
  },
};

Adicione ferramentas personalizadas ao campo de mensagem

Para aumentar a produtividade, permita que os usuários acionem ações específicas do aplicativo pela barra do campo de mensagem. O modelo receberá a ferramenta selecionada como preferência de ferramenta.

1
2
3
4
5
6
7
8
9
10
11
12const options = {
  composer: {
    tools: [
      {
        id: "add-note",
        label: "Add Note",
        icon: "write",
        pinned: true,
      },
    ],
  },
};

Ative ou desative áreas e recursos da interface

Se você precisar personalizar o cabeçalho além do que as opções disponíveis permitem e quiser implementar suas próprias opções, desative as principais áreas e recursos da interface. Pode ser útil desativar o histórico quando organizar as mensagens em conversas e manter um histórico não fizer sentido para o seu caso de uso, como em um chatbot de suporte.

1
2
3
4const options = {
  history: { enabled: false },
  header: { enabled: false },
};

Substitua a configuração regional

Se o aplicativo tiver uma configuração global de idioma, use-a para substituir a configuração regional padrão. Por padrão, o ChatKit usa a configuração regional do navegador.

1
2
3const options = {
  locale: "de-DE",
};