tencent_sms 0.2.0

Tencent Cloud SMS SDK for Dart/Flutter - verification code, batch send, CSV template mapping

tencent_sms

Tencent Cloud SMS SDK for Dart/Flutter - Supporting verification code sending, batch sending, CSV template mapping, and multi-scene templates.

中文文档

Features

• Verification Code Sending - Single verification code SMS sending
• Batch Sending - Support batch sending to multiple phone numbers
• Multi-scene Templates - Different templates for login/registration/password reset
• CSV Template Mapping - Support reading template IDs from CSV exported from Tencent Cloud console
• TC3 Signature - Using the latest Tencent Cloud API signature algorithm
• Pure Dart - No framework dependency, supports Flutter and server-side

Installation

dependencies:
  tencent_sms: ^0.2.0

Quick Start

import 'package:tencent_sms/tencent_sms.dart';

void main() async {
  final config = TencentSmsConfig(
    secretId: 'your-secret-id',
    secretKey: 'your-secret-key',
    smsSdkAppId: '1400000000',
    signName: 'YourSignName',
    region: 'ap-guangzhou',
    verificationTemplateId: '123456',
  );

  final client = TencentSmsClient(config);

  try {
    final response = await client.sendVerificationCode(
      phoneNumber: '[phone]',
      verificationCode: '123456',
    );
    print('Sent successfully: ${response.requestId}');
  } catch (e) {
    print('Failed to send: $e');
  } finally {
    client.close();
  }
}

Usage

Send Verification Code

// Single verification code (using default template)
await client.sendVerificationCode(
  phoneNumber: '[phone]',
  verificationCode: '123456',
);

// Specify template ID
await client.sendVerificationCode(
  phoneNumber: '[phone]',
  verificationCode: '123456',
  templateId: '789012',
);

Multi-scene Templates

final config = TencentSmsConfig(
  // ...basic config
  templateCsvPath: 'config/sms/templates.csv',
  verificationTemplateNameLogin: 'Login Verification',
  verificationTemplateNameRegister: 'Registration Verification',
  verificationTemplateNameResetPassword: 'Password Reset Verification',
);

final client = TencentSmsClient(config);

// Login scene
await client.sendVerificationCodeForScene(
  scene: SmsVerificationScene.login,
  phoneNumber: '[phone]',
  verificationCode: '123456',
);

// Registration scene
await client.sendVerificationCodeForScene(
  scene: SmsVerificationScene.register,
  phoneNumber: '[phone]',
  verificationCode: '654321',
);

Batch Sending

final response = await client.sendSms(
  phoneNumbers: ['[phone]', '[phone]'],
  templateId: '123456',
  templateParams: ['Order shipped', 'SF Express', 'SF123456'],
);

for (final status in response.statuses) {
  print('${status.phoneNumber}: ${status.isOk ? 'Success' : status.message}');
}

Configuration

Parameter	Required	Description
secretId	Yes	Tencent Cloud SecretId
secretKey	Yes	Tencent Cloud SecretKey
smsSdkAppId	Yes	SMS SDK AppID
signName	Yes	SMS signature
region	No	Region, default ap-guangzhou
verificationTemplateId	No	Verification template ID (highest priority)
templateCsvPath	No	Template CSV file path
verificationTemplateNameLogin	No	Login template name
verificationTemplateNameRegister	No	Registration template name
verificationTemplateNameResetPassword	No	Password reset template name

Phone Number Format

Supports the following formats, automatically converted to E.164 format:

• [phone] - E.164 format (used as-is)
• 13800138000 - 11-digit Chinese mobile number (auto-prefixed with +86)
• 008613800138000 - International format (auto-converted)

Exception Handling

try {
  await client.sendVerificationCode(...);
} on TencentSmsConfigException catch (e) {
  // Configuration error
  print('Config error: ${e.message}');
} on TencentSmsSendException catch (e) {
  // Send failure
  print('Send failed: ${e.message} (${e.code})');
} on TencentSmsHttpException catch (e) {
  // HTTP request failure
  print('Network error: HTTP ${e.statusCode}');
}

Serverpod Integration

If you use Serverpod, we recommend using tencent_sms_serverpod package for reading config from passwords.yaml:

dependencies:
  tencent_sms_serverpod: ^0.2.0

See tencent_sms_serverpod for details.

Resources

• Tencent Cloud SMS Documentation
• SendSms API Documentation

License

MIT License