API Personalizada

As ações de Custom API permitem que seu agente interaja com serviços externos. Busque dados em tempo real, envie formulários ou acione fluxos de trabalho em outras ferramentas.

Criando uma Ação de Custom API

1. Vá até a aba Ações do seu agente
2. Clique em Adicionar ação → API personalizada
3. Configure a chamada de API:
   • URL do endpoint - O endpoint de API a ser chamado
   • Método HTTP - GET, POST, PUT, PATCH ou DELETE
   • Cabeçalhos - Autenticação e content-type
   • Corpo da solicitação - Dados a serem enviados (para POST/PUT/PATCH)
4. Salve e teste

Opções de Configuração

Endpoint URL

A URL completa do endpoint de API:

https://api.yourservice.com/v1/data

Use apenas endpoints HTTPS. Endpoints HTTP são bloqueados por segurança.

HTTP Method

Headers

Adicione cabeçalhos de autenticação e conteúdo:

Authorization: Bearer {{SECRET:service_api_key}}
Content-Type: application/json

Crie o segredo nomeado separadamente. O Agentkit resolve {{SECRET:name}} apenas no servidor. As leituras de ações e os logs nunca incluem o valor armazenado.

Origem dos dados de entrada

Para um campo de texto com um único endereço de e-mail, escolha o e-mail verificado com pergunta quando indisponível. O Agentkit usa o contato web verificado ou o remetente da mensagem recebida. Visitantes anônimos recebem uma pergunta sobre o endereço. O modelo não pode substituir um endereço verificado.

Request Body

Para requisições POST/PUT, defina o corpo JSON com os dados que você deseja enviar.

Quando a API é Chamada

A IA decide quando chamar a API com base no contexto da conversa e na descrição da ação. Você pode orientar esse comportamento fornecendo uma descrição clara de quando a ação deve ser acionada.

Tratamento de Respostas

Resposta de Sucesso

Quando a API retorna com sucesso (status 2xx):

• Exiba uma mensagem de sucesso ao visitante
• Inclua os dados da resposta no chat
• Acione ações subsequentes

Tratamento de Erros

Quando a API falha:

• Exiba uma mensagem de erro amigável
• Registre o erro para depuração
• Opcionalmente, tente a requisição novamente

Exemplos de Casos de Uso

Verificar Status do Pedido

Configure um endpoint GET para buscar dados do pedido quando visitantes perguntarem sobre o status do pedido deles.

Enviar para o CRM

Configure um endpoint POST para enviar dados de leads para o seu sistema de CRM.

Obter Dados em Tempo Real

Configure um endpoint GET para buscar dados em tempo real (como disponibilidade ou estoque) dos seus sistemas.

Considerações de Segurança

Chaves de API

• Armazene as chaves de API como segredos nomeados e use referências {{SECRET:name}}.
• Use chaves específicas de ambiente para testes
• Faça a rotação das chaves periodicamente

Limitação de Taxa

• APIs externas podem ter limites de taxa
• Configure a limitação de taxa do seu agente adequadamente
• Monitore o uso da API nos logs

Privacidade de Dados

• Envie apenas os dados necessários
• Garanta que os serviços externos estejam em conformidade com o GDPR, se necessário
• Não registre dados sensíveis de resposta

Timeout e Tentativas

Testando sua Ação de API

1. Configure a ação com um endpoint de teste
2. Vá até o Playground
3. Acione a ação com a entrada apropriada
4. Verifique a resposta no chat
5. Revise os logs para depuração

Próximos Passos

• Configure webhooks para entrega confiável
• Conecte-se ao Zapier para integrações sem código
• Veja a documentação de API para chamadas de API recebidas