La Conexión Universal permite integrar el CRM Datacrazy a cualquier servicio externo que proporcione una API o webhook para envío y recepción de mensajes.
La configuración se divide en dos partes:
Envío: define cómo el CRM debe llamar a la API externa para enviar mensajes.
Recepción: define cómo el CRM debe interpretar los webhooks enviados por la API externa cuando se reciba un mensaje.
La conexión también permite configurar endpoints específicos para diferentes tipos de medios, como imágenes, vídeos, audios y documentos.
La sección Envío define cómo el CRM realizará una solicitud a la API o webhook responsable del envío de
mensajes.
URL del endpoint que será llamado por el CRM para realizar el envío del mensaje.
Ejemplo:
https://api.exemplo.com/messages
La URL puede utilizar variables disponibles en la conexión, incluyendo credenciales:
https://api.exemplo.com/${credentials.apiEndpoint}
Define el método HTTP utilizado en la solicitud.
Los métodos más comunes son:
POST
GET
PUT
PATCH
DELETE
Para el envío de mensajes, normalmente se utiliza:
POST
Define la ruta/camino utilizado para el envío de mensajes de texto.
Ejemplo:
/messages/send
Cuando se combina con la URL base:
https://api.exemplo.com/messages/send
Define el cuerpo JSON que se enviará a la API externa.
La plantilla puede utilizar variables dinámicas proporcionadas por el CRM.
Variable | Descripción |
${contact.contactId} Identificador del contacto
${contact.name} Nombre del contacto
${message.body} Contenido del mensaje
${credentials.xxx} Valor de una credencial registrada
Ejemplo:
{
"phone": "${contact.contactId}",
"name": "${contact.name}",
"message": "${message.body}"
}
Las variables se reemplazan por el CRM en el momento de la ejecución de la solicitud.
Define el tipo de contenido enviado en el cuerpo de la solicitud.
El formato más utilizado es:
application/json
Ejemplo:
Content-Type: application/json
La configuración debe corresponder al formato esperado por la API externa.
Define el tiempo máximo, en milisegundos, que el CRM esperará por la respuesta de la API.
Ejemplo:
5000
En este caso, el CRM esperará hasta 5 segundos por la respuesta de la solicitud.
Si la API no responde dentro del período configurado, la solicitud se considerará como fallida.
La autenticación define cómo el CRM deberá enviar las credenciales necesarias para acceder a la API externa.
Ninguna información de autenticación se agregará automáticamente a la solicitud.
Se utiliza cuando el endpoint no requiere autenticación.
Agrega un token de autenticación en el encabezado de la solicitud.
Ejemplo:
Authorization: Bearer SEU_TOKEN
Se utiliza cuando la API requiere una clave de acceso.
La clave puede enviarse en el encabezado según la configuración de la API.
Ejemplo:
X-API-Key: SUA_API_KEY
Utiliza autenticación HTTP Basic, normalmente basada en usuario y contraseña.
Ejemplo:
Authorization: Basic <credencial>
Permite configurar manualmente los encabezados utilizados por la API.
Es útil cuando el servicio externo utiliza un formato de autenticación específico.
La sección Credenciales permite almacenar valores sensibles que se utilizarán en las solicitudes.
Se pueden almacenar:
Tokens
Claves API
Contraseñas
Secretos
URLs
Otros valores necesarios para la integración
Nombre de la variable
Valor
Ejemplo:
Nombre: apiToken
Valor: abc123xyz
La credencial se puede utilizar en los campos de la conexión a través de la variable:
${credentials.apiToken}
Se puede utilizar en:
URL
Encabezados
Cuerpo
Parámetros de consulta
Ejemplo:
{
"token": "${credentials.apiToken}",
"message": "${message.body}"
}
Se recomienda utilizar credenciales para información sensible en lugar de insertar tokens directamente en los
templates.
Permite agregar encabezados personalizados a la solicitud de envío.
Nombre
Valor
Ejemplo:
Nombre: X-API-Key
Valor: ${credentials.apiKey}
Los encabezados se pueden utilizar cuando:
La API requiere información específica;
Existe un middleware entre el CRM y la API;
La autenticación utiliza un formato personalizado;
La API requiere identificadores adicionales.
Permite configurar parámetros que se enviarán en la URL de la solicitud.
Ejemplo:
https://api.exemplo.com/messages?instance=123
Nombre: instance
Valor: 123
También es posible utilizar credenciales:
Nombre: token
Valor: ${credentials.apiToken}
Después de realizar el envío, la API externa debe devolver un payload JSON.
El CRM utiliza este payload para identificar:
1. El ID del mensaje enviado;
2. Si el envío se realizó correctamente.
Defina la ruta dentro del JSON donde se encuentra el identificador del mensaje.
Ejemplo de respuesta:
{
"success": true,
"message": {
"id": "abc123"
}
}
Ruta del ID del Mensaje:
Defina la ruta dentro del JSON que indica si la operación se realizó correctamente.
Ejemplo:
{
"success": true,
"message": {
"id": "abc123"
}
}
Ruta de éxito:
success
El CRM considera la respuesta exitosa cuando el valor encontrado en la ruta configurada corresponde a
un valor válido de éxito.
Se consideran valores de éxito:
true
1
Valores numéricos mayores que 0
Una cadena "1"
Los valores diferentes de estos se consideran un fallo.
Ejemplo:
{
"success": false
}
Resultado:
Error al enviar
El botón Probar conexión ejecuta una solicitud utilizando la configuración actual de la conexión.
La prueba verifica si el endpoint es accesible y si la solicitud puede ser procesada.
Cuando el endpoint devuelve HTTP:
200
la prueba se considera exitosa.
Si la API devuelve otro estado HTTP u ocurre una falla durante la solicitud, la prueba se considerará
inválida.
Los detalles de la ejecución se pueden consultar en la pestaña Registros.
Los registros ayudan a identificar problemas como:
URL incorrecta;
Token inválido;
Encabezado incorrecto;
Cuerpo inválido;
Tiempo de espera agotado;
Error devuelto por la API externa.
Los puntos finales adicionales permiten configurar rutas específicas para diferentes tipos de medios.
Esto es útil cuando una API tiene puntos finales diferentes para:
Imágenes
Vídeos
Audios
Documentos
Otros anexos
Cada endpoint adicional posee su propia configuración de:
Método;
Ruta;
Plantilla del Body;
Content-Type;
Tiempo de espera;
Encabezados;
Parámetros de Query.
Al configurar un endpoint adicional, es posible definir qué tipos de medios deberán utilizar esa ruta.
Por ejemplo:
Tipos de medios:
Imagen
Vídeo
Documento
Cuando el CRM necesite enviar un medio de ese tipo, utilizará automáticamente el endpoint correspondiente.
Una conexión puede poseer:
POST /messages/text
para mensajes de texto y:
POST /messages/media
para imágenes, vídeos y documentos.
Al enviar una imagen a través del CRM, la ruta /messages/media se utilizará automáticamente.
Las plantillas de puntos finales de medios poseen variables específicas.
Variable | Descripción |
${attachment.url} URL del archivo
${attachment.mimeType} Tipo MIME del archivo
${attachment.fileName} Nombre del archivo
Ejemplo:
{
"url": "${attachment.url}",
"mimeType": "${attachment.mimeType}",
"fileName": "${attachment.fileName}",
"phone": "${contact.contactId}"
}
Una imagen JPEG normalmente tiene:
image/jpeg
Un PDF:
application/pdf
Un vídeo MP4:
video/mp4
El tipo MIME enviado debe corresponder al formato real del archivo y al formato aceptado por la API externa.
La sección Recepción define cómo el CRM recibirá e interpretará los mensajes enviados por la API externa.
El interruptor Habilitar recepción de mensajes determina si la conexión utilizará el sistema de recepción
de mensajes.
Cuando está habilitado, el CRM pone a disposición un webhook para que el servicio externo envíe los eventos de mensajes
recibidos.
Cada mensaje recibido por el CRM posee un payload enviado por la API externa.
El Mapeo de Campos informa al CRM dónde encontrar cada información dentro de ese payload.
La estructura del payload puede variar de acuerdo con el servicio integrado.
Por eso, es necesario informar la ruta correcta de cada campo.
Define dónde está ubicado el identificador del contacto en el payload recibido.
Este valor se utiliza para identificar con cuál contacto/conversación está relacionado el mensaje.
Ejemplo:
{
"data": {
"contact": {
"id": "5511999999999"
}
}
}
Define dónde se encuentra el contenido textual del mensaje.
Ejemplo:
{
"message": {
"body": "Hola, ¿qué tal?"
}
}
message.body
Define dónde se encuentra el identificador único del mensaje recibido.
Ejemplo:
{
"message": {
"id": "ABC123"
}
}
Este identificador es utilizado por el CRM para identificar el mensaje recibido.
Define dónde se encuentra el nombre del contacto en el payload.
Ejemplo:
{
"contact": {
"name": "Carlos"
}
}
Define dónde se encuentra la fecha y hora en que se recibió el mensaje.
Ejemplo:
{
"message": {
"timestamp": "2026-09-21T14:30:00Z"
}
}
message.timestamp
La marca de tiempo debe representar la fecha y hora del mensaje recibido.
Campo opcional utilizado cuando la API posee un identificador externo adicional para el mensaje.
Ejemplo:
{
"message": {
"id": "internal-id",
"externalId": "external-id"
}
}
message.externalId
Si la API no posee un ID externo separado, se puede utilizar la misma ruta configurada para el ID del
mensaje.
Define dónde se encuentra la URL del archivo cuando el mensaje contiene un medio.
Ejemplo:
{
"attachment": {
"url": "https://cdn.exemplo.com/image.jpg"
}
}
attachment.url
Define dónde se encuentra el tipo MIME del archivo recibido.
Ejemplo:
{
"attachment": {
"mimeType": "image/jpeg"
}
}
attachment.mimeType
El tipo MIME debe corresponder al tipo real del archivo.
Una configuración incorrecta puede hacer que los medios recibidos se interpreten o procesen
incorrectamente por el CRM.
Define dónde se encuentra el campo booleano que indica si el mensaje fue enviado por el propio
usuario/sistema.
Ejemplo:
{
"message": {
"isFromMe": true
}
}
message.isFromMe
El valor esperado debe ser booleano:
true
false
Este campo se utiliza principalmente para diferenciar mensajes recibidos de mensajes enviados por el
propio sistema.
La validación del webhook permite verificar si una solicitud recibida realmente fue enviada por una fuente
autorizada.
La validación es opcional.
Define el nombre del encabezado utilizado para transportar la firma.
Ejemplo:
X-Signature
Define el secreto utilizado para validar la autenticidad de la solicitud.
Este valor debe mantenerse en seguridad y, cuando sea aplicable, debe corresponder al secreto configurado en
el servicio externo.
Define el método utilizado para validar la firma.
Algoritmo criptográfico que produce un hash de 256 bits.
Se utiliza para generar una representación criptográfica de los datos.
Algoritmo de hash más antiguo, con 160 bits.
Se mantiene principalmente para compatibilidad con sistemas heredados y no se recomienda para nuevos
sistemas cuando existen alternativas más seguras.
Utiliza SHA-256 combinado con una clave secreta compartida.
Es una opción común para autenticación de webhooks porque permite verificar si el payload fue enviado por
quien posee el secreto.
Utiliza un token fijo para validación.
Ejemplo:
X-Webhook-Token: meu-token
Es una alternativa simple para APIs que no utilizan firmas criptográficas.
Los filtros permiten definir condiciones mínimas para que un webhook sea procesado por el CRM.
Define la ruta de un campo que obligatoriamente debe existir en el payload.
Ejemplo:
Si el campo no existe en el payload recibido, el CRM no procesará el evento como un mensaje.
Esto puede utilizarse para evitar que eventos que no representan mensajes sean procesados.
Permite ignorar mensajes enviados por el propio sistema.
Para ello, debe informarse la ruta del campo booleano que identifica si el mensaje fue enviado por
el propio sistema.
Ejemplo:
message.isFromMe
Si el valor encontrado en esta ruta es:
true
el CRM ignora el mensaje como un nuevo mensaje recibido del contacto.
Cuando la recepción de mensajes está habilitada, el CRM genera una URL exclusiva para la conexión.
El formato es similar a:
https://messaging.g1.datacrazy.io/webhooks/universal/{instance_id}/{webhook_id}
La URL generada debe configurarse en el servicio externo responsable de enviar los eventos de mensajes.
Cuando se reciba un mensaje en el servicio externo, deberá realizar una solicitud a esta URL,
enviando el payload del mensaje.
POST https://messaging.g1.datacrazy.io/webhooks/universal/instance_id/webhook_id
Content-Type: application/json
{
"message": {
"id": "123456",
"body": "¡Hola!"
},
"contact": {
"id": "5511999999999",
"name": "Carlos"
}
}
El CRM utilizará la Asignación de Campos configurada en la conexión para interpretar este payload.
El botón Webhook abre el modal de configuración del webhook de recepción.
En este modal se proporcionan:
URL del Webhook
La URL generada automáticamente para la conexión.
Esta es la misma URL presentada en la sección Recepción.
Token de Verificación
Campo opcional utilizado cuando el servicio externo requiere un token para validar el webhook.
El token debe configurarse de acuerdo con las reglas de la API externa.
El botón Finalizar guarda la configuración de la Conexión Universal.
Después de finalizar, la conexión podrá ser utilizada por el CRM de acuerdo con los recursos configurados:
Envío de mensajes;
Envío de medios;
Recepción de mensajes;
Autenticación;
Mapeo de respuestas;
Validación de webhook.
El botón Eliminar suprime la instancia de la Conexión Universal del CRM.
Después de la eliminación, la configuración de la conexión deja de estar disponible para su uso en el CRM.
