API Reference
API Reference

Custom Messages List

List the existing custom_messages

GET/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

Query parameters

page integer | null query optional

The page number from which to start (0-based)

Default 0Minimum 0Example 0
limit integer query optional

The maximum number of items to return

Default 25Minimum 0Example 25
search_fields enum<string>[] query optional

String names of fields to search. Correspond by index to search field values

Default []Example name
Item schema
itemsenum<string>required
Allowed values ["id","name","name_exact","text","label","type","updated_at","agent_id"]
search_field_values string[] query optional

Values of fields to search. Correspond by index to search fields. Unless field name contains "list", an individual search field value cannot be a list

Default []Example Some Object Name
Item schema
itemsstringrequired
order_by enum<string> | null query optional

The field whose value should be used to order the results

Allowed values ["id","name","name_exact","text","label","type","updated_at","agent_id"]Example name
order_by_direction enum<string> | null query optional

The direction in which to order the results

Allowed values ["asc","desc"]
fields enum<string>[] | null query optional

The fields to include in the response

Default []Example []
Item schema
itemsenum<string>required
Allowed values ["id","name","name_exact","text","label","type","updated_at","agent_id"]
start_datetime string | null query optional

The start datetime for filtering results

Example 2023-01-01T00:00:00Z
end_datetime string | null query optional

The end datetime for filtering results

Example 2024-01-01T00:00:00Z

Responses

200Successful Response

application/json

response ListResponse_CustomMessageResponse_ required
5 fields
itemsCustomMessageResponse[]required

List of items returned from the query

Item schema
itemsCustomMessageResponserequired

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.

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

pageintegerrequired

The page number of the results (0-based)

page_sizeintegerrequired

The number of items returned per page

total_pagesinteger | nulloptional

The total number of pages of results given the indicated page size

total_countinteger | nulloptional

The total number of items returned from the query

Response example
{
  "items": [
    {
      "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"
    }
  ],
  "page": 0,
  "page_size": 0,
  "total_pages": "string",
  "total_count": "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"
    }
  ]
}