Templates API

A template is a reusable message body you author once and send many times — a WhatsApp/RCS template that needs carrier approval before it can be used, an SMS or email body, or an interactive layout. Templates carry their own scope (templates:read / templates:write) distinct from messages:*, because managing a template is a content-authoring + carrier-approval action, not just a send. Base path: /api/v1/messages/templates Authentication: API key (X-API-Key) or session JWT.

Method	Path	Scope	Purpose
`GET`	`/api/v1/messages/templates`	`templates:read`	List / search templates (`?search=`, `?channel=`, `?status=`, `?waba_id=`)
`GET`	`/api/v1/messages/templates/summary`	`templates:read`	Per-channel template counts
`POST`	`/api/v1/messages/templates`	`templates:write`	Create a template
`GET`	`/api/v1/messages/templates/{id}`	`templates:read`	Get one template
`PATCH`	`/api/v1/messages/templates/{id}`	`templates:write`	Update a template
`DELETE`	`/api/v1/messages/templates/{id}`	`templates:write`	Delete a template

GET /api/v1/templates is a read-only search alias at the top level (used by the dashboard’s command-palette search) that delegates to the same list handler and scope — writes always go through /messages/templates.

Using the SDKs

curl -X GET "https://api.orbit.devotel.io/api/v1/messages/templates" \
  -H "X-API-Key: $ORBIT_API_KEY"

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await orbit.templates.list({
  channel: 'whatsapp',
  status: 'approved',
})
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/messages/templates")
print(res)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/messages/templates", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/templates')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/templates');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);

echo curl_exec($ch);

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Creating a template

For channel: "whatsapp" with a components array (the rich HEADER / BODY / FOOTER / BUTTONS shape), the template is submitted for carrier approval using your own WhatsApp Business Account credentials rather than platform-shared ones. Other channels (SMS, email, RCS, etc.) use a plain content string.

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/templates" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "channel": "whatsapp",
    "category": "utility",
    "language": "en",
    "components": [
      { "type": "BODY", "text": "Your order {{1}} has shipped and will arrive by {{2}}." }
    ]
  }'

const res = await orbit.templates.create({
  name: 'order_shipped',
  channel: 'whatsapp',
  category: 'utility',
  language: 'en',
  components: [
    { type: 'BODY', text: 'Your order {{1}} has shipped and will arrive by {{2}}.' },
  ],
})
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("POST", "/messages/templates", json={
    "name": "order_shipped",
    "channel": "whatsapp",
    "category": "utility",
    "language": "en",
    "components": [
      { "type": "BODY", "text": "Your order {{1}} has shipped and will arrive by {{2}}." }
    ]
  })
print(res)

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/templates", bytes.NewBuffer([]byte(`{
  "name": "order_shipped",
  "channel": "whatsapp",
  "category": "utility",
  "language": "en",
  "components": [
    { "type": "BODY", "text": "Your order {{1}} has shipped and will arrive by {{2}}." }
  ]
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/templates')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  name: 'order_shipped',
  channel: 'whatsapp',
  category: 'utility',
  language: 'en',
  components: [
    { type: 'BODY', text: 'Your order {{1}} has shipped and will arrive by {{2}}.' },
  ],
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/templates');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "name": "order_shipped",
  "channel": "whatsapp",
  "category": "utility",
  "language": "en",
  "components": [
    { "type": "BODY", "text": "Your order {{1}} has shipped and will arrive by {{2}}." }
  ]
}
JSON);

echo curl_exec($ch);

A newly-created WhatsApp/RCS template starts in a pending carrier-approval status; poll GET /{id} or listen for the template-approval webhook to know when it’s ready to send. The response carries the template id and its initial status:

{
  "data": {
    "id": "tpl_9f8e7d6c5b4a",
    "name": "order_shipped",
    "channel": "whatsapp",
    "status": "pending",
    "category": "utility",
    "language": "en",
    "components": [
      { "type": "BODY", "text": "Your order {{1}} has shipped and will arrive by {{2}}." }
    ]
  }
}

A WhatsApp template can only be sent once it reaches approved. For non-carrier-approval channels (SMS, email) the template is usable immediately.

Listing, updating, and deleting templates

Filter the list with ?search=, ?channel=, ?status=, or ?waba_id= — the same filter set powers the dashboard’s template picker. Read one template by id; patch the fields you want to rewrite (a WhatsApp body edit re-enters carrier approval); delete a template you no longer send.

List templates (filtered)

curl -X GET "https://api.orbit.devotel.io/api/v1/messages/templates?search=order&channel=whatsapp&status=approved" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.templates.list({
  channel: 'whatsapp',
  status: 'approved',
})
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/messages/templates?search=order&channel=whatsapp&status=approved")
print(res)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/messages/templates?search=order&channel=whatsapp&status=approved", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/templates?search=order&channel=whatsapp&status=approved')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/templates?search=order&channel=whatsapp&status=approved');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

Get a template by id

curl -X GET "https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.templates.get('tpl_9f8e7d6c5b4a')
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/messages/templates/tpl_9f8e7d6c5b4a")
print(res)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

Update a template (PATCH)

curl -X PATCH "https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "order_shipped_v2" }'

const res = await orbit.templates.update('tpl_9f8e7d6c5b4a', { name: 'order_shipped_v2' })
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("PATCH", "/messages/templates/tpl_9f8e7d6c5b4a", json={"name": "order_shipped_v2"})
print(res)

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("PATCH", "https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a", bytes.NewBuffer([]byte(`{ "name": "order_shipped_v2" }`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a')
req = Net::HTTP::Patch.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = { "name": "order_shipped_v2" }.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{ "name": "order_shipped_v2" }
JSON);

echo curl_exec($ch);

Delete a template

curl -X DELETE "https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.templates.delete('tpl_9f8e7d6c5b4a')
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("DELETE", "/messages/templates/tpl_9f8e7d6c5b4a")
print(res)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a')
req = Net::HTTP::Delete.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/templates/tpl_9f8e7d6c5b4a');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

Sending a template message

Reference the approved template by name on the unified send endpoint and pass the positional variable substitutions in variables (keyed by the {{1}}, {{2}} placeholders you authored):

curl -X POST "https://api.orbit.devotel.io/api/v1/messages" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "channel": "whatsapp",
    "template_name": "order_shipped",
    "language": "en",
    "variables": { "1": "DV-48291", "2": "Aug 26" }
  }'

const res = await orbit.request('POST', '/messages', {
  to: '+14155550123',
  channel: 'whatsapp',
  template_name: 'order_shipped',
  language: 'en',
  variables: { 1: 'DV-48291', 2: 'Aug 26' },
})
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("POST", "/messages", json={
    "to": "+14155550123",
    "channel": "whatsapp",
    "template_name": "order_shipped",
    "language": "en",
    "variables": { "1": "DV-48291", "2": "Aug 26" },
  })
print(res)

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages", bytes.NewBuffer([]byte(`{
  "to": "+14155550123",
  "channel": "whatsapp",
  "template_name": "order_shipped",
  "language": "en",
  "variables": { "1": "DV-48291", "2": "Aug 26" }
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  to: '+14155550123',
  channel: 'whatsapp',
  template_name: 'order_shipped',
  language: 'en',
  variables: { '1' => 'DV-48291', '2' => 'Aug 26' },
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "to": "+14155550123",
  "channel": "whatsapp",
  "template_name": "order_shipped",
  "language": "en",
  "variables": { "1": "DV-48291", "2": "Aug 26" }
}
JSON);

echo curl_exec($ch);

Either body, template_name, or media_url is required on every send — a template send substitutes for the freeform body. See the Messaging API reference for the full request shape. The template send returns a 202 acceptance: the message is queued and its status settles asynchronously via status webhooks.

{
  "data": {
    "id": "msg_4c8a12d9be",
    "channel": "whatsapp",
    "to": "+14155550123",
    "status": "queued",
    "template_name": "order_shipped",
    "template_language": "en"
  },
  "meta": {
    "request_id": "req_01CX7QP2LK",
    "timestamp": "2026-09-01T12:00:00Z"
  }
}

AI localization

POST /{id}/localize auto-translates one canonical template’s body and button labels into up to 25 target locales, then creates one (channel, name, language) row per locale through the same carrier-submission path a hand-authored variant uses — so each translated variant goes through carrier approval exactly like an original. GET /{id}/localizations returns the per-locale approval tracker: every language variant sharing the template’s (channel, name), each with its own status.

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/templates/tpl_abc123/localize" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targetLocales": ["es", "fr", "pt-BR"] }'

const res = await orbit.request('POST', '/messages/templates/tpl_abc123/localize', { targetLocales: ['es', 'fr', 'pt-BR'] })
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("POST", "/messages/templates/tpl_abc123/localize", json={"targetLocales": ["es", "fr", "pt-BR"]})
print(res)

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/templates/tpl_abc123/localize", bytes.NewBuffer([]byte(`{ "targetLocales": ["es", "fr", "pt-BR"] }`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/templates/tpl_abc123/localize')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = { "targetLocales": ["es", "fr", "pt-BR"] }.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/templates/tpl_abc123/localize');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{ "targetLocales": ["es", "fr", "pt-BR"] }
JSON);

echo curl_exec($ch);

The 201 response lists one entry per requested locale with a created / skipped / failed verdict, the new variant’s id for each created row, and missingLocales for locales the model returned no variant for:

{
  "data": {
    "source": {
      "id": "tpl_abc123",
      "channel": "whatsapp",
      "name": "order_shipped",
      "language": "en"
    },
    "model": "gpt-4o",
    "localizations": [
      { "locale": "es", "status": "created", "templateId": "tpl_es9a4b", "templateStatus": "pending" },
      { "locale": "fr", "status": "created", "templateId": "tpl_fr2c7e", "templateStatus": "pending" },
      { "locale": "pt-BR", "status": "skipped", "reason": "model_returned_no_variant" }
    ],
    "missingLocales": ["pt-BR"]
  },
  "meta": {
    "request_id": "req_01CY8RZ3MN",
    "timestamp": "2026-09-01T12:01:00Z"
  }
}

A skipped entry carrying reason: "variant_already_exists" means that locale already had a variant — localization is idempotent and re-running it does not duplicate the row. Because localization creates each variant through the same create path as a hand-authored one, WhatsApp/RCS variants start pending carrier approval and platform-only channels (SMS, email) start active. GET /{id}/localizations returns the per-locale approval tracker — one row per (channel, name, language) variant sharing the source template’s identity:

curl -X GET "https://api.orbit.devotel.io/api/v1/messages/templates/tpl_abc123/localizations" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.request('GET', '/messages/templates/tpl_abc123/localizations')
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/messages/templates/tpl_abc123/localizations")
print(res)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/messages/templates/tpl_abc123/localizations", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/templates/tpl_abc123/localizations')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/templates/tpl_abc123/localizations');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

{
  "data": {
    "channel": "whatsapp",
    "name": "order_shipped",
    "source_language": "en",
    "variants": [
      { "id": "tpl_abc123", "language": "en", "status": "approved", "category": "utility", "external_id": "719283174628", "submission_error": null, "is_source": true },
      { "id": "tpl_es9a4b", "language": "es", "status": "pending", "category": "utility", "external_id": null, "submission_error": null, "is_source": false },
      { "id": "tpl_fr2c7e", "language": "fr", "status": "rejected", "category": "utility", "external_id": null, "submission_error": "category_mismatch", "is_source": false }
    ]
  },
  "meta": {
    "request_id": "req_01CZAC91XY",
    "timestamp": "2026-09-01T12:05:00Z"
  }
}

Every variant sharing (channel, name) appears — whether it came from AI localization or was authored by hand. A submission_error on a variant means the carrier rejected that locale; the value is the rejection reason the carrier returned for it.

Reusable content templates

/api/v1/messages/content-templates is a separate, channel-agnostic layer above per-channel templates — group several channel-specific variants under one logical content id with an author-declared fallback chain (send WhatsApp if approved, else fall back to SMS), similar to Twilio’s Content API.

Method	Path	Purpose
`GET`	`/api/v1/messages/content-templates`	List content templates
`POST`	`/api/v1/messages/content-templates`	Create one
`GET`	`/api/v1/messages/content-templates/{id}`	Get one
`PATCH`	`/api/v1/messages/content-templates/{id}`	Update one
`DELETE`	`/api/v1/messages/content-templates/{id}`	Delete one
`GET`	`/api/v1/messages/content-templates/{id}/render`	Preview the rendered output for a channel (no send)

A create carries the logical id, a default_channel, an ordered fallback_chain, a variants object keyed by channel, and the {{N}} placeholders it expects. For a WhatsApp variant the components array uses the same rich HEADER / BODY / FOOTER / BUTTONS shape shown in “Creating a template” above:

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/content-templates" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "friendly_name": "order_shipped_group",
    "language": "en",
    "default_channel": "whatsapp",
    "fallback_chain": ["sms"],
    "variants": {
      "whatsapp": {
        "template_name": "order_shipped",
        "components": [
          { "type": "BODY", "text": "Your order {{1}} has shipped and will arrive by {{2}}." }
        ]
      },
      "sms": { "body": "Order {{1}} shipped; arrives by {{2}}." }
    },
    "variables": [
      { "name": "1", "example": "DV-48291" },
      { "name": "2", "example": "Aug 26" }
    ]
  }'

const res = await orbit.request('POST', '/messages/content-templates', {
  friendly_name: 'order_shipped_group',
  language: 'en',
  default_channel: 'whatsapp',
  fallback_chain: ['sms'],
  variants: {
    whatsapp: {
      template_name: 'order_shipped',
      components: [
        { type: 'BODY', text: 'Your order {{1}} has shipped and will arrive by {{2}}.' },
      ],
    },
    sms: { body: 'Order {{1}} shipped; arrives by {{2}}.' },
  },
  variables: [
    { name: '1', example: 'DV-48291' },
    { name: '2', example: 'Aug 26' },
  ],
})
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("POST", "/messages/content-templates", json={
    "friendly_name": "order_shipped_group",
    "language": "en",
    "default_channel": "whatsapp",
    "fallback_chain": ["sms"],
    "variants": {
      "whatsapp": {
        "template_name": "order_shipped",
        "components": [
          { "type": "BODY", "text": "Your order {{1}} has shipped and will arrive by {{2}}." }
        ]
      },
      "sms": { "body": "Order {{1}} shipped; arrives by {{2}}." }
    },
    "variables": [
      { "name": "1", "example": "DV-48291" },
      { "name": "2", "example": "Aug 26" }
    ]
  })
print(res)

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/content-templates", bytes.NewBuffer([]byte(`{
  "friendly_name": "order_shipped_group",
  "language": "en",
  "default_channel": "whatsapp",
  "fallback_chain": ["sms"],
  "variants": {
    "whatsapp": {
      "template_name": "order_shipped",
      "components": [
        { "type": "BODY", "text": "Your order {{1}} has shipped and will arrive by {{2}}." }
      ]
    },
    "sms": { "body": "Order {{1}} shipped; arrives by {{2}}." }
  },
  "variables": [
    { "name": "1", "example": "DV-48291" },
    { "name": "2", "example": "Aug 26" }
  ]
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/content-templates')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  friendly_name: 'order_shipped_group',
  language: 'en',
  default_channel: 'whatsapp',
  fallback_chain: ['sms'],
  variants: {
    whatsapp: {
      template_name: 'order_shipped',
      components: [
        { type: 'BODY', text: 'Your order {{1}} has shipped and will arrive by {{2}}.' },
      ],
    },
    sms: { body: 'Order {{1}} shipped; arrives by {{2}}.' },
  },
  variables: [
    { name: '1', example: 'DV-48291' },
    { name: '2', example: 'Aug 26' },
  ],
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/content-templates');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "friendly_name": "order_shipped_group",
  "language": "en",
  "default_channel": "whatsapp",
  "fallback_chain": ["sms"],
  "variants": {
    "whatsapp": {
      "template_name": "order_shipped",
      "components": [
        { "type": "BODY", "text": "Your order {{1}} has shipped and will arrive by {{2}}." }
      ]
    },
    "sms": { "body": "Order {{1}} shipped; arrives by {{2}}." }
  },
  "variables": [
    { "name": "1", "example": "DV-48291" },
    { "name": "2", "example": "Aug 26" }
  ]
}
JSON);

echo curl_exec($ch);

The 201 response returns the row as stored:

{
  "data": {
    "id": "ctpl_7d2f8a1b3c",
    "friendly_name": "order_shipped_group",
    "language": "en",
    "default_channel": "whatsapp",
    "fallback_chain": ["sms"],
    "variants": {
      "whatsapp": { "template_name": "order_shipped", "components": [ { "type": "BODY", "text": "Your order {{1}} has shipped and will arrive by {{2}}." } ] },
      "sms": { "body": "Order {{1}} shipped; arrives by {{2}}." }
    },
    "variables": [ { "name": "1", "example": "DV-48291" } ],
    "status": "draft",
    "organization_id": "org_2a9cd74f"
  },
  "meta": {
    "request_id": "req_01CZBN42UV",
    "timestamp": "2026-09-01T12:10:00Z"
  }
}

The render endpoint resolves a channel against the variant set — Target channel is optional and defaults to the template’s default_channel; params substitutes {{N}} positionally — so you can preview exactly what a recipient on the requested channel would see before you send:

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/content-templates/ctpl_7d2f8a1b3c/render" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "target_channel": "sms", "params": { "1": "DV-48291", "2": "Aug 26" } }'

const res = await orbit.request('POST', '/messages/content-templates/ctpl_7d2f8a1b3c/render', {
  target_channel: 'sms',
  params: { 1: 'DV-48291', 2: 'Aug 26' },
})
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("POST", "/messages/content-templates/ctpl_7d2f8a1b3c/render", json={"target_channel": "sms", "params": {"1": "DV-48291", "2": "Aug 26"}})
print(res)

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/content-templates/ctpl_7d2f8a1b3c/render", bytes.NewBuffer([]byte(`{ "target_channel": "sms", "params": { "1": "DV-48291", "2": "Aug 26" } }`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/content-templates/ctpl_7d2f8a1b3c/render')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = { "target_channel": "sms", "params": { "1" => "DV-48291", "2" => "Aug 26" } }.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/content-templates/ctpl_7d2f8a1b3c/render');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{ "target_channel": "sms", "params": { "1": "DV-48291", "2": "Aug 26" } }
JSON);

echo curl_exec($ch);

{
  "data": {
    "content_id": "ctpl_7d2f8a1b3c",
    "friendly_name": "order_shipped_group",
    "requested_channel": "sms",
    "rendered_channel": "sms",
    "resolution": "primary",
    "variant": { "body": "Order DV-48291 shipped; arrives by Aug 26." },
    "language": "en"
  },
  "meta": {
    "request_id": "req_01CZCR85PX",
    "timestamp": "2026-09-01T12:12:00Z"
  }
}

When the requested channel has no variant but a fallback resolves one, rendered_channel names the fallback hop and resolution reflects that — for example, asking for sms on a WhatsApp-only content template returns "rendered_channel": "whatsapp", "resolution": "fallback". When neither the target nor any fallback resolves, the request returns 422 NO_VARIANT_FOR_CHANNEL.

Cross-campaign analytics

GET /api/v1/templates/{id}/analytics returns the consolidated engagement rollup for a template reused across many campaigns — sent / delivered / read / click counts aggregated across every campaign that used it, rather than the per-campaign view alone.

curl -X GET "https://api.orbit.devotel.io/api/v1/templates/tpl_9f8e7d6c5b4a/analytics" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.templates.analytics('tpl_9f8e7d6c5b4a')
console.log(res.data)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/templates/tpl_9f8e7d6c5b4a/analytics")
print(res)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/templates/tpl_9f8e7d6c5b4a/analytics", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/templates/tpl_9f8e7d6c5b4a/analytics')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/templates/tpl_9f8e7d6c5b4a/analytics');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

The response contains four groups of fields:

template — the template’s id, name, channel, and current approval status. A 404 here means the id does not exist in your tenant.
totals — engagement counters aggregated across every campaign that referenced the template: sent, delivered, failed, opened, clicked.
rates — the derived funnel: delivery_rate (delivered over terminal messages), open_rate (opened over delivered), and click_rate (clicked over delivered). Rates are fractions rounded to two decimals, e.g. 0.42 for 42%.
campaigns — the per-campaign breakdown, one entry per campaign that used the template with its own counters and status, so a strong- or weak-performing campaign is visible against the rollup.

A degraded: true flag on the response means the live per-message scan timed out and the numbers were read from denormalized campaign counters instead — the totals remain correct for campaigns that have run, but very recent sends may not be reflected yet. The full response envelope, with every group populated:

{
  "data": {
    "template": {
      "id": "tpl_9f8e7d6c5b4a",
      "name": "order_shipped",
      "channel": "whatsapp",
      "status": "approved"
    },
    "totals": {
      "campaigns": 3,
      "sent": 48200,
      "delivered": 46110,
      "failed": 1240,
      "terminal": 47350,
      "opened": 21050,
      "clicked": 5180
    },
    "rates": {
      "delivery_rate": 0.96,
      "open_rate": 0.46,
      "click_rate": 0.11
    },
    "campaigns": [
      {
        "campaign_id": "camp_a1b2c3d4",
        "name": "May promo",
        "status": "completed",
        "channel": "whatsapp",
        "sent": 12000,
        "delivered": 11580,
        "failed": 410,
        "opened": 6200,
        "clicked": 1540
      }
    ],
    "degraded": false
  },
  "meta": {
    "request_id": "req_tpl_roll",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

API Reference

All Endpoints

Templates API: cross-channel approved message templates

Templates API

Using the SDKs

Creating a template

Listing, updating, and deleting templates

List templates (filtered)

Get a template by id

Update a template (PATCH)

Delete a template

Sending a template message

AI localization

Reusable content templates

Cross-campaign analytics

See also

​Templates API

​Using the SDKs

​Creating a template

​Listing, updating, and deleting templates

​List templates (filtered)

​Get a template by id

​Update a template (PATCH)

​Delete a template

​Sending a template message

​AI localization

​Reusable content templates

​Cross-campaign analytics

​See also

Templates API

Using the SDKs

Creating a template

Listing, updating, and deleting templates

List templates (filtered)

Get a template by id

Update a template (PATCH)

Delete a template

Sending a template message

AI localization

Reusable content templates

Cross-campaign analytics

See also