Integración de usernames y BSUID de WhatsApp

Conversación con número de teléfono

Es el caso habitual y se comporta igual que antes. El agente ve el número del cliente y su nombre, y responde normalmente.

Lo que cambia por debajo: además del teléfono se registran el BSUID y el nombre de usuario si el proveedor los informa. El BSUID se usa para rutear el mensaje a la conversación existente, de modo que un cambio en el identificador que informa el proveedor durante la conversación no abre un chat duplicado. El envío sigue usando el número de teléfono.

Conversación sin número de teléfono

El cliente se identifica solo con su nombre de usuario y el proveedor no informa el teléfono. La conversación entra, se rutea a la campaña y se puede atender igual que cualquier otra, con dos diferencias visibles:

• El cliente se identifica por su nombre completo o, si el proveedor no lo informa, por su nombre de usuario. No se muestra ningún número.

• El agente dispone de un botón para pedirle formalmente el número al cliente (ver más abajo).

Internamente la conversación se identifica por el BSUID, que también es el destinatario al responder.

Cómo se identifica al cliente en pantalla

En todas las vistas se aplica la misma prioridad:

El número de teléfono se muestra como dato adicional solo cuando existe. El BSUID no se muestra nunca.

En las Grabaciones, una conversación sin número no se encuentra filtrando por Origen: hay que buscarla por Guid de interacción, campaña o agente.

Soporte por api de proveedor

La tabla describe qué hace uContact hoy, no la capacidad del proveedor:

Importante: con Infobip v1 y Wavy la conversación le llega al agente pero no puede ser responderse.

JelouWhatsApp quedó en desuso: los proveedores ya configurados siguen operando, pero la api se quitó del selector y no se pueden crear proveedores nuevos con ella.

Solicitud de número de contacto

En una conversación sin teléfono, el agente cuenta con un botón en la bandeja unificada que envía un mensaje interactivo de solicitud de información de contacto: el cliente recibe un pedido formal para compartir su número y lo acepta con un toque.

Requisitos para que el botón esté disponible:

• Api del proveedor: Meta, Gupshup V3 o Infobip v2.

• La conversación todavía no debe tener teléfono conocido.

Qué pasa cuando el cliente comparte el número

El cliente responde compartiendo una tarjeta de contacto. uContact toma de ahí el teléfono y el nombre completo y, junto con el nombre de usuario, los aplica en un solo paso:

• La conversación pasa a identificarse por el teléfono en lugar del BSUID, y se re-indexa el ruteo para que los mensajes siguientes lleguen al mismo chat.

• Se actualizan el registro de la conversación y su historial.

• En la interfaz del agente se refrescan en vivo el número, el nombre y el nombre de usuario; aparece un aviso de que el cliente compartió su información y el botón de solicitud desaparece.

• El historial completo de la conversación se mantiene.

Funciona tanto si la interacción ya está atendida por un agente como si todavía está esperando en cola.

La tarjeta de contacto no se guarda como un mensaje del chat. Cuando se consume como respuesta a la solicitud, se registra el aviso en su lugar. Si un cliente pregunta por qué no ve la tarjeta en el historial, es el comportamiento esperado.

Condiciones y limitaciones

• Tiene que haber una solicitud pendiente. Una tarjeta de contacto que el cliente comparte espontáneamente, sin solicitud previa, se trata como contenido normal del mensaje y no migra la conversación al teléfono.

• La conversación tiene que estar todavía sin teléfono. Si ya se conocía el número y el cliente comparte la tarjeta de un tercero, no reemplaza al cliente de la conversación.

• La solicitud pendiente no sobrevive un reinicio del servicio. El estado "esperando respuesta" vive en memoria: si uContact se reinicia entre el envío de la solicitud y la respuesta del cliente, esa respuesta llega como una tarjeta común y el teléfono no se aplica. El agente tiene que volver a presionar el botón.

• El BSUID rutea dentro del mismo DID. Si el mismo cliente le escribe a dos números distintos de la cuenta, son dos conversaciones separadas aunque compartan BSUID.

• Los marcadores siguen requiriendo número de teléfono. No se puede lanzar un envío masivo ni un mensaje único hacia una conversación identificada solo por nombre de usuario.

• Visibilidad del teléfono en Infobip v2. Infobip incluye el teléfono en el webhook solo si hubo interacción en los últimos 30 días desde ese número de empresa, o si el contacto está en el Contact Book. Enviar salientes con regularidad reinicia esa ventana y mantiene los teléfonos visibles.

• Cambio de número del cliente. Cuando un cliente cambia de número, Meta genera un BSUID nuevo y lo notifica. uContact todavía no procesa ese evento: la próxima conversación de ese cliente se abre como un contacto nuevo y el historial anterior queda asociado al identificador viejo. Si un cliente reporta historiales duplicados, esta es la causa probable.

Solución de problemas

Datos a pedir en un reporte: nombre y api del proveedor, guid de la interacción, payload entrante del proveedor (log api) y, si el problema es de envío, el bloque correspondiente del log externalservices.

Impacto en reportes propios

Dos cambios en ccrepo.sms_repo afectan a cualquier reporte o integración propia que lea esa tabla.

Columnas nuevas, ambas nulables y agregadas sin afectar las existentes:

callerid mantiene su significado: es el identificador de la conversación, que ahora puede ser un teléfono o un BSUID. Revisar validaciones de "solo dígitos", parseos a entero y normalizaciones que quiten caracteres no numéricos. Si un reporte necesita distinguir el caso, usar bsuid/username en lugar de inferirlo del formato de callerid.

Lo mismo aplica a ccrepo.sms_log_repo: el identificador del cliente que guarda (data1, data5) también puede ser un BSUID. Ahí no se agregaron columnas; para obtener el BSUID o el nombre de usuario hay que cruzar por channels_guid contra sms_repo.

Filas de evento: direction = 'E'. Hasta ahora sms_repo.direction solo tomaba 'I' (entrante) y 'O' (saliente). Ahora existe un tercer valor, 'E', que marca una fila de aviso de la conversación y no un mensaje real:

En estas filas la columna message contiene la clave del evento, no texto conversacional. Se guardan para poder reconstruir el aviso en el chat al recuperar la interacción (reapertura, históricos, reinicio del servicio).

Qué revisar:

• Conteos de mensajes (totales, entrantes vs. salientes, primer y último mensaje): excluir direction = 'E', o se cuentan avisos como mensajes.

• Reportes que asumen direction IN ('I','O'): ya no cubren todas las filas.

• Extracción de texto de mensajes: filtrar 'E' evita que aparezcan claves como REQUESTCONTACTINFOSENT mezcladas con el contenido real.

Solo se generan filas 'E' en conversaciones de WhatsApp donde se usó la solicitud de número.