Send SMS to All Contacts

POST /api/messages/sms/all

Send SMS messages to all available contacts in your database. The operation is asynchronous: the API records every message in persistence, schedules delivery in BullMQ, and returns an enqueue summary.

Caution

This endpoint sends messages to all contacts with valid phone numbers in your database. Use it carefully.

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 SmsAllMessagePayload {
  message: string; // Text body, keep under the per-provider character limit
  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
type	MessageType	No	Message type (defaults to SMS)
country	string	No	ISO 3166-1 alpha-2 country code

Example Request Body

{
  "message": "Important! Update on our terms of service available on our website.",
  "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-67890",
  "channel": "sms",
  "messages": [
    {
      "id": "msg-uuid-1",
      "recipient": "+573001234567"
    },
    {
      "id": "msg-uuid-2",
      "recipient": "+573009876543"
    },
    {
      "id": "msg-uuid-3",
      "recipient": "+573007654321"
    }
  ]
}

No Valid Recipients (200 OK)

When there are no valid contacts in the database, the service responds with 200 OK, an empty queueId, and an empty messages array.

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

Usage Examples

Fetch API

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

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

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

// Usage
const result = await sendSmsToAll('your-token', {
  message: 'Special promotion: 50% off all our products until Friday.',
  country: 'CO'
});

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

Axios

import axios from 'axios';

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

  return data;
}

// Usage
const result = await sendSmsToAll('your-token', {
  message: 'Scheduled system maintenance tomorrow from 2:00 AM to 4:00 AM.'
});

cURL

curl -X POST "/api/messages/sms/all" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "message": "Important update: New feature available in your account.",
    "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.
• Important: Consider carefully the impact of sending to all contacts, especially for cost and message relevance.