Templates

Template-Based System

Transactional uses a pool-based template system for SMS messaging. This ensures:

• Carrier compliance - Templates are pre-approved by carriers
• Quality control - Consistent, professional messaging
• Simplified sending - No need to compose messages in code

How Templates Work

1. Pool Templates

Pool templates are created and maintained by Transactional. They are:

• Pre-approved by carriers for all supported countries
• Designed for common use cases (OTP, alerts, notifications)
• Available to all organizations

Browse available pool templates in your dashboard under SMS > Templates > Pool Templates.

2. Adding Templates to Your Organization

Before using a pool template, you must add it to your organization:

1. Go to SMS > Templates
2. Click the Pool Templates tab
3. Find a template that matches your use case
4. Click Add to Organization

3. Custom Aliases

After adding a template, you can create a custom alias:

Pool Template: "otp-verification-v1"
Your Alias: "my-otp"

This allows you to:

• Use shorter, memorable names in your code
• Switch underlying templates without code changes
• Organize templates by your own naming convention

Template Categories

OTP / Verification

For two-factor authentication and verification codes:

Your {{company}} verification code is {{code}}. Valid for {{expiry}} minutes.

Variables: company, code, expiry

Transactional Alerts

For order confirmations, shipping updates, etc:

{{company}}: Your order #{{order_id}} has shipped. Track at {{tracking_url}}

Variables: company, order_id, tracking_url

Account Notifications

For password resets, security alerts:

{{company}}: Your password was changed. If this wasn't you, contact support.

Variables: company

Appointment Reminders

For bookings and appointments:

Reminder: Your appointment with {{business}} is on {{date}} at {{time}}.

Variables: business, date, time

Using Templates

By Template Alias

Use either the pool template's alias or your custom alias:

// Using pool template alias
await client.sms.send({
  to: '+14155551234',
  templateAlias: 'otp-verification',
  templateModel: { code: '123456' },
});
 
// Using your custom alias
await client.sms.send({
  to: '+14155551234',
  templateAlias: 'my-otp',
  templateModel: { code: '123456' },
});

By Template ID

You can also use the numeric template ID:

await client.sms.send({
  to: '+14155551234',
  templateId: 1,
  templateModel: { code: '123456' },
});

Template Variables

Templates use {{variable}} syntax for dynamic content:

Defining Variables

When adding a template, you'll see its required and optional variables:

Passing Variables

Include variables in the templateModel object:

await client.sms.send({
  to: '+14155551234',
  templateAlias: 'otp-verification',
  templateModel: {
    code: '123456',
    company: 'Acme Inc',
    expiry: '10',
  },
});

Missing Variables

If a required variable is missing, it will be replaced with an empty string. Always provide all required variables.

Custom Templates (Enterprise)

Enterprise customers can request custom templates:

1. Contact support with your template requirements
2. We'll work with carriers to get approval
3. Once approved, the template is added to your organization

Custom template requirements:

• Clear business use case
• Compliant with carrier guidelines
• No promotional content (for transactional streams)

Best Practices

1. Use Descriptive Aliases

// Good
templateAlias: 'password-reset-notification'
 
// Avoid
templateAlias: 'template1'

2. Keep Messages Concise

SMS messages over 160 characters (or 70 for Unicode) are split into multiple segments, increasing cost.

3. Include Company Name

Always include your company name for brand recognition and compliance:

Acme Inc: Your verification code is 123456

4. Add Opt-Out Instructions

For non-OTP messages, include opt-out instructions:

Reply STOP to unsubscribe

Next Steps

• Sending - Learn about single and batch sending
• Compliance - Understand regulatory requirements
• API Reference - Complete API documentation