Ações personalizadas HTTP: criar e configurar uma integração

Conecte seu agente de IA a qualquer API externa para consultar planos, registrar pedidos ou chamar seus sistemas durante a conversa.

Jun 26, 2026

Veja este passo no vídeo · Ações personalizadas: criar uma

O que são ações personalizadas

As ações personalizadas são endpoints HTTP que seu agente de IA pode chamar por conta própria durante uma conversa. Servem para o agente consultar informações ao vivo (planos, estoque, status de um pedido) ou registrar dados nos seus sistemas (abrir um ticket, criar um lead) sem intervenção humana. Enquanto as Ferramentas nativas cobrem ações internas do Omnifox (encerrar conversa, atribuir, disparar workflow), as ações personalizadas conectam seu agente a qualquer API externa.

Requisitos

  • Sua organização precisa do plano Impulsa ou superior (o plano Lite não as inclui). Se o seu plano não as inclui, você verá um cadeado e o botão Ver planos.
  • O agente deve ser de texto (as ações são configuradas em agentes de texto, não de voz).
  • A API de destino deve responder por HTTPS e, normalmente, aceitar um header de autenticação (token ou API key).

Passos para criar uma ação

  1. Vá em Configurações → Agentes IA e entre no agente que deseja editar.
  2. Selecione a aba Ações personalizadas.
  3. Na seção Ações personalizadas (abaixo de Ferramentas nativas), clique em Nova ação.
  4. Preencha a identidade da ação:
    • Nome técnico: em snake_case, ex.: consultar_planos. O modelo a invoca no prompt como !consultar_planos.
    • Rótulo: o nome legível exibido na lista, ex.: Consultar planos.
    • Descrição (para o LLM): explique quando usá-la. É o texto que o modelo lê para decidir se a chama, então seja específico (entre 10 e 500 caracteres).
  5. Configure a Solicitação HTTP:
    • Método HTTP: GET, POST, PUT, PATCH ou DELETE.
    • URL: o endpoint completo, ex.: https://api.seudominio.com/planos.
    • Headers: adicione os que precisar, normalmente Authorization: Bearer ....
    • Timeout (s): entre 1 e 60 segundos.
  6. Clique em Salvar ação.

Ao salvar, a ação aparece na lista com seu método, URL e um interruptor para ativá-la ou desativá-la.

Verificação

  • A nova ação consta na lista com a etiqueta !nome em âmbar.
  • O interruptor está Ativa.
  • Após salvar, o botão Testar fica disponível, executando uma chamada real e mostrando a resposta. Veja como em Testar e editar ações personalizadas.

Se não funcionar

  • Não vejo a aba ou aparece um cadeado: seu plano não inclui ações personalizadas. Clique em Ver planos e faça upgrade para Impulsa ou superior.
  • Não deixa salvar: o Nome técnico deve ser snake_case começando por uma letra; a Descrição precisa de no mínimo 10 caracteres; a URL deve começar com https://.
  • O agente não a usa: confira se o interruptor está Ativa e melhore a Descrição para deixar claro quando invocá-la.

Dica: use um nome técnico que descreva a intenção (consultar_estoque, criar_pedido). O modelo se apoia no nome e na descrição para decidir.

Dica: comece por uma ação GET simples, somente leitura. É mais fácil de testar e não altera dados se algo der errado.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp