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 Criar fluxo do bot. 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
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.