Funções Personalizadas de IA

1. Introdução

As Funções Personalizadas permitem que a IA do WAzion chame suas APIs externas durante uma conversa com um cliente. Isso permite consultar informações em tempo real ou executar ações automaticamente.

Como funciona?

1 O cliente pergunta algo (ex: “Vocês têm o produto X disponível?“)
2 A IA detecta que precisa de informação externa
3 WAzion chama sua API com os parâmetros necessários
4 Sua API responde com as informações solicitadas
5 A IA usa essa informação para responder ao cliente

Casos de uso típicos

• Consultar disponibilidade de produtos/serviços
• Realizar reservas automáticas
• Consultar status de pedidos
• Consultar preços dinâmicos
• Buscar informações de clientes
• Verificar horários disponíveis

2. Estrutura JSON

As funções são definidas como um array JSON. Cada função tem um nome, descrição e parâmetros que incluem o endpoint a ser chamado.

[
  {
    "name": "nombreDeLaFuncion",
    "description": "Descripción clara de qué hace esta función",
    "parameters": {
      "type": "object",
      "properties": {
        "parametro1": {
          "type": "string",
          "description": "Descripción del parámetro"
        },
        "parametro2": {
          "type": "number",
          "description": "Otro parámetro"
        },
        "endpoint": {
          "url": "https://tu-api.com/endpoint",
          "method": "GET",
          "format": "json",
          "auth": {
            "type": "header",
            "fields": {
              "Authorization": "Bearer tu-token-aqui"
            }
          }
        }
      },
      "required": ["parametro1"]
    }
  }
]

Campos principais

name: Identificador único da função
description: Descreve quando usar esta função
parameters: Define os parâmetros e o endpoint

Objeto endpoint

url: URL completa do endpoint (HTTPS)
method: GET, POST, PUT, DELETE, PATCH
format: json texto é maior que o número máximo de caracteres permitido. Por favor, divida em textos menores. form
auth: Configuração de autenticação

Importante: A descrição de cada função e parâmetro é crucial. A IA usa essas descrições para decidir quando chamar cada função.

3. Tipos de Autenticação

WAzion suporta 4 tipos de autenticação para proteger seus endpoints:

Cabeçalho Auth (Recomendado)

Mais seguro

Envie credenciais como headers HTTP. Ideal para tokens Bearer ou Chaves de API.

"auth": {
  "type": "header",
  "fields": {
    "Authorization": "Bearer tu-token-secreto",
    "X-API-Key": "otra-clave-si-necesitas"
  }
}

Basic Auth

Autenticação HTTP básica com usuário e senha (codificados em Base64).

"auth": {
  "type": "basic",
  "fields": {
    "username": "tu-usuario",
    "password": "tu-contraseña"
  }
}

Query Auth

Envia credenciais como parâmetros na URL. Menos seguro, mas simples.

"auth": {
  "type": "query",
  "fields": {
    "api_key": "tu-api-key",
    "secret": "tu-secret"
  }
}
// Resultado: ?api_key=tu-api-key&secret=tu-secret

Body Auth

Inclua credenciais no corpo da requisição (apenas POST/PUT/PATCH).

"auth": {
  "type": "body",
  "fields": {
    "api_key": "tu-api-key",
    "token": "tu-token"
  }
}
// Se añade al JSON del body junto con los parámetros

Sem autenticação

Se o seu endpoint não exigir autenticação, simplesmente omita o campo “auth“ do objeto endpoint.

4. Especificações Técnicas

Tempos limite

Tempo limite total	60s
Tempo limite de conexão	10s

Repetições

Máximo de tentativas	4
Estratégia	Recuo exponencial

Calendário de novas tentativas

Tento 1	Imediato
Tento 2	2s
Tento 3	4s
Tento 4	8s

Cabeçalhos HTTP enviados

Header	Valor
Content-Type	application/json
Accept	application/json
User-Agent	WAzion-Functions/1.0
+ Cabeçalhos de autenticação	De acordo com a configuração

Códigos HTTP que activam nova tentativa

429 500 502 503 504

Códigos sem nova tentativa

400 401 403 404

Requisitos do endpoint

HTTPS obrigatório (certificado SSL válido)
{ “Respuesta“: “em formato JSON válido“ }
Content-Type: application/json na resposta
Resposta em menos de 60 segundos

Parâmetro reservado: telefone

Se a sua função declara um parâmetro chamado “phone“, o WAzion o sobrescreverá automaticamente com o telefone do cliente atual no formato E.164 (ex: +34612345678). Isso garante que sempre seja usado o telefone correto do cliente com quem se está conversando, independentemente do valor que a IA enviar. Use-o para enviar notificações, registrar consultas ou personalizar respostas de acordo com o cliente.

5. Exemplos Práticos

Exemplo 1: Consultar disponibilidade

Permite que a IA consulte se um produto está disponível em estoque.

[
  {
    "name": "consultarDisponibilidad",
    "description": "Consulta si un producto específico está disponible en stock",
    "parameters": {
      "type": "object",
      "properties": {
        "producto": {
          "type": "string",
          "description": "Nombre o referencia del producto a consultar"
        },
        "cantidad": {
          "type": "number",
          "description": "Cantidad deseada (opcional, por defecto 1)"
        },
        "endpoint": {
          "url": "https://tu-tienda.com/api/stock",
          "method": "GET",
          "format": "json",
          "auth": {
            "type": "header",
            "fields": {
              "Authorization": "Bearer token-secreto-123"
            }
          }
        }
      },
      "required": ["producto"]
    }
  }
]

Exemplo 2: Criar uma reserva

Permite que a IA crie reservas automaticamente no seu sistema.

[
  {
    "name": "crearReserva",
    "description": "Crea una reserva para el cliente en la fecha y hora indicada",
    "parameters": {
      "type": "object",
      "properties": {
        "nombre_cliente": {
          "type": "string",
          "description": "Nombre completo del cliente"
        },
        "fecha": {
          "type": "string",
          "description": "Fecha de la reserva en formato YYYY-MM-DD"
        },
        "hora": {
          "type": "string",
          "description": "Hora de la reserva en formato HH:MM"
        },
        "servicio": {
          "type": "string",
          "description": "Tipo de servicio a reservar"
        },
        "endpoint": {
          "url": "https://tu-negocio.com/api/reservas",
          "method": "POST",
          "format": "json",
          "auth": {
            "type": "header",
            "fields": {
              "X-API-Key": "mi-api-key-secreta"
            }
          }
        }
      },
      "required": ["nombre_cliente", "fecha", "hora", "servicio"]
    }
  }
]

Exemplo 3: Consultar status do pedido

Permite que a IA consulte o status de um pedido usando seu número de referência.

[
  {
    "name": "consultarPedido",
    "description": "Consulta el estado de envío de un pedido por su número",
    "parameters": {
      "type": "object",
      "properties": {
        "numero_pedido": {
          "type": "string",
          "description": "Número de pedido o referencia"
        },
        "endpoint": {
          "url": "https://tu-tienda.com/api/pedidos/estado",
          "method": "GET",
          "format": "json",
          "auth": {
            "type": "query",
            "fields": {
              "token": "mi-token-secreto"
            }
          }
        }
      },
      "required": ["numero_pedido"]
    }
  }
]

6. Código de Exemplo

Exemplos de como implementar os endpoints no seu servidor:

PHP

<?php
// Endpoint: /api/stock

header('Content-Type: application/json');

// Verificar autenticación
$authHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
if ($authHeader !== 'Bearer token-secreto-123') {
    http_response_code(401);
    echo json_encode(['error' => 'Unauthorized']);
    exit;
}

// Get parameters
$producto = $_GET['producto'] ?? '';
$cantidad = intval($_GET['cantidad'] ?? 1);

// Query your database
$stock = consultarStockEnBD($producto);

// Respond
echo json_encode([
    'producto' => $producto,
    'disponible' => $stock >= $cantidad,
    'stock_actual' => $stock,
    'mensaje' => $stock >= $cantidad
        ? "Yes, we have $stock units available"
        : "Sorry, only $stock units left"
]);

Node.js / Express

// Endpoint: /api/stock

app.get('/api/stock', (req, res) => {
  // Verificar autenticación
  const authHeader = req.headers.authorization;
  if (authHeader !== 'Bearer token-secreto-123') {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Get parameters
  const { producto, cantidad = 1 } = req.query;

  // Query your database
  const stock = consultarStockEnBD(producto);

  // Respond
  res.json({
    producto,
    disponible: stock >= cantidad,
    stock_actual: stock,
    mensaje: stock >= cantidad
      ? `Yes, we have ${stock} units available`
      : `Sorry, only ${stock} units left`
  });
});

Python / Flask

# Endpoint: /api/stock

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/api/stock', methods=['GET'])
def consultar_stock():
    # Verificar autenticación
    auth_header = request.headers.get('Authorization', '')
    if auth_header != 'Bearer token-secreto-123':
        return jsonify({'error': 'Unauthorized'}), 401

    # Get parameters
    producto = request.args.get('producto', '')
    cantidad = int(request.args.get('cantidad', 1))

    # Query your database
    stock = consultar_stock_en_bd(producto)

    # Respond
    return jsonify({
        'producto': producto,
        'disponible': stock >= cantidad,
        'stock_actual': stock,
        'mensaje': f'Yes, we have {stock} units available'
            if stock >= cantidad
            else f'Sorry, only {stock} units left'
    })

Histórico de alterações

Sem alterações recentes nesta documentação.

1. Introdução

Como funciona?

Casos de uso típicos

2. Estrutura JSON

Campos principais

Objeto endpoint

3. Tipos de Autenticação

Cabeçalho Auth (Recomendado)

Basic Auth

Query Auth

Body Auth

Sem autenticação

4. Especificações Técnicas

Tempos limite

Repetições

Calendário de novas tentativas

Cabeçalhos HTTP enviados

Códigos HTTP que activam nova tentativa

Códigos sem nova tentativa

Requisitos do endpoint

Parâmetro reservado: telefone

5. Exemplos Práticos

Exemplo 1: Consultar disponibilidade

Exemplo 2: Criar uma reserva

Exemplo 3: Consultar status do pedido

6. Código de Exemplo

Histórico de alterações

Artigos relacionados

Pontos finais CRM →

Webhooks →

1. Introdução

Como funciona?

Casos de uso típicos

2. Estrutura JSON

Campos principais

Objeto endpoint

3. Tipos de Autenticação

Cabeçalho Auth (Recomendado)

Basic Auth

Query Auth

Body Auth

Sem autenticação

4. Especificações Técnicas

Tempos limite

Repetições

Calendário de novas tentativas

Cabeçalhos HTTP enviados

Códigos HTTP que activam nova tentativa

Códigos sem nova tentativa

Requisitos do endpoint

Parâmetro reservado: telefone

5. Exemplos Práticos

Exemplo 1: Consultar disponibilidade

Exemplo 2: Criar uma reserva

Exemplo 3: Consultar status do pedido

6. Código de Exemplo

Histórico de alterações

Artigos relacionados

Pontos finais CRM →

Webhooks →

Instalar WAzion no Chrome

Configurar cookies

Cookies essenciais

Cookies de análise

Cookies de marketing

Aproveite agora

Assistente WAzion