amb-templates

Get an Apple Messages template

Returns one Apple Messages template's metadata, policies, language states, draft revision, and draft and live version IDs. The response is shallow; read a version to retrieve content and variables. An unknown or deleted template returns 404.

get/v1/amb/templates/{template_ref}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/amb/templates/{template_ref}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The requested Apple Messages template.

idstring required
workspace_idstring required
slugstring required

A template's slug: what you send it by, for example welcome-email. Email and SMS slugs stay fixed after creation. WhatsApp slugs can change only before the first submission. A slug can contain lowercase letters, numbers, hyphens, and underscores, has to start and end with a letter or a number, and can be up to 63 characters long.

namestring required

The template's display name. It defaults to the slug and can be changed on workspace templates.

descriptionstring nullable required

What the template is for. Null if it has no description.

scope'system' | 'workspace' required

Whether the template is one of our built-in templates (system) or one your workspace created (workspace).

status'draft' | 'pending' | 'active' | 'rejected' | 'inactive' required

Where the template stands as a whole. The same five states on every channel.

  • draft: nothing has ever gone live.
  • pending: nothing is live and at least one language is in review.
  • active: at least one language is live, so something can be sent.
  • rejected: it was reviewed and every language was refused.
  • inactive: nothing is live and nothing is in review, so content was withdrawn or was blocked before anything went live.

A template with one language live is active even while another is still drafted or refused. Read languages for the state of each language and its reason.

Which values a channel reports follows its review model. A channel whose content a third party reviews uses all five. On email and SMS, where content goes live on publish, a template is draft, active or inactive, and pending and rejected are reserved for the review stage coming to both, so a template reaching either is not a breaking change.

category'transactional' | 'marketing' required

Why messages use this template, fixed at creation. On Apple Messages the category describes intent and becomes the message's reporting category; it grants and restricts nothing. Use marketing for promotions and transactional for service messages.

content_kind'text' | 'attachment' | 'rich_link' | 'quick_reply' | 'list_picker' | 'time_picker' | 'form' | 'apple_pay' | 'authenticate' | 'imessage_app' | 'interactive' required

Derived message classification for filtering and statistics. Send requests use the native content.type families. Create Apple Pay and authentication requests through the conversation payment and authentication operations.

  • text: Text, optionally with a subject.
  • attachment: One or more files, images, audio clips, or videos.
  • rich_link: A link with a preview card.
  • quick_reply: Two to five reply choices.
  • list_picker: A grouped menu of choices.
  • time_picker: Appointment time slots; a reply may contain only a selected label.
  • form: A multi-page form.
  • imessage_app: A custom iMessage app interaction on a compatible device.
  • interactive: An opaque interactive reference whose subtype is unknown.
  • apple_pay: An Apple Pay request created through the conversation payment operations.
  • authenticate: An identity verification request created through the conversation authentication operations.
draft_version_idstring required
live_version_idstring required
published_version_idstring required
revisioninteger nullable required

The draft revision to use for concurrent-edit checks. Null for a built-in template.

languagesobject required

Each language the template has, keyed by canonical BCP-47 tag, with its live state and whether the draft contains unpublished changes. Content is available from version reads.

default_languagestring required

A language tag in BCP-47 form, for example en or pt-BR.

available_languagesLanguageTag[] required

Languages the live version can currently send. Empty before first publication.

on_missing_language'fallback' | 'fail' required

What a send or a preview does when it asks for a language the template cannot serve.

fallback serves the closest match instead. It tries a broader form of the same language first, so a request for pt-BR can be served by a stocked pt, and then the template's default language. A send never fails because a language is missing.

fail rejects the send rather than serving a different language, for content where sending the wrong language is worse than not sending at all. It matches the requested tag or a broader form of it and refuses a sibling variant, so pt-BR is never served by pt-PT. A send that names no language still uses the default language.

The default is per channel and stated on each channel's own field, because what a wrong-language send costs differs. Where every language is separately reviewed and separately priced, falling back silently would send content the recipient did not expect at a rate the sender did not choose.

language_source_requiredboolean required

Whether each send must name a language instead of using the live version's default.

last_submitted_atstring date-time nullable required

When the template was last published. Null before first publication and for built-in templates.

created_atstring date-time nullable required

When the template was created. Null for built-in templates.

updated_atstring date-time nullable required

When the template was last modified. Null for built-in templates.

Example response

{
  "id": "amt_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "slug": "welcome-email",
  "name": "Order shipped",
  "status": "active",
  "draft_version_id": "amv_01krdgeqcxet5s7t44vh8rt9mg",
  "live_version_id": "amv_01krdgeqcxet5s7t44vh8rt9mg",
  "published_version_id": "amv_01krdgeqcxet5s7t44vh8rt9mg",
  "languages": {
    "en": {
      "status": "live"
    },
    "nl": {
      "status": "live",
      "draft": true
    }
  },
  "default_language": "pt-BR",
  "available_languages": [
    "en"
  ],
  "on_missing_language": "fallback"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.