Summary — not the spec. This file orients you and links to the authoritative developers.sinch.com doc; it may lag, omit fields, or simplify nesting. Do not copy field names, nesting, encodings, or enums from here into shipped code without confirming them in the linked doc. See "Source of Truth" in this skill's SKILL.md.

← 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!"
      }
    }
  ]
}

(Summary only — confirm exact names/encoding/enums against the authoritative Templates V2 API doc before implementing.)

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. (Summary only — confirm exact names/encoding/enums against the authoritative Templates V2 API doc before implementing.)
• 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. (Summary only — confirm exact names/encoding/enums against the authoritative Templates V2 API doc before implementing.)

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