Resumo
Este guia explica como os atributos de ação da API REST funcionam na Astra e como são usados em agentes Astra. Atributos funcionam como espaços reservados que armazenam e transferem dados entre instruções e ações.
Você aprenderá os diferentes tipos de atributos, como eles se comportam e como usá-los corretamente ao configurar ações de API REST (Representational State Transfer).
Instruções
O que é um atributo
Na Astra, um atributo é um espaço reservado que armazena um valor. Isso permite que seu agente use dados dinamicamente durante a execução.
Por exemplo, atributos como first name ou last name podem armazenar detalhes do cliente e ser reutilizados em respostas ou ações.
Pontos chave
Atributos funcionam como variáveis dentro do seu agente
Eles podem ser usados em instruções e ações
Em instruções, os atributos são usados principalmente para clareza ou para estruturar entradas e saídas
Atributos de entrada e saída
Os atributos na Astra são categorizados com base em como são usados:
Atributos de entrada
Fornecem dados para uma ação ou etapa
Exemplo: passar um nome de cliente para uma solicitação de API
Atributos de saída
Armazenam resultados retornados de uma ação
Exemplo: salvar um ID de resposta de uma API
Ambos os tipos podem ser referenciados em todo o fluxo de trabalho do seu agente.
A. Atributos de contato
Atributos de contato são um tipo específico de atributo vinculado a dados do cliente.
Atributos de contato predefinidos
Exemplos comuns incluem:
first namelast name
Atributos de contato personalizados
Você pode criar atributos personalizados com base no seu caso de uso dentro do agente.
Importante
Atributos de contato só recebem valores quando os dados são realmente capturados.
Eles são preenchidos quando:
Um Formulário personalizado é enviado durante a conversa
Uma ação de API REST é acionada após a conversa
Outros pontos importantes a serem observados
Atributos de contato não são o mesmo que campos de contato
Campos de contato incluem:
emailphone
Eles também podem vir de:
Formulários personalizados
Critérios de qualificação de leads
Atributos de contato são vinculados a esses campos apenas quando os dados são capturados através desses fluxos.
B. Atributos de ação
Atributos de ação estão vinculados a ações configuradas em seu agente.
Tipos de atributos de ação
Atributos de ação de API REST
Atributos de ação predefinidos
1. Atributos de ação predefinidos
Estes ficam disponíveis quando você adiciona ações específicas ao seu agente.
Exemplos:
Wati enviar resumo de vendas →
sales_summary_content(entrada)Slack enviar mensagem →
message_content(entrada)Google Sheets adicionar linha →
inserted_data_id(saída)Google Sheets atualizar linha →
target_data_id(entrada)
2. Atributos de ação de API REST
Atributos de entrada são criados quando você configura a ação
Atributos de saída são gerados após a execução da ação (durante o teste ou execução ao vivo)
Importante
Você deve adicionar a ação correspondente ao seu agente antes de usar seus atributos.
Como configurar o payload da ação da API REST
Ações de API REST na Astra usam espaços reservados para transferir dados dinâmicos.
O que são espaços reservados
Espaços reservados são escritos usando: ##{{placeholder_name}}
Você pode usá-los em:
Parâmetros de consulta
Cabeçalhos
Corpo da solicitação
Método recomendado: usar entrada de dados
Esta é a abordagem mais flexível e recomendada.
A. Usando Entrada de Dados
Etapa 1: adicionar um campo de entrada de dados
Crie uma entrada de dados na configuração da sua ação.
Etapa 2: configurar o campo
Defina:
Tipo de dado
Nome
Descrição
Obrigatório ou opcional
Atributo de referência (opcional)
Valor padrão (opcional)
Etapa 3: escolher como o valor é obtido
Você tem 3 opções:
Sem referência
O agente gera o valor do contexto
Adicione uma descrição clara para que o agente saiba o que passar
Referenciar um atributo de contato
Use apenas se o valor já foi capturado
Evite usar isso a menos que:
Um formulário personalizado foi enviado, ou
Um evento de API pós-conversa ocorreu
Referenciar um atributo de saída de ação
Use a saída de uma ação anterior
A ação referenciada deve ser executada antes da atual
Etapa 4: usar o espaço reservado
Referencie-o no seu payload: ##{{data_input_name}}
Certifique-se de que o nome corresponda exatamente.
B. Usando atributo de contato direto
Você pode referenciar diretamente um atributo de contato: ##{{contact.attribute_name}}
Não é necessário definir uma entrada de dados
Pode ser inserido diretamente da interface do usuário
C. Usando atributo de ação direto
Você pode referenciar a saída de uma ação: ##{{action.<action_id>#out#<attribute_name>}}
Vincula à saída de uma ação anterior
Pode ser inserido da interface do usuário
Não é necessário digitar manualmente o formato completo
Melhores práticas
Use entrada de dados para a maioria dos casos de uso
Evite depender de atributos de contato, a menos que você tenha certeza de que eles estão preenchidos
Garanta que a ordem de execução da ação esteja correta ao usar saídas
Teste todas as ações de API antes de implantar
Ao entender os atributos da Astra, você pode criar agentes mais estruturados, confiáveis e dinâmicos dentro da Wati.