Node.js Server SDK

The ChimeKit Node.js SDK provides a TypeScript-first way to interact with the ChimeKit API from your server-side applications. It handles authentication, request formatting, and response parsing with full type definitions.

All endpoints in this reference are rooted at /sdk/v1 and require an Authorization: Bearer {token} header. The SDK signs this token for you.

Install

npm install @chimekit/node

Audience

Audience endpoints let you identify members, update profiles, and manage channel suppressions.

POST/sdk/v1/audience/identify

Identify an audience member

Identify creates (or updates) an audience member by externalUserId. This is the canonical way to upsert profiles before sending messages or running workflows.

Required attributes

  • Name
    externalUserId
    Type
    string
    Description

    Your system's stable identifier for the end user.

Optional attributes

  • Name
    displayName
    Type
    string
    Description

    A human-friendly name for the member.

  • Name
    attributes
    Type
    object
    Description

    Arbitrary JSON attributes to attach to the member.

  • Name
    identities
    Type
    array
    Description

    Channel identities for the member. Currently supports email identities.

Request

POST
/sdk/v1/audience/identify
import { ChimeKit } from "@chimekit/node";

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

const member = await ck.identify("user_123", {
  displayName: "Ava Example",
  identities: [{ type: "email", value: "ava@example.com", verified: true }],
  attributes: { plan: "pro" },
});

Response

{
  "member": {
    "id": "user_123",
    "email": "ava@example.com",
    "displayName": "Ava Example",
    "identities": [{ "type": "email", "value": "ava@example.com", "verified": true }],
    "attributes": { "plan": "pro" },
    "created": "2025-01-01T00:00:00.000Z",
    "updated": "2025-01-01T00:00:00.000Z",
    "deleted": null,
    "lastSeen": null
  }
}
GET/sdk/v1/audience/members/:externalUserId

Get an audience member

Returns the member profile for the provided externalUserId, or null if no active member exists.

Path parameters

  • Name
    externalUserId
    Type
    string
    Description

    The member's external identifier.

Request

GET
/sdk/v1/audience/members/:externalUserId
const member = await ck.audience.findMember("user_123");

Response

{
  "member": {
    "id": "user_123",
    "email": "ava@example.com",
    "displayName": "Ava Example",
    "identities": [{ "type": "email", "value": "ava@example.com", "verified": true }],
    "attributes": { "plan": "pro" },
    "created": "2025-01-01T00:00:00.000Z",
    "updated": "2025-01-01T00:00:00.000Z",
    "deleted": null,
    "lastSeen": null
  }
}
PUT/sdk/v1/audience/members/:externalUserId

Update an audience member

Updates an existing member. If the member does not exist, the response is { "member": null }.

Path parameters

  • Name
    externalUserId
    Type
    string
    Description

    The member's external identifier.

Optional attributes

  • Name
    displayName
    Type
    string
    Description

    Updates the member's display name.

  • Name
    attributes
    Type
    object
    Description

    Replaces the member's attribute object.

  • Name
    identities
    Type
    array
    Description

    Replaces the member's identities array (email identities are supported).

Request

PUT
/sdk/v1/audience/members/:externalUserId
const updated = await ck.audience.updateMember("user_123", {
  displayName: "Ava Example (Updated)",
  attributes: { plan: "enterprise" },
});

Response

{
  "member": {
    "id": "user_123",
    "email": "ava@example.com",
    "displayName": "Ava Example (Updated)",
    "identities": [{ "type": "email", "value": "ava@example.com", "verified": true }],
    "attributes": { "plan": "enterprise" },
    "created": "2025-01-01T00:00:00.000Z",
    "updated": "2025-01-02T00:00:00.000Z",
    "deleted": null,
    "lastSeen": null
  }
}
DELETE/sdk/v1/audience/members/:externalUserId

Delete an audience member

Soft-deletes an audience member by externalUserId. If the member does not exist, id will be null.

Path parameters

  • Name
    externalUserId
    Type
    string
    Description

    The member's external identifier.

Request

DELETE
/sdk/v1/audience/members/:externalUserId
const deletedId = await ck.audience.deleteMember("user_123");

Response

{ "id": "user_123" }
GET/sdk/v1/audience/members/:externalUserId/suppressions

List member suppressions

Lists suppressions for a member. Suppressions prevent delivery for a specific identity, optionally scoped to a category.

Path parameters

  • Name
    externalUserId
    Type
    string
    Description

    The member's external identifier.

Request

GET
/sdk/v1/audience/members/:externalUserId/suppressions
const suppressions = await ck.audience.listSuppressions("user_123");

Response

{
  "suppressions": [
    {
      "id": "sup_123",
      "reason": "opt-out",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z",
      "identity": {
        "id": "aid_123",
        "type": "email",
        "value": "ava@example.com",
        "verified": true,
        "metadata": null
      },
      "category": null
    }
  ]
}
POST/sdk/v1/audience/members/:externalUserId/suppressions

Add a member suppression

Creates a suppression for a specific identity. If categoryId is omitted, the suppression is global for that identity.

Path parameters

  • Name
    externalUserId
    Type
    string
    Description

    The member's external identifier.

Required attributes

  • Name
    identity
    Type
    object
    Description

    The identity to suppress. Must include type and value (email identities are supported).

Optional attributes

  • Name
    categoryId
    Type
    string
    Description

    If set, suppresses only for a specific category. If omitted, suppression is global.

Request

POST
/sdk/v1/audience/members/:externalUserId/suppressions
const suppression = await ck.audience.suppress("user_123", {
  identity: { type: "email", value: "ava@example.com" },
});

Response

{
  "suppression": {
    "id": "sup_123",
    "reason": "opt-out",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z",
    "identity": {
      "id": "aid_123",
      "type": "email",
      "value": "ava@example.com",
      "verified": true,
      "metadata": null
    },
    "category": null
  }
}
DELETE/sdk/v1/audience/members/:externalUserId/suppressions/:suppressionId

Remove a member suppression

Removes a suppression by id. The response body is empty on success.

Path parameters

  • Name
    externalUserId
    Type
    string
    Description

    The member's external identifier.

  • Name
    suppressionId
    Type
    string
    Description

    The suppression identifier.

Request

DELETE
/sdk/v1/audience/members/:externalUserId/suppressions/:suppressionId
await ck.audience.removeSuppression("user_123", "sup_123");

Response

null

Messages

Message endpoints let you send messages, fetch message detail, and list recent activity for a member.

POST/sdk/v1/messages/send

Send a message

Sends a message to an audience member.

Content can be provided in one of two ways:

  • A top-level content.templateId (send a template as-is, with optional variables), or
  • One or more channels (content.in_app and/or content.email).

Required attributes

  • Name
    externalUserId
    Type
    string
    Description

    The audience member's external identifier.

  • Name
    content
    Type
    object
    Description

    Message content definition (template or channels).

content (template)

  • Name
    content.templateId
    Type
    string
    Description

    Template id to send.

  • Name
    content.variables
    Type
    object
    Description

    Variables to resolve in the template.

content (channels)

  • Name
    content.in_app
    Type
    object
    Description

    In-app content definition (manual or template reference).

  • Name
    content.email
    Type
    object
    Description

    Email content definition (manual).

  • Name
    content.variables
    Type
    object
    Description

    Base variables merged into channel variables.

Request

POST
/sdk/v1/messages/send
const result = await ck.messages.sendMessage("user_123", {
  content: {
    in_app: {
      title: "Welcome!",
      snippet: "A quick hello from ChimeKit",
      body: "Sent from the SDK endpoints.",
    },
  },
});

Response

{
  "message": {
    "id": "msg_123",
    "memberId": "mem_123",
    "categoryId": "cat_123",
    "source": "sdk",
    "templateId": null,
    "templateVersionId": null,
    "payload": {},
    "dispatchStatus": "dispatched",
    "scheduledFor": null,
    "createdAt": "2025-01-01T00:00:00.000Z"
  },
  "delivery": null,
  "notification": {
    "id": "not_123",
    "title": "Welcome!",
    "snippet": "A quick hello from ChimeKit",
    "body": "Sent from the SDK endpoints.",
    "actions": null,
    "readAt": null,
    "archivedAt": null
  },
  "audienceMember": {
    "id": "mem_123"
  }
}
GET/sdk/v1/messages/:messageId

Get a message

Fetches a message by id, including delivery + notification details when available.

Path parameters

  • Name
    messageId
    Type
    string
    Description

    The message identifier.

Request

GET
/sdk/v1/messages/:messageId
const detail = await ck.messages.getMessage("msg_123");

Response

{
  "message": {
    "message": {
      "id": "msg_123",
      "memberId": "mem_123",
      "categoryId": "cat_123",
      "source": "sdk",
      "templateId": null,
      "templateVersionId": null,
      "payload": {},
      "dispatchStatus": "dispatched",
      "scheduledFor": null,
      "createdAt": "2025-01-01T00:00:00.000Z"
    },
    "delivery": null,
    "notification": {
      "id": "not_123",
      "title": "Welcome!",
      "snippet": "A quick hello from ChimeKit",
      "body": "Sent from the SDK endpoints.",
      "actions": null,
      "readAt": null,
      "archivedAt": null
    },
    "recipient": {
      "id": "mem_123",
      "externalUserId": "user_123",
      "displayName": "Ava Example",
      "email": "ava@example.com"
    }
  }
}
GET/sdk/v1/messages/members/:externalUserId/messages

List messages for a member

Lists recent message activity for a member.

Path parameters

  • Name
    externalUserId
    Type
    string
    Description

    The audience member's external identifier.

Optional query parameters

  • Name
    limit
    Type
    integer
    Description

    Number of items to return (min 1, max 100). Defaults to 20.

  • Name
    offset
    Type
    integer
    Description

    Number of items to skip. Defaults to 0.

Request

GET
/sdk/v1/messages/members/:externalUserId/messages
const { messages, pagination } = await ck.messages.listMessagesForUser(
  "user_123",
  { limit: 20, offset: 0 }
);

Response

{
  "messages": [
    {
      "message": {
        "id": "msg_123",
        "memberId": "mem_123",
        "categoryId": "cat_123",
        "source": "sdk",
        "dispatchStatus": "dispatched",
        "scheduledFor": null,
        "createdAt": "2025-01-01T00:00:00.000Z",
        "snippet": "A quick hello from ChimeKit"
      },
      "delivery": null,
      "recipient": {
        "id": "mem_123",
        "externalUserId": "user_123",
        "displayName": "Ava Example",
        "email": "ava@example.com"
      },
      "category": {
        "id": "cat_123",
        "name": "Product"
      }
    }
  ],
  "pagination": { "totalCount": 1, "limit": 20, "offset": 0 }
}

Workflows

Workflow endpoints let you run a workflow for a member and query run status.

POST/sdk/v1/workflows/:key/run

Run a workflow

Queues a workflow run for an existing audience member.

Path parameters

  • Name
    key
    Type
    string
    Description

    The workflow key to run.

Required attributes

  • Name
    externalUserId
    Type
    string
    Description

    The audience member's external identifier.

Optional attributes

  • Name
    context
    Type
    object
    Description

    Arbitrary JSON context merged into the workflow run context.

Request

POST
/sdk/v1/workflows/:key/run
const run = await ck.workflow.run("welcome-sequence", {
  externalUserId: "user_123",
  context: { utmCampaign: "winter-launch" },
});

Response

{ "runId": "wr_123", "status": "queued" }
GET/sdk/v1/workflows/runs/:runId

Get a workflow run

Returns workflow run metadata for a previously queued run.

Path parameters

  • Name
    runId
    Type
    string
    Description

    The workflow run identifier.

Request

GET
/sdk/v1/workflows/runs/:runId
const run = await ck.workflow.getRun("wr_123");

Response

{
  "run": {
    "id": "wr_123",
    "workflowVersionId": "wv_123",
    "workflowId": "w_123",
    "workflowKey": "welcome-sequence",
    "status": "queued",
    "memberId": "mem_123",
    "memberExternalUserId": "user_123",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "startedAt": null,
    "finishedAt": null,
    "context": { "utmCampaign": "winter-launch", "apiKeyId": "key_123" }
  }
}

Was this page helpful?