Enviar y Recibir Mensajes

Envíe y reciba mensajes cifrados de extremo a extremo entre el operador y el cliente.

Direcciones de Mensajes

1. Empresa → Contacto: enviada por la API, mostrada en el chat del cliente.
2. Contacto → Empresa: enviada desde el chat del cliente, entregada vía webhook.

Todo el contenido de los mensajes está cifrado de extremo a extremo. El backend solo almacena y retransmite ciphertext — nunca ve el texto plano.

Enviar Mensaje (Empresa)

Envíe mensajes de texto con application/json o mensajes de medios con multipart/form-data. Para mensajes de medios, el campo content se convierte en el pie de foto cifrado.

curl -X POST https://api.ixblix.app/api/messages/company \
  -H "X-API-Key: smci_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_xxxx",
    "content": "<base64 ciphertext AES-GCM>",
    "iv": "<base64>",
    "authTag": "<base64>",
    "encryptedKey": "<base64 clave AES envuelta con RSA-OAEP>",
    "selfEncryptedKey": "<base64 clave AES envuelta con RSA-OAEP>",
    "keyId": "<id de clave del operador>"
  }'

curl -X POST https://api.ixblix.app/api/messages/company \
  -H "X-API-Key: smci_xxxx" \
  -F "conversationId=conv_xxxx" \
  -F "content=<base64 pie de foto AES-GCM>" \
  -F "file=@archivo_cifrado.bin" \
  -F "iv=<base64>" \
  -F "authTag=<base64>" \
  -F "encryptedKey=<base64>" \
  -F "selfEncryptedKey=<base64>" \
  -F "keyId=<id de clave del operador>"

Campos de la Solicitud

Enviar Mensaje (Contacto)

curl -X POST https://api.ixblix.app/api/messages/contact \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abc123def456",
    "content": "<base64 ciphertext AES-GCM>",
    "iv": "<base64>",
    "authTag": "<base64>",
    "encryptedKey": "<base64>",
    "selfEncryptedKey": "<base64>",
    "keyId": "<id de clave del cliente>"
  }'

Listar Mensajes

curl https://api.ixblix.app/api/messages/{conversationId} \
  -H "X-API-Key: smci_xxxx"

Prefiera webhooks en lugar de polling. ixblix envía un webhook MESSAGE_RECEIVED cada vez que un contacto envía un mensaje.

Entrega y Acuses de Lectura

Todo mensaje pasa por tres estados de confirmación: sent, delivered y read. read implica delivered — marcar como leído también registra la entrega cuando aún no ocurrió. Ambos timestamps se exponen en el mensaje como deliveredAt y readAt.

Marque un mensaje del cliente como entregado (lado del operador) en cuanto su cliente lo reciba:

curl -X POST https://api.ixblix.app/api/messages/company/delivered \
  -H "X-API-Key: smci_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "conversationId": "conv_xxxx", "messageId": "msg_xxxx" }'

Marque un mensaje del cliente como leído (lado del operador) cuando el operador realmente lo haya visto:

curl -X POST https://api.ixblix.app/api/messages/company/read \
  -H "X-API-Key: smci_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "conversationId": "conv_xxxx", "messageId": "msg_xxxx" }'

Solo reporte lectura cuando la ventana del chat esté enfocada y el mensaje esté visible en el viewport. Reporte entrega cuando el mensaje esté fuera de pantalla o la ventana esté en segundo plano — de lo contrario el cliente ve un acuse de lectura falso.

Del lado del cliente, ixblix envía un webhook MESSAGE_DELIVERED cuando el dispositivo del cliente recibe su mensaje y un webhook MESSAGE_READ cuando el cliente realmente lo ve.

Reacciones

Las reacciones son mensajes cifrados con contentType establecido en react y replyToId apuntando al mensaje objetivo. Envíe content vacío para limpiar una reacción.

Vistas Previas de Notificación Push

Cuando el cliente tiene notificaciones push activadas, el dispositivo muestra una notificación para cada nuevo mensaje de la empresa. Por defecto, la notificación muestra un texto genérico "Nuevo mensaje". Para mostrar el contenido real del mensaje, incluya un encryptedPushPayload en los metadata del mensaje.

La vista previa es un pequeño objeto JSON cifrado con la clave RSA pública del cliente (RSA-OAEP/SHA-256):

{
  "text": "Hola, ¿cómo puedo ayudar?",
  "senderName": "Agente",
  "thumbnailBase64": "/9j/4AAQ..." // opcional, para mensajes de medios
}

Cifre la vista previa e inclúyala en los metadata del mensaje:

{
  "conversationId": "conv_xxxx",
  "content": "<ciphertext AES-GCM en base64>",
  "iv": "<base64>",
  "authTag": "<base64>",
  "encryptedKey": "<base64>",
  "selfEncryptedKey": "<base64>",
  "keyId": "<id de clave del operador>",
  "metadata": {
    "encryptedPushPayload": "<ciphertext RSA-OAEP en base64 del JSON de vista previa>"
  }
}

El backend nunca ve el texto plano de la vista previa push. Solo retransmite el ciphertext opaco al dispositivo del cliente, que lo descifra con su clave privada.

Helper del SDK

El SDK proporciona encryptPushPreview() para cifrar el JSON de vista previa, y sendEncryptedMessage() acepta una opción pushPreview que genera e incluye automáticamente el payload cifrado:

await client.sendEncryptedMessage(conversationId, {
  content: "Hola, ¿cómo puedo ayudar?",
  operatorIdentity: { uuid: "op-1", name: "Agente" },
  pushPreview: {
    text: "Hola, ¿cómo puedo ayudar?",
    senderName: "Agente",
  },
});