Helpdesk

Receba pedidos de clientes por um formulário público, por um link ou por um widget no seu site. Cada pedido vira um card no board Helpdesk do projeto. O cliente acompanha o andamento por um link, sem criar conta, e a equipe responde direto pelo card.

Versão em Markdown puro deste guia: https://app.krakendock.com/docs/helpdesk.md?lang=pt-BR. Use-a para colar num assistente de IA ou na documentação interna do seu time.

Visão geral

O fluxo de um chamado:

1. O cliente envia o formulário, com anexos e os campos extras que você escolher.
2. O pedido vira um card na coluna Novo do board Helpdesk, com os dados do solicitante.
3. O cliente recebe um e-mail de confirmação com o link de acompanhamento.
4. A equipe responde pelo card. Cada resposta ao solicitante vai por e-mail e aparece no link de acompanhamento. As notas internas ficam só com a equipe.
5. O cliente pode responder pelo link. Se o chamado estava aguardando o cliente ou já tinha sido resolvido, a resposta reabre o atendimento.

Configurar em 5 minutos

Você precisa da permissão de gerenciar o projeto.

1. Abra o projeto e vá em Configurações → Helpdesk. A opção fica no grupo Integrações.

2. Clique em Novo formulário. Preencha o Nome (uso interno) e o Título da página (o que o cliente vê).

3. Mantenha o formulário Ativo e salve. Ao ativar o primeiro formulário, o KrakenDock cria o board Helpdesk com quatro colunas:

   Coluna	Papel	O cliente vê
   Novo	new	Recebido
   Em atendimento	in_progress	Em atendimento
   Aguardando solicitante	waiting	Aguardando você
   Resolvido	resolved (coluna de concluídos)	Resolvido

4. Na janela que aparece depois de salvar, copie o link público, o iframe ou o botão flutuante (widget). Veja Divulgar o formulário.

5. Faça um pedido de teste. Ele aparece em segundos no board Helpdesk.

Pode renomear as colunas à vontade: cada uma guarda o seu papel. Uma coluna sem papel conta como Resolvido se for de concluídos e como Em atendimento nos outros casos. Os cards não passam do board Helpdesk para os outros boards do projeto, nem o contrário.

Opções do formulário

Cada projeto pode ter vários formulários (por exemplo, "Suporte" e "Financeiro"). Todos entram no mesmo board Helpdesk.

Geral

• Nome: até 80 caracteres, só para a equipe.
• Título da página: até 120 caracteres, aparece no topo do formulário.
• Ativo: um formulário inativo deixa de ser encontrado e não aceita pedidos.
• Tipo do card: Tarefa, Bug ou História.
• Coluna de entrada: por padrão, a coluna Novo.

Textos

• Introdução: até 2.000 caracteres, em Markdown, mostrada acima dos campos. Os links abrem em nova aba.
• Mensagem de sucesso: até 1.000 caracteres, mostrada depois do envio.
• Texto de consentimento: até 1.000 caracteres. Sem texto, vale o padrão: "Concordo que os dados enviados sejam usados para responder a este pedido."
• Consentimento coletado pelo sistema integrado: veja Identidade assinada.

Campos

• Os campos fixos são nome, e-mail, assunto (até 255 caracteres) e descrição (até 20.000 caracteres, em Markdown).
• Telefone do solicitante: Não pedir, Opcional ou Obrigatório. Aceita de 8 a 15 dígitos.
• Campos extras: até 20 campos customizados do projeto, cada um com rótulo, ajuda e a opção de ser obrigatório. Os tipos aceitos são texto, número, data, seleção, seleção múltipla, caixa de seleção e URL. Os campos customizados são criados nas configurações do projeto, em Campos (guia de campos e templates). O plano Free permite 3 por projeto, e os planos pagos, 50.

Anexos

• Permitir anexos: ligado por padrão. O tamanho e a quantidade de arquivos dependem do plano (veja Limites por plano).
• Executáveis, scripts e arquivos vazios são recusados.

Incorporação

• Endereço da página (slug): de 3 a 48 caracteres, com letras minúsculas, números e hífen, sem começar nem terminar com hífen. O slug é único em todo o KrakenDock. Trocar o slug quebra o link antigo.
• Origens permitidas: até 20 sites que podem mostrar o formulário num iframe ou no widget, no formato https://app.suaempresa.com (sem caminho). http só é aceito para localhost, e domínios com acento vão em punycode. Sem nenhuma origem, o formulário só funciona pelo link.

Aparência

• Cor de destaque: #rrggbb, usada em botões, links e foco. As configurações avisam quando a cor tem pouco contraste.
• O logo é o avatar do projeto.

Divulgar o formulário

Link

O jeito mais simples: mande o link por e-mail, coloque num botão do site ou na assinatura.

https://app.krakendock.com/f/SEU-SLUG

Iframe

Mostra o formulário dentro de uma página do seu site. A origem do site precisa estar em Origens permitidas.

<iframe
  id="kraken-form"
  src="https://app.krakendock.com/f/SEU-SLUG?embed=1"
  title="Fale com o suporte"
  style="width:100%;min-height:640px;border:0"
  loading="lazy"
></iframe>

Para combinar com o seu site, acrescente à URL do iframe os parâmetros abaixo. Eles só valem junto com embed=1; valores inválidos são ignorados.

Exemplo: https://app.krakendock.com/f/SEU-SLUG?embed=1&theme=light&lang=pt-BR. Sem eles, o formulário não sabe o tema nem o idioma que o visitante escolheu no Kraken: um iframe em outro site não recebe esses cookies.

O formulário avisa a altura do conteúdo por postMessage. Para o iframe crescer junto e não mostrar barra de rolagem, acrescente:

<script>
  window.addEventListener('message', function (event) {
    var frame = document.getElementById('kraken-form');
    if (event.origin !== 'https://app.krakendock.com' || event.source !== frame.contentWindow) return;
    if (event.data && event.data.type === 'kraken-intake:resize') {
      frame.style.height = event.data.height + 'px';
    }
  });
</script>

Widget (botão flutuante)

Um botão no canto da página abre o formulário num painel no estilo chat. Em telas de até 639 px, o painel ocupa a tela inteira. O painel não bloqueia a página, e o rascunho continua lá se o cliente fechar e abrir de novo. A origem do site precisa estar em Origens permitidas.

<script
  src="https://app.krakendock.com/intake.js"
  data-form="SEU-SLUG"
  data-label="Suporte"
  data-close-label="Fechar"
  data-color="#4f46e5"
  async
></script>

Os textos padrão dos botões são em português. Num site em outro idioma, defina data-label e data-close-label. Para o formulário combinar com o site, use data-theme e data-lang: o painel não recebe os cookies do Kraken, então sem eles segue o tema do sistema operacional e o idioma do navegador do visitante.

API do widget

Depois que o intake.js carrega, a página ganha o objeto window.KrakenIntake:

Exemplo: abrir o suporte a partir de um link do seu menu.

<a href="#" onclick="window.KrakenIntake.open(); return false;">Precisa de ajuda?</a>

A tecla Esc também fecha o painel.

Pré-preenchimento

Sugere valores que o cliente ainda pode editar. Não comprova quem é o usuário (para isso, use a identidade assinada). Funciona em todos os planos.

Pelo widget:

window.KrakenIntake.prefill({
  name: 'Ana Souza',
  email: 'ana@cliente.com',
  phone: '+55 11 91234-5678',
  subject: 'Problema no pedido 1234',
  description: 'Descreva o que aconteceu…',
  fields: { 'ID-DO-CAMPO': 'valor' },
});

• Cada texto aceita até 20.000 caracteres, e fields aceita até 50 campos.
• As chaves de fields são os ids dos campos extras, e cada valor segue o tipo do campo:

• Número, seleção, seleção múltipla e caixa de seleção fora do formato, ids de campo desconhecidos e opções que não existem no campo são ignorados sem aviso.
• Texto, URL e data são usados como vieram: confira o formato antes de enviar. Uma URL sem https:// bloqueia o envio até o cliente corrigir, e uma data fora de AAAA-MM-DD faz o envio falhar.
• Os ids estão na configuração pública do formulário: o id do campo em data.fields[].field_id e os das opções em data.fields[].options[].id.

curl https://app.krakendock.com/api/intake/SEU-SLUG

Pelo link (fragmento #), só os campos fixos:

https://app.krakendock.com/f/SEU-SLUG#name=Ana%20Souza&email=ana%40cliente.com&subject=Pedido%201234

• As chaves aceitas são name, email, phone, subject e description.
• Os valores vão codificados para URL.
• O fragmento é lido uma vez e apagado da barra de endereço. Ele só preenche campos vazios.

Identidade assinada (login do seu sistema)

Quando o cliente já está logado no seu sistema, o widget pode abrir com o nome, o e-mail e o telefone dele preenchidos e travados. Nesse caso o envio:

• não pede captcha;
• marca o chamado como Verificado;
• libera a aba Meus chamados.

A identidade assinada está disponível nos planos Pro e Business.

1. Gere a chave do projeto

Em Configurações → Helpdesk → Integração com seu sistema, clique em Gerar chave.

• A chave começa com khd_ e aparece uma única vez. Guarde-a num cofre de segredos do servidor. Ela nunca pode ir para o navegador.
• Trocar chave invalida a anterior na hora. Remover desliga a identidade assinada.

2. Gere o token no seu servidor

O token é um JWT HS256 assinado com a chave inteira, incluindo o prefixo khd_.

Node (jsonwebtoken):

import jwt from 'jsonwebtoken';

const token = jwt.sign(
  {
    sub: String(user.id),
    name: user.name,
    email: user.email,
    ...(user.phone ? { phone: user.phone } : {}),
  },
  process.env.KRAKEN_IDENTITY_KEY,
  { algorithm: 'HS256', expiresIn: '1h' },
);

PHP (firebase/php-jwt):

use Firebase\JWT\JWT;

$claims = [
    'sub' => (string) $user->id,
    'name' => $user->name,
    'email' => $user->email,
    'exp' => time() + 3600,
];
if ($user->phone) {
    $claims['phone'] = $user->phone;
}

$token = JWT::encode($claims, getenv('KRAKEN_IDENTITY_KEY'), 'HS256');

Python (PyJWT):

import os
from datetime import datetime, timedelta, timezone

import jwt

claims = {
    "sub": str(user.id),
    "name": user.name,
    "email": user.email,
    "exp": datetime.now(timezone.utc) + timedelta(hours=1),
}
if user.phone:
    claims["phone"] = user.phone

token = jwt.encode(claims, os.environ["KRAKEN_IDENTITY_KEY"], algorithm="HS256")

Go (golang-jwt):

import (
	"os"
	"time"

	"github.com/golang-jwt/jwt/v5"
)

claims := jwt.MapClaims{
	"sub":   userID, // string
	"name":  user.Name,
	"email": user.Email,
	"exp":   time.Now().Add(time.Hour).Unix(),
}
if user.Phone != "" {
	claims["phone"] = user.Phone
}

token, err := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).
	SignedString([]byte(os.Getenv("KRAKEN_IDENTITY_KEY")))

3. Entregue o token ao widget

Na página do usuário logado:

<script src="https://app.krakendock.com/intake.js" data-form="SEU-SLUG" data-identity="TOKEN" async></script>

Ou depois que o script carregar (por exemplo, numa aplicação de página única):

window.KrakenIntake.identify(token);
// no logout:
window.KrakenIntake.reset();

No logout, prefira reset() a identify(null): além de esquecer a identidade, ele descarta o rascunho do formulário (assunto, descrição, anexos e campos pré-preenchidos), o pré-preenchimento e a função registrada em onIdentityExpired. Uma renovação de token que ainda esteja em andamento vai até o fim (a função do seu site roda e a requisição acontece), mas o token que ela devolver é descartado. Assim, a próxima pessoa que usar a mesma aba começa com o formulário limpo. O reset() vale para todos os widgets da página, mesmo que haja mais de um formulário. O botão continua na página; depois do reset(), chame identify(token) e prefill(values) de novo para o próximo usuário.

Para renovar o token quando ele expira com o widget aberto, registre uma função que busque um token novo no seu backend:

window.KrakenIntake.onIdentityExpired(async () => {
  const response = await fetch('/kraken-token'); // rota do seu backend que gera o JWT
  if (!response.ok) return null; // sem token: o formulário volta a pedir os dados
  return response.text();
});

• O widget chama essa função no máximo uma vez a cada 50 segundos.
• Sem a função, o formulário volta a pedir os dados e mantém o que já foi digitado.

Regras importantes:

• A identidade só é aceita pelo widget (ou por um iframe, com o protocolo de mensagens), vindo de uma origem permitida.
• #identity= no link é ignorado, para ninguém conseguir mandar um link que abra chamados no nome de outra pessoa.
• Nunca coloque o token na query string.
• Não há proteção contra reuso: o token vale até expirar. Por isso, use validades curtas.
• Com Consentimento coletado pelo sistema integrado ligado no formulário, o usuário identificado não vê a caixa de consentimento. O consentimento fica registrado como coletado pela integração.

Erros da identidade

Uma identidade recusada não trava o formulário: ele volta ao modo normal e registra o motivo no console do navegador, por exemplo [Kraken] Identidade assinada recusada (signature): o formulário segue sem identificação. A API responde 422 INTAKE_IDENTITY_INVALID com o motivo em fields.identity:

Num plano sem a identidade assinada, a resposta é 403 PLAN_FEATURE_REQUIRED.

Pelo widget ou por um iframe, disabled e o 403 não chegam a aparecer. Se o projeto não tem chave, ou se o plano não inclui o recurso, o formulário nem consulta a API: ele só registra no console [Kraken] Identidade assinada ignorada: o formulário não aceita identidade (chave do projeto ausente ou plano sem o recurso). Um token com mais de 4.096 caracteres é descartado pelo intake.js sem aviso.

Meus chamados

Com a identidade assinada, o widget mostra as abas Novo chamado e Meus chamados. Na segunda, o usuário vê os últimos 50 pedidos verificados dele no projeto (do mesmo sub), do mais novo para o mais antigo, e abre cada conversa sem depender do e-mail. Quando é a mesma pessoa, as respostas enviadas por ali não pedem captcha.

O que o cliente vê

Acompanhamento

Depois do envio, o cliente vê o número do pedido e o link de acompanhamento, que também chega por e-mail. A página https://app.krakendock.com/t/… mostra:

• as etapas Recebido → Em atendimento → Aguardando você → Resolvido;
• a conversa: a descrição é a primeira mensagem, e depois vêm as respostas do cliente e as da equipe marcadas para o solicitante;
• uma caixa de resposta, com até 10.000 caracteres e anexos;
• os arquivos e os detalhes do pedido;
• o bloco Seus dados, para baixar ou excluir os dados.

O link de acompanhamento é pessoal: quem tem o link vê o pedido. Ele não é indexado por buscadores.

E-mails ao solicitante

• As respostas do próprio cliente não geram e-mail.
• Enviar e aguardar manda só o e-mail da resposta, sem um segundo e-mail de status.
• Nos planos pagos, os e-mails e as páginas saem sem a marca KrakenDock.

Atender um chamado (equipe)

Abra o card no board Helpdesk.

• Solicitante: mostra nome, e-mail, telefone, o id no seu sistema (com identidade assinada), o formulário, a data de abertura, o consentimento e o selo Verificado. Quem gerencia o projeto também vê as ações Bloquear e-mail, Bloquear IP e Anonimizar solicitante.

• Conversa: o fio com o cliente. Responda em Responder ao solicitante:

  • Enviar manda a resposta por e-mail e a mostra no link de acompanhamento.
  • Enviar e aguardar faz o mesmo e move o card para Aguardando solicitante.
  • Imagens coladas no editor não aparecem para o cliente. Para mandar arquivos, use anexos.

• Botões de status, conforme a coluna em que o card está:

  Status atual	Botões
  Novo	Iniciar atendimento, Resolver
  Em atendimento	Aguardar solicitante, Resolver
  Aguardando solicitante	Retomar atendimento, Resolver
  Resolvido	Reabrir

• Notas internas: os comentários comuns do card são internos (selo Interno) e nunca chegam ao cliente. O Histórico do card mostra as notas internas e a atividade, sem as mensagens da conversa.

• Se o cliente responder enquanto o card está em Aguardando solicitante ou Resolvido, o card volta para Em atendimento sozinho.

• Um card arquivado, ou com comentários travados, não recebe novas respostas do cliente.

Proteção contra abuso

• Captcha (Cloudflare Turnstile): só aparece quando o Cloudflare pede uma interação. Não é pedido para usuários com identidade assinada.
• Campo isca (honeypot): robôs que preenchem campos ocultos são recusados.
• Limites de envio por IP, por e-mail e por link de acompanhamento. Quem passa do limite recebe 429 RATE_LIMITED.
• Bloqueios: em Configurações → Helpdesk → Bloqueios, ou pelo painel do solicitante no card, bloqueie um e-mail ou um IP, com um motivo opcional. O bloqueio vale para todos os formulários do projeto (403 INTAKE_BLOCKED).
• O board Helpdesk é visível só para os membros do projeto, mesmo num projeto público.

LGPD e dados do solicitante

• O formulário pede o consentimento do solicitante (ou o registra como coletado pela integração, se o formulário estiver configurado assim).
• Pelo link de acompanhamento, o próprio solicitante pode:
  • Baixar meus dados: um JSON com os dados pessoais, as mensagens visíveis e a lista de arquivos. As notas internas nunca entram.
  • Excluir meus dados: apaga nome, e-mail, telefone, IP, id externo e a cópia do assunto e da descrição. O link para de funcionar, mas o card continua com a equipe.
• A equipe pode Anonimizar solicitante pelo card, com o mesmo efeito. A ação é irreversível.

Limites por plano

• O uso do mês aparece em Configurações → Helpdesk → Uso do helpdesk.
• Excluir um card não devolve a cota.
• Os anexos também contam no armazenamento da conta.

Veja os planos em https://app.krakendock.com/pricing.

Integrar com outros sistemas

Os webhooks dos cards do Helpdesk não levam nome, e-mail nem IP do solicitante.

Protocolo de mensagens

O widget e o formulário conversam por postMessage. Se você usar um iframe próprio (?embed=1) em vez do widget, pode usar as mesmas mensagens:

Regras do protocolo:

• O formulário só aceita mensagens da janela que o contém (window.parent) e de uma origem permitida.
• Mande as mensagens com targetOrigin igual a https://app.krakendock.com.

var frame = document.getElementById('kraken-form');
window.addEventListener('message', function (event) {
  if (event.origin !== 'https://app.krakendock.com' || event.source !== frame.contentWindow) return;
  if (event.data && event.data.type === 'kraken-intake:ready') {
    frame.contentWindow.postMessage({ type: 'kraken-intake:identity', token: TOKEN }, 'https://app.krakendock.com');
  }
});

Solução de problemas

Ainda com dúvidas? Fale com a gente em https://app.krakendock.com/help.