# Agilize Docs para IA - Página atual

Este arquivo contém uma versão focada e legível por IA da página aberta na documentação pública da Agilize.
Use esta versão quando a pergunta do usuário estiver restrita ao documento atual.

Última geração: 2026-09-15T03:39:32.217Z

## Página

- Título: Carregar Entidade Vinculada
- URL humana: https://agilize.app/docs/configuracao/referencias/nodes-fluxos-do-bot/carregar-entidade-vinculada
- Leitura completa para IA: https://agilize.app/docs/llms.txt
- Descrição: Carrega no contexto os dados permitidos de uma entidade vinculada à conversa.

## Seções

- Quando usar
- Campos de configuração
- Entradas e saídas
- Exemplo prático
- Onde configurar
- Variável criada pelo node
- Dados disponíveis
- Como o carregamento funciona

## Conteúdo da página

# Carregar Entidade Vinculada

Carrega no contexto os dados permitidos de uma entidade vinculada à conversa. Este node deve ser usado dentro de fluxos do bot, sempre conectado a uma jornada com objetivo claro, rota esperada e tratamento para exceções.

## Quando usar

- Use quando mensagens, condições, cadastros ou integrações precisam acessar dados de uma oportunidade, contato ou empresa vinculada à conversa.
- Use antes do primeiro node que referencia campos como nome, telefone, etapa, temperatura, site ou dados personalizados da entidade.

## Campos de configuração

- **Entidade vinculada**: escolha Oportunidade, Contato ou Empresa para definir qual registro será carregado nas variáveis do fluxo.

## Entradas e saídas

- Entradas: recebe 1 entrada.
- Saídas: possui 2 saídas.
- Entidade carregada: o registro foi encontrado ou seus dados já estavam disponíveis nas variáveis desta conversa.
- Entidade indisponível: a conversa não possui o vínculo selecionado ou o registro não pôde ser encontrado.

## Exemplo prático

Carregue a oportunidade vinculada e use `{{lead.name}}`, `{{lead.score}}` ou um campo personalizado em uma mensagem, condição ou integração posterior.

## Onde configurar

Acesse :ScreenEntry{href="https://my.agilize.app/messenger/bot/flow/create" label="Criar fluxo do bot" path="Mensageria > Configurações > Bots / Fluxos Automáticos"}. No editor, localize **Carregar Entidade Vinculada** no grupo **Dados e integrações**, arraste o node para o canvas e escolha a entidade.

## Variável criada pelo node

O registro é disponibilizado em uma variável com nome fixo, conforme a entidade selecionada:

| Entidade | Variável base | Exemplos de uso |
| --- | --- | --- |
| Oportunidade | `{{lead}}` | `{{lead.name}}`, `{{lead.score}}`, `{{lead.stage}}` |
| Contato | `{{contact}}` | `{{contact.name}}`, `{{contact.phones.0.phone}}`, `{{contact.emails.0.email}}` |
| Empresa | `{{company}}` | `{{company.name}}`, `{{company.website}}`, `{{company._.segmento}}` |

Use os caminhos nos nodes seguintes do fluxo. O seletor de variáveis também apresenta os campos carregáveis de oportunidade, contato e empresa.

## Dados disponíveis

O node carrega apenas os campos previstos para automações, reduzindo o volume mantido no contexto da conversa.

| Disponibilidade | Campos |
| --- | --- |
| Todas as entidades | ID, nome, telefones, e-mails, redes sociais, observação, responsável, criador, tags, campos personalizados, data de criação e origem do registro. |
| Somente oportunidade | Etapa, funil, origem da oportunidade, motivo de arquivamento, ticket, temperatura, previsão de fechamento, dados UTM e identificadores de clique. |
| Somente empresa | Site. |

Campos personalizados ficam dentro de `_`. Por exemplo, um campo com a chave `segmento` pode ser usado como `{{company._.segmento}}`. Campos de relacionamento, como `user`, `stage` e `funnel`, representam o identificador do registro relacionado.

## Como o carregamento funciona

---
title: "Carregamento sob demanda da entidade"
caption: "A consulta ao CRM só acontece quando os dados ainda não estão disponíveis ou quando o vínculo da conversa mudou."
definition: |
  flowchart LR
    A[Fluxo chega ao node] --> B{A conversa possui o vínculo?}
    B -->|Não| F[Entidade indisponível]
    B -->|Sim| C{Mesmo registro já carregado?}
    C -->|Sim| D[Reutilizar variável]
    C -->|Não| E[Consultar registro e salvar na variável]
    D --> G[Entidade carregada]
    E --> G
---

O carregamento é feito somente nos fluxos que possuem este node. Depois da primeira consulta, os próximos usos do mesmo vínculo reaproveitam a variável da conversa. Se o vínculo mudar, o node busca o novo registro e substitui o valor correspondente.

Este node não cria, atualiza ou vincula registros. Quando o fluxo precisar apenas decidir se o vínculo existe, sem usar seus campos, prefira **Verificar Vínculo com Entidade**.

## Boas práticas e riscos comuns

- Posicione o node antes do primeiro uso dos dados da entidade em mensagens, condições, cadastros ou integrações.
- Conecte também a saída **Entidade indisponível** para tratar conversas sem vínculo ou registros que não estejam mais disponíveis.
- O node reutiliza o registro já carregado enquanto o vínculo for o mesmo; alterações posteriores nesse registro podem não aparecer imediatamente no mesmo contexto do fluxo.
- Os campos de relacionamento, como responsável, etapa e funil, ficam disponíveis como identificadores e não como o cadastro completo relacionado.
- Use caminhos como lead.name, contact.phones.0.phone ou company._.campo.
- Posicione este node antes do primeiro uso dos dados da entidade.

## Como testar

- Teste uma conversa com a entidade selecionada vinculada e confirme a saída **Entidade carregada**.
- Use uma variável carregada em um node posterior e confirme o valor esperado, inclusive para um campo personalizado quando aplicável.
- Teste outra conversa sem o vínculo e confirme a saída **Entidade indisponível**.
- Troque o vínculo da conversa por outro registro do mesmo tipo e confirme que o fluxo passa a usar os dados do novo registro.

## Guias relacionados

- [Verificar Vínculo com Entidade](/docs/configuracao/referencias/nodes-fluxos-do-bot/verificar-vinculo-com-entidade)
- [Fluxos por Variável](/docs/configuracao/referencias/nodes-fluxos-do-bot/fluxos-por-variavel)
- [Mensagem Texto de Variáveis](/docs/configuracao/referencias/nodes-fluxos-do-bot/mensagem-texto-de-variaveis)
- [Gerar Entidade](/docs/configuracao/referencias/nodes-fluxos-do-bot/gerar-entidade)
- [Nodes de fluxos do bot](/docs/configuracao/referencias/nodes-fluxos-do-bot)
- [Guia geral de fluxos do bot](/docs/configuracao/fluxos-automacoes/guia-geral-de-fluxos-do-bot)
- [Fluxos do bot](/docs/configuracao/fluxos-automacoes/fluxos-do-bot)