Notas Internas

Uma Nota interna é uma mensagem de texto que a equipe coloca na linha do tempo de uma conversa sem responder ao cliente e sem entregar o conteúdo à IA. Ela é útil para resumir uma decisão, deixar contexto para o próximo atendente ou registrar um próximo passo humano.

Nota interna não é Anotação

O SquadOS também chama de Anotações a memória estruturada de chave/valor do contato ou da conversa. A ferramenta nativa Anotações (manage_notes) permite que a IA leia e altere essa memória. Os dois recursos têm escopos e destinatários diferentes; não use um nome como sinônimo do outro.

O que acontece quando você adiciona uma nota interna

A nota:

• aparece em ordem cronológica entre as mensagens da conversa;
• mostra que Só sua equipe vê, além do autor e do horário;
• aceita de 1 a 4.000 caracteres depois de remover espaços nas extremidades;
• fica fora da tabela de mensagens, do contexto da IA e das entregas do canal;
• não responde ao cliente, não muda a vez da resposta, não altera o responsável, o SLA, o estado da conversa ou a configuração da IA;
• não gera cobrança de mensagem ou execução de agente.

As alterações chegam em tempo real para integrantes autorizados que estiverem com a conversa aberta.

Adicionar uma nota

1. Abra Conversas e selecione a conversa.
2. No compositor, troque Responder por Nota interna.
3. Escreva a observação. A moldura de aviso, o cadeado e o texto Só sua equipe vê confirmam o modo privado.
4. Clique em Adicionar nota.

O texto entra na linha do tempo; ele não é enviado ao cliente. Se a conversa não puder receber uma resposta — por exemplo, porque está com a IA, concluída, adiada, fora da janela do WhatsApp ou é uma conversa interna — o compositor pode abrir diretamente em Nota interna, com Responder desabilitado.

Uma nota interna não assume a conversa nem reabre uma conversa concluída. Para mudar o fluxo de atendimento, use as ações descritas em Estados de Conversa e Intervenção Humana.

Editar ou excluir

Na própria nota, use Editar nota interna ou Excluir nota interna:

• o autor pode editar ou excluir a própria nota;
• administradores podem gerenciar notas de outras pessoas;
• outros atendentes com acesso à conversa podem ler a nota, mas não recebem essas ações;
• uma edição preserva o horário original e acrescenta o indicador Editada;
• a exclusão remove o conteúdo da linha do tempo depois da confirmação.

Criar, editar e excluir geram eventos operacionais. A aba Contexto → Atividade preserva o fato e o autor da operação, mas não mantém uma cópia do texto excluído.

Quem pode ver e escrever

No fluxo normal, o acesso exige uma sessão autenticada, papel de Atendente ou superior e acesso à caixa de entrada da conversa. Superadmins também são autorizados pelo backend.

Pessoa ou sistema	Lê o texto da nota interna?	Pode criar?
Cliente no WhatsApp, chat público, widget ou outro canal	Não	Não
Agente de IA	Não	Não
Atendente com acesso à caixa	Sim	Sim
Administrador com acesso à organização	Sim	Sim

O conteúdo fica associado somente à conversa em que foi escrito. Ele não acompanha o contato para outro atendimento.

Arquivar não é controle de acesso

Uma conversa arquivada desaparece das listas, mas o produto atual ainda permite abrir sua URL direta e executar ações. Não use o arquivamento para proteger uma nota sensível.

Eventos de webhook

O catálogo oferece conversation.internal_note_created, conversation.internal_note_updated e conversation.internal_note_deleted. Eles não entram na seleção em massa porque a interface os classifica como conteúdo interno.

No emissor atual, porém, o payload operacional contém o tipo do evento e note_id, não o corpo da nota. Portanto, não trate esses webhooks como exportação, backup ou sincronização do texto. Essa divergência entre a interface e o payload está registrada no dossiê de bugs. Consulte Webhooks de Eventos para o contrato geral de entrega.

Não confunda com Anotações

	Nota interna	Anotações
Formato	Texto livre de até 4.000 caracteres	Objeto JSON de chave/valor
Quem grava	Integrante da equipe	IA pela ferramenta Anotações; a equipe também pode ajustar no painel
Onde aparece	Linha do tempo da conversa	Contexto → Contato, no card Anotações
Escopo	Somente a conversa	Contato nos canais externos; conversa no Hub sem contato externo
A IA recebe?	Nunca pelo fluxo de conversa	Sim, quando chama manage_notes
Uso recomendado	Coordenação e registro humano	Fatos estruturados que a IA precisa reutilizar

Para habilitar a memória da IA, abra o agente, entre em Ferramentas e adicione Anotações. É uma ferramenta única e sem configuração extra: action: "read" lê uma chave ou o objeto completo; action: "write" cria, atualiza ou exclui uma chave (value: null exclui).

Em canais ligados a um contato externo, como WhatsApp ou Telegram, as Anotações pertencem ao contato e atravessam conversas. Em conversas internas do Hub, pertencem à conversa atual. Use chaves canônicas em inglês, minúsculas e snake_case; leia as chaves existentes antes de gravar para não criar duplicatas.

Boas práticas

• Comece a nota com a decisão ou ação: Reembolso aprovado; financeiro responde até sexta.
• Registre apenas contexto necessário para a equipe; não copie todo o histórico.
• Não salve senhas, tokens, chaves de API ou outros segredos.
• Use Nota interna para coordenação humana e Anotações para memória estruturada que a IA precisa consultar.
• Depois de um handoff, registre dono e próximo passo; não suponha que a nota altera o responsável ou o estado da conversa.