Como a API do Toolzz Bots economiza tempo na integração com CRM

Lucas (CEO Toolzz)
10 de agosto de 2026

Em um cenário onde cada lead conta, integrar seu chatbot de qualificação ao CRM pode ser a diferença entre uma venda perdida e um cliente fidelizado. No entanto, a transferência manual de dados entre sistemas consome horas preciosas da equipe de vendas e está sujeita a erros. Neste tutorial técnico, você aprenderá a usar a API do Toolzz Bots para automatizar a sincronização de resultados do seu bot diretamente com ferramentas como Salesforce, HubSpot ou qualquer CRM via webhook, liberando seu time para o que realmente importa: vender.

Pré-requisitos

Antes de mergulhar na implementação, tenha em mãos os seguintes itens:

1. Conta no Toolzz Bots: Acesse bots.toolzz.ai e crie sua conta caso ainda não tenha. A plataforma oferece um plano gratuito para testes.
2. Workspace configurado: Um workspace é o ambiente onde seus bots serão criados e gerenciados. Dentro do painel, vá em Configurações do Workspace para anotar o workspace_id.
3. Token de API: Navegue até as configurações do seu workspace e procure pela seção API Keys. Gere um token de acesso (Bearer token). Guarde-o com segurança, pois será usado em todas as requisições.
4. Bot publicado: Este tutorial pressupõe que você já criou um bot com um fluxo visual que captura dados do lead (nome, email, telefone) e que ele está publicado — a API só retorna resultados de bots ativos. Caso ainda não tenha, vamos construir um exemplo simples na próxima seção.
5. Ferramentas: cURL, Postman ou seu ambiente de desenvolvimento favorito (Python, Node.js).

Arquitetura da integração

O fluxo de dados é bastante direto:

1. O usuário interage com o chatbot através de um canal (site, WhatsApp, Instagram).
2. O bot, construído visualmente no Toolzz Bots, guia a conversa e coleta informações em variáveis (ex: lead_nome, lead_email).
3. A plataforma armazena automaticamente cada sessão de chat como um resultado, contendo todas as variáveis capturadas e logs da conversa.
4. Um script externo (ou automação) consome a API do Toolzz Bots periodicamente para listar resultados recentes e obter seus detalhes.
5. Os dados extraídos são enviados ao CRM via sua própria API ou webhook.

A beleza dessa abordagem é que a lógica conversacional permanece visual e sem código, enquanto a parte de integração é tratada por algumas chamadas REST simples — e é exatamente essa simplicidade que a Toolzz Bots oferece para sua operação.

Configuração no produto: criando um bot de qualificação de leads

Antes de usar a API, é preciso ter um bot que capture leads. Vamos montar um fluxo básico na interface do Toolzz Bots.

1. Crie um novo bot: No painel do Toolzz Bots, clique em "Novo Bot". Dê um nome, como "Qualificador de Leads", e escolha o canal (ex: "Web Chat").
2. Monte o fluxo:
   • Arraste um bloco Enviar mensagem para saudar o usuário: "Olá! Para continuarmos, por favor, me informe seu nome completo."
   • Em seguida, um bloco Capturar resposta e armazene o valor na variável lead_nome.
   • Repita o processo para capturar lead_email e lead_telefone.
   • Adicione um bloco Condição para validar se o email contém "@" e, se sim, confirme a captura com uma mensagem final: "Obrigado, seus dados foram registrados com sucesso!"
   • Caso contrário, peça para corrigir.
3. Publique o bot: Após revisar o fluxo, clique em "Publicar". O status do bot mudará para "Publicado".

Pronto. Agora, qualquer interação que siga esse fluxo gerará um resultado com as variáveis preenchidas. É exatamente isso que vamos acessar via API.

💡 Dica: Use o Preview Chat (ícone de "Testar" no canto superior direito) para simular conversas e gerar exemplos de resultados antes de conectar o CRM. Assim você valida o fluxo e já tem dados para testar os endpoints.

Implementação via API

A documentação completa está disponível em docs.toolzz.dev/bots-reference. Vamos focar nos três endpoints que compõem a espinha dorsal da integração com CRM: List Results, Get a Result e List logs in Results.

Todos os endpoints exigem autenticação via Bearer Token no header Authorization. Inclua também Content-Type: application/json para requisições com corpo.

1. Listando resultados recentes

O endpoint GET /v1/bots/results permite buscar as últimas sessões finalizadas do seu bot. Você pode filtrar por workspace_id, bot_id, período de datas e com status completed para pegar apenas conversas concluídas (onde o lead chegou ao fim do fluxo).

URL: https://api.toolzz.ai/v1/bots/results

Método: GET

Headers:

{ "Authorization": "Bearer SEU_TOKEN", "Content-Type": "application/json" }

Parâmetros de query (todos obrigatórios, exceto quando indicado):

Exemplo de requisição com cURL:

bash curl -X GET "https://api.toolzz.ai/v1/bots/results?workspace_id=ws_abc123&bot_id=bot_xyz789&status=completed&from_date=2026-03-01T00:00:00Z&to_date=2026-03-15T23:59:59Z&page=1&limit=5"
-H "Authorization: Bearer SEU_TOKEN"
-H "Content-Type: application/json"

Exemplo em JavaScript (Node.js):

javascript const axios = require('axios');

async function listResults() { const url = 'https://api.toolzz.ai/v1/bots/results'; const params = { workspace_id: 'ws_abc123', bot_id: 'bot_xyz789', status: 'completed', from_date: '2026-03-01T00:00:00Z', to_date: '2026-03-15T23:59:59Z', page: 1, limit: 5 };

try { const response = await axios.get(url, { headers: { 'Authorization': 'Bearer SEU_TOKEN', 'Content-Type': 'application/json' }, params }); console.log(response.data); } catch (error) { console.error(error.response?.data || error.message); } }

listResults();

Exemplo em Python (requests):

python import requests

url = "https://api.toolzz.ai/v1/bots/results" headers = { "Authorization": "Bearer SEU_TOKEN", "Content-Type": "application/json" } params = { "workspace_id": "ws_abc123", "bot_id": "bot_xyz789", "status": "completed", "from_date": "2026-03-01T00:00:00Z", "to_date": "2026-03-15T23:59:59Z", "page": 1, "limit": 5 }

response = requests.get(url, headers=headers, params=params) if response.status_code == 200: data = response.json() print(data) else: print(f"Erro: {response.status_code}", response.text)

Resposta típica (200 OK):

{ "data": [ { "id": "res_001", "bot_id": "bot_xyz789", "status": "completed", "created_at": "2026-03-14T14:35:22Z", "updated_at": "2026-03-14T14:36:10Z", "variables": { "lead_nome": "Ana Silva", "lead_email": "[email protected]", "lead_telefone": "+5511999999999" }, "channel": "webchat" } ], "pagination": { "page": 1, "limit": 5, "total_pages": 10, "total_items": 48 } }

Quer levar essa automação para produção? Ver planos Toolzz Bots e garanta escalabilidade e suporte de verdade.

Com essa lista em mãos, seu script pode iterar sobre os resultados, extrair o id de cada um e obter mais detalhes se necessário.

2. Obtendo detalhes de um resultado específico

Para capturar todas as variáveis e logs de uma sessão específica, use o endpoint GET /v1/bots/results/{id}. Ele é útil para quando você já tem o ID do resultado e quer inseri-lo no CRM com todas as informações disponíveis.

URL: https://api.toolzz.ai/v1/bots/results/{result_id}

Método: GET

Headers:

Authorization: Bearer SEU_TOKEN Content-Type: application/json

Parâmetros de URL (obrigatório):

Exemplo de requisição com cURL:

bash curl -X GET "https://api.toolzz.ai/v1/bots/results/res_001"
-H "Authorization: Bearer SEU_TOKEN"
-H "Content-Type: application/json"

Exemplo em JavaScript (fetch nativo):

javascript fetch('https://api.toolzz.ai/v1/bots/results/res_001', { method: 'GET', headers: { 'Authorization': 'Bearer SEU_TOKEN', 'Content-Type': 'application/json' } }) .then(response => response.json()) .then(data => console.log(data)) .catch(err => console.error('Erro:', err));

Exemplo em Python (requests):

python import requests

result_id = "res_001" url = f"https://api.toolzz.ai/v1/bots/results/{result_id}" headers = { "Authorization": "Bearer SEU_TOKEN", "Content-Type": "application/json" }

response = requests.get(url, headers=headers) if response.status_code == 200: detalhe = response.json() print(detalhe) else: print(f"Erro: {response.status_code} - {response.text}")

Resposta típica:

{ "id": "res_001", "bot_id": "bot_xyz789", "workspace_id": "ws_abc123", "status": "completed", "created_at": "2026-03-14T14:35:22Z", "updated_at": "2026-03-14T14:36:10Z", "variables": { "lead_nome": "Ana Silva", "lead_email": "[email protected]", "lead_telefone": "+5511999999999" }, "channel": "webchat", "session_duration": 48, "log_count": 12 }

Com esses dados, uma chamada simples para a API do seu CRM cria ou atualiza o lead. Por exemplo, no HubSpot você usaria o endpoint POST /crm/v3/objects/contacts com as variáveis mapeadas.

3. Listando logs de um resultado (para depuração)

Quando uma integração falha ou você deseja analisar a conversa completa, o endpoint GET /v1/bots/results/{result_id}/logs retorna a linha do tempo da interação. Ele é extremamente útil para auditoria e troubleshooting.

URL: https://api.toolzz.ai/v1/bots/results/{result_id}/logs

Método: GET

Headers: mesmo padrão.

Parâmetros de URL:

Parâmetros de query (opcionais):

Exemplo de requisição com cURL:

bash curl -X GET "https://api.toolzz.ai/v1/bots/results/res_001/logs?type=variable_capture&limit=10"
-H "Authorization: Bearer SEU_TOKEN"
-H "Content-Type: application/json"

Resposta de exemplo:

{ "result_id": "res_001", "logs": [ { "timestamp": "2026-03-14T14:35:30Z", "type": "user_message", "content": "Ana Silva" }, { "timestamp": "2026-03-14T14:35:32Z", "type": "variable_capture", "variable_name": "lead_nome", "value": "Ana Silva" }, { "timestamp": "2026-03-14T14:35:50Z", "type": "user_message", "content": "[email protected]" }, { "timestamp": "2026-03-14T14:35:52Z", "type": "variable_capture", "variable_name": "lead_email", "value": "[email protected]