Skip to main content
The sms capability sends SMS text messages to phone numbers worldwide.

Providers

ProviderFeatures
TwilioGlobal coverage, delivery tracking

Basic Usage

const result = await saturn.sms({
  to: '+14155551234',
  message: 'Your verification code is: 123456',
});

console.log(result.data.messageId);

Parameters

to
string
required
Phone number in E.164 format (e.g., +14155551234).
message
string
required
Message text. Max 1600 characters.

Response

interface SmsResponse {
  data: {
    messageId: string;  // Unique message ID
    status: string;     // 'queued', 'sent', 'delivered'
  };
  metadata: {
    chargedUsdCents: number;
    provider: string;
    latencyMs: number;
    auditId: string;
  };
}

Examples

Verification Code

async function sendVerificationCode(phoneNumber: string) {
  const code = Math.floor(100000 + Math.random() * 900000);

  await saturn.sms({
    to: phoneNumber,
    message: `Your verification code is: ${code}. Valid for 10 minutes.`,
  });

  return code;
}

Alert Notification

async function sendAlert(phoneNumber: string, alert: string) {
  await saturn.sms({
    to: phoneNumber,
    message: `ALERT: ${alert}. Log in to view details.`,
  });
}

With AI-Generated Content

async function sendSmsSummary(phoneNumber: string, data: any) {
  // Generate concise summary
  const summary = await saturn.reason({
    prompt: `Summarize this data in under 160 characters for SMS:
    ${JSON.stringify(data)}`,
    maxTokens: 50,
  });

  // Send SMS
  return saturn.sms({
    to: phoneNumber,
    message: summary.data.content,
  });
}

Pricing

DestinationCost per message
US/Canada~$0.01
International~$0.05-0.15

Phone Number Format

Phone numbers must be in E.164 format: +[country code][number]
Examples:
  • US: +14155551234
  • UK: +447911123456
  • Germany: +4915123456789
// This will fail
await saturn.sms({
  to: '415-555-1234', // Wrong format
  message: 'Hello',
});

// This works
await saturn.sms({
  to: '+14155551234', // E.164 format
  message: 'Hello',
});

Message Length

SMS messages are limited by segment size:
  • Standard SMS: 160 characters
  • Unicode SMS: 70 characters
  • Long messages are split into multiple segments (each charged separately)
// This sends as 1 segment
await saturn.sms({
  to: '+1...',
  message: 'Short message', // Under 160 chars
});

// This sends as 2 segments (charged as 2 messages)
await saturn.sms({
  to: '+1...',
  message: 'A'.repeat(200), // Over 160 chars
});

Best Practices

  • Include opt-out instructions for marketing messages
  • Don’t send messages outside business hours
  • Keep messages concise
  • Include sender identification
  • Follow local regulations (TCPA in US, GDPR in EU)