# 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.

| | Webhooks | Funções Personalizadas |
|---|----------|------------------|
| **Direção** | Unidirecional (disparar e esquecer) | Bidirecional (chamar e aguardar) |
| **O que o bot faz** | Envia uma notificação quando algo acontece e continua o fluxo. | Chama um serviço, **pausa, aguarda a resposta** e usa o que foi retornado para continuar a conversa. |
| **Visibilidade na conversa** | O resultado do processamento é invisível para o bot — ele nunca vê o que aconteceu. | A resposta é enviada diretamente de volta para a IA, para que o bot possa citá-la, raciocinar sobre ela e responder ao cliente com base nela. |
| **Ideal para** | Registrar eventos, sincronizar dados com um CRM, acionar automações externas (Zapier, Make, n8n). | Qualquer situação em que o bot precise de uma **resposta** antes de poder responder — consultas ao vivo, preços em tempo real, geração de conteúdo sob demanda. |

**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:

| Nível de Qualidade de IA | Créditos por chamada de função personalizada | Com sua própria chave Anthropic (BYOK) conectada |
|---|---|---|
| Pro | 1 crédito | 0 créditos — executado na sua chave |
| Economy (obsoleto) | 0,5 créditos | 0 créditos — executado na sua chave |
| Max | 0,25 créditos | ainda 0,25 créditos, cobrado mesmo com sua própria chave conectada, porque o Max é executado em nosso próprio modelo |
| Mini | 0,15 créditos | ainda 0,15 créditos, cobrado mesmo com sua própria chave conectada, porque o Mini é executado em nosso próprio modelo |

---

## 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:

| Coluna | O que mostra |
|--------|--------------|
| **Nome** | O nome da função (por exemplo, `check_order_status`) |
| **Descrição** | Um breve resumo do que a função faz (truncado para 50 caracteres na tabela) |
| **Método** | O método HTTP usado, exibido como um selo colorido: GET (azul), POST (verde), PUT (laranja), DELETE (vermelho) |
| **Criado** | A data em que a função foi criada |

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

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


| Campo | O que inserir | Exemplo |
|-------|--------------|---------|
| **Nome** | Um nome curto usando letras, números e sublinhados | `check_order_status` |
| **Descrição** | Explique o que esta função faz (a IA lê isso para decidir quando usá-la) | "Consulta o status atual do pedido de um cliente usando o número do pedido" |
| **Propósito (Ação da IA)** | Diga à IA exatamente quando e como usar esta função | "Use isto quando um cliente perguntar sobre o status do pedido, envio ou entrega. Peça o número do pedido primeiro." |

**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:

| Campo | O que inserir | Exemplo |
|-------|--------------|---------|
| **URL** | O endereço web do endpoint do seu sistema (o endereço específico no seu sistema que recebe a solicitação e envia dados de volta) | `https://api.yourstore.com/v1/orders/status` |
| **Método** | O tipo de solicitação a ser enviada | Veja as opções abaixo |

**Qual método escolher:**

| Método | Quando usar |
|--------|---------------|
| **GET** | Consultar informações (status do pedido, inventário, detalhes da conta) |
| **POST** | Criar novos registros (tickets de suporte, leads, reservas) ou consultas complexas |
| **PUT** | Atualizar um registro existente completamente |
| **PATCH** | Atualizar parte de um registro existente |
| **DELETE** | Remover um registro |

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:

| Cabeçalho | Valor de Exemplo |
|--------|--------------|
| `Authorization` | `Bearer your-api-key-here` |
| `Content-Type` | `application/json` |

**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:

| Propriedade | O que significa |
|----------|--------------|
| **Nome** | O nome do parâmetro (deve corresponder ao que seu sistema espera) |
| **Tipo** | Que tipo de dado é (texto, número, verdadeiro/falso, etc.) |
| **Descrição** | Diga à IA o que é essa informação e onde encontrá-la na conversa |
| **Obrigatório** | Se definido como Sim, o bot solicitará essa informação ao cliente antes de prosseguir |

**Tipos de parâmetros disponíveis:**

| Tipo | O que significa |
|------|--------------|
| **string** | Texto (nomes, números de pedido, endereços) |
| **number** | Um valor numérico (quantidade, preço) |
| **boolean** | Verdadeiro ou falso (valores sim/não) |
| **array** | Uma lista de itens. Enviada como uma lista JSON real — no **Run Test** você pode digitá-la como `[8624]`, `["a", "b"]` ou simplesmente separada por vírgulas (`8624, 8625`) e ela é convertida para você. Se sua API for rigorosa quanto ao que a lista contém — por exemplo, apenas números — defina o **Item type** opcional ao lado do tipo e cada valor na lista será convertido para ele. |
| **query_param** | Texto que é enviado como um parâmetro de URL em vez de no corpo da requisição. Use isso quando sua API espera dados na URL (por exemplo, `?order_id=123`). |

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`:

| Campo do Sistema | O que ele contém |
|-------------|----------------|
| `system.contactId` | O ID da plataforma do contato na conversa |
| `system.campaignId` | O ID da campanha à qual a conversa pertence |
| `system.userId` | Seu ID de usuário |
| `system.channel` | O canal de mensagens (por exemplo, `"whatsapp"`, `"instagram"`) |
| `system.contact` | O registro completo do contato (nome, telefone, e-mail, tags, etc.) |
| `system.campaign` | A configuração da campanha |
| `system.test` | `true` se este for um teste de Experimentação, `false` para conversas ao vivo |

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

> **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 de campanha. 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](../ai-agents/ai-agents.md) em **AI Studio → Agentes de IA**.
2. Vá para a aba **Habilidades de IA** (AI Abilities). (Para uma campanha que ainda mantém suas próprias configurações de IA diretamente, em vez de através de um Agente separado, a mesma lista aparece na própria etapa de **Habilidades de IA** daquela campanha.)
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](#step-3-add-authentication-headers) é 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 — credenciais incorretas, endpoint fora do ar, tempo limite — a conversa agora exibe 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 indicar exatamente o que corrigir (um `401` com uma mensagem "unauthorized" significa o cabeçalho de autenticação, um tempo limite significa que seu endpoint levou mais de 30 segundos).

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.

---

## 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](mcp-servers.md#ready-made-example-connect-a-shopify-store).)

**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](https://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 <span data-t="appName">Your AI Connector</span>. 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](#assigning-functions-to-an-agent)). Este é o motivo mais comum pelo qual uma função criada corretamente nunca é disparada.

::: tip
**Dica:** o bot também possui uma ferramenta integrada de **Atualizar E-mail do Contato**, que salva o endereço no registro do contato dentro da plataforma. Isso é separado desta função e útil em conjunto com ela — a ferramenta integrada mantém seu próprio registro de contato completo, a função personalizada envia o endereço para o seu CRM.
:::


---

## 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. **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.

---

## 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. Habilite 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 acidentalmente duas vezes.

**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).

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 (e sua campanha vinculada) 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:

| Nível de Qualidade de IA | Créditos por chamada de ferramenta | Com sua própria chave Anthropic (BYOK) conectada |
|---|---|---|
| Pro | 1 crédito | 0 créditos — executado na sua chave |
| Economy (obsoleto) | 0,5 créditos | 0 créditos — executado na sua chave |
| Max | 0,25 créditos | ainda 0,25 créditos, cobrado mesmo com sua própria chave conectada, porque o Max é executado em nosso próprio modelo |
| Mini | 0,15 créditos | ainda 0,15 créditos, cobrado mesmo com sua própria chave conectada, porque o Mini é executado em nosso próprio modelo |

### Ferramentas de Equipe e Tarefas

| Ferramenta | O que ela faz | Quando o bot a utiliza |
|------|--------------|----------------------|
| **Alertar um Membro da Equipe** | Pausa o bot para este contato e envia um e-mail para sua equipe informando que um humano é necessário. O chat é sinalizado para que um colega possa assumi-lo. | Quando o cliente pede por um humano, está frustrado ou pergunta algo que o bot não tem permissão ou capacidade de responder. |
| **Criar uma Tarefa** | Cria uma nova tarefa no seu quadro de tarefas, opcionalmente vinculada ao contato e à conversa. O bot continua respondendo normalmente — a tarefa é apenas um lembrete para sua equipe acompanhar. | Para itens não urgentes, como uma solicitação de recurso, uma oportunidade de upsell ou um retorno de chamada que a equipe deve tratar mais tarde. |
| **Sugerir uma Atualização de FAQ** | Quando o bot encontra uma pergunta que não consegue responder bem, ele cria uma tarefa pedindo à sua equipe que adicione uma resposta à base de conhecimento. | Quando um contato pergunta algo não coberto pelas suas FAQs existentes — para que a lacuna seja corrigida na próxima vez. |
| **Adicionar Contexto a uma Sugestão de FAQ** | Se outro contato perguntar algo semelhante mais tarde com um ângulo diferente, o bot anexa esse contexto à sugestão de FAQ existente em vez de criar uma tarefa duplicada. | Automático — mantém sua lista de tarefas organizada quando várias pessoas levantam a mesma lacuna de conhecimento. |

### Ferramentas de Contato

| Ferramenta | O que faz | Quando o bot a utiliza |
|------|--------------|----------------------|
| **Marcação** | Executa automaticamente após cada resposta do bot — não é uma ferramenta que o bot voltado para o cliente decide chamar. O sistema revisa a conversa recente e aplica tags relevantes, reutilizando suas tags existentes sempre que possível (e criando uma nova apenas quando necessário). | Automático — sempre que a conversa revela algo que vale a pena segmentar, como interesse, intenção, qualidade do lead ou idioma. |
| **Atualizar Nome do Contato** | Salva o primeiro e/ou último nome do contato quando ele o compartilha. | Quando o cliente se apresenta ou corrige um nome. |
| **Atualizar E-mail do Contato** | Salva o endereço de e-mail do contato quando ele o compartilha. | Quando o cliente fornece um e-mail — para newsletters, recibos, consultas de conta, etc. |

### Ferramentas de Agendamento e Reservas

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

| Ferramenta | O que ela faz | Quando o bot a utiliza |
|------|--------------|----------------------|
| **Verificar Horários Disponíveis** | Procura quais horários estão livres no seu calendário conectado para uma data ou intervalo de datas específico. | Quando o cliente deseja agendar e o bot precisa oferecer disponibilidade real. |
| **Agendar um Compromisso** | Cria o compromisso no seu calendário e confirma o agendamento para o cliente. | Após o cliente confirmar uma data e hora específicas. |
| **Mover um Compromisso** | Reagenda um compromisso existente para uma nova data e hora. | Quando o cliente pede para reagendar. |
| **Cancelar um Compromisso** | Cancela um compromisso existente. | Quando o cliente pede para cancelar. |
| **Consultar Compromissos** | Busca os compromissos existentes de um contato para que o bot saiba o que já está agendado. | Quando o cliente pergunta "quando é meu compromisso?" ou antes de oferecer o reagendamento. |

### Ferramentas de Conhecimento e Web

| Ferramenta | O que ela faz | Quando o bot a utiliza |
|------|--------------|----------------------|
| **Pesquisar em seu site** | Analisa as URLs que você adicionou à lista de URLs dinâmicas da campanha para encontrar páginas de produtos, artigos ou outros conteúdos que respondam à pergunta do cliente. Disponível apenas quando a **Pesquisa Web por IA** está ativada e você adicionou pelo menos uma URL dinâmica. Se a Pesquisa Web por IA estiver desativada, o bot não consegue ler páginas ou links — mesmo aqueles que o cliente cola no chat. | Quando o cliente pergunta sobre algo que provavelmente está em seu site — produtos, preços, locais, políticas. |
| **Verificar um link** | Lê o conteúdo de uma URL específica para que o bot possa responder a perguntas sobre essa página. Disponível apenas quando a **Pesquisa Web por IA** está ativada e você adicionou pelo menos uma URL dinâmica. Se a Pesquisa Web por IA estiver desativada, o bot não consegue ler páginas ou links — mesmo aqueles que o cliente cola no chat. | Quando o cliente compartilha um link ou pergunta sobre uma página específica em seu site. |
| **Pesquisar na Web** | Executa uma pesquisa pública no Google e retorna os principais resultados, para que o bot possa responder a perguntas fora do seu próprio conteúdo. | Quando o cliente pergunta sobre algo geral (por exemplo, direções, informações públicas) que não está na sua base de conhecimento. Usado apenas se a pesquisa na web estiver ativada. |

### Ferramentas de Acompanhamento (Follow-Up)

Essas ferramentas exigem que os acompanhamentos (follow-ups) estejam ativados na campanha vinculada ao seu Agente.

| Ferramenta | O que ela faz | Quando o bot a utiliza |
|------|--------------|----------------------|
| **Agendar um Acompanhamento Inteligente** | Agenda uma mensagem de acompanhamento inteligente usando sua sequência de acompanhamento — escolhe o modelo e o momento certos com base na conversa. | Quando o cliente fica em silêncio ou pede ao bot para "verificar mais tarde". |
| **Agendar um Acompanhamento** | Agenda um acompanhamento básico em um horário específico. | Quando o bot precisa impulsionar a conversa em um momento definido. |

### Executor de Funções Personalizadas

| Ferramenta | O que ela faz | Quando o bot a utiliza |
|------|--------------|----------------------|
| **Executar uma Função Personalizada** | Executa uma das funções personalizadas que você criou e atribuiu ao Agente (veja o restante desta página). | Quando a solicitação do cliente corresponde ao objetivo de uma de suas 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.

| Ferramenta | O que ela faz | Quando o bot a utiliza |
|------|--------------|----------------------|
| **Verificar Disponibilidade do Restaurante** | Procura horários de reserva abertos para uma data, número de pessoas e (opcionalmente) área de assentos. | Quando um cliente pede para reservar uma mesa. |
| **Criar uma Reserva de Restaurante** | Cria uma nova reserva. | Após o cliente confirmar um horário específico. |
| **Atualizar uma Reserva de Restaurante** | Altera a data, hora, número de pessoas ou observações de uma reserva existente. | Quando o cliente pede para modificar sua reserva. |
| **Cancelar ou Alterar Status da Reserva** | Cancela uma reserva ou atualiza seu status (ex: confirmado, não compareceu). | Quando o cliente cancela, ou quando o bot precisa marcar uma mudança de status. |
| **Pesquisar Reservas** | Encontra reservas existentes que correspondem a critérios como nome, e-mail ou data. | Quando um cliente recorrente pergunta sobre uma reserva existente. |
| **Atualizar Perfil do Cliente** | Atualiza o perfil do cliente no sistema do restaurante (preferências, observações, informações de contato). | Quando o cliente compartilha preferências alimentares, um novo número de telefone ou outras informações de perfil. |
| **Listar Produtos do Restaurante** | Puxa a lista de menus, menus fixos ou adicionais disponíveis para reserva. | Quando o cliente pergunta "quais menus fixos vocês têm?" ou o bot precisa anexar um menu a uma reserva. |

### Ativando e Desativando Ferramentas

A maioria das ferramentas é controlada na aba **Habilidades de IA** do Agente (ou na etapa **Habilidades de IA** da campanha, se você estiver trabalhando em uma campanha ainda clássica):

- **Ferramentas de agendamento** são ativadas quando você habilita agendamentos e conecta um calendário — isso permanece uma configuração por campanha por enquanto, com um link direto para a etapa dessa campanha a partir da própria aba de Habilidades de IA do Agente
- **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** tem seu próprio botão de alternância na aba **FAQs e Conhecimento**
- **Ferramentas de tarefas** podem ser desativadas por Agente com a opção **Permitir que a IA crie tarefas** (elas estão ativadas por padrão; o botão de alternância de Tarefas em toda a conta em **Configurações → Perfil → Recursos** desativa todo o sistema de tarefas em todos os lugares)
- **Ferramentas de atualização de contato** são controladas na mesma aba **Habilidades de IA** — se a IA pode renomear contatos ou salvar informações extras coletadas neles
- **Ferramentas de alerta** estão sempre disponíveis; a **marcação (tagging)** é executada 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](../automations/automations.md#letting-your-ai-agent-call-an-automation).

---

## 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](mcp-servers.md) — um pacote de ferramentas pronto para uso em vez de uma função de cada vez.
- [Agentes de IA](../ai-agents/ai-agents.md) — 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.