Skip to main content

​
Custom templates for Telnyx Verify

Telnyx Verify now enables you to create and register your own verification message templates instantly. This feature allows you to build compliant, branded one-time password (OTP) messages that match your brand voice while maintaining security standards.

​
Overview

Custom templates give you complete control over your verification messaging. Instead of using pre-built templates, you can create personalized messages that:
  • Align with your brand guidelines and tone of voice.
  • Include industry-specific security warnings and disclaimers.
  • Maintain compliance with regulatory requirements.
  • Deploy instantly without manual approval processes.

​
When to use custom templates

Use custom templates when:
  • You need branded verification messages that match your company’s voice.
  • Your industry requires specific compliance language in OTP messages.
  • You want to include custom security warnings or instructions.
  • You need different templates for different user segments or regions.
Use pre-built templates when:
  • You’re getting started quickly and don’t need customization.
  • Standard verification messages meet your requirements.
  • You want to minimize setup time.

​
Template variables

All verification templates support the following variables that will be automatically replaced when sending verifications:
  • {{app_name}} - Your application name as configured in the verify profile.
  • {{code}} - The verification code sent to the user.

​
Creating custom templates

Use the Telnyx API to create custom verification message templates.

​
Create a custom template

curl -L 'https://api.telnyx.com/v2/verify_profiles/templates' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "text": "Your {{app_name}} verification code is {{code}}. Do not share this code."
  }'

​
Example response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "text": "Your {{app_name}} verification code is {{code}}. Do not share this code."
  }
}
Save the template id returned in the response. You’ll need this ID to reference the template when creating verify profiles. For complete API details, see the Create Message Template API reference.

​
Real-world template examples

Here are industry-specific template examples to inspire your custom messaging:

​
E-commerce and retail

Your {{app_name}} verification code is {{code}}. Complete your purchase securely.

​
Banking and finance

{{code}} is your {{app_name}} security code. Never share this with anyone, including our staff.

​
Healthcare and telemedicine

Your {{app_name}} appointment verification code: {{code}}. If you didn't request this, contact support immediately.

​
Social media and gaming

Welcome to {{app_name}}! Your verification code is {{code}}. Start connecting with friends now.

​
Delivery and logistics

Your {{app_name}} delivery confirmation code is {{code}}. Track your package now.

​
Travel and hospitality

{{code}} is your {{app_name}} booking verification code.

​
Using custom templates in verify profiles

Once you’ve created a custom template, reference its ID when creating or updating a verify profile.

​
Example: Create verify profile with custom template

curl -L 'https://api.telnyx.com/v2/verify_profiles' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "name": "my-app-verification",
    "language": "en-US",
    "sms": {
      "messaging_template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "whitelisted_destinations": ["US", "CA"],
      "default_timeout_secs": 300,
      "code_length": 6
    }
  }'
The messaging_template_id field references your custom template. When you send verifications using this profile, your custom template will be used instead of the default.

​
Updating custom templates

You can update existing custom templates to refine messaging or fix errors.

​
Update a template

curl -L -X PATCH 'https://api.telnyx.com/v2/verify_profiles/templates/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "text": "Your {{app_name}} verification code is {{code}}. Contact support if you did not request this."
  }'

​
Example response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "text": "Your {{app_name}} verification code is {{code}}. Contact support if you did not request this."
  }
}
Updating a template affects all verify profiles that reference it. Test template changes carefully before updating production templates.
For complete API details, see the Update Message Template API reference.

​
Best practices

​
Keep messages concise

SMS messages have character limits. Keep your templates under 160 characters when possible to avoid message splitting and additional costs.

​
Include security warnings

For sensitive use cases like banking or healthcare, include warnings about not sharing codes: 
Never share this code with anyone, including our staff.
If you didn't request this, contact support immediately.

​
Test before production

Always test new templates in a development environment before using them in production verify profiles. Send test verifications to confirm:
  • Variables are replaced correctly.
  • Message formatting appears as expected.
  • Character count is within limits.
  • Links or special characters display properly.

​
Follow compliance guidelines

Ensure your templates comply with:
  • Industry regulations (HIPAA, PCI-DSS, GDPR, etc.).
  • Carrier requirements for SMS messaging.
  • Local laws regarding verification messages.
  • Your organization’s security policies.

​
Consider localization

If you serve multiple regions, create separate templates for different languages and cultures. Use the verify profile’s language parameter to organize templates by locale.

​
Next steps