---
title: "Create Custom Message"
method: POST
path: "/api/v1/custom_messages/"
tags: ["custom_messages"]
---

# Create Custom Message

`POST /api/v1/custom_messages/`

Create a new custom message

## Request body

- CustomMessageCreateRequest — Request model to create a custom message.
  - `name` string, required — The name of the custom message
  - `type` 'greeting' | 'email_template' — Type of custom message. Greeting is for voice; email_template is for email (subject + body).
  - `preamble` string, nullable — An optional preamble that will be delivered before the main message, regardless of whether the current time and date match a rule or the system uses the default message. Cannot contain the "{{ language.mode }}" tag. In the case of a voice conversation, the user will not be able to interrupt the preamble. Can be used for e.g. legal disclaimers that the user must always see/hear.
  - `text` string, required — The default message that the agent will deliver if no rules are set or no rules match the current timestamp. For email_template, this is the body.
  - `subject` string, nullable — Email subject. Required for email_template (in type_config); ignored otherwise.
  - `label` string, nullable — The label of the custom message
  - `repeat_after_language_change` boolean, nullable — If true, if the caller changes language using the language menu in the custom message, the message will be repeated in the new language (not including the language menu). If omitted or null on create, false is stored. If omitted or null on update, existing value will not be changed.
  - `rules` CustomMessageRule[] — Rules for time-specific message variants
    - `description` string, required — The description of the rule
    - `time_range_start` string, nullable — The start of the time range for the rule in 24-hour format hh:mm (should be null for "all day" cases)
    - `time_range_end` string, nullable — The end of the time range for the rule in 24-hour format hh:mm (should be null for "all day" cases)
    - `date` string, nullable — The date for the rule in YYYY-MM-DD format
    - `days_of_week` DayOfWeek[], nullable — The days of the week for the rule
    - `invert` boolean, required — Whether the rule logic should be inverted (i.e. "not")
    - `text` string, required — Message text associated with the rule

## Response `200`

Successful Response

- CustomMessageResponse — Response model for custom message operations. A custom message is a pre-configured message delivered by an agent (e.g. as a greeting at the beginning of a conversation, or as an email template with subject and body). Multiple agents can use the same custom message. Greeting-type messages may have rules for time-based variants; email templates have a subject and body only. For more information, see [Console docs](https://docs.syllable.ai/Resources/Messages).
  - `name` string, required — The name of the custom message
  - `type` 'greeting' | 'email_template' — Type of custom message. Greeting is for voice; email_template is for email (subject + body).
  - `preamble` string, nullable — An optional preamble that will be delivered before the main message, regardless of whether the current time and date match a rule or the system uses the default message. Cannot contain the "{{ language.mode }}" tag. In the case of a voice conversation, the user will not be able to interrupt the preamble. Can be used for e.g. legal disclaimers that the user must always see/hear.
  - `text` string, required — The default message that the agent will deliver if no rules are set or no rules match the current timestamp. For email_template, this is the body.
  - `subject` string, nullable — Email subject. Required for email_template (in type_config); ignored otherwise.
  - `label` string, nullable — The label of the custom message
  - `repeat_after_language_change` boolean, required — If true, if the caller changes language using the language menu in the custom message, the message will be repeated in the new language (not including the language menu).
  - `rules` CustomMessageRule[] — Rules for time-specific message variants
    - `description` string, required — The description of the rule
    - `time_range_start` string, nullable — The start of the time range for the rule in 24-hour format hh:mm (should be null for "all day" cases)
    - `time_range_end` string, nullable — The end of the time range for the rule in 24-hour format hh:mm (should be null for "all day" cases)
    - `date` string, nullable — The date for the rule in YYYY-MM-DD format
    - `days_of_week` DayOfWeek[], nullable — The days of the week for the rule
    - `invert` boolean, required — Whether the rule logic should be inverted (i.e. "not")
    - `text` string, required — Message text associated with the rule
  - `id` integer, required — The ID of the custom message
  - `updated_at` string, date-time, required — Timestamp of the most recent update to the custom message
  - `agent_count` integer, nullable — The number of agents using the custom message
  - `last_updated_by` string, required — The email address of the user who most recently updated the custom message

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/asksyllable/apis/syllablesdk.md) · [All operations](https://skmtc.net/asksyllable/apis/syllablesdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/asksyllable/syllablesdk/versions/3e0721420b23/schema)