---
title: "Create an embedded message template"
method: POST
path: "/api/templates/embedded/upsert"
tags: ["templates"]
---

# Create an embedded message template

`POST /api/templates/embedded/upsert`

Create an embedded message template if it doesn't exist yet, otherwise update all embedded message templates that match the name provided.

## Request body

- UpsertEmbeddedTemplateModel
  - `body` string — Body text of the embedded message
  - `campaignDataFields` object — Campaign-level data fields available as {{field}} merge parameters during message rendering. These fields are overridden by user and event data fields of the same name.
  - `clientTemplateId` string, required — ID used by the client to identify a template. If multiple templates exist with the ID, all will be updated
  - `creatorUserId` string — Specify a specific creator user ID (email). The email must be an existing member of the project. Defaults to the organization creator.
  - `elements` Elements
    - `buttons` Button[] — Buttons to display with the embedded message. Each template may have up to two buttons with associated open URLs or custom actions.
      - `action` Action
        - `data` string — For URL actions, this field is a full URL. For custom actions, it's an empty string.
        - `type` string — For URL actions, this field is <code>openUrl</code>. For custom actions, it's the full URL of the custom action.
      - `id` string — ID of the button.
      - `title` string — Text to display on the button.
    - `defaultAction` Action
      - `data` string — For URL actions, this field is a full URL. For custom actions, it's an empty string.
      - `type` string — For URL actions, this field is <code>openUrl</code>. For custom actions, it's the full URL of the custom action.
    - `mediaUrl` string — URL for image or video content to display in the embedded message.
    - `mediaUrlCaption` string — Alt text for the media specified by <code>mediaUrl</code>.
    - `text` Text[] — Custom text fields for the template. Each custom text field has a <code>label</code> key that is predefined by the template's associated placement, and a configurable <code>text</code> value.
      - `label` string — Identifier for the text field, specified by the user who created its associated placement. This field is a key, not content. Do not display it.
      - `text` string — Text to display.
  - `isDefaultLocale` boolean — Ask your Iterable CSM to enroll you in the beta for this feature. Sets the locale associated with the request content as the template's default. If empty or flexible default locales are not enabled for the project, the project's default locale is assigned.
  - `locale` string — The locale for the content in this request. Leave empty for default locale. Iterable will automatically send the content with locale that matches a 'locale' field in the user profile.
  - `messageTypeId` integer — Message type ID
  - `name` string — Name of the template
  - `payload` JsObject
    - `underlying` object, required
  - `placementId` object — Placement ID that this template is associated with
  - `title` string — Title of the embedded message

## Response `200`

successful operation

## Other responses

- `400` — Invalid parameters
- `401` — Invalid API key

---

[API](https://skmtc.net/iterable/apis/iterable-api.md) · [All operations](https://skmtc.net/iterable/apis/iterable-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/iterable/iterable-api/revisions/afaab604b58c/schema)