Message templates API: 5 Endpoints with Examples

List message templates in the current workspace

GET/v1/message-templatesmessage-templates.list

Needs the whatsapp feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Ordered by id. channel accepts only whatsapp. Any member.

Parameters

Name

In

Type

Required

Description

cursor

In: query

string

optional

limit

In: query

integer (int32)

optional

channel

In: query

string

optional

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

optional

The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.

X-Ken-Workspace-Id

In: header

integer (int64)

optional

The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

Response 200

data is a list of MessageTemplate. Each item has these fields. The response also carries pagination.

Field

Type

Description

id

integer (int64)

channel

string

name

string

body

string

variables

array of string

mediaIds

array of integer (int64)

voiceProvider

string

voiceId

string

authorSource

string

createdAt

string (date-time)

updatedAt

string (date-time)

Request

curl -X GET "https://api.ken.so/v1/message-templates?limit=1" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 812,
      "channel": "string",
      "name": "string",
      "body": "string",
      "variables": [
        "string"
      ],
      "mediaIds": [
        812
      ],
      "voiceProvider": "string",
      "voiceId": "string",
      "authorSource": "string",
      "createdAt": "2026-09-23T15:02:11Z",
      "updatedAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}

Create a message template

POST/v1/message-templatesmessage-templates.create

Needs the whatsapp feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

The author is the caller (user for a person in the dashboard, else agent). A body variable is a source and one of its fields, joined by a dot, in double braces: {{account.name}}, {{person.title}}. The fields are first_name, last_name, full_name and title on person; name on account; and first_name, full_name and company on sender. Up to 6 mediaIds, or a voice, never both; a voice limits the body to 900 characters.

Parameters

Name

In

Type

Required

Description

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

optional

The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.

X-Ken-Workspace-Id

In: header

integer (int64)

optional

The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

Request body

application/json, optional.

Field

Type

Required

Description

channel

string

optional

name

string

optional

body

string

optional

mediaIds

array of integer (int64)

optional

voiceProvider

string

optional

voiceId

string

optional

authorSource

string

optional

Response 201

data is a MessageTemplate.

Field

Type

Description

id

integer (int64)

channel

string

name

string

body

string

variables

array of string

mediaIds

array of integer (int64)

voiceProvider

string

voiceId

string

authorSource

string

createdAt

string (date-time)

updatedAt

string (date-time)

Request

curl -X POST "https://api.ken.so/v1/message-templates" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "string",
  "name": "string",
  "body": "string",
  "mediaIds": [
    812
  ],
  "voiceProvider": "string",
  "voiceId": "string",
  "authorSource": "string"
}'

Response 201

{
  "success": true,
  "data": {
    "id": 812,
    "channel": "string",
    "name": "string",
    "body": "string",
    "variables": [
      "string"
    ],
    "mediaIds": [
      812
    ],
    "voiceProvider": "string",
    "voiceId": "string",
    "authorSource": "string",
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Return one message template in the current workspace

GET/v1/message-templates/{messageTemplateId}message-templates.get

Needs the whatsapp feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

A missing, deleted or cross-workspace id is not_found. Any member.

Parameters

Name

In

Type

Required

Description

messageTemplateId

In: path

integer (int64)

required

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

optional

The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.

X-Ken-Workspace-Id

In: header

integer (int64)

optional

The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

Response 200

data is a MessageTemplate.

Field

Type

Description

id

integer (int64)

channel

string

name

string

body

string

variables

array of string

mediaIds

array of integer (int64)

voiceProvider

string

voiceId

string

authorSource

string

createdAt

string (date-time)

updatedAt

string (date-time)

Request

curl -X GET "https://api.ken.so/v1/message-templates/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 200

{
  "success": true,
  "data": {
    "id": 812,
    "channel": "string",
    "name": "string",
    "body": "string",
    "variables": [
      "string"
    ],
    "mediaIds": [
      812
    ],
    "voiceProvider": "string",
    "voiceId": "string",
    "authorSource": "string",
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Update a message template

PATCH/v1/message-templates/{messageTemplateId}message-templates.update

Needs the whatsapp feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Only the fields sent are written. mediaIds [] clears; voiceProvider and voiceId go together (both null clears the voice). A template holds images or a voice, never both. An agent cannot edit a template a person wrote.

Parameters

Name

In

Type

Required

Description

messageTemplateId

In: path

integer (int64)

required

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

optional

The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.

X-Ken-Workspace-Id

In: header

integer (int64)

optional

The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

Request body

application/json, optional: object.

Response 200

data is a MessageTemplate.

Field

Type

Description

id

integer (int64)

channel

string

name

string

body

string

variables

array of string

mediaIds

array of integer (int64)

voiceProvider

string

voiceId

string

authorSource

string

createdAt

string (date-time)

updatedAt

string (date-time)

Request

curl -X PATCH "https://api.ken.so/v1/message-templates/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "success": true,
  "data": {
    "id": 812,
    "channel": "string",
    "name": "string",
    "body": "string",
    "variables": [
      "string"
    ],
    "mediaIds": [
      812
    ],
    "voiceProvider": "string",
    "voiceId": "string",
    "authorSource": "string",
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Delete a message template

DELETE/v1/message-templates/{messageTemplateId}message-templates.delete

Needs the whatsapp feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Returns 204. An agent cannot delete a template a person wrote.

Parameters

Name

In

Type

Required

Description

messageTemplateId

In: path

integer (int64)

required

authorSource

In: query

string

optional

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

optional

The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.

X-Ken-Workspace-Id

In: header

integer (int64)

optional

The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

Response 204

Request

curl -X DELETE "https://api.ken.so/v1/message-templates/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 204

HTTP/1.1 204 No Content