> ## Documentation Index
> Fetch the complete documentation index at: https://mayahub.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ferramentas Personalizadas Durante a Chamada

> Aprenda como criar e configurar integrações personalizadas de API que seu assistente de IA pode usar durante as chamadas 

<Note>
  As Ferramentas Personalizadas Durante a Chamada permitem que seu assistente de IA interaja com sistemas externos durante as chamadas. Seja para verificar estoque, confirmar dados do cliente ou buscar informações em tempo real, essas ferramentas tornam seu assistente mais poderoso e conectado.
</Note>

## **Visão Geral**

As Ferramentas Personalizadas Durante a Chamada permitem que seu assistente de IA:

* Faça chamadas de API em tempo real durante as conversas
* Busque ou envie dados para seus sistemas
* Tome decisões informadas com base em dados ao vivo
* Forneça informações precisas e atualizadas aos clientes

<Card title="Principais Benefícios" icon="star">
  - Não é necessário programar — basta configurar o endpoint da API e os parâmetros.\
    O assistente de IA sabe automaticamente quando e como usar as ferramentas.
    * Acesso a dados em tempo real durante as chamadas
    * Integração perfeita com seus sistemas existentesSetting Up Your Tool
</Card>

### 1. Configuraçao Básica

<Frame>
  <img src="https://mintcdn.com/mayahub/jLorboul40ctksf_/images/mid-callGET.avif?fit=max&auto=format&n=jLorboul40ctksf_&q=85&s=8fe51299ebe4711021d19060251ef4ba" alt="mid-callGET.avif" width="560" height="381" data-path="images/mid-callGET.avif" />
</Frame>

<Steps>
  <Step title="Acessar Criação de Ferramenta">
    Navegue até **Ferramentas Durante a Chamada** e clique em **Criar Ferramenta Durante a Chamada**

    Preencha os detalhes essenciais:
  </Step>

  <Step title="Configurar Configurações Principais">
    * **Nome:** Use letras minúsculas e underscores (ex.: `check_order_status`)
    * **Descrição:** Explique quando e como a IA deve usar esta ferramenta
    * **Endpoint:** URL da sua API (ex.: `https://api.suaempresa.com/pedidos`)
    * **Timeout:** Tempo de espera pela resposta (em segundos)
    * **Método:** Escolha entre `GET`, `POST`, `PUT`, `PATCH` ou `DELETE`
  </Step>

  <Step title="Add Headers">
    Headers comuns que você pode precisar:

    ```yaml theme={null}
    Content-Type: application/json
    Authorization: Bearer your_token
    ```
  </Step>
</Steps>

### 2. Configurações Variáveis

<Frame>
  <img src="https://mintcdn.com/mayahub/jLorboul40ctksf_/images/mid-call-param.avif?fit=max&auto=format&n=jLorboul40ctksf_&q=85&s=f3851e81c19ec16ff943461e591f61d1" alt="mid-call-param.avif" width="2506" height="776" data-path="images/mid-call-param.avif" />
</Frame>

<Steps>
  <Step title="Defina Parâmetros">
    Estas são as informações que seu assistente de IA irá coletar durante a chamada:

    ```yaml theme={null}
    Name: order_number
    Type: string
    Description: "10-digit order number from the customer"
    ```
  </Step>

  <Step title="Definir Regras de Validação">
    Adicione formatos requeridos na descrição

    ```yaml theme={null}
    "Date in dd/mm/yyyy format"
    "Phone number without spaces"
    "Email address for confirmation"
    ```
  </Step>
</Steps>

## Entendendo os Tipos de Parâmetros

<CardGroup cols={2}>
  <Card title="Texto" icon="font">
    Valores de texto, como nomes, endereços ou números de referência

    ```yaml theme={null}
    Type: string
    Examples: "John Doe", "123 Main St"
    ```
  </Card>

  <Card title="Número" icon="calculator">
    Valores numéricos, como quantias, quantidades ou IDs

    ```yaml theme={null}
    Type: number
    Examples: 42, 99.99
    ```
  </Card>

  <Card title="Verdadeiro_Falso" icon="toggle-on">
    Valores booleanos para situações de sim/não

    ```yaml theme={null}
    Type: true_false
    Examples: true, false
    ```
  </Card>

  <Card title="Ajuda de formatação" icon="wand-magic-sparkles">
    Adicione instruções de formatação nas descrições

    ```yaml theme={null}
    "Date in dd/mm/yyyy"
    "Phone without spaces"
    ```
  </Card>
</CardGroup>

## Endpoints Dinâmicos

<Warning>
  Ao usar variáveis na URL do endpoint, certifique-se de colocá‑las entre chaves `{}` e usar exatamente o nome do parâmetro.
</Warning>

Você pode tornar seus endpoints dinâmicos usando variáveis:

```yaml theme={null}
Basic URL:
https://api.example.com/orders/status

With Variables:
https://api.example.com/orders/{order_id}/status
```

A IA substituirá automaticamente `{order_id}` pelo valor real coletado durante a conversa.

## Testing Made Easy

<Card title="Teste Facilitado" icon="vial">
  Clique em **“Testar Ferramenta”** para executar um teste com dados fictícios:

  * **Parâmetros do tipo texto:** `"teste"`
  * **Parâmetros numéricos:** `1`
  * **Parâmetros booleanos:** `true`

  Você verá o **código de resposta** e o **corpo da resposta**, ajudando a verificar se tudo está funcionando corretamente.
</Card>

## **Recurso Avançado: Integração com Plataforma de Automação**

Precisa de lógica mais complexa? Conecte sua ferramenta à plataforma de automação para fluxos de trabalho avançados.

Para integrações avançadas e fluxos complexos, você pode combinar ferramentas personalizadas com nossa Plataforma de Automação.

**Como criar integrações poderosas:**

***

### **1. Na plataforma de automação:**

* Crie um **novo fluxo**
* Adicione um **gatilho de webhook**
* Construa sua **lógica** (chamadas de API, transformação de dados, etc.)
* Finalize com **“Return Response”**

***

### **2. Na sua ferramenta personalizada:**

* Use a **URL do webhook** como endpoint
* Adicione `/sync` ao final
* Exemplo: `https://automation.mayahub.ai/webhook/abc123/sync`

***

### **3. Isso permite que você:**

* Transforme dados antes/depois das chamadas de API
* Faça múltiplas chamadas de API em sequência
* Aplique lógica de negócios complexa
* Trate erros de forma adequada

## Exemplos no Mundo

<AccordionGroup>
  <Accordion title="Sistema de Consulta de Pedidos" icon="magnifying-glass">
    ```yaml theme={null}
    Name: check_order
    Endpoint: https://api.yourshop.com/orders/{order_number}
    Parameters:
      - Name: order_number
        Type: string
        Description: "Order reference (format: ORD-XXXXX)"
    ```

    A IA irá:

    * Solicitar o número do pedido
    * Buscar o status
    * Explicar as datas de entrega e o status para o cliente
  </Accordion>

  <Accordion title="Disponibilidade de Compromissos" icon="calendar">
    ```yaml theme={null}
    Name: check_slots
    Endpoint: https://api.calendar.com/availability
    Parameters:
      - Name: service
        Type: string
        Description: "Service type (haircut, massage, consultation)"
      - Name: date
        Type: string
        Description: "Preferred date (dd/mm/yyyy)"
    ```

    A IA irá:

    * Perguntar sobre o serviço desejado
    * Obter a data preferida
    * Mostrar os horários disponíveis
  </Accordion>

  <Accordion title="Verificação de Cliente" icon="shield-check">
    ```yaml theme={null}
    Name: verify_customer
    Endpoint: https://api.crm.com/verify
    Parameters:
      - Name: phone
        Type: string
        Description: "10-digit phone number"
      - Name: email
        Type: string
        Description: "Email address for verification"
    ```

    A IA irá:

    * Coletar os dados de contato
    * Verificar no seu CRM
    * Prosseguir com base no status da verificação
  </Accordion>
</AccordionGroup>

## Configurando sua IA

<Info>
  A IA precisa de instruções claras em seu **system prompt** para usar suas ferramentas personalizadas de forma eficaz.
</Info>

**Exemplo de seção de prompt:**

```yaml theme={null}
**Quando usar a ferramenta `check_order`:**

1. O cliente pergunta sobre o status do pedido
2. Menciona rastreamento ou entrega
3. Quer saber onde está a encomenda

**Como usá-la:**

1. Solicite o número do pedido se não for fornecido
2. Verifique o formato (ORD-XXXXX)
3. Use a ferramenta para buscar o status
4. Explique os resultados de forma simples
```

<Tip>
  Teste suas ferramentas com diferentes fluxos de conversa para garantir que a IA lide com todos os cenários de forma fluida. Comece com chamadas de teste simples antes de ir ao vivo.
</Tip>