API Reference
API Reference

Create Custom Message

Create a new custom message

POST/api/v1/custom_messages/

Authentication

Syllable-API-Keyrequired

Send Syllable-API-Key in the header.

Need a credential? Create or manage an API token in the Syllable Console.

Parameters

This endpoint has no declared parameters.

Request body

application/json

body CustomMessageCreateRequest required
8 fields
namestringrequired

The name of the custom message

typeenum<string>optional

Type of the custom message: greeting (voice) or email_template.

Allowed values ["greeting","email_template"]Default greeting
preamblestring | nulloptional

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.

textstringrequired

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.

subjectstring | nulloptional

Email subject. Required for email_template (in type_config); ignored otherwise.

labelstring | nulloptional

The label of the custom message

repeat_after_language_changeboolean | nulloptional

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.

rulesCustomMessageRule[]optional

Rules for time-specific message variants

Default []
Item schema
itemsCustomMessageRulerequired

A rule used to determine whether a custom message should present a variant message based on the current timestamp.

7 fields
descriptionstringrequired

The description of the rule

time_range_startstring | nulloptional

The start of the time range for the rule in 24-hour format hh:mm (should be null for "all day" cases)

Pattern ^([01]\d|2[0-3]):[0-5]\d$
time_range_endstring | nulloptional

The end of the time range for the rule in 24-hour format hh:mm (should be null for "all day" cases)

Pattern ^([01]\d|2[0-3]):[0-5]\d$
datestring | nulloptional

The date for the rule in YYYY-MM-DD format

Pattern \b(19|20)\d{2}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])\b
days_of_weekenum<string>[] | nulloptional

The days of the week for the rule

Item schema
itemsenum<string>required

Available options for day of the week for use in message rules.

Allowed values ["mo","tu","we","th","fr","sa","su"]
invertbooleanrequired

Whether the rule logic should be inverted (i.e. "not")

textstringrequired

Message text associated with the rule

Request example
{
  "name": "string",
  "type": "greeting",
  "preamble": "string",
  "text": "string",
  "subject": "string",
  "label": "string",
  "repeat_after_language_change": "string",
  "rules": []
}

Responses

200Successful Response

application/json

response CustomMessageResponse required
12 fields
namestringrequired

The name of the custom message

typeenum<string>optional

Type of the custom message: greeting (voice) or email_template.

Allowed values ["greeting","email_template"]Default greeting
preamblestring | nulloptional

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.

textstringrequired

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.

subjectstring | nulloptional

Email subject. Required for email_template (in type_config); ignored otherwise.

labelstring | nulloptional

The label of the custom message

repeat_after_language_changebooleanrequired

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).

rulesCustomMessageRule[]optional

Rules for time-specific message variants

Default []
Item schema
itemsCustomMessageRulerequired

A rule used to determine whether a custom message should present a variant message based on the current timestamp.

7 fields
descriptionstringrequired

The description of the rule

time_range_startstring | nulloptional

The start of the time range for the rule in 24-hour format hh:mm (should be null for "all day" cases)

Pattern ^([01]\d|2[0-3]):[0-5]\d$
time_range_endstring | nulloptional

The end of the time range for the rule in 24-hour format hh:mm (should be null for "all day" cases)

Pattern ^([01]\d|2[0-3]):[0-5]\d$
datestring | nulloptional

The date for the rule in YYYY-MM-DD format

Pattern \b(19|20)\d{2}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])\b
days_of_weekenum<string>[] | nulloptional

The days of the week for the rule

Item schema
itemsenum<string>required

Available options for day of the week for use in message rules.

Allowed values ["mo","tu","we","th","fr","sa","su"]
invertbooleanrequired

Whether the rule logic should be inverted (i.e. "not")

textstringrequired

Message text associated with the rule

idintegerrequired

The ID of the custom message

updated_atstring (date-time)required

Timestamp of the most recent update to the custom message

agent_countinteger | nulloptional

The number of agents using the custom message

last_updated_bystringrequired

The email address of the user who most recently updated the custom message

Response example
{
  "name": "string",
  "type": "greeting",
  "preamble": "string",
  "text": "string",
  "subject": "string",
  "label": "string",
  "repeat_after_language_change": true,
  "rules": [],
  "id": 0,
  "updated_at": "string",
  "agent_count": "string",
  "last_updated_by": "string"
}
422Validation Error

application/json

response HTTPValidationError required
1 field
detailValidationError[]optional
Item schema
itemsValidationErrorrequired
3 fields
locstring | integer[]required
Item schema
itemsstring | integerrequired
2 options
Option 1stringrequired
Option 2integerrequired
msgstringrequired
typestringrequired
Response example
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}