Enviar SMS por Etiquetas

POST /api/messages/sms/tags

Envía mensajes SMS a contactos que tienen etiquetas específicas asignadas. La operación es asíncrona: la API registra cada mensaje en la persistencia, programa la entrega en BullMQ y retorna un resumen del encolado.

Autenticación

• Incluye el token bearer en Authorization: Bearer <token>.
• Solo los miembros que han aceptado los términos actuales pueden activar acciones de mensajería; de lo contrario, el servicio retorna 403 Forbidden.

Cuerpo de la petición

interface SmsTagsMessagePayload {
  message: string; // Cuerpo del texto, mantén bajo el límite de caracteres del proveedor
  tagIds: string[]; // Identificadores UUID de las etiquetas de contactos
  type?: MessageType; // Por defecto MessageType.SMS cuando se omite
  country?: string; // Código ISO 3166-1 alpha-2 opcional para normalización de números
}

Campo	Tipo	Requerido	Descripción
message	string	Sí	Contenido del mensaje SMS
tagIds	string[]	Sí	Lista de IDs de etiquetas (UUID)
type	MessageType	No	Tipo de mensaje (por defecto SMS)
country	string	No	Código de país ISO 3166-1 alpha-2

Ejemplo del cuerpo

{
  "message": "¡Oferta exclusiva para clientes VIP! 30% de descuento en tu próxima compra.",
  "tagIds": ["tag-uuid-1", "tag-uuid-2"],
  "type": "SMS",
  "country": "CO"
}

Respuesta

La API responde con el contrato compartido MessageEnqueueResultDto:

interface MessageEnqueueResultDto {
  queueId: string; // Identificador del job de BullMQ, vacío cuando no se encoló nada
  channel: 'sms';
  messages: Array<{
    id: string; // UUID del mensaje persistido
    recipient: string; // Número telefónico normalizado por el backend
  }>;
}

Respuesta exitosa (201 Created)

{
  "queueId": "sms-queue-13579",
  "channel": "sms",
  "messages": [
    {
      "id": "msg-uuid-1",
      "recipient": "+573001234567"
    },
    {
      "id": "msg-uuid-2",
      "recipient": "+573009876543"
    }
  ]
}

Sin destinatarios válidos (200 OK)

Cuando las etiquetas especificadas no tienen contactos asociados, el servicio responde con 200 OK, un queueId vacío y un array de messages vacío.

{
  "queueId": "",
  "channel": "sms",
  "messages": []
}

Ejemplos de uso

Fetch API

async function sendSmsToTags(token: string, payload: SmsTagsMessagePayload) {
  const response = await fetch('/api/messages/sms/tags', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    throw new Error(`SMS tag campaign failed: ${response.status}`);
  }

  const data: MessageEnqueueResultDto = await response.json();
  return data;
}

// Uso
const result = await sendSmsToTags('your-token', {
  message: 'Recordatorio: Tu cita médica es mañana a las 10:00 AM.',
  tagIds: ['patients-tag-uuid', 'reminder-tag-uuid'],
  country: 'CO'
});

console.log(`SMS enviados a ${result.messages.length} pacientes`);

Axios

import axios from 'axios';

async function sendSmsToTags(token: string, payload: SmsTagsMessagePayload) {
  const { data } = await axios.post<MessageEnqueueResultDto>(
    '/api/messages/sms/tags',
    payload,
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    },
  );

  return data;
}

// Uso para campaña segmentada
const result = await sendSmsToTags('your-token', {
  message: 'Nueva colección disponible. ¡Echa un vistazo a nuestros últimos productos!',
  tagIds: ['fashion-lovers-uuid', 'frequent-buyers-uuid']
});

cURL

curl -X POST "/api/messages/sms/tags" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "message": "Evento especial este sábado. ¡No te lo pierdas!",
    "tagIds": ["event-subscribers-uuid", "vip-members-uuid"],
    "country": "CO"
  }'

Casos de uso comunes

Campañas segmentadas

Envía mensajes específicos basados en intereses o comportamiento de los usuarios:

// Para usuarios que compraron recientemente
await sendSmsToTags(token, {
  message: 'Gracias por tu compra. ¿Cómo calificarías tu experiencia?',
  tagIds: ['recent-buyers-uuid']
});

// Para usuarios inactivos
await sendSmsToTags(token, {
  message: 'Te extrañamos. Regresa y obtén un 15% de descuento.',
  tagIds: ['inactive-users-uuid']
});

Notificaciones por ubicación

// Para usuarios en una ciudad específica
await sendSmsToTags(token, {
  message: 'Nueva tienda abierta en Bogotá. ¡Visítanos y obtén descuentos!',
  tagIds: ['bogota-users-uuid'],
  country: 'CO'
});

Notas operacionales

• El backend elimina destinatarios duplicados por lote y omite silenciosamente destinos inválidos.
• Los contactos pueden tener múltiples etiquetas; el sistema evita envíos duplicados cuando un contacto cumple múltiples criterios de etiquetas.
• La validación del saldo se ejecuta antes del encolado; créditos insuficientes retornan una respuesta de error sin encolar mensajes.
• Usa el queueId retornado para correlacionar el estado de entrega dentro de la UI de administración o vía endpoints de estado dedicados.
• Cada mensaje persiste metadatos del proveedor y puede ser auditado a través de los filtros del módulo de mensajería.