# About the Templates API

The Templates API gives you access to the catalog of activity templates and categories used by the
[Activities API](fallback::https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/activity-log/activity-v1).
Templates are predefined formats that Wix uses to record activities automatically: they define the
message wording, with placeholders for relevant details, an optional icon, and optional links.
Every activity created from a template produces a consistent, recognizable message.

With the Templates API, you can:

- **Browse available templates** to understand what kinds of activities Wix records automatically
  for a contact. Retrieve template details such as `activityDescription` and `icon` to enrich the
  display of activities in a contact's log.
- **Browse available categories** to understand how templates are organized and to get category IDs
  for filtering a contact's activity history by type in
  [List Activities](fallback::https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/activity-log/activity-v1/list-activities).

Templates and categories are provided by Wix and can't be created, edited, or deleted through
the API.

## Template anatomy

Each template defines how an activity's message is composed:

- **Name**: A constant display name for the template, not translated.
- **Activity description**: A translated description of what the template records, without
  parameter placeholders (for example, "Purchased tickets to an event"). Not present for all
  templates.
- **Params**: Named placeholders that define what values are used when composing the activity's
  message. Each param key corresponds to a key in `activity.params` for activities created from
  this template. If an `activity_key` param is present, it is for internal use.
- **Links**: Optional structured URLs associated with the template. A link's key can appear as a
  placeholder in the template's message, and its URL can itself contain param placeholders — for
  example, `https://example.com/orders/{{orderId}}`. Links are embedded as plain text in the
  rendered `activity.message`.
- **Icon**: An image representing the template. Use `icon.url` to display the icon.

## Use cases

- [Enrich a contact's activity feed with template details](fallback::https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/activity-log/template-v1/templates-sample-flows#enrich-a-contacts-activity-feed-with-template-details)

## Terminology

- **Template**: A predefined format that Wix uses to record activities automatically. Defines the
  message wording, with placeholders for relevant details, optional links, and an icon.
- **Category**: A grouping of related templates. Use a category ID to filter which templates are
  shown or to filter a contact's activity history by type.
- **Parameter**: A named placeholder in a template's wording. Values for each parameter are stored
  in `activity.params` for activities created from this template.
- **Activity description**: A translated description of what the template records, without
  parameter placeholders.

@sdk_package_setup

# Templates API: Sample Flows

This article presents a possible use case and corresponding sample flow that you can support. It provides a useful starting point as you plan your implementation.

## Enrich a contact's activity feed with template details

When displaying a contact's activity timeline you may want to show the template's icon and
description alongside each activity. This flow shows how to look up template details for a list
of activities.

To enrich a contact's activity feed with template details:

1. Call [List Activities](fallback::https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/activity-log/activity-v1/list-activities) with the contact's `contactId` to retrieve the
   contact's activities.
2. Call [List Templates](fallback::https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/activity-log/template-v1/list-templates), iterating through all pages until no `next` cursor is
   returned in `metadata.cursors`. Build a lookup map of `id → template` from the results.
3. For each activity with a `templateId`, look up the matching template. Use `template.icon.url`
   to display an icon next to the activity and `template.activityDescription` for a short
   human-readable summary of what the activity represents.

Coding Examples

Overview

Sled Tests

Go Headless

Extend Websites with SDK

Build Apps

Client (Deprecated)

API Preview

Wix CLI

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

GraphQL (Alpha)

value

BoolValue

Int32Value

values

ListValue

NullValue

StringValue

fields

Struct

nanos

seconds

Timestamp

Value

boolValue

listValue

nullValue

numberValue

stringValue

structValue

kind

Default value for this parameter, used when no value is supplied for the parameter.

defaultValue

displayName

Parameter key, in camelCase format. Used to identify the parameter and as a placeholder in the template's message.

Whether the parameter value contains personally identifiable information (PII). When `true`, the parameter value is anonymized if the contact's data is erased through a GDPR request.

Default: `false`

Whether the parameter is required. When `true`, activities created from this template always include a value for this parameter in `activity.params`.

Default: `false`

required

type

ActivityParam

A JSON object in the format `{ "currency": "<code>", "amount": <decimal> }`.

ParamType

A label that groups related templates together. Categories let you organize activities by type
and filter a contact's history to a specific area of interest, such as Email Marketing or Invoices.

Category name. Translated based on the `language` parameter.

name

Icon

description

Link identifier, in camelCase format. For example, `invoiceLink`. Can appear as a placeholder in the template's message, embedding this link in the rendered activity message.

Link URL. Can contain Mustache-style placeholders using parameter keys. For example, `https://manage.wix.com/dashboard/{{siteId}}/store/orders/order/{{orderId}}`.

Link

2-letter language code in ISO 639-1 alpha-2 format. Determines the language of translated fields (`name`).

Default: Language from the request context, or `en`.

language

ListCategoriesRequest

ListCategoriesResponse

ID of a category to filter templates by. Can't be used together with `cursorPaging`.

categoryId

Cursor token for retrieving subsequent pages. Pass `metadata.cursors.next` from the previous response. When providing a cursor, don't pass `categoryId`.

2-letter language code in ISO 639-1 alpha-2 format. Determines the language of translated fields (`activityDescription`).

Default: Language from the request context, or `en`.

ListTemplatesRequest

templates

ListTemplatesResponse

A predefined format for logging activities. Instead of a free-text message, a template defines
the wording, with placeholders for the relevant details, optional links, and an icon. Activities
logged from the same template produce consistent messages and can be filtered by category.

Translated description of what the template records, without parameter placeholders. Returned in the language specified by the `language` parameter.

Not present for all templates.

activityDescription

Parameters that define what values are used to compose the activity's message. Each parameter key corresponds to a key in `activity.params` for activities created from this template.

activityParams

ID of the category this template belongs to.

Template icon. Use `icon.url` to display the icon image.

Optional structured links associated with the template. A link's `key` can appear as a Mustache-style placeholder in the template's message, embedding the link in the rendered activity message.

links

Date and time the template was last updated.

updatedDate

Template

Pointer to the next or previous page in the list of results.

You can get the relevant cursor token
from the `pagingMetadata` object in the previous call's response.
Not relevant for the first request.

cursor

limit

CursorPaging

Cursor for the next page of results. Pass this value in `cursorPaging.cursor` to retrieve the next page.

Cursors

Number of items returned in the response.

count

Cursors for navigating between result pages. Returned when cursor paging is used.

offset

Whether the server failed to calculate `total`. If `true`, `total` is omitted.

tooManyToCount

Total number of items that match the request. Returned when offset paging is used and `tooManyToCount` is `false`.

total

PagingMetadataV2

list

Retrieves available activity templates.

Use this method to browse the templates that Wix uses to record activities automatically. Retrieve template details such as `activityDescription` and `icon` to enrich the display of activities in a contact's log. Use `categoryId` to filter templates by category.

To learn about cursor paging, see [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging).

Retrieve activity templates in the Bookings category, returned with English descriptions.

List templates by category

ListTemplates

cursorPaging

Read Contacts

Retrieves all activity categories.

Use a category ID to filter a contact's activities by type in [List Activities](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/activity-log/activity-v1/list-activities), or to filter templates by category in [List Templates](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/activity-log/template-v1/list-templates).

Retrieve all activity categories in English.

List all categories

ListCategories

Bookings canceled booking

addressLine1

addressLine2

city

country

formatted

postalCode

subdivision

Address

GoogleProtoDuration

latitude

longitude

Location

number

StreetAddress

_updatedDate

ListCategoriesOptions

ListCategoriesRequestSignature

ListTemplatesOptions

ListTemplatesRequestSignature

import { wixCrmContactsActivityLogV1Template } from "@wix/dev";

async function listTemplates() {
  const response = await wixCrmContactsActivityLogV1Template.listTemplates({
    categoryId: "939d4361-6f56-4be7-ac58-415667ca09a7",
    language: "en",
  });
}

/* Promise resolves to:
 * {
 *   "templates": [
 *     {
 *       "_id": "43dd6712-fbe0-4e99-a3b4-38f9c10ae05f",
 *       "name": "Bookings canceled booking",
 *       "activityDescription": "Canceled a session",
 *       "icon": {
 *         "name": "WixBooking",
 *         "url": "https://wixmp-8be454c954980f083caba37c.wixmp.com/activity-log/WixBooking.png"
 *       },
 *       "categoryId": "939d4361-6f56-4be7-ac58-415667ca09a7",
 *       "_updatedDate": "2026-01-20T09:48:17.198Z",
 *       "activityParams": [
 *         {
 *           "key": "activity_key",
 *           "displayName": "activity_key",
 *           "required": false,
 *           "pii": false,
 *           "type": "STRING",
 *           "defaultValue": "last.activity.text.canceled.booking"
 *         },
 *         {
 *           "key": "ServiceTitle",
 *           "displayName": "ServiceTitle",
 *           "required": false,
 *           "pii": false,
 *           "type": "STRING"
 *         },
 *         {
 *           "key": "StartDate",
 *           "displayName": "StartDate",
 *           "required": false,
 *           "pii": false,
 *           "type": "DATE"
 *         },
 *         {
 *           "key": "ContactId",
 *           "displayName": "ContactId",
 *           "required": false,
 *           "pii": false,
 *           "type": "STRING"
 *         },
 *         {
 *           "key": "metaSiteId",
 *           "displayName": "metaSiteId",
 *           "required": true,
 *           "pii": false,
 *           "type": "STRING"
 *         }
 *       ],
 *       "links": [
 *         {
 *           "key": "BookingsTab_link",
 *           "url": "https://manage.wix.com/dashboard/{{metaSiteId}}/app/74bff718-5977-47f2-9e5f-a9fd0047fd1f/view/{{ContactId}}?tab_name=bookings"
 *         }
 *       ]
 *     }
 *   ],
 *   "metadata": {
 *     "count": 1,
 *     "cursors": {}
 *   }
 * }
 */


Retrieve activity templates filtered by category in English.

List templates

import { createClient } from '@wix/sdk';
import { contactsActivityLogTemplates } from '@wix/contacts-activity-log-templates';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { contactsActivityLogTemplates },
  // Include the auth strategy and host as relevant
});


async function listTemplates(options) {
  const response = await myWixClient.contactsActivityLogTemplates.listTemplates(options);
};

Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

listTemplates (self-hosted)

import { wixCrmContactsActivityLogV1Template } from "@wix/dev";

async function listCategories() {
  const response = await wixCrmContactsActivityLogV1Template.listCategories({
    language: "en",
  });
}

/* Promise resolves to:
 * {
 *   "categories": [
 *     {
 *       "_id": "165b2721-d2c5-4891-a6ae-9cb0666e18bc",
 *       "name": "Email Marketing"
 *     },
 *     {
 *       "_id": "419a6043-f73a-41c0-a72f-ee5e2bed811a",
 *       "name": "Events"
 *     },
 *     {
 *       "_id": "939d4361-6f56-4be7-ac58-415667ca09a7",
 *       "name": "Bookings"
 *     }
 *   ]
 * }
 */


List categories

import { createClient } from '@wix/sdk';
import { contactsActivityLogTemplates } from '@wix/contacts-activity-log-templates';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { contactsActivityLogTemplates },
  // Include the auth strategy and host as relevant
});


async function listCategories(options) {
  const response = await myWixClient.contactsActivityLogTemplates.listCategories(options);
};