API de conversaciones: agregar mensaje entrante usando el ID de contacto

API de conversaciones: agregar mensaje entrante usando el Id de contacto

Cuando un aspirante escribe por SMS, WhatsApp o correo y tu sistema ya conoce su Id de contacto, esta funcionalidad permite registrar ese mensaje directamente en la conversacion correcta, sin tener que buscar primero el Id de la conversacion.

Como funciona

• Envias el Id de contacto, el canal y el contenido del mensaje.
• Si ya existe una conversacion abierta en ese canal, el mensaje se agrega a ese hilo.
• Si no existe, se crea una conversacion nueva.

Cuerpo de la peticion (representativo):

{
  "contactId": "CONTACT_ID",
  "channel": "sms | whatsapp | email | messenger | instagram | webchat",
  "endpoint": {"phone": "+15551234567", "email": "user@example.com"},
  "content": {"text": "Mensaje recibido"},
  "idempotencyKey": "identificador-unico"
}

Reglas de asociacion: si el contacto tiene varios teléfonos o correos, incluye el dato de endpoint para evitar ambiguedad.

Manejo de errores comunes

• 400: datos invalidos o faltantes.
• 401/403: falta de autorizacion o permisos insuficientes.
• 404: el contacto no existe o no es visible en tu cuenta.
• 409: conflicto por clave de idempotencia duplicada.
• 429: límite de solicitudes excedido.

Recomendacion: incluye siempre una idempotencyKey para evitar mensajes duplicados -- especialmente importante durante picos de trafico como el inicio de temporada de inscripciones.