SMS

Send SMS messages to contacts using templates and your configured SMS provider.

Send SMS

Send to Direct Phone Number

const result = await sendmator.sms.send({
  recipient_type: 'direct_sms',
  direct_sms: '+14155552671',
  template_key: 'otp-sms',
  variables: {
    code: '123456',
    appName: 'Acme App'
  }
});

console.log('SMS sent:', result.success);

Send to Contact

await sendmator.sms.send({
  recipient_type: 'contact',
  contact_external_id: 'CRM-12345',
  template_key: 'order-shipped',
  variables: {
    orderNumber: '#12345',
    trackingNumber: 'TRK-ABC123'
  }
});

Send to Tags

await sendmator.sms.send({
  recipient_type: 'tag',
  tag: ['customer', 'vip'],
  template_key: 'flash-sale',
  variables: {
    discount: '50%',
    expiresIn: '2 hours'
  }
});

Complete Request Options

await sendmator.sms.send({
  // Recipient selection (required)
  recipient_type: 'direct_sms',        // 'direct_sms' | 'contact' | 'tag' | 'all'
  direct_sms: '+14155552671',          // For direct_sms type
  contact_external_id: 'CRM-123',      // For contact type
  tag: ['customer'],                   // For tag type

  // Template (required)
  template_key: 'otp-sms',             // Template identifier
  variables: {                         // Template variables
    code: '123456'
  },

  // Optional
  sms_identity_id: 'identity-uuid',    // Specific SMS sender ID
  metadata: {                          // Custom tracking data
    campaign: 'otp',
    source: 'web'
  },
  triggerAt: '2024-02-01T10:00:00Z'   // Schedule for future
});

Execution Status

const status = await sendmator.sms.getExecutionStatus('execution-uuid');

console.log('Status:', status.data.status);
console.log('Sent at:', status.data.executed_at);

List Executions

const executions = await sendmator.sms.listExecutions({
  page: 1,
  limit: 20
});

console.log('Total:', executions.data.total);

Examples

OTP Verification

async function sendOTPSMS(phone: string, code: string) {
  await sendmator.sms.send({
    recipient_type: 'direct_sms',
    direct_sms: phone,
    template_key: 'otp-verification',
    variables: {
      code,
      appName: 'Acme App',
      expiresIn: '5 minutes'
    },
    metadata: {
      event: 'otp_sent',
      phone_last_4: phone.slice(-4)
    }
  });
}

Order Update

async function sendOrderUpdate(externalId: string, order: any) {
  await sendmator.sms.send({
    recipient_type: 'contact',
    contact_external_id: externalId,
    template_key: 'order-update',
    variables: {
      orderNumber: order.number,
      status: order.status,
      trackingUrl: order.trackingUrl
    }
  });
}

Appointment Reminder

async function sendAppointmentReminder() {
  const tomorrow = new Date();
  tomorrow.setDate(tomorrow.getDate() + 1);
  tomorrow.setHours(9, 0, 0, 0);

  await sendmator.sms.send({
    recipient_type: 'tag',
    tag: ['appointment-tomorrow'],
    template_key: 'appointment-reminder',
    triggerAt: tomorrow.toISOString(),
    variables: {
      date: 'Tomorrow',
      time: '2:00 PM',
      location: '123 Main St'
    }
  });
}

Best Practices

1. Keep it Short - SMS has character limits (160 for GSM, 70 for Unicode)
2. Use Templates - Pre-approved templates ensure compliance
3. Include Brand Name - Always identify your brand
4. Opt-Out Instructions - Include "Reply STOP to unsubscribe" in marketing SMS
5. Time Zones - Be mindful of recipient time zones for scheduled messages
6. Track Metadata - Add campaign and source tracking
7. Test Phone Numbers - Verify phone number format before sending

Recipient Types

Type	Use Case	Required Field
direct_sms	Send to phone without creating contact	direct_sms
contact	Send to existing contact	contact_external_id
tag	Send to contacts with specific tags	tag (array)
all	Send to all contacts with phone numbers	None

Next Steps

• WhatsApp SDK - Send WhatsApp messages
• Email SDK - Send emails
• OTP SDK - Multi-channel OTP verification