Totum Connect — Documentação da API

Autenticação

Todos os endpoints exigem autenticação via Bearer Token no header HTTP. Solicite seu token no painel do Totum Connect.

Header de autenticação

Authorization: Bearer seu_token_aqui
Content-Type: application/json

Base URL

Servidor Node.js (envio, conexão, voz)

https://connect.sistematotum.com.br:3000/Connect/Api

Servidor App (mensagens, contatos, canais)

https://connect.sistematotum.com.br/Connect/Api

GET /Status

Status do serviço

Verifica se o serviço está online e valida o token de autenticação.

Não requer body. Apenas o header Authorization.

200 OK

Serviço online e token válido.

401 Unauthorized

Token inválido ou ausente.

Resposta 200

{
  "servico": "Connect",
  "status":  "online",
  "usuario": { "id": 1, "nome": "João" },
  "timestamp": "2026-04-20T12:00:00.000Z"
}

POST /GerarQRCode

Gerar QR Code

Inicia uma sessão WhatsApp e retorna o QR Code para escanear com o celular. Após o escaneamento, a conexão fica ativa em memória.

Body

Campo	Tipo	Descrição
IdUsuarioobrigatório	number	ID do usuário autenticado.
IdCanalobrigatório	number	ID do canal ao qual a conexão pertence.

Resposta 200

{
  "qrcode": "data:image/png;base64,...",
  "IdConexao": 3
}

// Ou, se já estiver conectado:
{ "conectado": true, "IdConexao": 3 }

POST /DesconectarConexao

Desconectar Conexão

Encerra a sessão WhatsApp ativa. A conexão permanece cadastrada, mas fica inativa até um novo QR Code ser gerado.

Body

Campo	Tipo	Descrição
IdConexaoobrigatório	number	ID da conexão a desconectar.
IdCanalobrigatório	number	ID do canal da conexão.

200 OK

{ "sucesso": true }

401 / 400

Token inválido ou parâmetros ausentes.

POST /ExcluirConexao

Excluir Conexão

Remove permanentemente uma conexão e encerra a sessão WhatsApp associada.

Body

Campo	Tipo	Descrição
IdConexaoobrigatório	number	ID da conexão.
IdCanalobrigatório	number	ID do canal.

POST /ImportarMensagens

Importar Histórico do WhatsApp

Varre todas as conversas individuais da conexão ativa e importa o histórico de mensagens para o banco de dados.

A conexão deve estar ativa em memória (QR Code escaneado). Pode demorar alguns segundos dependendo do volume de conversas.

Body

Campo	Tipo	Descrição
IdConexaoobrigatório	number	ID da conexão.
IdCanalobrigatório	number	ID do canal.

Resposta 200

{
  "Sucesso":    true,
  "Importadas": 342,
  "Ignoradas":  58,
  "Chats":      37
}

POST /EnvioMensagem

Enviar Mensagem

Envia texto, arquivo (base64), ou arquivo via URL para um número WhatsApp. Suporta imagens, vídeos, PDFs e áudios.

Body

Campo	Tipo	Descrição
IdConexaoobrigatório	number	ID da conexão a usar para o envio.
Paraobrigatório	string	Número destino com código do país e DDD. Ex: `5521999999999`. Aceita JID `@c.us` ou `@lid`.
Mensagemopcional	string	Texto da mensagem. Obrigatório se não houver arquivo.
Arquivoopcional	string	Arquivo em formato Data URL base64 (`data:image/jpeg;base64,...`).
UrlArquivoopcional	string	URL pública de um arquivo. O servidor faz o download automaticamente.
NomeArquivoopcional	string	Nome do arquivo com extensão. Ex: `contrato.pdf`.
IdCampanhaopcional	number	Vincula o envio a uma campanha.

200 OK

{ "Sucesso": true, "Mensagem": "Enviado com sucesso" }

400

Número inválido, não é WhatsApp, ou parâmetros ausentes.

Exemplo — texto simples

// POST /Connect/Api/EnvioMensagem
{
  "IdConexao": 1,
  "Para":      "5521999999999",
  "Mensagem": "Olá! Temos uma oferta especial para você 🎯"
}

Exemplo — arquivo via URL

{
  "IdConexao":  1,
  "Para":       "5521999999999",
  "UrlArquivo": "https://exemplo.com/boleto.pdf",
  "NomeArquivo":"boleto.pdf",
  "Mensagem":   "Segue seu boleto em anexo."
}

POST /EnvioMensagemVoz

Enviar Mensagem de Voz (TTS)

Converte texto em áudio com voz sintética (Piper TTS) e envia como PTT (Push-to-Talk) no WhatsApp. O destinatário recebe como uma mensagem de voz normal.

Body

Campo	Tipo	Descrição
IdConexaoobrigatório	number	ID da conexão.
Paraobrigatório	string	Número destino. Ex: `5521999999999`.
Mensagemobrigatório	string	Texto a ser convertido em áudio.
TipoVozopcional	string	`M1` (voz feminina) ou `M2` (voz masculina). Padrão: `M1`.
Velocidadeopcional	number	Escala de velocidade: `-2` (muito lenta) · `-1` (lenta) · `0` (normal) · `1` (rápida) · `2` (muito rápida). Padrão: `0`.
IdCampanhaopcional	number	Vincula o envio a uma campanha.

Exemplo

{
  "IdConexao": 1,
  "Para":      "5521999999999",
  "Mensagem": "Olá! Tentamos entrar em contato e não conseguimos. Podemos conversar por aqui?",
  "TipoVoz":  "M2",
  "Velocidade": 0
}

POST /EnvioMensagemVozCallCenter

Enviar Voz com Fundo de Call Center

Idêntico ao EnvioMensagemVoz, com a adição de um ruído de fundo de call center mixado ao áudio — aumenta a percepção de atendimento humano. O destinatário recebe como PTT normal.

Body

Campo	Tipo	Descrição
IdConexaoobrigatório	number	ID da conexão.
Paraobrigatório	string	Número destino. Ex: `5521999999999`.
Mensagemobrigatório	string	Texto a ser convertido em áudio.
TipoVozopcional	string	`M1` (voz feminina) ou `M2` (voz masculina). Padrão: `M1`.
Velocidadeopcional	number	Escala: `-2` a `2`. Padrão: `0` (normal).
IdCampanhaopcional	number	Vincula o envio a uma campanha.

Use este endpoint para campanhas de cobrança ou atendimento ativo — o fundo sonoro reduz a percepção de mensagem automatizada.

Exemplo

{
  "IdConexao": 1,
  "Para":      "5521999999999",
  "Mensagem": "Olá, aqui é da central de atendimento. Identificamos um débito em aberto. Podemos regularizar agora?",
  "TipoVoz":   "M1",
  "Velocidade": 0
}

200 OK

{ "Sucesso": true, "Mensagem": "Áudio enviado com sucesso" }

400

Parâmetros obrigatórios ausentes ou conexão inativa.

GET /ListarMensagens

Listar Mensagens

Retorna o histórico de mensagens dos canais do usuário autenticado, com direção (Enviada/Recebida) calculada automaticamente.

Query String

Parâmetro	Tipo	Descrição
Limitopcional	number	Máximo de registros. Padrão: `500`.
DDDTelefoneopcional	string	Filtra mensagens de/para um número.
NaoLidasopcional	string	Passe `1` para retornar apenas mensagens não lidas.

Resposta 200

{
  "Sucesso": true,
  "Total": 42,
  "Mensagens": [
    {
      "Id":          101,
      "IdCanal":    1,
      "IdConexao":  1,
      "De":         "5521964772747",
      "Para":       "5521999999999",
      "Mensagem":   "Olá, tudo bem?",
      "Midia":      null,
      "Lida":       1,
      "DataHora":   "20/04/2026 14:32:00",
      "NomeContato":"João Silva",
      "Direcao":    "Enviada",
      "Contato":    "5521999999999"
    }
  ]
}

POST /EditarMensagem

Editar Mensagem

Atualiza o texto de uma mensagem existente no banco de dados.

Body

Campo	Tipo	Descrição
Idobrigatório	number	ID da mensagem.
Mensagemobrigatório	string	Novo texto da mensagem.

POST /ExcluirMensagem

Excluir Mensagem

Remove uma mensagem específica do banco de dados.

Body

Campo	Tipo	Descrição
Idobrigatório	number	ID da mensagem a excluir.

POST /ExcluirConversa

Excluir Conversa

Remove todas as mensagens de uma conversa com um contato específico.

Body

Campo	Tipo	Descrição
Contatoobrigatório	string	Número ou JID do contato.

POST /MarcarLidas

Marcar Mensagens como Lidas

Marca todas as mensagens recebidas de um contato como lidas.

Body

Campo	Tipo	Descrição
Contatoobrigatório	string	Número ou JID do contato.

POST /TranscreverAudio

Transcrever Áudio

Transcreve um arquivo de áudio recebido no WhatsApp usando IA. O resultado é salvo automaticamente na mensagem e retornado na resposta.

Cada transcrição consome um crédito da conta. Verifique o saldo disponível no painel.

Body

Campo	Tipo	Descrição
CaminhoMidiaobrigatório	string	Caminho relativo do arquivo. Ex: `1/1745123456_1.ogg`.
IdMensagemopcional	number	Se informado, salva a transcrição na mensagem correspondente.

Resposta 200

{
  "Sucesso":     true,
  "Transcricao": "Olá, quero saber sobre o boleto vencido.",
  "Restante":    47
}

GET /ListarCanais

Listar Canais

Retorna todos os canais do usuário autenticado. Canais agrupam conexões por departamento ou finalidade.

Resposta 200

{
  "Sucesso": true,
  "Canais": [
    { "Id": 1, "Descricao": "Vendas", "Status": 1 }
  ]
}

GET /ListarConexoes

Listar Conexões

Retorna todas as conexões (chips) do usuário com status e telefone vinculado.

Resposta 200

{
  "Sucesso": true,
  "Conexoes": [
    {
      "Id":          1,
      "IdCanal":    1,
      "Descricao":  "Chip Principal",
      "DDDTelefone":"5521999999999",
      "Status":     1
    }
  ]
}

POST /CriarCanal

Criar Canal

Cria um novo canal para agrupar conexões. Útil para separar departamentos como Vendas, Suporte e Cobrança.

Body

Campo	Tipo	Descrição
Descricaoobrigatório	string	Nome do canal. Ex: `"Cobrança"`.

POST /CriarConexao

Criar Conexão

Cadastra uma nova conexão (chip) em um canal. Após criar, use GerarQRCode para ativá-la.

Body

Campo	Tipo	Descrição
IdCanalobrigatório	number	Canal ao qual a conexão pertence.
Descricaoopcional	string	Apelido do chip. Ex: `"Chip Vendas 01"`.
DDDTelefoneopcional	string	Número do chip com código do país.

GET /ListarContatos

Listar Contatos

Retorna a agenda de contatos do usuário cadastrada na plataforma.

Resposta 200

{
  "Sucesso": true,
  "Contatos": [
    {
      "Id":          5,
      "Nome":        "Maria Oliveira",
      "DDDTelefone":"5521988888888",
      "Apelido":     "Mari"
    }
  ]
}

POST /SalvarContato

Salvar Contato

Cadastra ou atualiza um contato na agenda da plataforma.

Body

Campo	Tipo	Descrição
IdConexaoobrigatório	number	Conexão associada ao contato.
DDDTelefoneobrigatório	string	Número com código do país.
Nomeopcional	string	Nome completo do contato.
Apelidoopcional	string	Apelido ou nome curto.

Totum Connect
API Reference

Precisa de ajuda para integrar?

Totum ConnectAPI Reference

Precisa de ajuda para integrar?

Totum Connect
API Reference