Funções Personalizadas #

As funções personalizadas permitem que o seu bot de IA se ligue a outros sistemas durante conversas em direto. Em vez de dizer “Vou verificar e já lhe respondo”, o bot pode consultar o estado de uma encomenda, verificar o inventário ou criar um registo no seu CRM (sistema de gestão de relacionamento com o cliente - o software que utiliza para acompanhar potenciais clientes e clientes, como o HubSpot ou o 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 apenas precisa de informar outro sistema de que algo aconteceu, utilize um webhook - uma mensagem automatizada unidirecional enviada para outro sistema (consulte Definições → Integrações → Webhooks). Se o bot precisar de aprender algo de outro sistema antes de continuar a conversa, utilize uma função personalizada.

Exemplos do que as Funções Personalizadas permitem #

Como a resposta é integrada na conversa, as funções personalizadas permitem realizar tarefas que os webhooks simplesmente não conseguem fazer:

• Consulta de inventário em direto no Shopify ou WooCommerce — Antes de dar um orçamento a um cliente, o bot verifica o stock em tempo real e responde “Sim, temos 12 unidades no tamanho M” em vez de “deixe-me verificar e entro em contacto consigo”.
• Preços dinâmicos a partir de uma folha Google — A sua equipa de vendas atualiza os preços numa folha; o bot lê a linha mais recente a meio da conversa e indica o preço atual sem que ninguém tenha de tocar na configuração da IA.
• Agente de retorno de chamada por voz (Voice-AI) — Quando o bot qualifica um potencial cliente, aciona um agente de voz (por exemplo, um sistema baseado em ElevenLabs) para ligar de volta ao cliente no espaço de minutos, e confirma ao cliente “ótimo, espere uma chamada nos próximos 5 minutos”.
• PDF de orçamento personalizado, gerado e enviado por e-mail a meio do chat — O bot recolhe os requisitos, chama o seu gerador de orçamentos, obtém um URL de PDF e diz ao cliente “acabei de enviar o seu orçamento por e-mail — verifique a sua caixa de entrada”.

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

Pense nas funções personalizadas como algo que confere ao seu bot superpoderes para além de apenas conversar. Eis exemplos do mundo real:

• Rastreio de encomendas - Um cliente pergunta “Onde está a minha encomenda?” e o bot verifica o seu sistema de e-commerce e responde com o estado do envio e o link de rastreio
• Verificação de inventário - “Têm isto no tamanho 10?” O bot verifica o seu sistema de stock e dá uma resposta em tempo real
• Atualizações de CRM - Quando o bot qualifica um potencial cliente, cria ou atualiza automaticamente um registo no HubSpot, Salesforce ou qualquer outro CRM
• Geração de orçamentos - O bot recolhe os requisitos do cliente e gera um orçamento personalizado a partir do seu sistema de preços
• Marcações - O bot cria um agendamento no seu sistema de marcações externo
• Verificação de descontos - “Este código de cupão é válido?” O bot verifica e confirma
• Consulta de conta - Um cliente recorrente é automaticamente reconhecido e os detalhes da sua conta são consultados

O cliente nunca vê o que acontece nos bastidores. Apenas experiencia um bot capaz de responder às suas perguntas com informações reais e atualizadas.

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

Eis o que acontece quando uma função personalizada é acionada durante uma conversa:

1. O cliente pergunta algo que necessita de dados em tempo real (por exemplo, “Onde está a minha encomenda?”)
2. O bot reconhece que precisa de usar uma função personalizada para responder
3. O bot recolhe qualquer informação em falta do cliente (por exemplo, “Qual é o número da sua encomenda?”)
4. A plataforma envia um pedido para o seu sistema (o seu site, CRM ou qualquer outra ferramenta) com os detalhes relevantes
5. O seu sistema responde com os dados (por exemplo, estado da encomenda, número de seguimento, data de entrega)
6. O bot lê a resposta e elabora uma resposta natural: “A sua encomenda ORD-4582 foi enviada e deverá chegar até sexta-feira!”

Quanto custa uma chamada de função personalizada #

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

Configurar 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 apresenta uma tabela com as seguintes colunas:

Isto torna fácil analisar as suas funções rapidamente e encontrar a que precisa.

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

Dica: Seja muito específico na descrição e no objetivo. Quanto mais claro for sobre quando a função deve ser usada, mais fiável será a utilização da mesma pelo bot no momento certo.

Passo 2: Configurar a Ligação #

Precisa de dizer à aplicação para onde enviar o pedido:

Qual o método a escolher:

Se não tiver a certeza de qual utilizar, verifique com o seu programador ou com a documentação do sistema ao qual se está a ligar. GET (para pesquisas) e POST (para criar registos) são os mais comuns.

Passo 3: Adicionar Cabeçalhos de Autenticação #

A maioria dos sistemas requer autenticação para aceitar pedidos. Adicione quaisquer cabeçalhos necessários:

Os valores de cabeçalhos que contêm uma chave ou palavra-passe, tais como Authorization ou X-API-Key, são apresentados como pontos após serem introduzidos. Clique no olho junto ao valor para o visualizar.

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

Onde encontrar chaves de API: Verifique as definições ou a secção de programador do sistema ao qual se está a ligar (por exemplo, o seu CRM, plataforma de comércio eletrónico ou ferramenta de reservas).

Passo 4: Definir a Entrada (O que o Bot Envia) #

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

Para cada parâmetro, especifica:

Tipos de parâmetros disponíveis:

Cada parâmetro tem também um campo opcional de Caminho do corpo do pedido. Normalmente, um parâmetro é enviado como um campo de nível superior no corpo do pedido (ou como um valor de string de consulta, para o tipo query_param). Se o seu endpoint esperar que este esteja aninhado — por exemplo, {"order": {"id": "ORD-123"}} — defina o caminho como order.id e a plataforma aninha o valor aí por si.

Exemplo: Para uma consulta de estado de encomenda, pode definir:

• order_number (string, obrigatório): “O número de encomenda do cliente. Normalmente começa com ORD- seguido de dígitos. Peça isto ao cliente se ele ainda não o tiver mencionado.”
• email (string, opcional): “O endereço de e-mail do cliente para verificação adicional. Apenas necessário se o número de encomenda, por si só, não encontrar uma correspondência.”

O que o seu sistema recebe automaticamente #

Para além dos parâmetros de entrada que define, a plataforma inclui automaticamente dados de sistema em cada pedido. O seu endpoint recebe isto num campo system:

Isto é útil se o seu sistema precisar de identificar o contacto, verificar que agente chamou a função ou comportar-se de forma diferente durante os testes.

Quando uma verificação de seguimento chama a sua função (ver Enviar apenas quando uma verificação é bem-sucedida), o pedido é diferente de uma chamada durante a conversação: não tem parâmetros de entrada e o campo system contém apenas system.contact (com o seu id) mais um bloco system.follow_up (type, cycle_number, follow_up_number, reason, campaign_id, agent_id). Não contém qualquer objeto campaign. A opção Ignorar Dados do Sistema também se aplica a essa chamada.

Não precisa dos dados de sistema? Ative o botão Ignorar Dados de Sistema no construtor de funções. O bot enviará apenas os parâmetros de entrada que definiu — sem dados de contacto ou de agente. Utilize isto se o seu endpoint rejeitar campos inesperados ou se pretender apenas um payload mais leve.

Passo 5: Teste-o e, em seguida, deixe o bot ler a resposta #

Normalmente, não precisa de mapear os campos de resposta de todo. Assim que o seu endpoint responde, o bot lê toda a resposta JSON e utiliza a Descrição e o Objetivo (Ação de IA) da sua função — além da descrição de cada parâmetro — para determinar o que é importante e apresentá-lo de forma natural. Uma Descrição clara na própria função (“Recupera o estado atual de uma encomenda de cliente, incluindo informações de envio e rastreio”) faz mais trabalho aqui do que o mapeamento campo a campo faria.

Se o seu endpoint devolver uma resposta grande e pretender que o bot veja apenas alguns valores específicos, abra a secção Mapeamento de resposta (recolhida por predefiniçã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 secção vazia para manter o comportamento predefinido de resposta completa.

Antes de guardar, utilize a secção Testar na parte inferior do construtor para disparar o pedido exatamente como configurado e ver a resposta real, sem sair da aplicação:

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

Atribuir Funções a um Agente #

Após criar uma função personalizada, precisa de indicar a cada Agente quais as funções que pode utilizar:

1. Abra o Agente em AI Studio → Agentes de IA.
2. Aceda ao separador Capacidades de IA.
3. Verá uma lista de todas as funções personalizadas que criou. Ative cada função que pretende que o bot deste Agente possa chamar.
4. Clique em Guardar alterações na parte inferior. As seleções só são aplicadas após serem guardadas.

Apenas as funções atribuídas estão disponíveis para o bot desse Agente. Isto evita que o bot utilize acidentalmente funções que não são relevantes.

Testar as Suas Funções Personalizadas #

Antes de entrar em funcionamento, teste exaustivamente:

1. Execute o Teste integrado - Utilize a secção Testar dentro do construtor de funções (ver acima) para uma verificação rápida sem sair da aplicação — 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 o seu programador) aprofunda mais do que um simples Executar teste.
3. Teste em Experimentar - 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 encomenda inválido? E se o seu sistema estiver temporariamente em baixo?

Quando o teste devolve 401 ou 403 #

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

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

A versão mais comum disto é um webhook protegido com Autenticação Básica (o n8n, o Make e a maioria das ferramentas autoalojadas oferecem isto como uma opção no próprio webhook), enquanto a função envia um cabeçalho secreto personalizado como X-My-Secret. A Autenticação Básica só aceita um cabeçalho Authorization, pelo que um cabeçalho personalizado é ignorado e a chamada é rejeitada. Tem duas opções:

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

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

Quando o teste devolve 404 #

O URL do endpoint está incorreto ou o fluxo de trabalho não está publicado. No n8n especificamente, cada webhook tem um URL de Teste e um URL de Produção separados, e o de Teste só funciona enquanto tiver o editor aberto. Copie o URL de Produção e certifique-se de que o fluxo de trabalho está ativo.

Ver 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 que está em baixo ou um tempo limite (timeout), a conversa mostra-o agora: um marcador vermelho “(nome da função) falhou” aparece no tópico, tanto no separador Experimentar do agente como nas conversas reais em Chats. Clique no marcador para expandir os detalhes: o código de estado que o seu endpoint devolveu 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 o seu endpoint demorou mais de 30 segundos; para uma tarefa que necessita de mais tempo, ver Tarefas de longa duração).

As chamadas bem-sucedidas também mostram um marcador — clique nele para ver o que o seu endpoint enviou realmente de volta. Esta é a forma 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 do pedido sem sair da página.

Quando uma ferramenta continua a falhar em conversas reais #

Se a mesma função personalizada falhar 3 vezes num período de 24 horas enquanto o seu agente de IA está a conversar, receberá um alerta por dia sobre o assunto: por e-mail, na secção do sino e como notificação push, caso a tenha ativado. O alerta identifica a ferramenta, mostra o último erro e inclui ligações para as conversas afetadas, uma vez que o agente terá informado esses contactos de que encontrou um problema técnico. A linha da função nas Definições apresenta um estado A falhar com a contagem de erros e o último erro até que a ferramenta volte a funcionar; uma chamada bem-sucedida limpa este estado. Pode desativar estes alertas em Definições → Notificações → Erros de ferramentas.

Exemplo Completo: Consulta do Estado da Encomenda #

Aqui tem um exemplo totalmente configurado que pode utilizar como modelo:

Informações Básicas:

• Nome: check_order_status
• Descrição: “Obtém o estado atual de uma encomenda de cliente, incluindo informações de envio e rastreio”
• Ação de IA: “Chame isto quando um cliente perguntar sobre o estado da sua encomenda, onde está a sua encomenda ou quando chegará. Peça sempre o número da encomenda primeiro.”

Ligaçã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 da encomenda fornecido pelo cliente”
• customer_email (texto, opcional): “E-mail do cliente para verificação adicional”

Não é necessário mapeamento de resposta — com uma Descrição e Ação de IA claras já definidas acima, o bot lê qualquer JSON que o seu endpoint devolva (estado, número de rastreio, data de entrega, artigos) e descobre como falar sobre isso.

Como é a conversa:

Cliente: Olá, onde está a minha encomenda?

Bot: Olá! Terei todo o gosto em verificar a sua encomenda. Pode partilhar o número da encomenda comigo?

Cliente: É a ORD-78234

Bot: Deixe-me verificar isso para si…

A sua encomenda ORD-78234 foi enviada e está a caminho! A data prevista de entrega é 10 de março. Pode rastrear a sua encomenda aqui: https://tracking.example.com/1Z999AA1

Posso ajudar com mais alguma coisa?

Exemplo Completo: Estado da Encomenda Shopify #

Se a loja utiliza Shopify, não precisa de um programador para criar um endpoint de consulta — o próprio sistema da Shopify pode responder diretamente a questões sobre encomendas. (Para questões sobre produtos e stock numa loja Shopify, não precisa de uma função personalizada: ligue o servidor integrado da loja — veja Ligar uma loja Shopify.)

Primeiro, crie um token de acesso no Shopify. O Shopify alterou isto durante 2026: as aplicações já não podem ser criadas dentro do painel de administração do Shopify, e o novo ecrã de aplicações fornece-lhe um ID de Cliente e um Segredo de cliente em vez de um token pronto a usar. Os passos abaixo transformam esses dados num token permanente. Reserve cerca de dez minutos, uma vez por loja. (Se a loja já tiver uma aplicação antiga criada da forma anterior, o seu token existente continuará a funcionar — avance diretamente para a função personalizada abaixo.)

1. Aceda ao Painel de Programador da Shopify em dev.shopify.com, abra a sua organização e clique em Apps → Create app. Dê-lhe um nome como Order lookup.
2. Dê à aplicação a permissão read_orders, publique uma versão e instale a aplicação na loja.
3. Abra as Definições da aplicação e adicione o endereço Web da própria loja (por exemplo, https://www.yourstore.com/) aos URLs de redirecionamento permitidos. Guarde.
4. Ainda nas Definições, copie o ID do cliente e o Segredo do cliente.
5. Num navegador onde tenha sessão iniciada no administrador da Shopify dessa 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 o ecrã que aparece. O navegador irá para o seu endereço de redirecionamento e a barra de endereços conterá agora code= seguido de um valor longo — copie esse valor. Só é válido durante alguns minutos, por isso avance diretamente para o passo seguinte.
6. Troque esse código pelo token, o que pode fazer dentro de Your AI Connector. No construtor de funções personalizadas, defina o Método como POST e o 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, depois clique em Testar, 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, depois limpe o construtor e configure a função real abaixo.

De seguida, configure a função personalizada:

Informações Básicas:

• Nome: check_shopify_order
• Descrição: “Consulta uma encomenda no sistema Shopify da loja e devolve o seu estado, seguimento e artigos”
• Ação de IA: “Chame isto quando um cliente perguntar sobre o estado da sua encomenda ou entrega. Peça sempre o número da encomenda primeiro.”

Ligaçã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 utiliza o domínio técnico da 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 da encomenda do cliente exatamente como aparece na confirmação da encomenda, incluindo o sinal # — por exemplo #1001. Peça-o ao cliente caso este ainda não o tenha mencionado.”

Não é necessário mapeamento de resposta — o bot lê a encomenda devolvida (estado do pagamento, estado do cumprimento, seguimento, artigos) e responde de forma natural.

Bom saber: um token criado desta forma pode ver encomendas dos últimos 60 dias — suficiente para questões de apoio diárias, mas não para um histórico completo de encomendas.

Exemplo Completo: Marcar uma Consulta #

Informações Básicas:

• Nome: create_booking
• Descrição: “Cria uma nova marcação no nosso sistema de reservas”
• Ação de IA: “Utilize isto após confirmar a data, hora e detalhes de contacto com o cliente. Não chame até que o cliente confirme explicitamente que pretende marcar.”

Ligação:

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

Parâmetros de Entrada:

• date (texto, obrigatório): “Data da marcação no formato AAAA-MM-DD”
• time (texto, obrigatório): “Hora da marcação 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 a ser marcado”

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

Um padrão muito comum: o bot termina de responder, oferece a sua newsletter, o contacto responde com o seu endereço de e-mail e esse endereço deve ser enviado diretamente para a sua ferramenta de e-mail. A maioria dos CRMs (FluentCRM, ActiveCampaign, MailerLite, Brevo e outros) aceita um simples POST para este efeito, pelo que não é necessária uma plataforma de automação intermédia.

Este exemplo utiliza o FluentCRM no WordPress. A estrutura é a mesma para qualquer outra ferramenta que lhe forneça um “webhook de entrada” ou um endpoint de “criar subscritor”.

Primeiro, obtenha o URL do seu CRM. No WordPress, abra FluentCRM → Definições → Webhooks de Entrada e crie um webhook. Escolha a lista, as etiquetas e o estado de subscrição que os novos contactos devem receber e, em seguida, copie o URL do webhook gerado. Tudo o que definir aqui é aplicado automaticamente, pelo que o bot apenas tem de enviar o endereço de e-mail.

De seguida, configure a função personalizada:

Informações Básicas:

• Nome: add_newsletter_subscriber
• Descrição: “Adiciona alguém à nossa lista de newsletter utilizando o endereço de e-mail fornecido no chat”
• Ação de IA: “Utilize isto no momento em que o contacto concorda em subscrever a newsletter e fornece o seu endereço de e-mail. Não a invoque antes de terem fornecido um endereço e não a invoque duas vezes para a mesma pessoa.”

Ligação:

• URL: o URL do webhook que copiou do seu CRM
• Método: POST

Parâmetros de Entrada:

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

Ignorar Dados do Sistema: ative esta opção (on). O seu CRM apenas necessita dos campos acima, e um payload mais leve evita erros de ferramentas que rejeitam campos inesperados.

Mapeamento de resposta: não é necessário aqui. Não é preciso que nada seja devolvido para que o bot continue.

Não se esqueça de ativar a função para o Agente que executa a conversação (consulte Atribuir Funções a um Agente). Esta é a razão mais comum para uma função corretamente criada nunca ser disparada.

Dicas para Funções Personalizadas Fiáveis #

1. Certifique-se de que pedidos repetidos são seguros. Se o mesmo pedido for enviado acidentalmente duas vezes, não deverá criar registos duplicados. Falhas na rede podem causar isto ocasionalmente.

2. Devolva mensagens de erro claras. Se algo correr mal do lado do seu sistema, devolva um erro legível por humanos. O bot irá transmiti-lo ao cliente de forma elegante.

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

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

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

6. Teste com conversas reais. O Try Out é excelente para testes iniciais, mas monitorize as suas primeiras conversas em direto para garantir que tudo funciona com pedidos reais dos clientes.

7. Mantenha registos (logs) do seu lado. Peça ao seu programador para registar os pedidos provenientes da aplicação para que possa depurar rapidamente quaisquer problemas.

8. Se a sua firewall necessitar de uma lista de permissões de IP, cada chamada de função personalizada (e cada verificação de seguimento) é enviada a partir de um endereço IPv4 fixo, o mesmo que os nossos webhooks utilizam; sem intervalos, sem IPv6, sem rotação. Contacte o suporte e fornecer-lhe-emos o endereço. Ative a assinatura de pedidos e verifique a assinatura como a sua verdadeira verificação de confiança, tratando o IP como um filtro adicional.

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

Tarefas de longa duração: obter o resultado mais tarde #

Normalmente, uma função personalizada tem de responder no prazo de 30 segundos, enquanto o contacto aguarda a resposta. Algumas tarefas demoram mais tempo do que isso: processar um vídeo, executar uma verificação de crédito, esperar que alguém do seu lado aprove algo. Para esses casos, ative O resultado chega mais tarde (longa duração). A chamada da IA apenas inicia a tarefa. O seu serviço responde imediatamente, a IA informa o contacto de que o resultado está a caminho e continua a conversa, e o seu serviço envia o resultado para uma ligação de retorno (callback) assim que estiver concluído.

Quando utilizar #

Utilize-a quando o seu serviço não consegue responder de forma fiável no prazo de 30 segundos. Deixe-a desativada para consultas rápidas (um estado de encomenda, uma verificação de stock, um preço): estas são mais simples como uma chamada normal, porque a IA responde com o resultado na mesma resposta.

As definições no editor #

Encontra-as no editor de funções personalizadas, junto a Ignorar Dados de Sistema.

O que o seu serviço recebe #

Com o interruptor ativado, cada chamada transporta a ligação de retorno em três locais, além de tudo o que foi descrito acima (os seus parâmetros de entrada, o bloco system e os cabeçalhos de assinatura):

A ligação é única para cada chamada, pertence a esse contacto e a essa chamada, funciona uma vez e expira após o tempo definido em Esperar até. Não precisa de uma chave de API para a utilizar: a própria ligação é a permissão. Trate-a como uma palavra-passe e nunca a escreva num registo público.

Enviar o resultado #

Quando a tarefa estiver concluída, envie um POST para a ligação 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 tal como está, o contacto recebe message quando envia um, caso contrário result quando é texto.
• media_url é opcional: uma ligação https para um ficheiro (imagem, vídeo, áudio ou documento) que o contacto recebe como um anexo real, não como uma ligação. Consulte Enviar um ficheiro abaixo.
• Também pode enviar um corpo de texto simples com Content-Type: text/plain. É tratado como result.
• O corpo pode ter até 64 KB.

O que o link de callback responde:

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

1. A IA chama a sua função. 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. O seu serviço inicia a renderização e responde imediatamente:

{ "status": "started" }

3. A IA informa o contacto de que o vídeo está a ser criado e continua a conversar.
4. Três minutos depois, o seu serviço publica o resultado no link de callback:

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

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

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

O que acontece no chat #

O resultado é guardado na conversação como uma entrada de função, pelo que o vê na caixa de entrada como qualquer outra chamada de função personalizada. Depois, dependendo de Quando o resultado chega, a IA escreve e envia a mensagem seguinte (isto custa uma resposta da IA, como qualquer mensagem da IA), ou o seu texto é enviado tal como está. Com Enviar o texto tal como está, o campo message é enviado quando inclui um, caso contrário result quando é texto simples; se publicar apenas um objeto sem texto, a IA escreve a mensagem em vez disso.

Se a IA estiver desligada para esse contacto quando o resultado chegar (um membro da equipa assumiu o controlo, a IA foi pausada, o agente está desligado ou sem créditos), o resultado continua a ser guardado na conversação, mas não é enviada nenhuma mensagem. Também não é enviado mais tarde quando a IA é ligada novamente. O membro da equipa vê o resultado no chat e pode utilizá-lo.

No separador Experimentar do agente, todo o fluxo também funciona: o resultado chega ao chat de teste.

Enviar um ficheiro (vídeo, imagem, PDF) #

Um resultado que seja um ficheiro, por exemplo, um vídeo que o seu serviço processou em segundo plano, chega ao contacto como um anexo que este pode abrir no chat, em ambos os modos. A plataforma encontra o ficheiro no seu callback da seguinte forma:

1. media_url no corpo, quando envia um.
2. Caso contrário, um campo de ficheiro no objeto result: file_url, video_url, image_url, pdf_url, document_url, audio_url, attachment_url ou download_url.
3. Caso contrário, a primeira ligação https no texto que termine numa extensão de ficheiro como .mp4, .jpg, .png ou .pdf.

Com A IA escreve a mensagem seguinte, a IA escreve o texto e o ficheiro é anexado a essa mensagem (a IA é instruída para não colar a ligação). Com Enviar o texto tal como está, o 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 ficheiros podem ter até 16 MB e devem ser acessíveis através de https. Cada canal suporta tipos diferentes: por exemplo, o e-mail e os canais WhatsApp aceitam vídeo, imagens, áudio e documentos; o SMS não suporta ficheiros. Quando um canal não consegue aceitar o ficheiro, ou o ficheiro é demasiado grande, o contacto recebe a mensagem na mesma, com a ligação para o ficheiro adicionada no final.

Quando o resultado nunca chega #

Se nada for publicado antes de Aguardar até terminar, a IA é informada de que o resultado nunca chegou, para que possa avisar o contacto. Uma entrada com o código APP-3103 aparece em Definições → Registo de erros e recebe uma notificação de erro da ferramenta.

Limites num relance #

• Um resultado por ligação de callback. Publicações posteriores na mesma ligação são respondidas como duplicadas e não alteram nada.
• Até 64 KB por resultado.
• Um ficheiro por resultado, até 16 MB, através de https.
• Até 20 publicações por minuto para uma ligação.
• Aguardar até de 1 a 168 horas.
• O seu serviço continua a ter 30 segundos para responder à primeira chamada.

Verificar se uma chamada veio realmente da nossa parte #

Qualquer pessoa que descubra o URL da sua função pode enviar-lhe um pedido falso. Um segredo longo num cabeçalho de autenticação ajuda, mas é o mesmo valor em todas as chamadas, pelo que qualquer pessoa que veja um pedido (num registo ou numa captura de ecrã) pode reutilizá-lo. A assinatura de pedidos resolve isso: cada chamada transporta uma assinatura que apenas alguém que possua o seu segredo pode produzir, e que expira após alguns minutos.

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

Ativar a assinatura #

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

A partir do mesmo cartão, pode copiar o segredo novamente, Rodá-lo (o antigo deixa de funcionar imediatamente) ou Desativar a assinatura.

O que enviamos #

Assim que a assinatura estiver ativa, cada chamada efetuada por uma função personalizada transporta dois cabeçalhos adicionais: as chamadas da IA durante uma conversa, as condições de envio de seguimento e o botão Executar Teste no editor.

Todas as chamadas, assinadas ou não, transportam também o User-Agent: Custom-Function/1.0, a menos que defina o seu próprio cabeçalho User-Agent.

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

Como verificar #

A assinatura é um HMAC-SHA256 da cadeia <timestamp>.<raw request body>, utilizando o seu segredo de assinatura como chave. Verifique-a em relação ao corpo raw (bruto), os bytes exatos que recebeu: analisar o JSON e convertê-lo novamente em texto pode alterar os bytes, e a assinatura não coincidirá.

Uma função que utiliza GET (ou um POST sem nada para enviar) não tem corpo, pelo que a cadeia assinada é apenas <timestamp>. com um corpo vazio. A assinatura prova então que a chamada veio da nossa parte e é recente, mas não cobre a cadeia de consulta (query string).

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-o com Executar Teste no editor: assim que a assinatura estiver ativa, a chamada de teste é assinada exatamente como uma chamada real, pelo que uma função que passe no teste também passará na sua verificação durante conversas reais.

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

Limites de execução #

Cada função personalizada tem uma secção opcional de Limites de execução na parte inferior do editor. Esta controla a frequência com que 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 comportar-se-á exatamente como antes.

Função só de leitura. Ative esta opção se a sua função apenas lê dados — uma consulta de stock, uma verificação de preço, uma pesquisa de estado de encomenda — e nunca cria ou altera nada. Quando uma falha temporária na rede interrompe a IA a meio de uma resposta, a plataforma pode repetir o turno da conversação em segurança, em vez de deixar o cliente sem resposta. Apenas ative esta opção se a função nunca escrever nada: uma função que cria registos deve permanecer desativada, para que uma repetição nunca a execute acidentalmente duas vezes. As funções que utilizam o método GET são tratadas automaticamente como só de leitura, uma vez que os pedidos GET destinam-se apenas a obter dados; as funções POST, PUT, PATCH e DELETE necessitam deste interruptor.

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 o seu endpoint novamente. Os resultados em cache são mantidos por até 24 horas, e uma chamada com entradas diferentes vai sempre ao seu endpoint para obter dados atualizados.

Máximo de execuções por conversa. Um limite rígido sobre quantas vezes a função pode ser executada dentro de uma conversa. Defina como 1 para funções que só devem ser acionadas uma vez por chat — gerar um orçamento, solicitar um contacto, iniciar uma automatização. Quando o limite é atingido, a IA é informada de que a função já foi executada e recebe o resultado mais recente, para que possa continuar a responder ao cliente em vez de ficar em silêncio.

Máximo de execuções por janela de tempo. Um limite de taxa ao longo do tempo: por exemplo, no máximo 5 execuções dentro de 60 minutos. Útil para funções que chamam serviços de terceiros pagos ou acionam automatizações mais pesadas. Ambas as caixas devem ser preenchidas em conjunto (um número de execuções e uma janela em minutos, até 7 dias).

Enviar ofertas, contratos ou faturas no LinkedIn. Quando a IA responde no LinkedIn, fá-lo a partir da caixa de entrada do próprio proprietário da conta, pelo que não deve enviar uma oferta, contrato, orçamento, fatura, link de pagamento ou acesso em nome do proprietário, a menos que este o tenha autorizado. Com Automático (a predefinição), uma função cujo nome ou descrição indique que envia um destes elementos não é executada no LinkedIn: a IA é informada de que nada foi enviado e comunica à pessoa que o proprietário tratará do assunto. Escolha Permitido para permitir que a função seja executada no LinkedIn de qualquer forma, ou Nunca no LinkedIn para bloquear uma função que a verificação automática possa não detetar. Outros canais não são afetados e, ao contrário dos limites acima, esta definição também se aplica em Experimentar. Algumas coisas a saber:

• Os limites contam apenas as 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 a informação que já possui.
• Os limites aplicam-se a todos os locais onde a função é executada: chats regulares em todos os canais e funções geridas por uma automatização. As conversas de teste em “Experimentar” não são contabilizadas nem limitadas.

Ferramentas de Bot Integradas #

Para além das funções personalizadas que cria, a plataforma inclui uma biblioteca de ferramentas pré-criadas que o bot de IA pode utilizar durante uma conversa. Estas cobrem as tarefas mais comuns que um bot precisa de realizar — alertar um colega de equipa, marcar uma reunião, etiquetar um contacto, pesquisar no seu site, agendar um seguimento, e muito mais — para que não tenha de as configurar do zero.

O bot decide quando utilizar cada ferramenta com base no que está a acontecer na conversação e na forma como o seu Agente está configurado. A maioria destas ferramentas é ativada automaticamente quando a funcionalidade relacionada é ativada (por exemplo, as ferramentas de marcação só ficam disponíveis depois de ligar um calendário e ativar as marcações).

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

Ferramentas de Equipa e Tarefas #

Ferramentas de Contacto #

Ferramentas de Marcação e Agendamento #

Estas ferramentas só estão disponíveis quando as marcações estão ativadas no seu Agente e um tipo de evento de calendário está configurado.

Ferramentas de Conhecimento e Web #

Ferramentas de Acompanhamento #

Estas ferramentas requerem que os seguimentos (follow-ups) estejam ativados no seu Agente.

Executor de Funções Personalizadas #

Ferramentas de Reserva de Restaurantes (Zenchef e Formitable) #

Estas ferramentas só estão disponíveis quando uma integração Zenchef ou Formitable está ligada. Permitem que o bot faça a gestão de reservas de restaurantes de ponta a ponta.

Ligar e Desligar Ferramentas #

A maioria das ferramentas é controlada no separador Capacidades de IA do Agente:

• As ferramentas de marcação ativam-se quando ativa as marcações e liga um calendário, no cartão Marcações no mesmo separador Capacidades de IA
• As ferramentas de seguimento ativam-se quando ativa os seguimentos
• As ferramentas de restaurante ativam-se quando liga uma conta Zenchef ou Formitable
• A pesquisa web tem o seu próprio botão no separador FAQs e Conhecimento
• As ferramentas de tarefas podem ser desativadas por Agente com o botão Permitir que a IA crie tarefas (estão ativadas por predefinição; o interruptor de Tarefas para toda a conta em Definições → Perfil → Funcionalidades desativa todo o sistema de tarefas em todo o lado)
• As ferramentas de atualização de contactos são controladas no mesmo separador Capacidades de IA — se a IA pode ou não mudar o nome de contactos ou guardar informações extra recolhidas sobre eles
• As ferramentas de alerta estão sempre disponíveis; a etiquetagem ocorre automaticamente após cada resposta do bot (não é uma ferramenta que o bot escolha chamar)

Se quiser que o bot pare de utilizar uma ferramenta integrada específica, a forma mais limpa é desativar a funcionalidade subjacente (por exemplo, desative as marcações para desativar todas as ferramentas de marcação).

Funções geridas por uma automatização #

Algumas entradas na sua página de Funções Personalizadas podem apresentar um emblema de Gerida por automatização. Estas não foram criadas aqui — provêm de uma automatização com um gatilho de Função de Agente de IA, que confere ao seu agente uma capacidade cujos passos constrói visualmente na tela de automatização, em vez de apontar para um endereço Web externo.

Uma função gerida é tratada por si: o seu nome, descrição e campos seguem sempre o que está definido no acionador da automatização, pelo que não pode ser editada ou eliminada a partir desta página — utilize a ligação Abrir automatização e altere a própria automatização. Pode, no entanto, continuar a escolher quais os agentes que a possuem da forma habitual: no separador Capacidades de IA de um agente, esta aparece ao lado das outras capacidades do agente com um interruptor de ligar/desligar normal (se a sua automatização estiver em pausa, a linha indica-o — a capacidade fica ativa quando a automatização é ligada). Tudo o resto funciona como qualquer outra função personalizada: a IA decide quando a chamar, recolhe os detalhes que definiu e pode utilizar a resposta da automatização na mesma conversa.

Se estiver a escolher entre as duas opções: aponte uma função personalizada normal para um sistema que já tenha um endereço para chamar; crie uma automatização com um gatilho de Função de Agente de IA quando o trabalho for algo que prefere montar a partir de passos — pesquisar algo numa folha de cálculo ou base de dados, ramificar com base numa condição, criar registos — sem ter de executar o seu próprio servidor. Consulte Automatizações.

Requisitos do Plano #

As funções personalizadas estão disponíveis nos planos que incluem a funcionalidade de funções personalizadas. Verifique a sua subscrição para confirmar a disponibilidade.

Próximos Passos #

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