Logotipo da WAzion
CENTRO DE AJUDA

Funções Personalizadas de IA

Permita que a IA da WAzion chame suas APIs externas durante as conversas para consultar informações ou executar ações em tempo real.

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. 1 O cliente pergunta algo (ex: “Vocês têm o produto X disponível?“)
  2. 2 A IA detecta que precisa de informação externa
  3. 3 WAzion chama sua API com os parâmetros necessários
  4. 4 Sua API responde com as informações solicitadas
  5. 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 especial: _phone

WAzion adiciona automaticamente o parâmetro “_phone“ com o telefone do cliente no formato E.164 (ex: +34612345678). Você pode usá-lo para personalizar a resposta ou registrar quem fez a consulta.

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' => 'No autorizado']);
    exit;
}

// Obtener parámetros
$producto = $_GET['producto'] ?? '';
$cantidad = intval($_GET['cantidad'] ?? 1);

// Consultar tu base de datos
$stock = consultarStockEnBD($producto);

// Responder
echo json_encode([
    'producto' => $producto,
    'disponible' => $stock >= $cantidad,
    'stock_actual' => $stock,
    'mensaje' => $stock >= $cantidad
        ? "Sí, tenemos $stock unidades disponibles"
        : "Lo sentimos, solo quedan $stock unidades"
]);
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: 'No autorizado' });
  }

  // Obtener parámetros
  const { producto, cantidad = 1 } = req.query;

  // Consultar tu base de datos
  const stock = consultarStockEnBD(producto);

  // Responder
  res.json({
    producto,
    disponible: stock >= cantidad,
    stock_actual: stock,
    mensaje: stock >= cantidad
      ? `Sí, tenemos ${stock} unidades disponibles`
      : `Lo sentimos, solo quedan ${stock} unidades`
  });
});
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': 'No autorizado'}), 401

    # Obtener parámetros
    producto = request.args.get('producto', '')
    cantidad = int(request.args.get('cantidad', 1))

    # Consultar tu base de datos
    stock = consultar_stock_en_bd(producto)

    # Responder
    return jsonify({
        'producto': producto,
        'disponible': stock >= cantidad,
        'stock_actual': stock,
        'mensaje': f'Sí, tenemos {stock} unidades disponibles'
            if stock >= cantidad
            else f'Lo sentimos, solo quedan {stock} unidades'
    })

Histórico de alterações

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

Artigos relacionados

Pontos finais CRM →

Conecte WAzion com seu CRM externo

Webhooks →

Recebe eventos em tempo real

Assistente WAzion

Informações comerciais e suporte técnico

Olá! Sou o assistente da WAzion. Posso ajudá-lo com informações sobre preços e planos, dúvidas técnicas, configuração ou qualquer pergunta sobre o nosso produto. Como posso ajudá-lo?
Desenvolvido com WAzion AI