A Conexão Universal permite integrar o CRM Datacrazy a qualquer serviço externo que disponibilize uma API ou webhook para envio e recebimento de mensagens.
A configuração é dividida em duas partes:
Envio: define como o CRM deve chamar a API externa para enviar mensagens.
Recebimento: define como o CRM deve interpretar os webhooks enviados pela API externa quando uma mensagem for recebida.
A conexão também permite configurar endpoints específicos para diferentes tipos de mídia, como imagens, vídeos, áudios e documentos.
A seção Envio define como o CRM realizará uma requisição para a API ou webhook responsável pelo envio das
mensagens.
URL do endpoint que será chamado pelo CRM para realizar o envio da mensagem.
Exemplo:
https://api.exemplo.com/messages
A URL pode utilizar variáveis disponíveis na conexão, incluindo credenciais:
https://api.exemplo.com/${credentials.apiEndpoint}
Define o método HTTP utilizado na requisição.
Os métodos mais comuns são:
POST
GET
PUT
PATCH
DELETE
Para envio de mensagens, normalmente é utilizado:
POST
Define o caminho/rota utilizado para o envio de mensagens de texto.
Exemplo:
/messages/send
Quando combinado com a URL base:
https://api.exemplo.com/messages/send
Define o corpo JSON que será enviado para a API externa.
O template pode utilizar variáveis dinâmicas fornecidas pelo CRM.
Variável | Descrição |
${contact.contactId} Identificador do contato
${contact.name} Nome do contato
${message.body} Conteúdo da mensagem
${credentials.xxx} Valor de uma credencial cadastrada
Exemplo:
{
"phone": "${contact.contactId}",
"name": "${contact.name}",
"message": "${message.body}"
}
As variáveis são substituídas pelo CRM no momento da execução da requisição.
Define o tipo de conteúdo enviado no corpo da requisição.
O formato mais utilizado é:
application/json
Exemplo:
Content-Type: application/json
A configuração deve corresponder ao formato esperado pela API externa.
Define o tempo máximo, em milissegundos, que o CRM aguardará pela resposta da API.
Exemplo:
5000
Nesse caso, o CRM aguardará até 5 segundos pela resposta da requisição.
Se a API não responder dentro do período configurado, a requisição será considerada como falha.
A autenticação define como o CRM deverá enviar as credenciais necessárias para acessar a API externa.
Nenhuma informação de autenticação será adicionada automaticamente à requisição.
Utilizado quando o endpoint não exige autenticação.
Adiciona um token de autenticação no header da requisição.
Exemplo:
Authorization: Bearer SEU_TOKEN
Utilizado quando a API exige uma chave de acesso.
A chave pode ser enviada no header conforme a configuração da API.
Exemplo:
X-API-Key: SUA_API_KEY
Utiliza autenticação HTTP Basic, normalmente baseada em usuário e senha.
Exemplo:
Authorization: Basic <credencial>
Permite configurar manualmente os headers utilizados pela API.
É útil quando o serviço externo utiliza um formato de autenticação específico.
A seção Credenciais permite armazenar valores sensíveis que serão utilizados nas requisições.
Podem ser armazenados:
Tokens
API Keys
Senhas
Segredos
URLs
Outros valores necessários para a integração
Nome da variável
Valor
Exemplo:
Nome: apiToken
Valor: abc123xyz
A credencial pode ser utilizada nos campos da conexão através da variável:
${credentials.apiToken}
Ela pode ser utilizada em:
URL
Headers
Body
Parâmetros de Query
Exemplo:
{
"token": "${credentials.apiToken}",
"message": "${message.body}"
}
Recomenda-se utilizar credenciais para informações sensíveis em vez de inserir tokens diretamente nos
templates.
Permite adicionar headers personalizados à requisição de envio.
Nome
Valor
Exemplo:
Nome: X-API-Key
Valor: ${credentials.apiKey}
Os headers podem ser utilizados quando:
A API exige informações específicas;
Existe um middleware entre o CRM e a API;
A autenticação utiliza um formato personalizado;
A API exige identificadores adicionais.
Permite configurar parâmetros que serão enviados na URL da requisição.
Exemplo:
https://api.exemplo.com/messages?instance=123
Nome: instance
Valor: 123
Também é possível utilizar credenciais:
Nome: token
Valor: ${credentials.apiToken}
Após realizar o envio, a API externa deve retornar um payload JSON.
O CRM utiliza esse payload para identificar:
1. O ID da mensagem enviada;
2. Se o envio foi realizado com sucesso.
Define o caminho dentro do JSON onde está localizado o identificador da mensagem.
Exemplo de resposta:
{
"success": true,
"message": {
"id": "abc123"
}
}
Caminho do ID da Mensagem:
Define o caminho dentro do JSON que informa se a operação foi realizada com sucesso.
Exemplo:
{
"success": true,
"message": {
"id": "abc123"
}
}
Caminho do Sucesso:
success
O CRM considera a resposta bem-sucedida quando o valor encontrado no caminho configurado corresponde a
um valor válido de sucesso.
São considerados valores de sucesso:
true
1
Valores numéricos maiores que 0
A string "1"
Valores diferentes desses são considerados falha.
Exemplo:
{
"success": false
}
Resultado:
Falha no envio
O botão Testar conexão executa uma requisição utilizando a configuração atual da conexão.
O teste verifica se o endpoint está acessível e se a requisição consegue ser processada.
Quando o endpoint retorna HTTP:
200
o teste é considerado bem-sucedido.
Caso a API retorne outro status HTTP ou ocorra uma falha durante a requisição, o teste será considerado
inválido.
Os detalhes da execução podem ser consultados na aba Logs.
Os logs ajudam a identificar problemas como:
URL incorreta;
Token inválido;
Header incorreto;
Body inválido;
Timeout;
Erro retornado pela API externa.
Os Endpoints Adicionais permitem configurar rotas específicas para diferentes tipos de mídia.
Isso é útil quando uma API possui endpoints diferentes para:
Imagens
Vídeos
Áudios
Documentos
Outros anexos
Cada endpoint adicional possui sua própria configuração de:
Método;
Caminho;
Template do Body;
Content-Type;
Timeout;
Headers;
Parâmetros de Query.
Ao configurar um endpoint adicional, é possível definir quais tipos de mídia deverão utilizar aquela rota.
Por exemplo:
Tipos de mídia:
Imagem
Vídeo
Documento
Quando o CRM precisar enviar uma mídia desse tipo, ele utilizará automaticamente o endpoint correspondente.
Uma conexão pode possuir:
POST /messages/text
para mensagens de texto e:
POST /messages/media
para imagens, vídeos e documentos.
Ao enviar uma imagem pelo CRM, a rota /messages/media será utilizada automaticamente.
Os templates de endpoints de mídia possuem variáveis específicas.
Variável | Descrição |
${attachment.url} URL do arquivo
${attachment.mimeType} MIME type do arquivo
${attachment.fileName} Nome do arquivo
Exemplo:
{
"url": "${attachment.url}",
"mimeType": "${attachment.mimeType}",
"fileName": "${attachment.fileName}",
"phone": "${contact.contactId}"
}
Uma imagem JPEG normalmente possui:
image/jpeg
Um PDF:
application/pdf
Um vídeo MP4:
video/mp4
O MIME type enviado deve corresponder ao formato real do arquivo e ao formato aceito pela API externa.
A seção Recebimento define como o CRM receberá e interpretará mensagens enviadas pela API externa.
O toggle Habilitar recebimento de mensagens determina se a conexão utilizará o sistema de recebimento
de mensagens.
Quando habilitado, o CRM disponibiliza um webhook para que o serviço externo envie os eventos de mensagens
recebidas.
Cada mensagem recebida pelo CRM possui um payload enviado pela API externa.
O Mapeamento de Campos informa ao CRM onde encontrar cada informação dentro desse payload.
A estrutura do payload pode variar de acordo com o serviço integrado.
Por isso, é necessário informar o caminho correto de cada campo.
Define onde está localizado o identificador do contato no payload recebido.
Esse valor é utilizado para identificar com qual contato/conversa a mensagem está relacionada.
Exemplo:
{
"data": {
"contact": {
"id": "5511999999999"
}
}
}
Define onde está localizado o conteúdo textual da mensagem.
Exemplo:
{
"message": {
"body": "Olá, tudo bem?"
}
}
message.body
Define onde está localizado o identificador único da mensagem recebida.
Exemplo:
{
"message": {
"id": "ABC123"
}
}
Esse identificador é utilizado pelo CRM para identificar a mensagem recebida.
Define onde está localizado o nome do contato no payload.
Exemplo:
{
"contact": {
"name": "Carlos"
}
}
Define onde está localizada a data e hora em que a mensagem foi recebida.
Exemplo:
{
"message": {
"timestamp": "2026-09-21T14:30:00Z"
}
}
message.timestamp
O timestamp deve representar a data e hora da mensagem recebida.
Campo opcional utilizado quando a API possui um identificador externo adicional para a mensagem.
Exemplo:
{
"message": {
"id": "internal-id",
"externalId": "external-id"
}
}
message.externalId
Caso a API não possua um ID externo separado, pode ser utilizado o mesmo caminho configurado para o ID da
mensagem.
Define onde está localizada a URL do arquivo quando a mensagem contém uma mídia.
Exemplo:
{
"attachment": {
"url": "https://cdn.exemplo.com/image.jpg"
}
}
attachment.url
Define onde está localizado o MIME type do arquivo recebido.
Exemplo:
{
"attachment": {
"mimeType": "image/jpeg"
}
}
attachment.mimeType
O MIME type deve corresponder ao tipo real do arquivo.
Uma configuração incorreta pode fazer com que mídias recebidas sejam interpretadas ou processadas
incorretamente pelo CRM.
Define onde está localizado o campo booleano que informa se a mensagem foi enviada pelo próprio
usuário/sistema.
Exemplo:
{
"message": {
"isFromMe": true
}
}
message.isFromMe
O valor esperado deve ser booleano:
true
false
Esse campo é utilizado principalmente para diferenciar mensagens recebidas de mensagens enviadas pelo
próprio sistema.
A validação do webhook permite verificar se uma requisição recebida realmente foi enviada por uma fonte
autorizada.
A validação é opcional.
Define o nome do header utilizado para transportar a assinatura.
Exemplo:
X-Signature
Define o segredo utilizado para validar a autenticidade da requisição.
Esse valor deve ser mantido em segurança e, quando aplicável, deve corresponder ao segredo configurado no
serviço externo.
Define o método utilizado para validar a assinatura.
Algoritmo criptográfico que produz um hash de 256 bits.
É utilizado para gerar uma representação criptográfica dos dados.
Algoritmo de hash mais antigo, com 160 bits.
É mantido principalmente para compatibilidade com sistemas legados e não é recomendado para novos
sistemas quando existem alternativas mais seguras.
Utiliza SHA-256 combinado com uma chave secreta compartilhada.
É uma opção comum para autenticação de webhooks porque permite verificar se o payload foi enviado por
quem possui o segredo.
Utiliza um token fixo para validação.
Exemplo:
X-Webhook-Token: meu-token
É uma alternativa simples para APIs que não utilizam assinaturas criptográficas.
Os filtros permitem definir condições mínimas para que um webhook seja processado pelo CRM.
Define o caminho de um campo que obrigatoriamente deve existir no payload.
Exemplo:
Se o campo não existir no payload recebido, o CRM não processará o evento como uma mensagem.
Isso pode ser utilizado para evitar que eventos que não representam mensagens sejam processados.
Permite ignorar mensagens enviadas pelo próprio sistema.
Para isso, deve ser informado o caminho do campo booleano que identifica se a mensagem foi enviada pelo
próprio sistema.
Exemplo:
message.isFromMe
Se o valor encontrado nesse caminho for:
true
o CRM ignora a mensagem como uma nova mensagem recebida do contato.
Quando o recebimento de mensagens está habilitado, o CRM gera uma URL exclusiva para a conexão.
O formato é semelhante a:
https://messaging.g1.datacrazy.io/webhooks/universal/{instance_id}/{webhook_id}
A URL gerada deve ser configurada no serviço externo responsável por enviar os eventos de mensagens.
Quando uma mensagem for recebida no serviço externo, ele deverá realizar uma requisição para essa URL,
enviando o payload da mensagem.
POST https://messaging.g1.datacrazy.io/webhooks/universal/instance_id/webhook_id
Content-Type: application/json
{
"message": {
"id": "123456",
"body": "Olá!"
},
"contact": {
"id": "5511999999999",
"name": "Carlos"
}
}
O CRM utilizará o Mapeamento de Campos configurado na conexão para interpretar esse payload.
O botão Webhook abre o modal de configuração do webhook de recebimento.
Nesse modal são disponibilizadas:
URL do Webhook
A URL gerada automaticamente para a conexão.
Essa é a mesma URL apresentada na seção Recebimento.
Token de Verificação
Campo opcional utilizado quando o serviço externo exige um token para validar o webhook.
O token deve ser configurado de acordo com as regras da API externa.
O botão Finalizar salva a configuração da Conexão Universal.
Após finalizar, a conexão poderá ser utilizada pelo CRM de acordo com os recursos configurados:
Envio de mensagens;
Envio de mídias;
Recebimento de mensagens;
Autenticação;
Mapeamento de respostas;
Validação de webhook.
O botão Remover exclui a instância da Conexão Universal do CRM.
Após a remoção, a configuração da conexão deixa de estar disponível para utilização no CRM.
