Pular para o conteúdo

Referência

Referência: Integrações para desenvolvedores

Disponível no módulo integracoes

Atualizado em 16/11/2026

Para quem programa: o que o seu sistema recebe do ClickMassa, o que o ClickMassa espera de volta e como proteger cada ligação.

Nome na tela Sentido Para que serve
Enviar avisos (webhooks) ClickMassa para o seu sistema Cada coisa que acontece na conta (mensagem, negócio, cobrança) vira um POST no seu endereço.
Receber dados (endereços de entrada) Seu sistema para o ClickMassa O ClickMassa dá a você um endereço. Quando outro sistema envia dados a ele, por exemplo um pedido novo, o ClickMassa começa um fluxo (uma automação montada na tela).
Consultar sistema ClickMassa para o seu sistema Um fluxo ou um agente de IA chama a API do seu sistema e usa a resposta na conversa.
Chave de acesso (chave de API) Seu sistema para o ClickMassa Seu sistema chama a API do ClickMassa para ler e gravar dados.

Cada aviso é um POST com corpo JSON para o endereço que você cadastrou em Enviar avisos (webhooks). O corpo é sempre um envelope com estes campos:

Campo O que é
id Identificador do aviso. É o mesmo em todas as tentativas, no Reenviar e no Retomar.
type O evento, como message.received. A lista completa está em Eventos.
createdAt Quando o aviso foi montado para envio. Numa nova tentativa ele pode mudar. Não use para ordenar.
apiVersion A versão do formato do aviso. Hoje é 2026-10.
tenantId A sua conta.
channelId O número de WhatsApp (ou outro canal) em que aconteceu. Vem null nos eventos da conta.
data O que aconteceu, no formato de cada evento.
previous Como estava antes, nos eventos que mudam alguma coisa (a descrição do evento diz). Nos outros vem null.

O aviso também traz estes cabeçalhos:

Cabeçalho O que é
X-Webhook-Id O mesmo id do corpo.
X-Webhook-Event O mesmo type do corpo.
X-Webhook-Signature A assinatura, para você conferir que o aviso veio do ClickMassa.
X-Webhook-Sample Vem como true só no Enviar exemplo.
{
"id": "sample_3afa1ab4-4390-41a7-8ab6-3846591ac0e0",
"type": "message.received",
"createdAt": "2026-11-15T10:28:55.460Z",
"apiVersion": "2026-10",
"tenantId": "01a1dea1-8bf1-70fd-90ba-9d099adb5ccd",
"channelId": "019a0000-0000-7000-8000-000000000001",
"data": {
"id": "019a0000-0000-7000-8000-000000000004",
"conversationId": "019a0000-0000-7000-8000-000000000003",
"kind": "message",
"direction": "inbound",
"senderType": "contact",
"type": "text",
"text": "Olá, quero saber o preço",
"mediaMime": null,
"fileName": null,
"replyToId": null,
"providerMessageId": "wamid.EXEMPLO",
"status": null,
"source": null,
"channelId": "019a0000-0000-7000-8000-000000000001",
"channelName": "Atendimento",
"channelProvider": "waba",
"createdAt": "2026-10-17T13:00:00.000Z"
},
"previous": null
}

Confira a assinatura de todo aviso. Assim você sabe que ele veio do ClickMassa e não foi alterado.

O cabeçalho X-Webhook-Signature vem no formato t=<segundos>,v1=<assinatura>.

  1. Pegue o corpo cru, exatamente como chegou, antes de transformar em JSON.
  2. Leia o cabeçalho X-Webhook-Signature e separe t e v1.
  3. Calcule o HMAC-SHA256, em hexadecimal, do texto t, um ponto e o corpo cru, usando o segredo do aviso.
  4. Aceite se o resultado for igual a qualquer v1. Por 24 horas depois de Trocar segredo vêm duas assinaturas: uma do segredo novo e outra do antigo.
  5. Recuse se t estiver a mais de 5 minutos do seu relógio. Isso barra um aviso velho repetido.

O segredo aparece uma vez, ao criar o aviso ou ao trocar o segredo. Guarde em variável de ambiente, nunca no código.

const crypto = require('crypto')
function avisoValido(corpo, cabecalho, segredo, toleranciaSegundos = 300) {
const partes = String(cabecalho || '').split(',').map((parte) => {
const igual = parte.indexOf('=')
return [parte.slice(0, igual), parte.slice(igual + 1)]
})
const t = (partes.find(([nome]) => nome === 't') || [])[1]
const assinaturas = partes.filter(([nome]) => nome === 'v1').map(([, valor]) => valor)
if (!/^\d+$/.test(t || '') || Math.abs(Date.now() / 1000 - Number(t)) > toleranciaSegundos) return false
const esperada = crypto.createHmac('sha256', segredo).update(`${t}.${corpo}`).digest('hex')
return assinaturas.some((assinatura) =>
assinatura.length === esperada.length && crypto.timingSafeEqual(Buffer.from(assinatura), Buffer.from(esperada)))
}
const express = require('express')
const app = express()
app.post('/avisos', express.raw({ type: 'application/json' }), (req, res) => {
const corpo = req.body.toString('utf8')
if (!avisoValido(corpo, req.get('X-Webhook-Signature'), process.env.SEGREDO_DO_AVISO)) return res.sendStatus(401)
res.sendStatus(200)
const aviso = JSON.parse(corpo)
})
app.listen(3000)
import hashlib
import hmac
import json
import os
import time
from flask import Flask, request
app = Flask(__name__)
def aviso_valido(corpo: bytes, cabecalho: str, segredo: str, tolerancia_segundos: int = 300) -> bool:
partes = [parte.partition("=") for parte in cabecalho.split(",")]
t = next((valor for nome, _, valor in partes if nome == "t"), "")
assinaturas = [valor for nome, _, valor in partes if nome == "v1"]
if not t.isdigit() or abs(time.time() - int(t)) > tolerancia_segundos:
return False
esperada = hmac.new(segredo.encode(), t.encode() + b"." + corpo, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(assinatura, esperada) for assinatura in assinaturas)
@app.post("/avisos")
def receber_aviso():
corpo = request.get_data()
if not aviso_valido(corpo, request.headers.get("X-Webhook-Signature", ""), os.environ["SEGREDO_DO_AVISO"]):
return "", 401
aviso = json.loads(corpo)
return "", 200
<?php
function avisoValido(string $corpo, string $cabecalho, string $segredo, int $toleranciaSegundos = 300): bool
{
$t = null;
$assinaturas = [];
foreach (explode(',', $cabecalho) as $parte) {
[$nome, $valor] = array_pad(explode('=', $parte, 2), 2, '');
if ($nome === 't') {
$t = $valor;
} elseif ($nome === 'v1') {
$assinaturas[] = $valor;
}
}
if ($t === null || !ctype_digit($t) || abs(time() - (int) $t) > $toleranciaSegundos) {
return false;
}
$esperada = hash_hmac('sha256', $t . '.' . $corpo, $segredo);
foreach ($assinaturas as $assinatura) {
if (hash_equals($esperada, $assinatura)) {
return true;
}
}
return false;
}
$corpo = file_get_contents('php://input');
$cabecalho = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
if (!avisoValido($corpo, $cabecalho, getenv('SEGREDO_DO_AVISO'))) {
http_response_code(401);
exit;
}
http_response_code(200);
$aviso = json_decode($corpo, true);
Regra Valor
Tempo de espera pela resposta 10 segundos.
O que conta como entregue Qualquer resposta 2xx. Erro, redirecionamento (3xx) ou demora contam como falha.
Tentativas 4 no total, com espera crescente: 5, 10 e 20 segundos entre uma e outra.
Pausa automática Depois de 10 falhas seguidas, o ClickMassa para de enviar a esse endereço e guarda os avisos novos. Nada se perde.
Ao clicar em Retomar O ClickMassa envia os guardados, do mais antigo para o mais novo.
Pausa na mão Faz o mesmo: os avisos novos ficam guardados até você retomar.
Quanto tempo um aviso guardado espera Até 30 dias. Depois ele é descartado e aparece como falhou no Registro (o histórico das integrações, na mesma tela).

Boas práticas:

  • Responda 2xx rápido e processe depois, fora da requisição. Se o seu sistema passar de 10 segundos, o ClickMassa conta como falha e tenta de novo.
  • Não conte com a ordem. Um aviso pode chegar antes de outro que aconteceu primeiro.
  • Aceite repetição. O mesmo aviso pode chegar mais de uma vez (nova tentativa, Reenviar no Registro ou Retomar). Guarde o id e ignore os que você já processou.

Cada evento tem um nome técnico em type. Eventos de número saem nos avisos daquele número e nos avisos de Todos os números. Eventos da conta não pertencem a um número: saem só nos avisos de Todos os números, com channelId null.

Os eventos de mensagem, conversa e negócio aceitam filtro por pipeline, etapa, etiqueta e responsável. Os de contato aceitam filtro por etiqueta. Os demais não têm filtro. Para ver o corpo de exemplo de cada evento, use Enviar exemplo na tela ou a rota GET /v1/integrations/docs/events.

Evento Nome na tela Quando acontece Filtros
message.received Recebida Quando o contato manda uma mensagem. Nota interna, resposta do atendente e mensagem do fluxo não contam. pipeline, etapa, etiqueta, responsável
message.sent Enviada Quando uma mensagem sai do número para o contato. pipeline, etapa, etiqueta, responsável
message.delivered Entregue Quando a mensagem chega ao aparelho do contato. pipeline, etapa, etiqueta, responsável
message.read Lida Quando o contato abre a mensagem. pipeline, etapa, etiqueta, responsável
message.failed Falhou Quando o envio da mensagem não dá certo. pipeline, etapa, etiqueta, responsável
Evento Nome na tela Quando acontece Filtros
conversation.opened Aberta Quando uma conversa nova começa com um contato. pipeline, etapa, etiqueta, responsável
conversation.resolved Finalizada Quando a conversa é encerrada, por um atendente, pelo fluxo ou por falta de resposta. pipeline, etapa, etiqueta, responsável
conversation.transcript Histórico da finalizada Logo depois que a conversa é encerrada, envia o histórico completo do atendimento: mensagens em ordem, quem encerrou, tempos, nota da pesquisa e uma versão em texto. Notas internas ficam de fora. pipeline, etapa, etiqueta, responsável
conversation.assigned Atribuída Quando o responsável pela conversa muda, inclusive quando ela fica sem responsável. pipeline, etapa, etiqueta, responsável
conversation.reopened Reaberta Quando uma conversa encerrada volta a ficar aberta, por exemplo quando o contato escreve de novo. pipeline, etapa, etiqueta, responsável
conversation.department_changed Transferida de setor Quando a conversa passa para outro departamento, pela tela, pela API ou pelo fluxo. O departamento anterior vem em previous. pipeline, etapa, etiqueta, responsável
Evento Nome na tela Quando acontece Filtros
contact.created Criado Quando um contato novo entra na conta, cadastrado à mão, importado ou ao mandar a primeira mensagem. Evento da conta, channelId vem null. etiqueta
contact.updated Atualizado Quando um dado do contato muda, pela tela, pela API, pelo fluxo ou pelo assistente. Os campos que mudaram vêm em changedFields e o valor anterior em previous. Evento da conta, channelId vem null. etiqueta
contact.tag_added Etiqueta colocada Quando uma etiqueta é colocada no contato. Evento da conta, channelId vem null. etiqueta
contact.tag_removed Etiqueta retirada Quando uma etiqueta é retirada do contato. Evento da conta, channelId vem null. etiqueta
contact.blocked Bloqueado Quando o contato é bloqueado. Evento da conta, channelId vem null. etiqueta
contact.unblocked Desbloqueado Quando o contato é desbloqueado. Evento da conta, channelId vem null. etiqueta
Evento Nome na tela Quando acontece Filtros
deal.created Criado Quando um negócio é criado pela tela ou pela API. Evento da conta, channelId vem null. pipeline, etapa, etiqueta, responsável
deal.stage_changed Mudou de etapa Quando o negócio passa para outra etapa do pipeline. A etapa anterior vem em previous. Evento da conta, channelId vem null. pipeline, etapa, etiqueta, responsável
deal.assigned Atribuído Quando o negócio passa para outro responsável. O responsável anterior vem em previous. Evento da conta, channelId vem null. pipeline, etapa, etiqueta, responsável
deal.value_changed Valor alterado Quando o valor do negócio muda. O valor anterior vem em previous. Evento da conta, channelId vem null. pipeline, etapa, etiqueta, responsável
deal.won Ganho Quando o negócio é marcado como ganho. Evento da conta, channelId vem null. pipeline, etapa, etiqueta, responsável
deal.lost Perdido Quando o negócio é marcado como perdido, com o motivo da perda. Evento da conta, channelId vem null. pipeline, etapa, etiqueta, responsável
Evento Nome na tela Quando acontece Filtros
task.created Criada Quando uma tarefa é criada. Evento da conta, channelId vem null. Nenhum
task.completed Concluída Quando uma tarefa é marcada como feita. Evento da conta, channelId vem null. Nenhum
task.due Venceu Quando chega a hora marcada de uma tarefa que ainda não foi feita. Evento da conta, channelId vem null. Nenhum
Evento Nome na tela Quando acontece Filtros
charge.updated Atualizada Quando uma cobrança enviada numa conversa muda de situação. Evento da conta, channelId vem null. Nenhum
charge.paid Paga Quando o pagamento de uma cobrança é confirmado. Evento da conta, channelId vem null. Nenhum
Evento Nome na tela Quando acontece Filtros
appointment.changed Mudou Quando um agendamento é criado, remarcado ou cancelado. Evento da conta, channelId vem null. Nenhum
Evento Nome na tela Quando acontece Filtros
lead.received Recebido Quando chega um lead de formulário de anúncio da Meta. Evento da conta, channelId vem null. Nenhum
Evento Nome na tela Quando acontece Filtros
comment.received Recebido Quando alguém comenta numa publicação do Instagram ou do Facebook ligado ao número. Nenhum
Evento Nome na tela Quando acontece Filtros
survey.answered Respondida Quando o contato dá a nota na pesquisa de satisfação. Evento da conta, channelId vem null. Nenhum
Evento Nome na tela Quando acontece Filtros
channel.connected Conectado Quando o número conecta ou volta a conectar. Nenhum
channel.disconnected Desconectado Quando o número cai, é desconectado ou fica com erro, com o motivo. Nenhum
Evento Nome na tela Quando acontece Filtros
template.approved Aprovado Quando a Meta aprova um modelo de mensagem. Nenhum
template.rejected Rejeitado Quando a Meta rejeita um modelo de mensagem, com o motivo. Nenhum
Evento Nome na tela Quando acontece Filtros
campaign.started Começou Quando uma campanha começa a enviar. Evento da conta, channelId vem null. Nenhum
campaign.finished Terminou Quando uma campanha termina de enviar, ou para por falha. Evento da conta, channelId vem null. Nenhum
Evento Nome na tela Quando acontece Filtros
ai_goal.started Começou Quando um atendente passa a conversa para a IA com um objetivo. Evento da conta, channelId vem null. Nenhum
ai_goal.completed Cumprido Quando a IA cumpre o objetivo da conversa. Evento da conta, channelId vem null. Nenhum
ai_goal.returned Devolvido Quando a IA devolve a conversa para a equipe, com o motivo. Evento da conta, channelId vem null. Nenhum

A Chave de acesso (chave de API) deixa o seu sistema chamar a API do ClickMassa sem usar a senha de uma pessoa.

  1. Em Configurações, clique em Integrações e depois em Chaves de API, e crie a chave. Escolha só as permissões de que o seu sistema precisa.
  2. Copie a chave. Ela começa com dx_live_ e aparece inteira uma vez só.
  3. Mande a chave em cada chamada, no cabeçalho Authorization.
curl https://SEU-ENDERECO-DA-API/v1/contacts \
-H "Authorization: Bearer dx_live_..."
Regra Valor
Limite 60 chamadas por minuto, por chave.
Permissões A chave só faz o que as permissões dela permitem. Rota sem permissão volta com erro.
Registro Cada chamada aparece no Registro.
Rotas liberadas A chave só chama as rotas marcadas para uso com chave de acesso.

Cada rota pede uma ou mais permissões. Quando a rota aceita alternativas, uma delas é suficiente. A Referência da API lista todas as rotas que a Chave de acesso pode chamar, com os campos de cada uma e as permissões que ela pede. Use a busca do site para achar uma rota pelo nome ou pelo caminho.

Cada rota traz a lista de permissões no campo x-api-key-permissions. Cada item da lista externa é uma alternativa. Dentro dela, todas as permissões são necessárias.

Duas outras rotas de documentação ajudam a conferir os valores em uso:

Rota O que devolve
GET /v1/integrations/docs/events Os eventos, com quando saem, filtros e corpo de exemplo.
GET /v1/integrations/docs/delivery Tempo limite, tentativas, esperas, pausa, guarda e nomes dos cabeçalhos.

Essas rotas de documentação pedem a permissão Gerenciar canais ou Gerenciar chaves de API.

Em Receber dados (endereços de entrada) você vê os endereços que outro sistema usa para mandar dados ao ClickMassa. Existem dois tipos.

Tipo Para que serve Como o endereço nasce
Gatilho de webhook do fluxo Outro sistema (loja, formulário, ERP) chama o endereço e o fluxo começa para aquele contato. Ao configurar o gatilho no fluxo. O endereço aparece uma vez só, na hora em que é gerado.
Canal universal Outro sistema de mensagens manda as mensagens e os status para um canal do ClickMassa. Ao criar o canal. Dá para Revelar o endereço depois.
POST https://SEU-ENDERECO-DA-API/v1/public/flow-webhooks/{token}

O {token} tem 64 caracteres e faz o papel de senha. Quem tem o endereço consegue chamar. Não coloque o endereço em lugar público.

Item Como funciona
Corpo JSON, no formato que você quiser. No gatilho do fluxo você diz de onde tirar o telefone e os outros valores (por exemplo cliente.telefone).
Telefone É obrigatório. Sem ele o fluxo não começa e o Registro diz qual chave faltou.
Resposta de sucesso 202 com { "receiptId": "..." }. O fluxo roda depois, em segundo plano.
Corpo repetido Um corpo igual a outro dos últimos 5 minutos volta 200, com o receiptId do primeiro, e não roda de novo.
Token errado 404.
Limite 60 chamadas por minuto. Acima disso volta 429.
{
"cliente": { "nome": "Maria", "telefone": "5511999990000" },
"pedido": { "numero": "1042", "total": 189.9 }
}

O canal universal liga um sistema de mensagens que não tem integração pronta. Você diz no canal onde está cada dado no JSON do seu sistema.

POST {UNIVERSAL_URL}/webhooks/universal/{token} mensagem recebida
POST {UNIVERSAL_URL}/webhooks/universal/{token}/status status de uma mensagem enviada

O endereço completo aparece em Revelar. A resposta de sucesso é sempre 200 com { "received": true }, mesmo quando o corpo não vira mensagem. Nesse caso o motivo fica no Registro.

Mensagem recebida. O corpo é JSON, e cada campo abaixo é um caminho que você mapeia no canal:

Campo do mapeamento O que é Obrigatório
contactPhone Telefone do contato. Sim
contactName Nome do contato. Não
messageId Identificador da mensagem no seu sistema. Não
messageBody Texto da mensagem. Não
attachmentUrl e attachmentType Endereço e tipo do anexo. Não
fromMe Indica que a mensagem foi enviada por você, não pelo contato. Não
timestamp Quando a mensagem foi enviada. Não

Dois filtros descartam o que você não quer receber: um campo que precisa existir no corpo e um campo que, se tiver valor, faz o ClickMassa ignorar a mensagem (útil para mensagens enviadas por você mesmo).

Status de mensagem enviada. No mapeamento você diz onde estão messageId e status no corpo, e a tabela de valores traduz o status do seu sistema para o do ClickMassa.

Assinatura de entrada, quando o canal exige:

X-Vectax-Signature: sha256=<HMAC-SHA256 em hexadecimal do corpo cru, com o segredo do canal>

Sem assinatura válida, quando exigida, a resposta é 401. Diferente do aviso de saída, aqui não há t nem tolerância de tempo: a assinatura é só do corpo.

Em Consultar sistema você cadastra uma conexão: um endereço do seu sistema que o ClickMassa chama durante um fluxo (bloco API) ou a pedido de um agente de IA. Use para buscar um pedido, um saldo ou um cadastro e usar a resposta na conversa.

Parte O que você configura
Método GET, POST, PUT, PATCH ou DELETE.
Endereço A URL. Pode ter variáveis do fluxo entre chaves duplas, como {{pedido}}.
Parâmetros de consulta Pares chave e valor, também com variáveis.
Cabeçalhos Fixos, como X-Api-Key. Ficam guardados criptografados.
Credencial Bearer (token) ou Basic (usuário e senha). O ClickMassa monta o cabeçalho Authorization.
Corpo Texto com variáveis. Se o corpo é JSON, o ClickMassa escapa os valores para não quebrar o JSON.
{
"telefone": "{{telefone}}",
"pedido": "{{numero_do_pedido}}"
}

Variáveis na URL são codificadas para endereço (por exemplo, espaço vira %20). Não use endereço de rede interna: o ClickMassa recusa endereços privados e redirecionamentos.

Item Regra
Sucesso Qualquer resposta 2xx.
Falha Erro, 3xx, 4xx, 5xx, demora ou endereço recusado. O fluxo sai pela saída de falha, com o motivo.
Tempo limite 8 segundos para o bloco do fluxo e 15 segundos para ação de agente de IA.
Tamanho Até 100.000 bytes de resposta.
Uso da resposta Se a resposta é JSON, você mapeia caminhos (como cliente.saldo) para variáveis do fluxo. Só valores simples são lidos: texto, número ou verdadeiro/falso.
Ritmo Até 10 chamadas por segundo por conta (picos de 20).
Desligamento automático Depois de 10 falhas seguidas a conexão desliga sozinha. O bloco API sai direto pela saída de falha até você usar Religar.
{
"cliente": { "nome": "Maria", "saldo": 120.5 },
"status": "pago"
}

Mapeando cliente.saldo para saldo e status para situacao, o fluxo passa a ter as variáveis saldo (120.5) e situacao (pago). Um caminho que não existe vira texto vazio.