Ferramentas de Chamada Personalizadas

Ferramentas de Chamada Personalizadas permitem que sua SofIA interaja com sistemas externos durante as chamadas. Seja verificando o estoque, validando dados do cliente ou buscando informações em tempo real, essas ferramentas tornam sua SofIA mais poderosa e conectada.

Visão Geral

Ferramentas de Chamada Personalizadas permitem que sua SofIA:

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 chamadores

Principais Benefícios

Sem necessidade de codificação - basta configurar o endpoint da API e os parâmetros - A SofIA sabe automaticamente quando e como usar as ferramentas - Acesso a dados em tempo real durante as chamadas - Integração perfeita com seus sistemas existentes

Ferramentas de chamada e servidores MCP estão ambos na página Ferramentas de Chamada / MCP na barra lateral. Use uma ferramenta de chamada para um único endpoint HTTP que você define manualmente, e um servidor MCP para conectar a um servidor remoto que expõe muitas ferramentas de uma vez.

Tipos de Ferramentas

Ao criar uma ferramenta, você escolhe um dos dois tipos:

Requisição HTTP

Chame sua própria API diretamente. Você define a URL, método, cabeçalhos, parâmetros e (opcionalmente) um corpo estático. Melhor quando você já tem um endpoint.

Plataforma de Automação

A Sua SofIA cria um fluxo vinculado para você na Plataforma de Automação. O endpoint da ferramenta é gerado e bloqueado automaticamente — você apenas constrói a lógica no fluxo e termina com um passo de Retornar Resposta. Melhor para lógica sem código e em múltiplas etapas.

Configurando Sua Ferramenta

1. Configuração Básica

Acessar Criação de Ferramenta

Navegue até Ferramentas de Chamada e clique em Criar Ferramenta de Chamada

Configurar Configurações Principais

Preencha os detalhes essenciais:

Nome: Letras, números e sublinhados, começando com uma letra ou sublinhado (até 64 caracteres, ex: check_order_status)
Descrição: Explique quando e como a SofIA deve usar esta ferramenta
Endpoint: Sua URL da API (ex: https://api.suaempresa.com/pedidos)
Timeout: Quanto tempo esperar por respostas (1–30 segundos)
Método: Escolha GET, POST, PUT, PATCH ou DELETE
Formato do corpo: Para métodos de escrita (POST/PUT/PATCH), envie o corpo como JSON (padrão) ou formulário codificado (application/x-www-form-urlencoded)

Adicionar Cabeçalhos

Cabeçalhos comuns que você pode precisar:

Content-Type: application/json
Authorization: Bearer seu_token

2. Configuração de Variáveis

Definir Parâmetros

Estas são as informações que sua SofIA coletará durante a chamada:

Name: order_number
Type: string
Description: "Número do pedido de 10 dígitos do cliente"

Definir Regras de Validação

Adicione requisitos de formato na descrição:

"Data no formato dd/mm/yyyy"
"Número de telefone sem espaços"
"Endereço de e-mail para confirmação"

Compreendendo os Tipos de Parâmetros

String

Valores de texto como nomes, endereços ou números de referência

Type: string
Examples: "João Silva", "123 Rua Principal"

Número

Números inteiros como quantidades ou IDs

Type: number
Examples: 42, 1500

Float

Números decimais como preços ou quantidades

Type: float
Examples: 19.99, 4.5

Booleano

Valores verdadeiro/falso para situações de sim/não

Type: boolean
Examples: true, false

Cada parâmetro pode ser marcado como obrigatório ou opcional. Parâmetros opcionais são enviados apenas quando a SofIA realmente coletou um valor, então seu endpoint não receberá campos vazios. Adicione dicas de formato na descrição (ex: "Data no formato dd/mm/yyyy", "Telefone sem espaços").

Campos Estáticos

Campos estáticos são pares chave/valor fixos que são sempre enviados com cada requisição — a SofIA nunca os altera. Use-os para constantes como um id de locatário, um canal ou uma tag de origem.

source: suasofia
tenant: acme
channel: sms

Os valores dos campos estáticos também suportam variáveis de sistema (ex: defina caller como {{customer_phone}}).

Variáveis de Sistema & Valores Dinâmicos

Existem duas maneiras de injetar dados dinâmicos em sua ferramenta:

Parâmetros extraídos pela IA

Envolvidos em chaves simples {param}. Substituídos pelo valor que a IA coletou durante a conversa. Usados no caminho/consulta da URL.

https://api.exemplo.com/pedidos/{order_id}

Variáveis de sistema e conta

Envolvidas em chaves duplas {{variable}}. Preenchidas automaticamente pela plataforma no momento da chamada. Usáveis na URL, valores de cabeçalho e valores de campos estáticos.

Authorization: Bearer {{crm_key}}

Essas variáveis de sistema são injetadas automaticamente — sem necessidade de configuração:

Variável	Valor
`{{customer_phone}}`	O número de telefone da outra parte (chamador para entrada, chamado para saída). Vazio na web/chat.
`{{assistant_phone}}`	O número de telefone da própria SofIA, se tiver um.
`{{assistant_id}}`	O ID único da SofIA.
`{{assistant_name}}`	O nome da SofIA.
`{{current_date}}`	Data atual no fuso horário da SofIA (ex: `2026-06-15`).
`{{current_time}}`	Hora atual no fuso horário da SofIA (ex: `14:30`).

Quaisquer variáveis de conta personalizadas que você definir também estão disponíveis como {{name}} e podem ser usadas da mesma forma.

Endpoints Dinâmicos

Ao usar variáveis na URL do seu endpoint, certifique-se de envolvê-las em chaves e usar o nome exato do parâmetro.

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

URL Básica:
https://api.exemplo.com/pedidos/status

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

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

Testes Facilitados

Teste Automático

Clique em Testar ferramenta para disparar uma requisição real com dados de exemplo realistas:

Parâmetros String: "Dados de exemplo"
Parâmetros Número: 42
Parâmetros Float: 19.99
Parâmetros Booleano: true
Variáveis de sistema como {{customer_phone}} são preenchidas com espaços reservados realistas (ex: +1234567890, o nome/id da SofIA)

Você verá os dados da requisição, código de resposta e corpo, ajudando você a verificar se tudo funciona antes de entrar em operação.

Ferramentas da Plataforma de Automação não têm um botão Testar ferramenta — você as testa executando o fluxo vinculado dentro da Plataforma de Automação.

Ferramentas da Plataforma de Automação

Precisa de lógica mais complexa? Crie uma ferramenta da Plataforma de Automação e a Sua SofIA constrói e vincula o fluxo para você — sem necessidade de configuração manual de webhook.

Quando você define o tipo da ferramenta como Plataforma de Automação, a Sua SofIA cria automaticamente um fluxo conectado na Plataforma de Automação e conecta o endpoint da ferramenta a ele. O endpoint e o método são gerados e bloqueados, para que não possam ser alterados acidentalmente.

Criar a ferramenta

Escolha o tipo Plataforma de Automação, dê um nome à ferramenta, descrição e parâmetros. Ao salvar, o fluxo vinculado é criado automaticamente.

Abrir o fluxo

Na página de edição da ferramenta, o cartão de conexão mostra o status do fluxo (Ativo/Desativado) e um botão Abrir fluxo na Plataforma de Automação. O fluxo começa a partir de um gatilho de webhook e termina com um passo de Retornar Resposta.

Construa sua lógica

Adicione passos entre o gatilho e a resposta — chamadas de API, atualizações de CRM, ramificações, transformações de dados — e mantenha um passo de Retornar Resposta para que a SofIA receba um resultado.

Mantenha os parâmetros em sincronia

Se você alterar os parâmetros ou campos estáticos da ferramenta, use Re-sincronizar dados de exemplo para que o exemplo de gatilho do fluxo corresponda. Se a criação inicial do fluxo falhar, um botão Tentar criar fluxo novamente aparecerá na página de edição.

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
Lide com erros de forma elegante

Prefere configurar você mesmo? Você ainda pode usar uma ferramenta de Requisição HTTP simples apontada para uma URL de webhook da Plataforma de Automação existente com /sync anexado (ex: https://automate.suasofia.com.br/api/v1/webhooks/abc123/sync).

Exemplos do Mundo Real

Sistema de Consulta de Pedidos

Name: check_order
Endpoint: https://api.suaLoja.com/pedidos/{order_number}
Parameters:
  - Name: order_number
    Type: string
    Description: "Referência do pedido (formato: ORD-XXXXX)"

A SofIA irá:

Pedir o número do pedido
Buscar o status
Explicar datas de entrega e status ao cliente

Disponibilidade de Agendamentos

Name: check_slots
Endpoint: https://api.calendario.com/disponibilidade
Parameters:
  - Name: service
    Type: string
    Description: "Tipo de serviço (corte de cabelo, massagem, consulta)"
  - Name: date
    Type: string
    Description: "Data preferida (dd/mm/yyyy)"

A SofIA irá:

Perguntar sobre o serviço desejado
Obter a data preferida
Mostrar horários disponíveis

Verificação de Cliente

Name: verify_customer
Endpoint: https://api.crm.com/verificar
Parameters:
  - Name: phone
    Type: string
    Description: "Número de telefone de 10 dígitos"
  - Name: email
    Type: string
    Description: "Endereço de e-mail para verificação"

A SofIA irá:

Coletar detalhes de contato
Verificar no seu CRM
Prosseguir com base no status da verificação

Configurando Sua SofIA

A SofIA precisa de instruções claras em seu prompt de sistema para usar efetivamente suas ferramentas personalizadas.

Exemplo de seção de prompt:

Quando usar a ferramenta check_order:
O cliente pergunta sobre o status do pedido
Menciona rastreamento ou entrega
Quer saber onde está seu pacote

Como usá-la:
Pergunte pelo número do pedido se não for fornecido
Verifique o formato (ORD-XXXXX)
Use a ferramenta para buscar o status
Explique os resultados em termos simples

Teste suas ferramentas com vários fluxos de conversa para garantir que a SofIA lide com todos os cenários de forma suave. Comece com chamadas de teste simples antes de entrar em operação.

Introdução

Primeiros Passos

Visão Geral dos Assistentes de IA

Campaigns

Leads

Dashboards Personalizados

Conversas

WhatsApp Business

Números de Telefone

Chamadas de Entrada

Chamadas de Saída

AI Prompting & Conversation Design

Automação & Integrações

Provisionamento de Números

Configurações

Solução de Problemas & FAQs

Ferramentas de Chamada Personalizadas

Visão Geral

Principais Benefícios

Tipos de Ferramentas

Requisição HTTP

Plataforma de Automação

Configurando Sua Ferramenta

1. Configuração Básica

2. Configuração de Variáveis

Compreendendo os Tipos de Parâmetros

String

Número

Float

Booleano

Campos Estáticos

Variáveis de Sistema & Valores Dinâmicos

Parâmetros extraídos pela IA

Variáveis de sistema e conta

Endpoints Dinâmicos

Testes Facilitados

Teste Automático

Ferramentas da Plataforma de Automação

Exemplos do Mundo Real

Configurando Sua SofIA

​Visão Geral

Principais Benefícios

​Tipos de Ferramentas

Requisição HTTP

Plataforma de Automação

​Configurando Sua Ferramenta

​1. Configuração Básica

​2. Configuração de Variáveis

​Compreendendo os Tipos de Parâmetros

String

Número

Float

Booleano

​Campos Estáticos

​Variáveis de Sistema & Valores Dinâmicos

Parâmetros extraídos pela IA

Variáveis de sistema e conta

​Endpoints Dinâmicos

​Testes Facilitados

Teste Automático

​Ferramentas da Plataforma de Automação

​Exemplos do Mundo Real

​Configurando Sua SofIA

Visão Geral

Tipos de Ferramentas

Configurando Sua Ferramenta

1. Configuração Básica

2. Configuração de Variáveis

Compreendendo os Tipos de Parâmetros

Campos Estáticos

Variáveis de Sistema & Valores Dinâmicos

Endpoints Dinâmicos

Testes Facilitados

Ferramentas da Plataforma de Automação

Exemplos do Mundo Real

Configurando Sua SofIA