Funções Personalizadas #

Funções personalizadas permitem que seu bot de IA se conecte a outros sistemas durante conversas ao vivo. Em vez de dizer “Vou verificar e retorno para você”, o bot pode consultar o status de um pedido, verificar o estoque ou criar um registro no seu CRM (sistema de gestão de relacionamento com o cliente - o software que você usa para rastrear leads e clientes, como o HubSpot ou Salesforce) - tudo em tempo real, enquanto o cliente aguarda.

Funções Personalizadas vs Webhooks #

Este é o ponto de confusão mais comum, por isso vale a pena esclarecê-lo antes de construir qualquer coisa.

Quando escolher qual: Se você só precisa avisar outro sistema de que algo aconteceu, use um webhook - uma mensagem automatizada de mão única enviada para outro sistema (consulte Configurações → Integrações → Webhooks). Se o bot precisar aprender algo de outro sistema antes de continuar a conversa, use uma função personalizada.

Exemplos do que as Funções Personalizadas possibilitam #

Como a resposta retorna para a conversa, as funções personalizadas permitem coisas que webhooks simplesmente não conseguem fazer:

• Consulta de estoque ao vivo no Shopify ou WooCommerce — Antes de passar um orçamento ao cliente, o bot verifica o estoque em tempo real e responde “Sim, temos 12 unidades no tamanho M” em vez de “deixe-me verificar e retorno para você.”
• Preços dinâmicos a partir de uma Planilha Google — Sua equipe de vendas atualiza os preços em uma planilha; o bot lê a linha mais recente no meio da conversa e informa o preço atual sem que ninguém precise alterar a configuração da IA.
• Agente de retorno de chamada por voz (Voice-AI) — Quando o bot qualifica um lead, ele aciona um agente de voz (por exemplo, um chamador baseado em ElevenLabs) para ligar de volta para o lead em poucos minutos e confirma ao cliente: “ótimo, espere uma ligação nos próximos 5 minutos.”
• PDF de orçamento personalizado, gerado e enviado por e-mail durante o chat — O bot coleta os requisitos, chama seu gerador de orçamentos, recebe uma URL de PDF e diz ao cliente: “Acabei de enviar seu orçamento por e-mail — verifique sua caixa de entrada.”

O que as Funções Personalizadas podem fazer? #

Pense nas funções personalizadas como dar ao seu bot superpoderes além de apenas conversar. Aqui estão exemplos do mundo real:

• Rastreamento de pedidos - Um cliente pergunta “Onde está meu pedido?” e o bot verifica seu sistema de e-commerce e responde com o status de envio e o link de rastreamento
• Verificação de estoque - “Vocês têm isso no tamanho 10?” O bot verifica seu sistema de estoque e dá uma resposta em tempo real
• Atualizações de CRM - Quando o bot qualifica um lead, ele cria ou atualiza automaticamente um registro no HubSpot, Salesforce ou qualquer outro CRM
• Geração de orçamentos - O bot coleta os requisitos do cliente e gera um orçamento personalizado a partir do seu sistema de preços
• Agendamento - O bot cria um compromisso no seu sistema de agendamento externo
• Verificação de descontos - “Este código de cupom é válido?” O bot verifica e confirma
• Consulta de conta - Um cliente recorrente é reconhecido automaticamente e os detalhes da conta dele são recuperados

O cliente nunca vê o que acontece nos bastidores. Ele simplesmente experimenta um bot que pode responder às suas perguntas com informações reais e atualizadas.

Como as Funções Personalizadas funcionam (Versão simplificada) #

Aqui está o que acontece quando uma função personalizada é acionada durante uma conversa:

1. O cliente pergunta algo que precisa de dados em tempo real (por exemplo, “Onde está meu pedido?”)
2. O bot reconhece que precisa usar uma função personalizada para responder
3. O bot coleta qualquer informação ausente do cliente (por exemplo, “Qual é o número do seu pedido?”)
4. A plataforma envia uma solicitação para o seu sistema (seu site, CRM ou qualquer outra ferramenta) com os detalhes relevantes
5. Seu sistema responde com os dados (por exemplo, status do pedido, código de rastreamento, data de entrega)
6. O bot lê a resposta e elabora uma resposta natural: “Seu pedido ORD-4582 foi enviado e deve chegar até sexta-feira!”

Quanto custa uma chamada de função personalizada #

Cada chamada de função personalizada é cobrada de acordo com o nível de Qualidade de IA do seu Agente:

Configurando uma Função Personalizada (Passo a Passo) #

1. Na barra lateral principal, em AI Studio, clique em Custom Functions.

2. Clique no botão verde + Add Function (ou New function) no canto superior direito.

A lista de funções personalizadas exibe uma tabela com as seguintes colunas:

Isso torna fácil verificar suas funções rapidamente e encontrar a que você precisa.

Passo 1: Dê um Nome e uma Descrição #

Dica: Seja muito específico na descrição e no propósito. Quanto mais claro você for sobre quando a função deve ser usada, mais confiavelmente o bot a utilizará no momento certo.

Passo 2: Configure a Conexão #

Você precisa dizer ao aplicativo para onde enviar a solicitação:

Qual método escolher:

Se você não tiver certeza de qual usar, verifique com seu desenvolvedor ou na documentação do sistema ao qual você está se conectando. GET (para consultas) e POST (para criar registros) são os mais comuns.

Passo 3: Adicionar cabeçalhos de autenticação #

A maioria dos sistemas exige autenticação para aceitar solicitações. Adicione todos os cabeçalhos necessários:

Valores de cabeçalhos que contêm uma chave ou senha, como Authorization ou X-API-Key, são exibidos como pontos após serem digitados. Clique no ícone de olho ao lado do valor para visualizá-lo.

Dica de segurança: Use uma chave de API dedicada com permissões limitadas. Não use credenciais de nível de administrador.

Onde encontrar chaves de API: Verifique as configurações ou a seção de desenvolvedor do sistema ao qual você está se conectando (por exemplo, seu CRM, plataforma de e-commerce ou ferramenta de agendamento).

Passo 4: Definir a entrada (O que o bot envia) #

Os parâmetros de entrada são as informações que o bot coleta da conversa e envia para o seu sistema.

Para cada parâmetro, você especifica:

Tipos de parâmetros disponíveis:

Cada parâmetro também possui um campo opcional Caminho do corpo da requisição. Normalmente, um parâmetro é enviado como um campo de nível superior no corpo da requisição (ou como um valor de string de consulta, para o tipo query_param). Se o seu endpoint espera que ele esteja aninhado — por exemplo, {"order": {"id": "ORD-123"}} — defina o caminho como order.id e a plataforma aninha o valor lá para você.

Exemplo: Para uma consulta de status de pedido, você pode definir:

• order_number (string, obrigatório): “O número do pedido do cliente. Geralmente começa com ORD- seguido por dígitos. Peça isso ao cliente caso ele não tenha mencionado.”
• email (string, opcional): “O endereço de e-mail do cliente para verificação adicional. Necessário apenas se o número do pedido sozinho não encontrar uma correspondência.”

O que seu sistema recebe automaticamente #

Além dos parâmetros de entrada que você define, a plataforma inclui automaticamente dados do sistema em cada solicitação. Seu endpoint recebe isso em um campo system:

Isso é útil se o seu sistema precisar identificar o contato, verificar qual agente chamou a função ou se comportar de maneira diferente durante os testes.

Quando uma verificação de acompanhamento chama sua função (veja Enviar apenas quando uma verificação for aprovada), a solicitação é diferente de uma chamada durante a conversa: ela não possui parâmetros de entrada e o campo system contém apenas system.contact (com seu id) mais um bloco system.follow_up (type, cycle_number, follow_up_number, reason, campaign_id, agent_id). Não há um objeto campaign nela. Ignorar Dados do Sistema também se aplica a essa chamada.

Não precisa dos dados do sistema? Ative a opção Ignorar Dados do Sistema no construtor de funções. O bot enviará apenas os parâmetros de entrada que você definiu — sem dados de contato ou do agente. Use isso se o seu endpoint rejeitar campos inesperados ou se você simplesmente quiser um payload mais enxuto.

Passo 5: Teste, depois deixe o bot ler a resposta #

Normalmente, você não precisa mapear campos de resposta. Assim que o seu endpoint responde, o bot lê toda a resposta JSON e usa a Descrição e o Propósito (Ação de IA) da sua função — além da descrição de cada parâmetro — para entender o que é importante e apresentar isso de forma natural. Uma Descrição clara na própria função (“Recupera o status atual de um pedido de cliente, incluindo informações de envio e rastreamento”) faz mais trabalho aqui do que um mapeamento campo a campo faria.

Se o seu endpoint retornar uma resposta grande e você quiser que o bot veja apenas alguns valores específicos, abra a seção Mapeamento de resposta (recolhida por padrão, logo acima de Testar). Cada linha seleciona um campo de nível superior da resposta: Campo de resposta é o nome do campo na resposta JSON da sua API, e Campo de saída é o nome sob o qual o bot o recebe. Com pelo menos uma linha preenchida, o bot recebe apenas os seus valores mapeados em vez de todo o corpo da resposta. Deixe a seção vazia para manter o comportamento padrão de resposta completa.

Antes de salvar, use a seção Testar na parte inferior do construtor para disparar a requisição exatamente como configurada e ver a resposta real, sem sair do aplicativo:

A resposta que você vê aqui é a resposta bruta do endpoint. Se você configurou o Mapeamento de resposta acima, o bot em um chat real recebe apenas esses campos mapeados — o teste sempre mostra a resposta bruta completa para que você possa ver o que está disponível para mapear. Se algo parecer estranho (nomes de campos inesperados, aninhamento extra), corrija em seu endpoint ou ajuste seu mapeamento.

Atribuindo Funções a um Agente #

Após criar uma função personalizada, você precisa informar a cada Agente quais funções ele pode usar:

1. Abra o Agente em AI Studio → Agentes de IA.
2. Vá para a aba Habilidades de IA.
3. Você verá uma lista de todas as funções personalizadas que criou. Ative cada função que deseja que o bot deste Agente possa chamar.
4. Clique em Salvar alterações na parte inferior. As seleções só são aplicadas após serem salvas.

Apenas as funções atribuídas ficam disponíveis para o bot daquele Agente. Isso evita que o bot use acidentalmente funções que não são relevantes.

Testando Suas Funções Personalizadas #

Antes de entrar em operação, teste minuciosamente:

1. Execute o teste integrado - Use a seção Testar dentro do construtor de funções (veja acima) para uma verificação rápida sem sair do aplicativo — preencha valores realistas e clique em Executar teste.
2. Teste o endpoint do seu sistema diretamente - Para a lista de verificação completa abaixo, uma ferramenta dedicada como o Postman (ou seu desenvolvedor) investiga mais profundamente do que um único Executar teste.
3. Teste no “Experimentar” (Try Out) - Simule uma conversa onde o cliente pergunta algo que deveria acionar a função.
4. Verifique a resposta - Certifique-se de que o bot lê e apresenta os dados corretamente.
5. Teste cenários de erro - O que acontece se o cliente fornecer um número de pedido inválido? E se o seu sistema estiver temporariamente fora do ar?

Quando o teste retorna 401 ou 403 #

Um 401 ou 403 significa que seu endpoint recebeu a solicitação e a recusou. O sinal revelador é que nada aparece em seus próprios logs — a maioria das ferramentas rejeita uma chamada não autorizada antes mesmo de iniciar o fluxo de trabalho, portanto, não há nada para ver do seu lado e parece que a solicitação nunca chegou.

Quase sempre, isso é uma incompatibilidade de autenticação: seu endpoint deseja um tipo de credencial e a função está enviando outra. Verifique se o cabeçalho que você adicionou no Passo 3 é exatamente o que seu sistema espera.

A versão mais comum disso é um webhook protegido com Autenticação Básica (n8n, Make e a maioria das ferramentas auto-hospedadas oferecem isso como uma caixa de seleção no próprio webhook), enquanto a função envia um cabeçalho secreto personalizado como X-My-Secret. A Autenticação Básica aceita apenas um cabeçalho Authorization, portanto, um cabeçalho personalizado é ignorado e a chamada é rejeitada. Você tem duas opções:

• Desative a Autenticação Básica no webhook e verifique seu cabeçalho personalizado dentro do fluxo de trabalho.
• Mantenha a Autenticação Básica ativada e adicione um cabeçalho Authorization à função, cujo valor seja a palavra Basic seguida pelo seu username:password codificado em base64.

Qualquer uma das opções funciona — apenas certifique-se de que ambos os lados estejam de acordo.

Quando o teste retorna 404 #

A URL do endpoint está incorreta ou o fluxo de trabalho não foi publicado. No n8n especificamente, cada webhook possui uma URL de Teste e uma URL de Produção separadas, e a de Teste só escuta enquanto você está com o editor aberto. Copie a URL de Produção e certifique-se de que o fluxo de trabalho esteja ativo.

Visualizando falhas no Try Out e nos Chats #

Quando a IA chama uma função personalizada durante uma conversa e a chamada falha, por exemplo, devido a credenciais incorretas, um endpoint fora do ar ou um tempo limite (timeout), a conversa agora mostra isso: um marcador vermelho “(nome da função) falhou” aparece no tópico, tanto na aba Try Out do agente quanto nas conversas reais em Chats. Clique no marcador para expandir os detalhes: o código de status que seu endpoint retornou e o corpo da resposta, o que geralmente é suficiente para lhe dizer exatamente o que corrigir (um 401 com uma mensagem “unauthorized” significa o cabeçalho de autenticação, um timeout significa que seu endpoint levou mais de 30 segundos; para um trabalho que precisa de mais tempo, veja Trabalhos de longa duração).

Chamadas bem-sucedidas também exibem um marcador — clique nele para ver o que seu endpoint realmente enviou de volta. Esta é a maneira mais rápida de depurar uma integração de ponta a ponta: faça a conversa de teste no Try Out e, em seguida, clique no marcador da função para ver o resultado real da solicitação sem sair da página.

Quando uma ferramenta continua falhando em conversas reais #

Se a mesma função personalizada falhar 3 vezes em 24 horas enquanto seu agente de IA estiver conversando, você receberá um alerta por dia sobre isso: por e-mail, no ícone de sino e como notificação push, caso a tenha ativado. O alerta nomeia a ferramenta, mostra o último erro e fornece links para os chats afetados, já que o agente terá informado a esses contatos que encontrou um problema técnico. A linha da função em Configurações exibirá um status de Falha com a contagem de erros e o último erro até que a ferramenta volte a funcionar; uma chamada bem-sucedida limpa esse status. Você pode desativar esses alertas em Configurações → Notificações → Erros de ferramenta.

Exemplo Completo: Consulta de Status de Pedido #

Aqui está um exemplo totalmente configurado que você pode usar como modelo:

Informações Básicas:

• Nome: check_order_status
• Descrição: “Recupera o status atual de um pedido do cliente, incluindo informações de envio e rastreamento”
• Ação da IA: “Chame isso quando um cliente perguntar sobre o status do pedido, onde o pacote está ou quando ele chegará. Sempre peça o número do pedido primeiro.”

Conexão:

• URL: https://api.mystore.com/orders/lookup
• Método: POST

Cabeçalhos:

• Authorization: Bearer sk_live_abc123
• Content-Type: application/json

Parâmetros de Entrada:

• order_number (texto, obrigatório): “O número do pedido fornecido pelo cliente”
• customer_email (texto, opcional): “E-mail do cliente para verificação adicional”

Nenhum mapeamento de resposta necessário — com uma Descrição e Ação de IA já definidas acima, o bot lê qualquer JSON que seu endpoint retornar (status, número de rastreamento, data de entrega, itens) e descobre como falar sobre isso.

Como é a conversa:

Cliente: Ei, onde está meu pedido?

Bot: Olá! Ficarei feliz em verificar seu pedido. Você poderia compartilhar o número do pedido comigo?

Cliente: É ORD-78234

Bot: Deixe-me verificar isso para você…

Seu pedido ORD-78234 foi enviado e está a caminho! A data prevista de entrega é 10 de março. Você pode rastrear seu pacote aqui: https://tracking.example.com/1Z999AA1

Há mais alguma coisa em que eu possa ajudar?

Exemplo Completo: Status de Pedido no Shopify #

Se a loja utiliza o Shopify, você não precisa de um desenvolvedor para criar um endpoint de consulta — o próprio sistema do Shopify pode responder a perguntas sobre pedidos diretamente. (Para perguntas sobre produtos e estoque em uma loja Shopify, você não precisa de uma função personalizada: conecte o servidor integrado da loja — veja Conectar uma loja Shopify.)

Primeiro, crie um token de acesso no Shopify. O Shopify alterou isso durante 2026: aplicativos não podem mais ser criados dentro do admin do Shopify, e a nova tela de aplicativos fornece um Client ID e um Client secret em vez de um token pronto. As etapas abaixo transformam esses dados em um token permanente. Reserve cerca de dez minutos, uma vez por loja. (Se a loja já tiver um aplicativo antigo criado da maneira antiga, seu token existente continuará funcionando — pule direto para a função personalizada abaixo.)

1. Vá para o Shopify Dev Dashboard em dev.shopify.com, abra sua organização e clique em Apps → Create app. Dê a ele um nome como Order lookup.
2. Conceda ao app a permissão read_orders, publique uma versão e instale o app na loja.
3. Abra as Configurações do app e adicione o endereço da web da própria loja (por exemplo, https://www.yourstore.com/) aos URLs de redirecionamento permitidos. Salve.
4. Ainda em Configurações, copie o Client ID e o Client secret.
5. Em um navegador onde você esteja conectado ao admin da Shopify daquela loja, abra o endereço abaixo, substituindo o nome da loja, o ID do cliente e o endereço de redirecionamento pelos seus: https://YOUR-STORE.myshopify.com/admin/oauth/authorize?client_id=YOUR-CLIENT-ID&scope=read_orders&redirect_uri=https://www.yourstore.com/&state=12345 Aprove a tela que aparece. O navegador acessará seu endereço de redirecionamento e a barra de endereços agora conterá code= seguido por um valor longo — copie esse valor. Ele é válido apenas por alguns minutos, então vá direto para a próxima etapa.
6. Troque esse código pelo token, o que você pode fazer dentro de Your AI Connector. No construtor de funções personalizadas, defina Method como POST e URL como https://YOUR-STORE.myshopify.com/admin/oauth/access_token, adicione três parâmetros de entrada de texto chamados client_id, client_secret e code, clique em Test, preencha os três valores e execute-o. A resposta contém access_token — esse é o seu token permanente. Copie-o para um local seguro, limpe o construtor e configure a função real abaixo.

Em seguida, configure a função personalizada:

Informações Básicas:

• Nome: check_shopify_order
• Descrição: “Consulta um pedido no sistema Shopify da loja e retorna seu status, rastreamento e itens”
• Ação de IA: “Chame isso quando um cliente perguntar sobre o status ou a entrega do pedido. Sempre peça o número do pedido primeiro.”

Conexão:

• URL: https://YOUR-STORE.myshopify.com/admin/api/2026-01/orders.json?status=any — substitua YOUR-STORE pelo nome .myshopify.com da loja (este endereço usa o domínio técnico do Shopify, não o domínio personalizado da loja)
• Método: GET

Cabeçalhos:

• X-Shopify-Access-Token: shpat_... (o token obtido acima)

Parâmetros de Entrada:

• name (query_param, obrigatório): “O número do pedido do cliente exatamente como aparece na confirmação do pedido, incluindo o sinal # — por exemplo, #1001. Peça ao cliente se ele ainda não o tiver mencionado.”

Nenhum mapeamento de resposta é necessário — o bot lê o pedido retornado (status de pagamento, status de processamento, rastreamento, itens) e responde naturalmente.

É bom saber: um token criado desta forma pode ver pedidos dos últimos 60 dias — o suficiente para perguntas de suporte do dia a dia, mas não um histórico completo de pedidos.

Exemplo Completo: Agendar um Compromisso #

Informações Básicas:

• Nome: create_booking
• Descrição: “Cria um novo compromisso em nosso sistema de agendamento”
• Ação da IA: “Use isso após confirmar a data, hora e detalhes de contato com o cliente. Não chame até que o cliente confirme explicitamente que deseja agendar.”

Conexão:

• URL: https://booking.mycompany.com/api/appointments
• Método: POST

Parâmetros de Entrada:

• date (texto, obrigatório): “Data do compromisso no formato AAAA-MM-DD”
• time (texto, obrigatório): “Hora do compromisso no formato HH:MM”
• name (texto, obrigatório): “Nome completo do cliente”
• phone (texto, obrigatório): “Número de telefone do cliente”
• service_type (texto, obrigatório): “O tipo de serviço sendo agendado”

Exemplo Completo: Adicionar um Assinante de Newsletter ao seu CRM #

Um padrão muito comum: o bot termina de responder, oferece sua newsletter, o contato responde com seu endereço de e-mail e esse endereço deve ir direto para sua ferramenta de e-mail. A maioria dos CRMs (FluentCRM, ActiveCampaign, MailerLite, Brevo e outros) aceita um POST simples exatamente para isso, portanto, não é necessária nenhuma plataforma de automação intermediária.

Este exemplo usa o FluentCRM no WordPress. O formato é o mesmo para qualquer outra ferramenta que forneça um “webhook de entrada” ou um endpoint de “criar assinante”.

Primeiro, obtenha a URL do seu CRM. No WordPress, abra FluentCRM → Settings → Incoming Webhooks e crie um webhook. Escolha a lista, as tags e o status de assinatura que os novos contatos devem receber e, em seguida, copie a URL do webhook gerada. Tudo o que você definir aqui é aplicado automaticamente, então o bot só precisa enviar o endereço de e-mail.

Em seguida, configure a função personalizada:

Informações Básicas:

• Nome: add_newsletter_subscriber
• Descrição: “Adiciona alguém à nossa lista de newsletter usando o endereço de e-mail que forneceram no chat”
• Ação da IA: “Use isso no momento em que o contato concordar em assinar a newsletter e fornecer seu endereço de e-mail. Não chame antes que eles tenham realmente fornecido um endereço e não chame duas vezes para a mesma pessoa.”

Conexão:

• URL: a URL do webhook que você copiou do seu CRM
• Método: POST

Parâmetros de Entrada:

• email (string, obrigatório): “O endereço de e-mail que o contato forneceu na conversa”
• first_name (string, opcional): “O primeiro nome do contato, se eles tiverem mencionado”

Ignorar Dados do Sistema: ative esta opção. Seu CRM só precisa dos campos acima, e um payload mais enxuto evita erros de ferramentas que rejeitam campos inesperados.

Mapeamento de resposta: não é necessário aqui. Nada precisa retornar para que o bot continue.

Não se esqueça de ativar a função para o Agente que executa a conversa (consulte Atribuindo Funções a um Agente). Este é o motivo mais comum pelo qual uma função criada corretamente nunca é disparada.

Dicas para Funções Personalizadas Confiáveis #

1. Certifique-se de que solicitações repetidas sejam seguras. Se a mesma solicitação for enviada duas vezes acidentalmente, ela não deve criar registros duplicados. Falhas na rede podem ocasionalmente causar isso.

2. Retorne mensagens de erro claras. Se algo der errado no seu sistema, retorne um erro legível por humanos. O bot o transmitirá ao cliente de forma elegante.

3. Mantenha os tempos de resposta abaixo de 10 segundos. Se o seu sistema demorar mais, considere retornar um reconhecimento rápido primeiro.

4. Lide com credenciais expiradas ou inválidas. Se a sua chave de API expirar, certifique-se de que a mensagem de erro seja clara para que o bot saiba alertar um humano em vez de tentar novamente.

5. Escreva descrições detalhadas. A IA usa suas descrições para descobrir quando chamar a função e como extrair as informações corretas da conversa. Descrições vagas levam a erros.

6. Teste com conversas reais. A Experimentação é ótima para testes iniciais, mas monitore suas primeiras conversas ao vivo para garantir que tudo funcione com consultas reais de clientes.

7. Mantenha logs do seu lado. Peça ao seu desenvolvedor para registrar as solicitações vindas do aplicativo para que você possa depurar rapidamente quaisquer problemas.

8. Se o seu firewall precisar de uma lista de permissões de IP, cada chamada de função personalizada (e cada verificação de acompanhamento) é enviada de um endereço IPv4 fixo, o mesmo que nossos webhooks usam; sem intervalos, sem IPv6, sem rotação. Entre em contato com o suporte e forneceremos o endereço. Ative a assinatura de solicitação e verifique a assinatura como sua verificação de confiança real, e trate o IP como um filtro adicional.

9. Use uma URL final pública. A URL da sua função deve ser um endereço da web público (HTTP/HTTPS). Endereços internos, localhost e de rede privada são rejeitados por segurança, e a plataforma não segue redirecionamentos — aponte a função diretamente para a URL final, não para uma que redirecione para ela.

Trabalhos de longa duração: obtenha o resultado depois #

Normalmente, uma função personalizada precisa responder dentro de 30 segundos, enquanto o contato aguarda a resposta. Alguns trabalhos levam mais tempo do que isso: renderizar um vídeo, realizar uma verificação de crédito, aguardar que uma pessoa do seu lado aprove algo. Para esses casos, ative Resultado vem depois (longa duração). A chamada da IA então apenas inicia o trabalho. Seu serviço responde imediatamente, a IA informa ao contato que o resultado está a caminho e continua a conversa, e seu serviço envia o resultado para um link de retorno (callback) assim que terminar.

Quando usar #

Use quando seu serviço não puder responder de forma confiável dentro de 30 segundos. Deixe desativado para consultas rápidas (status de um pedido, verificação de estoque, preço): essas são mais simples como uma chamada normal, porque a IA responde com o resultado na mesma mensagem.

As configurações no editor #

Você as encontra no editor de funções personalizadas, ao lado de Ignorar Dados do Sistema.

O que seu serviço recebe #

Com a opção ativada, cada chamada carrega o link de retorno em três lugares, além de tudo o que foi descrito acima (seus parâmetros de entrada, o bloco system e os cabeçalhos de assinatura):

O link é exclusivo para cada chamada, pertence àquele contato e àquela chamada, funciona uma vez e expira após o tempo definido em Aguardar até. Você não precisa de uma chave de API para usá-lo: o link em si é a permissão. Trate-o como uma senha e nunca o escreva em um log público.

Enviando o resultado #

Quando o trabalho estiver concluído, envie um POST para o link de retorno:

POST https://api.<your host>/v1/custom-functions/callback/d3f9...
Content-Type: application/json

{
  "result": { "video_url": "https://cdn.example.com/spring-offer.mp4", "duration_seconds": 42 },
  "message": "Your video is ready: https://cdn.example.com/spring-offer.mp4"
}

• result é o que a IA lê. Pode ser texto ou um objeto JSON.
• message é opcional. Com Enviar o texto como está, o contato recebe message quando você envia um, caso contrário, recebe result quando for texto.
• media_url é opcional: um link https para um arquivo (imagem, vídeo, áudio ou documento) que o contato recebe como um anexo real, não como um link. Veja Enviando um arquivo abaixo.
• Você também pode enviar um corpo de texto simples com Content-Type: text/plain. Ele é tratado como result.
• O corpo pode ter até 64 KB.

O que o link de retorno responde:

Um exemplo completo: um vídeo que leva três minutos #

1. A IA chama sua função. Você recebe (abreviado):

POST https://api.example.com/render
X-Callback-Url: https://api.<your host>/v1/custom-functions/callback/d3f9...
Content-Type: application/json

{
  "video_title": "Spring offer",
  "callback_url": "https://api.<your host>/v1/custom-functions/callback/d3f9...",
  "system": {
    "contactId": "...",
    "callback_url": "https://api.<your host>/v1/custom-functions/callback/d3f9...",
    "callback_expires_at": "2026-10-20T19:15:00.000Z"
  }
}

2. Seu serviço inicia a renderização e responde imediatamente:

{ "status": "started" }

3. A IA informa ao contato que o vídeo está sendo feito e continua conversando.
4. Três minutos depois, seu serviço posta o resultado no link de retorno:

{ "result": { "video_url": "https://cdn.example.com/spring-offer.mp4", "duration_seconds": 42 } }

5. A IA escreve a próxima mensagem com suas próprias palavras, por exemplo, “Seu vídeo está pronto: https://cdn.example.com/spring-offer.mp4”.

Usando Zapier ou Make? Deixe o webhook de gatilho receber a chamada e faça com que a última etapa do fluxo seja um POST para callback_url a partir dos dados do gatilho.

O que acontece no chat #

O resultado é salvo na conversa como uma entrada de função, para que você o veja na caixa de entrada como qualquer outra chamada de função personalizada. Então, dependendo de Quando o resultado chegar, a IA escreve e envia a próxima mensagem (isso custa uma resposta da IA, como qualquer mensagem da IA), ou seu texto é enviado como está. Com Enviar o texto como está, o campo message é enviado quando você inclui um, caso contrário result quando for texto simples; se você apenas postar um objeto sem texto, a IA escreve a mensagem em vez disso.

Se a IA estiver desativada para esse contato quando o resultado chegar (um membro da equipe assumiu, a IA foi pausada, o agente está desligado ou sem créditos), o resultado ainda é salvo na conversa, mas nenhuma mensagem é enviada. Ele também não é enviado posteriormente quando a IA é reativada. O membro da equipe vê o resultado no chat e pode usá-lo.

Na aba Testar do agente, todo o fluxo também funciona: o resultado chega no chat de teste.

Enviando um arquivo (vídeo, imagem, PDF) #

Um resultado que é um arquivo, por exemplo, um vídeo que seu serviço renderizou em segundo plano, chega ao contato como um anexo que ele pode abrir no chat, em ambos os modos. A plataforma encontra o arquivo no seu callback desta forma:

1. media_url no corpo, quando você envia um.
2. Caso contrário, um campo de arquivo no objeto result: file_url, video_url, image_url, pdf_url, document_url, audio_url, attachment_url ou download_url.
3. Caso contrário, o primeiro link https no texto que termina com uma extensão de arquivo como .mp4, .jpg, .png ou .pdf.

Com A IA escreve a próxima mensagem, a IA escreve o texto e o arquivo é anexado a essa mensagem (a IA é instruída a não colar o link). Com Enviar o texto como está, seu message é a legenda do anexo.

{
  "result": { "status": "done", "title": "Spring offer" },
  "message": "Your video is ready.",
  "media_url": "https://cdn.example.com/spring-offer.mp4"
}

Os arquivos podem ter até 16 MB e devem ser acessíveis via https. Cada canal suporta tipos diferentes: por exemplo, e-mail e os canais do WhatsApp aceitam vídeo, imagens, áudio e documentos; SMS não suporta arquivos. Quando um canal não pode receber o arquivo, ou o arquivo é muito grande, o contato ainda recebe a mensagem, com o link para o arquivo adicionado ao final.

Quando o resultado nunca chega #

Se nada for postado antes que o tempo de Aguardar até expire, a IA é informada de que o resultado nunca chegou, para que ela possa avisar o contato. Uma entrada com o código APP-3103 aparece em Configurações → Log de erros, e você recebe uma notificação de erro da ferramenta.

Limites em resumo #

• Um resultado por link de callback. Postagens posteriores para o mesmo link são respondidas como duplicadas e não alteram nada.
• Até 64 KB por resultado.
• Um arquivo por resultado, até 16 MB, via https.
• Até 20 postagens por minuto para um link.
• Aguardar até de 1 a 168 horas.
• Seu serviço ainda tem 30 segundos para responder à primeira chamada.

Verificando se uma chamada realmente veio de nós #

Qualquer pessoa que descubra a URL da sua função pode enviar uma solicitação falsa para ela. Um segredo longo em um cabeçalho de autenticação ajuda, mas é o mesmo valor em todas as chamadas, portanto, qualquer pessoa que veja uma solicitação (em um log ou captura de tela) pode reutilizá-la. A assinatura de solicitação corrige isso: cada chamada carrega uma assinatura que apenas alguém que possua seu segredo pode produzir, e que expira após alguns minutos.

A assinatura é opcional e desativada por padrão, e é uma configuração para toda a sua conta: um único segredo assina todas as funções personalizadas.

Ativando a assinatura #

1. Abra Funções Personalizadas.
2. Abaixo da sua lista de funções, encontre o cartão Assinatura de solicitação e clique em Ativar assinatura.
3. Clique em Mostrar, copie o segredo (ele começa com whsec_) e armazene-o no sistema que recebe as chamadas. Trate-o como uma senha.

No mesmo cartão, você pode copiar o segredo novamente, Rotacioná-lo (o antigo para de funcionar imediatamente) ou Desativar a assinatura.

O que enviamos #

Assim que a assinatura estiver ativada, cada chamada feita por uma função personalizada carrega dois cabeçalhos extras: as chamadas da IA durante um chat, condições de envio de acompanhamento e o botão Executar Teste no editor.

Toda chamada, assinada ou não, também carrega User-Agent: Custom-Function/1.0, a menos que você defina seu próprio cabeçalho User-Agent.

Os cabeçalhos e a assinatura funcionam exatamente como webhooks assinados, portanto, se você já verifica nossos webhooks, o mesmo código funciona aqui. Apenas o segredo é diferente.

Como verificar #

A assinatura é um HMAC-SHA256 da string <timestamp>.<raw request body>, usando seu segredo de assinatura como a chave. Verifique-a em relação ao corpo bruto, os bytes exatos que você recebeu: analisar o JSON e transformá-lo de volta em texto pode alterar os bytes, e a assinatura não corresponderá.

Uma função que usa GET (ou um POST sem nada para enviar) não tem corpo, portanto, a string assinada é apenas <timestamp>. com um corpo vazio. A assinatura então prova que a chamada veio de nós e é recente, mas não cobre a string de consulta.

Exemplo em Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"] || ""; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const received = signature.replace("v1=", "");

  return received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Exemplo em Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-Webhook-Timestamp", "")
    signature = headers.get("X-Webhook-Signature", "").replace("v1=", "")
    if not timestamp or abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

Teste com Executar Teste no editor: assim que a assinatura estiver ativada, a chamada de teste é assinada exatamente como uma real, portanto, uma função que passa no teste também passará na sua verificação durante chats reais.

Usando a API? O mesmo segredo pode ser lido, gerado ou rotacionado e removido com GET, POST e DELETE em /v1/custom-functions/signing-secret.

Limites de execução #

Toda função personalizada possui uma seção opcional de Limites de execução na parte inferior do editor. Ela controla com que frequência a IA pode executar a função e se um resultado anterior pode ser reutilizado. Tudo aqui é opcional — deixe tudo vazio e a função se comportará exatamente como antes.

Função somente leitura. Ative isso se sua função apenas lê dados — uma consulta de estoque, uma verificação de preço, uma busca de status de pedido — e nunca cria ou altera nada. Quando uma falha temporária de rede interrompe a IA no meio da resposta, a plataforma pode tentar novamente o turno da conversa com segurança, em vez de deixar o cliente sem uma resposta. Ative apenas se a função realmente nunca gravar nada: uma função que cria registros deve permanecer desativada, para que uma nova tentativa nunca a execute duas vezes acidentalmente. Funções que usam o método GET são tratadas como somente leitura automaticamente, já que requisições GET destinam-se apenas a buscar dados; funções POST, PUT, PATCH e DELETE precisam da alternância.

Servir resultado em cache em chamadas repetidas. Quando a IA chama a função novamente com as mesmas entradas (por exemplo, o cliente faz a mesma pergunta duas vezes), o resultado anterior é reutilizado em vez de chamar seu endpoint novamente. Os resultados em cache são mantidos por até 24 horas, e uma chamada com entradas diferentes sempre vai para o seu endpoint como uma nova solicitação.

Execuções máximas por conversa. Um limite rígido de quantas vezes a função pode ser executada dentro de uma conversa. Defina como 1 para funções que devem ser disparadas apenas uma vez por chat — gerar uma cotação, acionar um retorno de chamada, iniciar uma automação. Quando o limite é atingido, a IA é informada de que a função já foi executada e recebe o resultado mais recente, para que ainda possa responder ao cliente em vez de ficar em silêncio.

Execuções máximas por janela de tempo. Um limite de taxa ao longo do tempo: por exemplo, no máximo 5 execuções em 60 minutos. Útil para funções que chamam serviços de terceiros pagos ou acionam automações mais pesadas. Ambos os campos devem ser preenchidos juntos (um número de execuções e uma janela em minutos, até 7 dias).

Enviando ofertas, contratos ou faturas no LinkedIn. Quando a IA responde no LinkedIn, ela escreve a partir da própria caixa de entrada do proprietário da conta, portanto, ela não deve enviar uma oferta, contrato, cotação, fatura, link de pagamento ou acesso em nome do proprietário, a menos que o proprietário tenha autorizado. Com Automático (o padrão), uma função cujo nome ou descrição indique que ela envia um desses itens não é executada no LinkedIn: a IA é informada de que nada foi enviado e avisa à pessoa que o proprietário cuidará disso. Escolha Permitido para permitir que a função seja executada no LinkedIn de qualquer maneira, ou Nunca no LinkedIn para bloquear uma função que a verificação automática deixaria passar. Outros canais não são afetados e, ao contrário dos limites acima, essa configuração também se aplica ao Testar. Algumas coisas para saber:

• Os limites contam apenas execuções bem-sucedidas. Uma chamada que falhou no lado do seu endpoint não consome o orçamento.
• Quando uma execução é bloqueada por um limite, o cliente nunca fica sem resposta — a IA é informada do motivo e trabalha com as informações que já possui.
• Os limites se aplicam onde quer que a função seja executada: chats regulares em todos os canais e funções gerenciadas por uma automação. Conversas de teste no “Experimentar” (Try Out) não são contadas e não são limitadas.

Ferramentas de Bot Integradas #

Além das funções personalizadas que você mesmo cria, a plataforma vem com uma biblioteca de ferramentas pré-construídas que o bot de IA pode usar durante uma conversa. Elas cobrem as coisas mais comuns que um bot precisa fazer — alertar um colega de equipe, agendar um compromisso, marcar um contato, pesquisar em seu site, agendar um acompanhamento e muito mais — para que você não precise configurá-las do zero.

O bot decide quando usar cada ferramenta com base no que está acontecendo na conversa e em como seu Agente está configurado. A maioria dessas ferramentas é ativada automaticamente quando o recurso relacionado é habilitado (por exemplo, as ferramentas de agendamento só ficam disponíveis depois que você conecta um calendário e habilita agendamentos).

Custo em créditos: Cada chamada de ferramenta é cobrada de acordo com o nível de Qualidade de IA do seu Agente, e as funções personalizadas que você mesmo cria são cobradas da mesma forma:

Ferramentas de Equipe e Tarefas #

Ferramentas de Contato #

Ferramentas de Agendamento e Reservas #

Essas ferramentas só estão disponíveis quando os agendamentos estão habilitados no seu Agente e um tipo de evento de calendário está configurado.

Ferramentas de Conhecimento e Web #

Ferramentas de Acompanhamento (Follow-Up) #

Essas ferramentas exigem que os acompanhamentos (follow-ups) estejam habilitados no seu Agente.

Executor de Funções Personalizadas #

Ferramentas de Reserva de Restaurante (Zenchef e Formitable) #

Estas ferramentas só estão disponíveis quando uma integração Zenchef ou Formitable está conectada. Elas permitem que o bot gerencie reservas de restaurante de ponta a ponta.

Ativando e Desativando Ferramentas #

A maioria das ferramentas é controlada na aba Habilidades de IA do Agente:

• Ferramentas de agendamento são ativadas quando você habilita agendamentos e conecta um calendário, no cartão Agendamentos na mesma aba Habilidades de IA
• Ferramentas de acompanhamento são ativadas quando você habilita acompanhamentos
• Ferramentas de restaurante são ativadas quando você conecta uma conta Zenchef ou Formitable
• Pesquisa na web possui seu próprio botão de alternância na aba FAQs e Conhecimento
• Ferramentas de tarefas podem ser desativadas por Agente com o botão Permitir que a IA crie tarefas (elas estão ativadas por padrão; o botão de Tarefas em toda a conta em Configurações → Perfil → Recursos desativa o sistema de tarefas em todos os lugares)
• Ferramentas de atualização de contato são controladas na mesma aba Habilidades de IA — definindo se a IA pode renomear contatos ou salvar informações extras coletadas sobre eles
• Ferramentas de alerta estão sempre disponíveis; a marcação (tagging) ocorre automaticamente após cada resposta do bot (não é uma ferramenta que o bot escolhe chamar)

Se você deseja que o bot pare de usar uma ferramenta integrada específica, a maneira mais limpa é desativar o recurso subjacente (por exemplo, desative os agendamentos para desativar todas as ferramentas de agendamento).

Funções Gerenciadas por uma Automação #

Algumas entradas na sua página de Funções Personalizadas podem exibir um selo Gerenciado por automação. Elas não foram criadas aqui — elas vêm de uma automação com um gatilho de Função de Agente de IA, que confere ao seu agente uma habilidade cujas etapas você constrói visualmente na tela de automação, em vez de apontar para um endereço da web externo.

Uma função gerenciada é cuidada para você: seu nome, descrição e campos sempre seguem o que está definido no gatilho da automação, portanto, ela não pode ser editada ou excluída a partir desta página — use seu link Abrir automação e altere a própria automação. Você ainda pode escolher quais agentes a possuem da maneira normal: na aba Habilidades de IA de um agente, ela aparece ao lado das outras habilidades do agente com um botão de ligar/desligar comum (se a automação estiver pausada, a linha indicará isso — a habilidade entra em funcionamento quando a automação é ligada). Todo o restante sobre ela se comporta como qualquer outra função personalizada: a IA decide quando chamá-la, coleta os detalhes que você definiu e pode usar a resposta da automação na mesma conversa.

Se você estiver escolhendo entre as duas opções: aponte uma função personalizada comum para um sistema que já possui um endereço para chamar; crie uma automação com um gatilho de Função de Agente de IA quando o trabalho for algo que você prefere montar a partir de etapas — pesquisar algo em uma planilha ou banco de dados, ramificar com base em uma condição, criar registros — sem executar seu próprio servidor. Veja Automações.

Requisitos do Plano #

Funções personalizadas estão disponíveis em planos que incluem o recurso de funções personalizadas. Verifique sua assinatura para confirmar a disponibilidade.

Próximos passos #

• Conectar Servidores MCP ao seu Bot — um pacote de ferramentas pronto para uso em vez de uma função de cada vez.
• Agentes de IA — a página principal do grupo do AI Studio onde as Funções Personalizadas residem e onde as funções personalizadas são atribuídas a um bot.