← Back to Conversation API SKILL.md

Template Management API Reference

Manages omni-channel templates — pre-defined message formats with dynamic parameters, multiple languages, and channel-specific overrides (e.g., WhatsApp-approved templates).

Use V2 exclusively — V1 reached end-of-life on January 31, 2026.

Sections: SDK Reference | When to Use | Base URLs | API Endpoints | Key Concepts | Template Structure | Creating Templates | Updating Templates | Translation Types | Channel-Specific | Common Pitfalls | Links

SDK Reference

• Node.js
• Python
• Java
• .NET

When to Use

• Creating, updating, listing, or deleting omni-channel message templates
• Setting up multi-language template translations
• Configuring channel-specific template overrides (e.g., WhatsApp template references)

Base URLs (Separate from Conversation API)

Templates use a separate base URL (template.api.sinch.com). Region-locked — templates can only be used by apps in the same region.

API Endpoints (V2)

All endpoints prefixed with /v2/projects/{project_id}.

Key Concepts

Template Structure

{
  "id": "01F8MECHZX3TBDSZ7XRADM79XE",
  "description": "Order confirmation template",
  "version": 1,
  "default_translation": "en-US",
  "translations": [
    {
      "language_code": "en-US",
      "version": "1",
      "variables": [
        { "key": "customer_name", "preview_value": "Jane Doe" },
        { "key": "order_number", "preview_value": "ORD-12345" }
      ],
      "text_message": {
        "text": "Hi ${customer_name}, your order ${order_number} has been confirmed!"
      }
    }
  ]
}

Creating Templates

POST /v2/projects/{project_id}/templates — see Templates V2 API for full request/response details.

Key patterns:

• Simple text: Set text_message in a translation with ${variable} placeholders
• WhatsApp override: Add channel_template_overrides.WHATSAPP.template_reference pointing to an approved Meta template, with parameter_mappings linking channel-specific keys to omni-channel variable keys. On WhatsApp: uses the approved channel-specific template. On all other channels: uses the generic message.
• Multi-language: Add multiple translations with different language_code values

Updating Templates

PUT /v2/projects/{project_id}/templates/{template_id} — include current version (optimistic concurrency). PUT fully replaces the template.

Translation Message Types

Each translation supports one of: text_message, card_message, carousel_message, choice_message, location_message, media_message, template_message, list_message.

Plus: channel_template_overrides, variables, language_code, version.

Channel-Specific Templates (NOT Managed Here)

Reference these via channel_template_overrides, but cannot create/modify them here.

Common Pitfalls

1. V1 is past EOL. Use V2 (/v2/projects/...) exclusively.
2. Region locking. Templates created in US can only be used by US apps.
3. Version conflicts on update. Must pass current version. Concurrent updates fail.
4. Omni-channel vs channel-specific confusion. This API manages omni-channel templates. Channel-specific templates (like Meta-approved WhatsApp templates) are separate.
5. WhatsApp requires approved templates outside service window. Reference these in an omni-channel template with WhatsApp channel_template_overrides field.
6. Variable key format. Use ${key_name} syntax. Key must match variables array.
7. Parameter mapping for overrides. parameter_mappings maps channel-specific keys to omni-channel variable keys.

Links

• Managing Templates
• Template API Overview
• Templates V2 API
• WhatsApp Template Messages
• Sinch Dashboard Message Composer