> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suasofia.online/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 de API personalizadas 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 verificando estoque, verificando dados de clientes ou buscando
  informações em tempo real, essas ferramentas tornam sua IA mais poderosa e conectada.
</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 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 chamadores

<Card title="Principais Benefícios" icon="star">
  - Nenhuma codificação necessária - basta configurar o endpoint de API e parâmetros - A IA
    automaticamente sabe quando e como usar as ferramentas - Acesso a dados em tempo real
    durante chamadas - Integração perfeita com seus sistemas existentes
</Card>

## Configurando Sua Ferramenta

### 1. Configuração Básica

<Frame>
  <img src="https://mintcdn.com/sofia-00a9d19b/BtL7iTEfbC7FXV-B/resources/mid-call.png?fit=max&auto=format&n=BtL7iTEfbC7FXV-B&q=85&s=847696328f567d49f6734bfaa3f8c0b8" alt="Configuração Principal da Ferramenta" width="2468" height="1680" data-path="resources/mid-call.png" />
</Frame>

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

  <Step title="Configurar Ajustes Principais">
    Preencha os detalhes essenciais:

    * **Nome**: Use letras minúsculas e sublinhados (ex: `verificar_status_pedido`)
    * **Descrição**: Explique quando e como a IA deve usar esta ferramenta
    * **Endpoint**: Sua URL de API (ex: `https://api.suaempresa.com/pedidos`)
    * **Tempo Limite**: Quanto tempo aguardar por respostas (em segundos)
    * **Método**: Escolha GET, POST, PUT, PATCH ou DELETE
  </Step>

  <Step title="Adicionar Cabeçalhos">
    Cabeçalhos comuns que você pode precisar:

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

### 2. Configuração de Variáveis

<Frame>
  <img src="https://mintcdn.com/sofia-00a9d19b/BtL7iTEfbC7FXV-B/resources/mid-call-param.png?fit=max&auto=format&n=BtL7iTEfbC7FXV-B&q=85&s=604eb9ca0a2db2988b968a5443aad834" alt="Configuração de Variáveis" width="2506" height="776" data-path="resources/mid-call-param.png" />
</Frame>

<Steps>
  <Step title="Definir Parâmetros">
    Estas são as informações que sua IA coletará durante a chamada:

    ```yaml theme={null}
    Nome: numero_pedido
    Tipo: string
    Descrição: "Número de pedido de 10 dígitos do cliente"
    ```
  </Step>

  <Step title="Definir Regras de Validação">
    Adicione requisitos de formato na descrição:

    ```yaml theme={null}
    "Data no formato dd/mm/aaaa"
    "Número de telefone sem espaços"
    "Endereço de e-mail para confirmação"
    ```
  </Step>
</Steps>

## Entendendo os Tipos de Parâmetros

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

    ```yaml theme={null}
    Tipo: string
    Exemplos: "João Silva", "Rua Principal 123"
    ```
  </Card>

  <Card title="Number" icon="calculator">
    Valores numéricos como valores, quantidades ou IDs

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

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

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

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

    ```yaml theme={null}
    "Data em dd/mm/aaaa"
    "Telefone sem espaços"
    ```
  </Card>
</CardGroup>

## Endpoints Dinâmicos

<Warning>
  Ao usar variáveis na URL do seu endpoint, certifique-se de colocá-las entre chaves
  e use o nome exato do parâmetro.
</Warning>

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

```yaml theme={null}
URL Básica:
https://api.exemplo.com/pedidos/status

Com Variáveis:
https://api.exemplo.com/pedidos/{id_pedido}/status
```

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

## Testes Facilitados

<Card title="Testes Automáticos" icon="vial">
  Clique em "Testar Ferramenta" para executar um teste com dados fictícios:

  * Parâmetros string: "test"
  * Parâmetros number: 1
  * Parâmetros booleanos: true

  Você verá o código de resposta e o corpo, ajudando a verificar se tudo funciona.
</Card>

## Recurso de Usuário Avançado: Integração com Plataforma de Automação

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

Para integrações avançadas e fluxos de trabalho complexos, você pode combinar ferramentas personalizadas com nossa [Plataforma de Automação](/automation-platform/introduction).

Veja 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.)
   * Termine com "Retornar Resposta"

2. Na sua ferramenta personalizada:
   * Use a URL do webhook como seu endpoint
   * Adicione `/sync` no final
   * Exemplo: `https://automation.suasofia.online/webhook/abc123/sync`

Isso permite que você:

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

## Exemplos do Mundo Real

<AccordionGroup>
  <Accordion title="Sistema de Consulta de Pedidos" icon="magnifying-glass">
    ```yaml theme={null}
    Nome: consultar_pedido
    Endpoint: https://api.sualoja.com/pedidos/{numero_pedido}
    Parâmetros:
      - Nome: numero_pedido
        Tipo: string
        Descrição: "Referência do pedido (formato: PED-XXXXX)"
    ```

    A IA irá:

    1. Perguntar o número do pedido
    2. Buscar o status
    3. Explicar datas de entrega e status ao cliente
  </Accordion>

  <Accordion title="Disponibilidade de Agendamento" icon="calendar">
    ```yaml theme={null}
    Nome: verificar_horarios
    Endpoint: https://api.calendario.com/disponibilidade
    Parâmetros:
      - Nome: servico
        Tipo: string
        Descrição: "Tipo de serviço (corte, massagem, consulta)"
      - Nome: data
        Tipo: string
        Descrição: "Data preferida (dd/mm/aaaa)"
    ```

    A IA irá:

    1. Perguntar sobre o serviço desejado
    2. Obter data preferida
    3. Mostrar horários disponíveis
  </Accordion>

  <Accordion title="Verificação de Cliente" icon="shield-check">
    ```yaml theme={null}
    Nome: verificar_cliente
    Endpoint: https://api.crm.com/verificar
    Parâmetros:
      - Nome: telefone
        Tipo: string
        Descrição: "Número de telefone de 10 dígitos"
      - Nome: email
        Tipo: string
        Descrição: "Endereço de e-mail para verificação"
    ```

    A IA irá:

    1. Coletar detalhes de contato
    2. Verificar contra seu CRM
    3. Prosseguir com base no status de verificação
  </Accordion>
</AccordionGroup>

## Configurando Sua IA

<Info>
  A IA precisa de instruções claras no prompt do sistema para usar efetivamente suas
  ferramentas personalizadas.
</Info>

Exemplo de seção de prompt:

```yaml theme={null}
Quando usar a ferramenta consultar_pedido:
1. Cliente pergunta sobre status do pedido
2. Menciona rastreamento ou entrega
3. Quer saber onde está o pacote

Como usá-la:
1. Perguntar número do pedido se não fornecido
2. Verificar formato (PED-XXXXX)
3. Usar ferramenta para buscar status
4. Explicar resultados em termos simples
```

<Tip>
  Teste suas ferramentas com vários fluxos de conversa para garantir que a IA lide com todos
  os cenários suavemente. Comece com chamadas de teste simples antes de entrar em produção.
</Tip>