amb-templates

List Apple Messages templates

Returns Apple Messages templates as a cursor-paginated list. The workspace's templates come first, newest first, followed by our built-in templates by default. Set order=asc to reverse this order.

Filter by scope, category, status, content kind, or language. Use q for a case-insensitive substring match against slug, name, and description. The response is shallow; read a version to retrieve its content and variables.

get/v1/amb/templates

Request

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

Query parameters

scope'system' | 'workspace'

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

Filter by who owns the template. Use system for built-in templates and workspace for templates your workspace created.

category'transactional' | 'marketing'

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.

Return templates in this category.

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

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.

Example:active

Return templates with this lifecycle status.

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

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.

Return templates whose live or draft content is this kind.

languagestring

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

Example:pt-BR

Return templates whose published content contains this language, after the tag is canonicalized. Draft-only languages do not match.

qstring

A case-insensitive substring search across slug, name, and description.

sort'created_at'

Field to sort Apple Messages templates and their versions by.

Field to sort by.

order'asc' | 'desc'

Sort direction, ascending or descending.

Sort direction. Defaults to desc, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

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

Paginated list of Apple Messages templates.

next_cursorstring nullable required

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursorstring nullable required

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursorstring nullable required

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Example response

{
  "data": [
    {
      "id": "amt_01krdgeqcxet5s7t44vh8rt9mg",
      "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
      "slug": "welcome-email",
      "status": "active",
      "draft_version_id": "amv_01krdgeqcxet5s7t44vh8rt9mg",
      "live_version_id": "amv_01krdgeqcxet5s7t44vh8rt9mg",
      "published_version_id": "amv_01krdgeqcxet5s7t44vh8rt9mg",
      "default_language": "pt-BR",
      "available_languages": [
        "pt-BR"
      ]
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Changes

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