Bloco Buscar Dados

O que é o Bloco Buscar Dados?

O bloco Buscar Dados permite que o agente consulte informações de forma automática e silenciosa — sem envolver a IA. Ele busca um dado específico (de uma API externa, de um atributo do contato ou da conversa) e armazena o resultado em uma variável, que pode ser usada em seguida por um bloco Condição para tomar decisões.

Configuração do bloco Buscar Dados — Painel de configuração do Bloco Buscar Dados

Por que usar?

Benefício	Descrição
Decisões instantâneas	Sem esperar a IA processar — execução imediata
Sem custo de LLM	Não consome tokens de IA para buscar o dado
Resultados previsíveis	Sempre busca a mesma informação da mesma forma
Integração com Chatwoot	Acessa atributos de contato e conversa diretamente

Como funciona?

Conversa chega → Buscar Dados executa automaticamente
                        ↓
              Consulta a fonte configurada
              (API, atributo de contato ou conversa)
                        ↓
              Armazena o resultado na variável
              (ex: fetched.plano)
                        ↓
              Bloco Condição avalia o valor
              (ex: se fetched.plano = "premium")
                        ↓
              Direciona para o caminho correto
              (verdadeiro ou falso)

O bloco Buscar Dados foi projetado para funcionar em conjunto com o bloco Condição (modo Determinístico). Juntos, eles formam uma cadeia de decisão automática que não depende da IA.

Fontes de Dados

O bloco oferece três fontes de dados diferentes, dependendo de onde a informação está:

1. Atributo do Contato

Busca um campo dos atributos personalizados do contato no Chatwoot. Ideal para identificar características do cliente que já estão cadastradas.

Campo	Descrição	Exemplo
Chave do Atributo	Nome do campo no Chatwoot	`plano`, `segmento`, `cliente_habitue`
Variável de Saída	Onde armazenar o resultado	`fetched.plano`

Exemplo: Plano do cliente
Exemplo: Tipo de parceiro

Configuração:

Fonte: Atributo do Contato
Chave do Atributo: plano
Variável de Saída: fetched.plano

Resultado: Se o contato tem plano = "premium", a variável fetched.plano recebe "premium".Condição seguinte: Se fetched.plano igual a "premium" → caminho VIP.

Configuração:

Fonte: Atributo do Contato
Chave do Atributo: tipo_parceiro
Variável de Saída: fetched.tipo_parceiro

Resultado: Se o contato tem tipo_parceiro = "agencia", o agente pode redirecionar automaticamente.

Os atributos disponíveis são os mesmos que você configura em Chatwoot > Configurações > Atributos Personalizados. Se o atributo não existir no contato, o valor retornado será vazio.

2. Atributo da Conversa

Busca um campo dos atributos personalizados da conversa no Chatwoot. Útil para informações que mudam de conversa para conversa.

Campo	Descrição	Exemplo
Chave do Atributo	Nome do campo na conversa	`status_pagamento`, `origem_campanha`
Variável de Saída	Onde armazenar o resultado	`fetched.status_pagamento`

Exemplo prático:

Fonte: Atributo da Conversa
Chave: status_pagamento
Variável: fetched.status_pagamento

→ Se o valor for "pendente", transfere para equipe financeira
→ Se o valor for "pago", continua atendimento normal

3. API Externa (HTTP)

Consulta uma API externa via HTTP para obter informações em tempo real. Útil para consultar sistemas internos (ERP, CRM, sistema de reservas, etc.).

Campo	Descrição	Exemplo
Método HTTP	GET, POST, PUT, etc.	`GET`
URL Base	Endereço da API	`https://api.exemplo.com`
Endpoint	Caminho do recurso	`/api/v1/clientes/status`
JSONPath	Caminho para extrair o valor	`$.data.status`
Variável de Saída	Onde armazenar o resultado	`fetched.status`

O que é JSONPath?

JSONPath é uma forma de navegar dentro de uma resposta JSON para extrair um valor específico.Exemplo de resposta da API:

{
  "data": {
    "cliente": "João",
    "status": "ativo",
    "plano": "premium"
  }
}

JSONPath	Resultado
`$.data.status`	`"ativo"`
`$.data.plano`	`"premium"`
`$.data.cliente`	`"João"`

Autenticação da API

Se sua API exige autenticação, configure na seção Autenticação:

Tipo	Quando usar
Nenhuma	API pública
API Key	Enviar chave via header
Bearer Token	Token de acesso
Basic Auth	Usuário e senha

A API externa é chamada a cada mensagem que passa pelo bloco. Configure com moderação para não sobrecarregar seus sistemas. Para informações que mudam raramente, prefira atributos de contato.

Variável de Saída

Toda informação buscada é armazenada em uma variável de saída que começa obrigatoriamente com fetched..

Regra	Descrição
Prefixo obrigatório	Toda variável começa com `fetched.`
Nome livre	Após o prefixo, escolha um nome descritivo
Usado na Condição	O bloco Condição referencia esta variável

Exemplos de nomes:

Fonte	Variável	Uso
Contato: `plano`	`fetched.plano`	Verificar plano do cliente
Contato: `cliente_habitue`	`fetched.cliente_habitue`	Identificar cliente VIP
Conversa: `status_pagamento`	`fetched.status_pagamento`	Checar pagamento
API: retorno JSON	`fetched.tem_reserva`	Verificar reserva ativa

Conectando ao Fluxo

O bloco Buscar Dados funciona como parte de uma cadeia de decisão automática:

[Início] → [Buscar Dados] → [Condição Determinística] → [Próximo bloco]
                                       │
                                       ├─ Verdadeiro → [Transferência / Cotação / etc.]
                                       │
                                       └─ Falso → [Roteador / IA responde]

Adicione o bloco Buscar Dados

Arraste o bloco para o canvas e conecte-o ao bloco Início (ou a uma rota do Roteador).

Configure a fonte de dados

Escolha entre API Externa, Atributo do Contato ou Atributo da Conversa. Preencha os campos necessários.

Defina a variável de saída

Escolha um nome descritivo com o prefixo fetched. (ex: fetched.plano).

Conecte ao bloco Condição

Arraste uma conexão da saída do Buscar Dados para um bloco Condição configurado no modo Determinístico.

Configure a condição

No bloco Condição, use a mesma variável (ex: fetched.plano) e defina a regra (ex: igual a “premium”).

O bloco Buscar Dados deve ter apenas uma conexão de entrada e estar conectado diretamente a um bloco Condição (modo Determinístico). Não conecte outros blocos entre eles.

Exemplos por Segmento

Hotel - Cliente VIP
E-commerce - Plano Premium
SaaS - Verificar API

Objetivo: Identificar clientes habitués e transferir automaticamente.Fluxo:

[Início] → [Buscar Dados: cliente_habitue] → [Condição: = true?]
                                                   │
                                                   ├─ Sim → [Transferência: equipe VIP]
                                                   │
                                                   └─ Não → [Roteador: fluxo normal]

Configuração do Buscar Dados:

Fonte: Atributo do Contato
Chave: cliente_habitue
Variável: fetched.cliente_habitue

Configuração da Condição:

Variável: fetched.cliente_habitue
Operador: Igual a
Valor: true

Objetivo: Oferecer atendimento diferenciado para clientes premium.Fluxo:

[Início] → [Buscar Dados: plano] → [Condição: = premium?]
                                          │
                                          ├─ Sim → [Roteador com rotas VIP]
                                          │
                                          └─ Não → [Roteador padrão]

Configuração do Buscar Dados:

Fonte: Atributo do Contato
Chave: plano
Variável: fetched.plano

Configuração da Condição:

Variável: fetched.plano
Operador: Igual a
Valor: premium

Objetivo: Consultar API interna para verificar se o cliente tem assinatura ativa.Fluxo:

[Início] → [Buscar Dados: API status] → [Condição: ativo?]
                                               │
                                               ├─ Sim → [IA responde]
                                               │
                                               └─ Não → [Transferência: vendas]

Configuração do Buscar Dados:

Fonte: API Externa
URL: https://api.meuapp.com/v1/subscription/check
JSONPath: $.data.status
Variável: fetched.status_assinatura

Perguntas Frequentes

O cliente vê alguma mensagem enquanto o dado é buscado?

Não. O bloco Buscar Dados executa de forma totalmente silenciosa. O cliente não percebe que uma consulta foi feita — tudo acontece em milissegundos antes da IA responder.

Posso usar Buscar Dados sem o bloco Condição?

Tecnicamente sim, mas o valor buscado não terá utilidade sem uma condição para avaliá-lo. O bloco foi projetado para funcionar em conjunto com o bloco Condição no modo Determinístico.

O que acontece se o atributo não existir no contato?

A variável de saída recebe um valor vazio. No bloco Condição, você pode usar o operador Está vazio para tratar esse caso.

Qual a diferença entre Buscar Dados e Integração API?

São dois modos do mesmo bloco:

Buscar Dados: Execução automática e silenciosa, sem IA. Armazena resultado em variável para uso em condições.
Integração API (Tool): A IA decide quando chamar a API durante a conversa e usa o resultado para responder ao cliente.

Posso ter vários blocos Buscar Dados no fluxo?

Sim, mas cada cadeia (Buscar Dados → Condição) deve ser independente. Evite encadear múltiplos blocos Buscar Dados em sequência.

Comece Aqui

Treinamento da IA

Operação

Administradores

Relatórios

O que é o Bloco Buscar Dados?

Por que usar?

Como funciona?

Fontes de Dados

1. Atributo do Contato

2. Atributo da Conversa

3. API Externa (HTTP)

Variável de Saída

Conectando ao Fluxo

Exemplos por Segmento

Perguntas Frequentes

Próximos passos

Bloco Condição

Bloco Integração API

​O que é o Bloco Buscar Dados?

​Por que usar?

​Como funciona?

​Fontes de Dados

​1. Atributo do Contato

​2. Atributo da Conversa

​3. API Externa (HTTP)

​Variável de Saída

​Conectando ao Fluxo

​Exemplos por Segmento

​Perguntas Frequentes

​Próximos passos

Bloco Condição

Bloco Integração API

O que é o Bloco Buscar Dados?

Por que usar?

Como funciona?

Fontes de Dados

1. Atributo do Contato

2. Atributo da Conversa

3. API Externa (HTTP)

Variável de Saída

Conectando ao Fluxo

Exemplos por Segmento

Perguntas Frequentes

Próximos passos