Send SMS to Specific Contacts

POST /api/messages/sms/contacts

Send SMS messages to a specific list of phone numbers. 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 SmsContactsMessagePayload {
  message: string; // Text body, keep under the per-provider character limit
  contacts: string[]; // List of phone numbers (E.164 recommended)
  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
contacts	string[]	Yes	List of phone numbers
type	MessageType	No	Message type (defaults to SMS)
country	string	No	ISO 3166-1 alpha-2 country code

Example Request Body

{
  "message": "Hello, this is a test message from SendMe",
  "contacts": ["3001234567", "3009876543"],
  "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-12345",
  "channel": "sms",
  "messages": [
    {
      "id": "msg-uuid-1",
      "recipient": "+573001234567"
    },
    {
      "id": "msg-uuid-2",
      "recipient": "+573009876543"
    }
  ]
}

No Valid Recipients (200 OK)

When the request does not resolve any valid recipients, the service responds with 200 OK, an empty queueId, and an empty messages array.

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

Usage Examples

Fetch API

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

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

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

// Usage
const result = await sendSmsToContacts('your-token', {
  message: 'Welcome to SendMe! Your account has been activated.',
  contacts: ['3001234567', '3007654321'],
  country: 'CO'
});

console.log(`SMS enqueued: ${result.messages.length}`);
console.log(`Queue ID: ${result.queueId}`);

Axios

import axios from 'axios';

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

  return data;
}

// Usage
const result = await sendSmsToContacts('your-token', {
  message: 'Your verification code is: 123456',
  contacts: ['3001234567'],
  type: 'OTP'
});

cURL

curl -X POST "/api/messages/sms/contacts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "message": "Hello, this is a message from SendMe",
    "contacts": ["3001234567", "3009876543"],
    "country": "CO"
  }'

Operational Notes

• The backend removes duplicated recipients per batch and silently skips invalid destinations.
• 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.