Documentação da API VTL HUB

Bem-vindo à documentação interativa da API VTL HUB. Nosso objetivo é fornecer todas as ferramentas para que você possa integrar suas automações e sistemas com nossa plataforma de forma simples e poderosa, permitindo uma gestão de interações no Instagram totalmente personalizada.

Conceitos Essenciais

O que é uma API?

Pense na API (Application Programming Interface) como um "garçom digital". Você (sua aplicação) faz um pedido com instruções claras (uma requisição), e a API (o garçom) leva esse pedido para a cozinha (nosso sistema), busca o que foi solicitado e traz de volta para você (a resposta). Ela é a ponte de comunicação que permite que seu sistema converse com o VTL HUB de forma segura e padronizada para trocar informações.

O que é um Webhook?

Se a API é você indo ao restaurante, o Webhook é o restaurante te ligando para avisar que seu pedido está pronto. Em vez de sua aplicação perguntar repetidamente ao VTL HUB "Já aconteceu algo novo?", o VTL HUB avisa proativamente sua aplicação assim que um evento ocorre (ex: uma nova mensagem é recebida). Você fornece uma URL, e nós enviamos os dados para lá em tempo real. É a forma mais eficiente de receber atualizações.

O que é o N8N?

O N8N é o "maestro" da sua orquestra de automação. É uma ferramenta visual onde você conecta diferentes serviços como se fossem blocos de montar. Você pode configurar o N8N para "ouvir" os avisos do Webhook do VTL HUB e, a partir daí, iniciar um fluxo de ações: usar nossa API para salvar uma resposta, adicionar o contato a um CRM, enviar uma notificação no Slack, e muito mais. Ele executa a lógica que conecta tudo.

Autenticação

Toda comunicação com nossa API deve ser autenticada. Para garantir a segurança, inclua um cabeçalho (header) em todas as suas requisições com o seu token secreto.

x-webhook-secret: SUA_N8N_WEBHOOK_SECRET

Endpoints da API

GET/get-prompts-data

Buscar Dados de Prompts

Recupera informações de prompts associadas a uma página do Instagram específica.

Simulador Interativo
URL da Requisição
POST/save-comment-reply

Salvar Resposta de Comentário

Registra no banco de dados a resposta gerada (pela IA) para um comentário específico.

Simulador Interativo
Corpo da Requisição (JSON)
POST/add-incoming-message

Adicionar Mensagem Recebida

Use este endpoint para registrar uma nova mensagem enviada por um usuário para sua conta.

⚠️ Use esta API quando um USUÁRIO enviar mensagem PARA você.
Simulador Interativo

Campos de perfil (opcionais, para criar/atualizar contato):

Corpo da Requisição (JSON)
💡 Notas Importantes
  • 📸 Para respostas a stories: envie is_story_reply=true e, se possível, a story_url.
  • Para áudio ou outras mídias, envie a URL em media_url. O campo message_content é opcional nesses casos.
POST/add-outgoing-message

Adicionar Mensagem Enviada

Registra uma mensagem enviada por você (ou sua automação) para um usuário.

ℹ️ Use esta API quando VOCÊ (ou sua IA) enviar mensagem para o usuário.
Simulador Interativo
Corpo da Requisição (JSON)
💡 Notas Importantes
  • 📸 Para respostas a stories: envie is_story_reply=true, a story_url e o story_media_type ('image' ou 'video').
  • Para mídias, o campo message_content pode ser usado como legenda ou enviado sozinho para mensagens de texto.
POST/create-contact

Criar Contato (Outbound)

Cria um novo contato na plataforma, útil para iniciar conversas (outbound) ou importar usuários existentes.

Simulador Interativo
Corpo da Requisição (JSON)
POST/toggle-contact-ai

Ativar/Desativar IA para Contato

Permite ativar ou desativar a automação de IA para um contato específico em tempo real.

💡 Esta API atualiza imediatamente o status da IA no chat.
Simulador Interativo
Corpo da Requisição (JSON)

Histórico de Versões (Changelog)

Changelog - Versão 1.1.4 (28/10/2025)

📋 Resumo da Atualização: Versão focada em automação inteligente e produtividade, introduzindo CRM completo com IA, análise avançada de sentimentos e melhorias substanciais na experiência de interação com comentários e navegação.

Novidades

  • CRM Inteligente (Plano Developer Pro):
    • CRM Interativo e Automatizado: Sistema completo de gerenciamento de relacionamento com clientes, 100% personalizado e integrado com inteligência artificial para automatização de fluxos de trabalho.
    • APIs de Automação: Conjunto robusto de APIs RESTful para integração do CRM com ferramentas externas, permitindo automatização completa de processos de vendas e atendimento.
  • Análise Avançada de Comentários:
    • Análise de Sentimentos: Nova funcionalidade que identifica automaticamente o tom e a emoção de comentários (positivo, negativo, neutro), auxiliando na priorização de respostas e compreensão do engajamento da audiência.
    • Comentários como Sugestões: Possibilidade de adicionar comentários reais como referência no prompt de geração, permitindo que a IA aprenda com interações autênticas e crie respostas mais contextualizadas.
  • IA de Resumos de Conversas:
    • Geração Automática de Resumos: Inteligência artificial que analisa e condensa conversas extensas em resumos objetivos, economizando tempo na revisão de históricos de interações.
    • Gerenciamento de Resumos: Nova aba dedicada para visualizar, organizar e exportar todos os resumos gerados, facilitando o acompanhamento de conversas importantes.

Melhorias

  • Interface e Navegação:
    • Menu Otimizado: Redesign completo do menu de navegação com maior interatividade, animações fluidas e acesso mais intuitivo às funcionalidades principais da plataforma.
📝 Notas da Versão

Esta atualização representa um salto significativo em automação e inteligência artificial, posicionando a plataforma como uma solução completa para gestão de relacionamento e engajamento digital. O novo CRM atende demandas de usuários avançados que necessitam de maior controle e personalização, enquanto as melhorias em análise de sentimentos e resumos automáticos democratizam o acesso a insights valiosos para todos os níveis de usuários.

A integração via API abre portas para ecossistemas customizados, permitindo que desenvolvedores construam soluções sob medida conectadas à plataforma.

Changelog - Versão 1.1.3 (17/10/2025)

📋 Resumo da Atualização: Versão focada em crescimento e experiência do usuário, introduzindo sistema completo de indicações com recompensas, suporte multi-usuários e melhorias significativas de usabilidade.

Novidades

  • Sistema de Indicações:
    • Programa de Indicações: Implementado sistema completo de referral que permite aos usuários indicarem novos clientes e acompanharem suas indicações em tempo real.
    • Ranking de Indicadores: Nova página de classificação exibindo os principais indicadores da plataforma, promovendo engajamento e competição saudável entre usuários.
    • Sistema de Prêmios: Estrutura de recompensas automática baseada em quantidade de indicações realizadas, incentivando o crescimento orgânico da base de usuários.
  • Gestão de Usuários:
    • Suporte Multi-Usuários: Agora é possível gerenciar múltiplos usuários dentro da mesma conta, facilitando o trabalho em equipe e a delegação de responsabilidades.
  • Canal de Feedback:
    • Sistema de Report: Nova funcionalidade para reportar bugs, sugerir melhorias e apontar pontos negativos diretamente pela plataforma, fortalecendo a comunicação entre usuários e equipe de desenvolvimento.

Correções

  • Interface e Usabilidade:
    • Botão Dashboard: Corrigido comportamento inconsistente do botão de acesso ao dashboard que ocasionalmente não direcionava corretamente para a página inicial.
    • Responsividade Mobile: Otimizada experiência em dispositivos móveis (smartphones e tablets), garantindo interface fluida e totalmente funcional em todas as resoluções de tela.
📝 Notas da Versão

Esta atualização marca um passo importante no crescimento da plataforma, introduzindo mecanismos de viralização através do sistema de indicações e melhorando significativamente a acessibilidade em dispositivos móveis. O novo canal de comunicação direta permitirá um ciclo de melhorias mais ágil e alinhado às necessidades reais dos usuários.

Changelog - Versão 1.1.2 (16/10/2025)

📋 Resumo da Atualização: Nova versão com correções importantes de bugs, implementação de controle de horário para IA e novas funcionalidades para criação de conteúdo viral.

Novidades

  • Sistema de IA:
    • IA para Post Viral: Nova funcionalidade de criação e ativação de inteligência artificial especializada em gerar posts com potencial viral, otimizada para engajamento em redes sociais.
    • Controle de Horário: Implementado sistema de configuração de horário de funcionamento da IA, permitindo definir períodos específicos em que o assistente deve ou não responder mensagens.
  • Conformidade Legal:
    • Termos e Condições: Adicionada página de termos e condições de uso, garantindo transparência e conformidade com regulamentações vigentes.

Correções

  • Interface e Navegação:
    • Bug de Scroll: Resolvido problema crítico de rolagem em conversas longas que impedia a visualização completa do histórico de mensagens.
  • Sistema de Integração:
    • Webhook para Contas Novas: Corrigido bug no processo de cadastro de webhook para contas recém-criadas, garantindo configuração adequada desde o primeiro acesso.
📝 Notas da Versão

Esta atualização prioriza a estabilidade do sistema e adiciona funcionalidades estratégicas para controle de horário e criação de conteúdo, além de resolver bugs importantes que afetavam a experiência de novos usuários.

Changelog - Versão 1.1.1 (15/10/2025)

📋 Resumo da Atualização: Nova versão com melhorias significativas no sistema de IA, otimização de áudio e aprimoramentos na experiência do usuário.

Novidades

  • Sistema de IA:
    • Testes de Prompt Aprimorados: Removidos templates de exemplo e implementado novo sistema de teste de prompts para melhor performance.
    • IA Stories: Ajustes nas variáveis do sistema de stories para maior estabilidade.
    • Configuração de Segurança: Adicionada configuração de palavra-chave para controle e travamento da IA quando necessário.
  • Diferenciação de Planos:
    • Implementada nova estrutura de diferenciação entre planos de assinatura.
    • Recursos específicos por tipo de plano.

Melhorias

  • Otimização de Áudio:
    • Sistema de recebimento e envio de áudio otimizado para funcionar de forma independente, com melhor performance e redução de latência.
  • Stories - Respostas:
    • Respostas de stories agora exibem "Respondeu do story:" como prefixo.
    • Implementada variável para tentar incluir link do story junto à mensagem quando disponível.

Correções

  • Interface de Chat:
    • Mensagens Quebradas: Corrigida identificação e replicação de mensagens quebradas no chat.
    • Links Invisíveis: Resolvido problema onde links não apareciam nas conversas.
    • Aviso de 24h: Implementado sistema de aviso de 24 horas conforme necessário.
📝 Notas da Versão

Esta atualização foca em estabilidade e melhorias de experiência do usuário, com atenção especial à otimização do sistema de IA e comunicação via stories.