Create a message template

Create a message template. It always lands in draft: nothing is sent with it and no registration is opened until you submit it for review.

In order to get access to this endpoint, contact our support team.

POST /v2/notify/management/templates

Create a message template

cURL

curl --request POST \
  --url https://api.prelude.dev/v2/notify/management/templates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme Receipts",
  "channels": [],
  "variants": [
    {
      "locale": "en",
      "text": "Hi {{name}}, your order {{order_id}} shipped."
    }
  ],
  "default_locale": "en",
  "countries": [
    {
      "country": "ES",
      "monthly_volume": 5000
    }
  ],
  "variable_examples": {
    "name": "Ana",
    "order_id": "A-1042"
  }
}
'

201

{
  "id": "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  "type": "transactional",
  "name": "Acme Receipts",
  "status": "draft",
  "channels": [
    "sms"
  ],
  "variables": [
    "name",
    "order_id"
  ],
  "variants": [
    {
      "locale": "en",
      "text": "Hi {{name}}, your order {{order_id}} shipped.",
      "whatsapp": {
        "status": "not_submitted",
        "category": "utility",
        "rejection_reason": "invalid_format",
        "rejection_detail": "Your template has parameters placed next to each other (like {{1}}{{2}}) without text or punctuation between them.",
        "rejection_recommendation": "Separate parameters with descriptive text and ensure each parameter is clearly contextualized.",
        "error": "<string>"
      }
    }
  ],
  "default_locale": "en",
  "countries": [
    {
      "country": "ES",
      "monthly_volume": 5000
    }
  ],
  "region_statuses": {},
  "created_at": "2024-01-01T12:00:00Z"
}

Create a message template. Only name is required, and the template always lands in draft: nothing is sent with it and no registration is opened until you submit it for review.

The variables of the template are read from the {{placeholder}} names in your variants, so you never set them yourself. The same goes for status and region_statuses, which follow the review and the per-country registrations. While the template is a draft, every country in region_statuses reads draft.

WhatsApp

When channels include whatsapp, set variable_examples with one sample value per variable: WhatsApp needs them to review the template. Once we approve the template, every variant is sent to your WhatsApp Business Account for review, and the whatsapp object of each variant shows how far it is.

A transactional template is submitted to WhatsApp as utility. WhatsApp can approve it as marketing instead when it finds promotional content in it, which changes its price. The whatsapp.category of each variant shows the category WhatsApp holds.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name · string · required

The name of the template.

Example:

"Acme Receipts"

type · enum<string>

What the template is used for. Defaults to transactional.

Available options: transactional, marketing

channels · enum<string>[]

The channels the template should be delivered over.

Available options: sms, rcs, whatsapp, viber, zalo, telegram

variants · object[]

The wording of the message, one entry per locale.

Show child attributes

default_locale · string

The locale used when the recipient's own locale has no variant. Defaults to en.

Example:

"en"

countries · object[]

The countries the template should work in.

Show child attributes

variable_examples · object

One sample value per {{variable}} of the variants. WhatsApp requires a sample for every variable to review the template, so set them on a template whose channels include whatsapp. Every key must be a variable used in the variants.

Show child attributes

Example:

{ "name": "Ana", "order_id": "A-1042" }

Response

201

application/json

Created

id · string · required

The identifier of the template, to pass as template_id when sending a message.

Example:

"template_01k8ap1btqf5r9fq2c8ax5fhc9"

type · enum<string> · required

What the template is used for. Possible values are:

• transactional - A message triggered by an action of the recipient.
• marketing - A promotional message, subject to marketing rules.

Available options: transactional, marketing

name · string · required

The name of the template.

Example:

"Acme Receipts"

status · enum<string> · required

Where the template stands in the approval flow. Possible values are:

• draft - Yours to edit. Nothing is sent with it yet.
• pending - Submitted, and waiting on our review and on the per-country registrations.
• ready - Approved and usable in every country you asked for.
• rejected - Refused. Contact support for the reason.

Available options: draft, pending, ready, rejected

channels · enum<string>[] · required

The channels the template can be delivered over.

Available options: sms, rcs, whatsapp, viber, zalo, telegram

variables · string[] · required

The placeholder names found in the variants, to fill in when sending.

Example:

["name", "order_id"]

variants · object[] · required

The wording of the message, one entry per locale.

Show child attributes

default_locale · string · required

The locale used when the recipient's own locale has no variant.

Example:

"en"

countries · object[] · required

The countries the template works in, with the monthly volume recorded for each.

Show child attributes

region_statuses · object · required

The readiness of the template per country, keyed by ISO 3166-1 alpha-2 country code.

Show child attributes

created_at · string<date-time> · required

The date and time when the template was created.

Example:

"2024-01-01T12:00:00Z"