Messages

Messages are the core unit of communication in ChimeKit. A message targets one audience member, is delivered through one or more channels (like in-app and email), and can be personalized with templates and variables.

What a message is

A message is a record of “we attempted to communicate something to someone”.

Depending on the channels you include, a message may also produce:

• An in-app notification (what you render in the inbox UI)
• An email delivery record (what gets queued/sent via an email provider)

Messages can be created from:

• Manual channel content (ad-hoc title/body/actions), or
• Templates (recommended for repeatability and consistency)

How it fits into the system

• Audience members are the recipient (identified by externalUserId).
• Messaging channels determine how the message is delivered.
• Templates provide reusable message definitions and variable interpolation.
• Categories determine user preference behavior (what someone can opt out of).
• Workflows and Broadcasts both ultimately create messages under the hood.

Getting started (send your first message)

There are three common ways to create messages:

1. Dashboard: best for quick validation and non-engineering teams.
2. Server SDK: best for product-driven messages triggered by backend events.
3. HTTP (SDK endpoints): best when you’re building your own SDK or want direct control over requests.

If you’ve already identified a member, you can send an in-app message with the Server SDK:

import { ChimeKit } from '@chimekit/node'

const ck = new ChimeKit({ secretKey: process.env.CHIMEKIT_SECRET_KEY! })

await ck.messages.sendMessage('user_123', {
  content: {
    in_app: {
      title: 'Welcome to ChimeKit',
      body: 'This is your first in-app message.',
    },
  },
})

Categories (and why they matter)

Categories are how you group messages into preference buckets. Users typically don’t want to opt out of “all notifications” — they want to control specific kinds of communication:

• Product updates
• Billing
• Security
• Marketing

In ChimeKit, categories let you:

• Attach meaning to messages (“what kind of message is this?”)
• Power preference UIs (like the Preferences widget in @chimekit/react)
• Apply suppressions/opt-outs by category and channel

Creating categories

The easiest way to create categories is in the Dashboard:

1. Create a category (name + key).
2. Decide which channels it supports.
3. Add a description so users understand what they’re opting into.

Then you can associate messages with that category by:

• Assigning the category to a template (recommended), or
• Providing categoryId when sending a message via /sdk/v1/messages/send (direct HTTP). The Server SDKs don’t currently expose categoryId on sendMessage.

Where to go next

• Define reusable content: Templates.
• Choose delivery surfaces: Messaging Channels.
• Build an in-app inbox quickly: Client SDKs.
• Trigger messages on a schedule: Workflows.