Send SMS by Tags

POST /api/messages/sms/tags

Send SMS messages to contacts that have specific tags assigned. The operation is asynchronous: the API records every message in persistence, schedules delivery in BullMQ, and returns an enqueue summary.

Authentication

• Include the bearer token in Authorization: Bearer <token>.
• Only members that accepted the current terms can trigger messaging actions; otherwise the service returns 403 Forbidden.

Request Body

interface SmsTagsMessagePayload {
  message: string; // Text body, keep under the per-provider character limit
  tagIds: string[]; // UUID identifiers of contact tags
  type?: MessageType; // Defaults to MessageType.SMS when omitted
  country?: string; // Optional ISO 3166-1 alpha-2 code for number normalization
}

Field	Type	Required	Description
message	string	Yes	SMS message content
tagIds	string[]	Yes	List of tag IDs (UUID)
type	MessageType	No	Message type (defaults to SMS)
country	string	No	ISO 3166-1 alpha-2 country code

Example Request Body

{
  "message": "Exclusive offer for VIP customers! 30% off your next purchase.",
  "tagIds": ["tag-uuid-1", "tag-uuid-2"],
  "type": "SMS",
  "country": "CO"
}

Response

The API responds with the shared MessageEnqueueResultDto contract:

interface MessageEnqueueResultDto {
  queueId: string; // BullMQ job identifier, empty when nothing was enqueued
  channel: 'sms';
  messages: Array<{
    id: string; // UUID of the persisted message
    recipient: string; // Phone number normalized by the backend
  }>;
}

Successful Response (201 Created)

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

No Valid Recipients (200 OK)

When the specified tags have no associated contacts, the service responds with 200 OK, an empty queueId, and an empty messages array.

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

Usage Examples

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;
}

// Usage
const result = await sendSmsToTags('your-token', {
  message: 'Reminder: Your appointment is tomorrow at 10:00 AM.',
  tagIds: ['patients-tag-uuid', 'reminder-tag-uuid'],
  country: 'CO'
});

console.log(`SMS sent to ${result.messages.length} patients`);

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;
}

// Usage for segmented campaign
const result = await sendSmsToTags('your-token', {
  message: 'New collection available. Check out our latest products!',
  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": "Special event this Saturday. Don'\''t miss it!",
    "tagIds": ["event-subscribers-uuid", "vip-members-uuid"],
    "country": "CO"
  }'

Common Use Cases

Segmented Campaigns

Send specific messages based on user interests or behavior:

// For users who recently purchased
await sendSmsToTags(token, {
  message: 'Thanks for your purchase. How would you rate your experience?',
  tagIds: ['recent-buyers-uuid']
});

// For inactive users
await sendSmsToTags(token, {
  message: 'We miss you. Come back and get 15% off.',
  tagIds: ['inactive-users-uuid']
});

Location-based Notifications

// For users in a specific city
await sendSmsToTags(token, {
  message: 'New store opened in Bogotá. Visit us and get discounts!',
  tagIds: ['bogota-users-uuid'],
  country: 'CO'
});

Operational Notes

• The backend removes duplicated recipients per batch and silently skips invalid destinations.
• Contacts can have multiple tags; the system prevents duplicate sends when a contact meets multiple tag criteria.
• Balance validation runs before queuing; insufficient credits return an error response without enqueuing messages.
• Use the returned queueId to correlate delivery status inside the admin UI or via dedicated status endpoints.
• Each message persists provider metadata and can be audited through the messaging module filters.