Ações de API

As Ações de API deixam o seu agente de IA consultar sistemas externos no meio da conversa — como checar se um cliente está em dia, buscar um pedido, olhar o estoque ou falar com outra ferramenta sua. Você cadastra a API uma vez, explica quando a IA deve usá-la, e ela faz sozinha na hora certa.

Onde fica

Vá em Integrações → Ferramentas avançadas (clique em Mostrar) → Ações de API → Nova ação.

Importante: a ação só é acionada quando há um agente de IA ativo na conversa. É a IA que decide chamá-la — com base na descrição que você escrever. Sem agente de IA no atendimento, a ação não roda.

Passo a passo

Ao criar uma nova ação, você preenche:

1. 1Nome (identificador): um nome curto, sem espaços, como verificar_pagamento. É o apelido técnico da ação.
2. 2Rótulo (opcional): um nome amigável só pra você se organizar (ex.: Situação do cliente).
3. 3Quando a IA deve usar (descrição): o campo mais importante. Escreva, em linguagem natural, a situação em que a IA deve chamar a ação. Ex.: 'Quando o cliente perguntar se está em dia ou sobre a situação do pagamento dele.' Quanto mais claro, melhor a IA acerta a hora.
4. 4URL do endpoint: o endereço da sua API. Use {campo} para os dados que a IA vai preencher. Ex.: https://api.suaempresa.com/cliente/status?email={email}
5. 5Dados (inputs): os campos que a IA precisa preencher pra montar a chamada. Para cada um: um nome (igual ao {campo} da URL), uma descrição (ex.: 'e-mail do cliente') e se é obrigatório. A IA extrai esses valores da conversa.
6. 6Autenticação: como sua API valida o acesso (veja abaixo).
7. 7Dica de resposta (opcional): como a IA deve interpretar o que a API devolve. Ex.: 'Se voltar ativo, diga que está tudo certo; se vencido, avise a data e ofereça o link de pagamento.'

Salve e pronto — a IA já passa a usar a ação nas conversas.

Exemplo: o cliente está em dia?

• Nome: verificar_pagamento
• Quando usar: Quando o cliente perguntar sobre a situação/pagamento dele.
• URL: https://api.suaempresa.com/cliente/status?email={email}
• Dado: email — e-mail do cliente (obrigatório)
• Autenticação: Bearer, com o seu token
• Dica de resposta: Se em dia, confirme que está tudo certo; se vencido, informe a data e mande o link.

Agora, quando um cliente perguntar 'tô em dia?', a IA pega o e-mail dele, consulta sua API e responde com a situação real — sozinha.

Autenticação

Se sua API exige uma chave, escolha o tipo:

• Nenhuma: API pública, sem chave.
• Bearer: manda a chave no cabeçalho Authorization: Bearer sua-chave.
• Header: você define o nome do cabeçalho e o valor (ex.: X-API-Key: sua-chave).

O segredo fica cifrado no Golden — depois de salvo, ele não é mostrado de volta (você só cola de novo se quiser trocar).

Bom saber

• No momento as ações são de consulta (GET) — servem pra ler informação (status, pedido, estoque, etc.). Ainda não gravam nem alteram dados.
• O Golden precisa conseguir alcançar a sua API pela internet. Se o sistema estiver numa rede interna, exponha por uma URL pública (ou túnel).
• A IA decide sozinha quando usar, então capriche na descrição e na dica de resposta — é o que guia o comportamento.

Dica: quer avisos proativos (ex.: 'me avise quando tal sistema cair')? Isso é diferente: as Ações de API são reativas (a IA consulta durante a conversa). Para algo que fica checando sozinho e te avisa, use uma automação agendada (como o n8n, em Integrações) que faz a verificação e dispara a mensagem.