Documentation | Users › List Messages

Users

users

Methods

Delete User -> string

delete/v1/users/{user_id}

Delete user

Get User ->

User

get/v1/users/{user_id}

Get user

Get Channel Data ->

ChannelData

get/v1/users/{user_id}/channel_data/{channel_id}

Get channel data

Get Preference Set ->

PreferenceSet

get/v1/users/{user_id}/preferences/{preference_set_id}

Get preference set

List Users -> EntriesCursor<

User

get/v1/users

List users

Parameters

after: string

Optional

The cursor to fetch entries after

before: string

Optional

The cursor to fetch entries before

page_size: number

Optional

The page size to fetch

Response fields

entries: Array<

User

Optional

The list of users

page_info: { __typename, page_size, after, 1 more... }

Optional

The information about a paginated result

Request example

curl https://api.knock.app/v1/users \
    -H "Authorization: Bearer $KNOCK_API_KEY"

200Example

{
  "entries": [
    {
      "id": "jane",
      "__typename": "User",
      "updated_at": "2024-05-22T12:00:00Z",
      "avatar": "avatar",
      "created_at": null,
      "email": "[email protected]",
      "name": "Jane Doe",
      "phone_number": "phone_number",
      "timezone": "timezone"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "page_size": 25,
    "after": null,
    "before": null
  }
}

List Messages -> EntriesCursor<

Message

get/v1/users/{user_id}/messages

List messages

Parameters

user_id: string

after: string

Optional

The cursor to fetch entries after

before: string

Optional

The cursor to fetch entries before

channel_id: string

Optional

The channel ID

engagement_status: Array<

Optional

The engagement status of the message

"seen"

"read"

"interacted"

"link_clicked"

"archived"

message_ids: Array<string>

Optional

The message IDs to filter messages by

page_size: number

Optional

The page size to fetch

source: string

Optional

The source of the message (workflow key)

status: Array<

Optional

The status of the message

"queued"

"sent"

"delivered"

"delivery_attempted"

"undelivered"

"not_sent"

"bounced"

tenant: string

Optional

The tenant ID

trigger_data: string

Optional

The trigger data to filter messages by. Must be a valid JSON object.

workflow_categories: Array<string>

Optional

The workflow categories to filter messages by

workflow_recipient_run_id: string

Optional

(format: uuid)

The workflow recipient run ID to filter messages by

workflow_run_id: string

Optional

(format: uuid)

The workflow run ID to filter messages by

Response fields

entries: Array<

Message

The list of messages

page_info: { __typename, page_size, after, 1 more... }

The information about a paginated result

Request example

curl https://api.knock.app/v1/users/$USER_ID/messages \
    -H "Authorization: Bearer $KNOCK_API_KEY"

200Example

{
  "entries": [
    {
      "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7",
      "__typename": "Message",
      "actors": [
        "user_123"
      ],
      "archived_at": null,
      "channel_id": "123e4567-e89b-12d3-a456-426614174000",
      "clicked_at": null,
      "data": {
        "foo": "bar"
      },
      "engagement_statuses": [
        "seen",
        "read"
      ],
      "inserted_at": "2021-01-01T00:00:00Z",
      "interacted_at": null,
      "link_clicked_at": null,
      "metadata": {
        "external_id": "bar"
      },
      "read_at": null,
      "recipient": "user_123",
      "scheduled_at": null,
      "seen_at": null,
      "source": {
        "__typename": "NotificationSource",
        "categories": [
          "collaboration"
        ],
        "key": "comment-created",
        "version_id": "123e4567-e89b-12d3-a456-426614174000"
      },
      "status": "queued",
      "tenant": "tenant_123",
      "updated_at": "2021-01-01T00:00:00Z",
      "workflow": "comment-created"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "page_size": 25,
    "after": null,
    "before": null
  }
}

List Preference Sets -> Array<

PreferenceSet

get/v1/users/{user_id}/preferences

List preference sets

List Schedules -> EntriesCursor<

Schedule

get/v1/users/{user_id}/schedules

List schedules

List Subscriptions -> EntriesCursor<

Subscription

get/v1/users/{user_id}/subscriptions

List subscriptions

Merge Users ->

User

post/v1/users/{user_id}/merge

Merge two users together, where the user specified with the from_user_id param will be merged into the user specified by user_id.

Set Channel Data ->

ChannelData

put/v1/users/{user_id}/channel_data/{channel_id}

Set channel data

Update Preference Set ->

PreferenceSet

put/v1/users/{user_id}/preferences/{preference_set_id}

Updates a complete preference set for a user. This is a destructive operation that will replace the existing preference set for the user.

Unset Channel Data -> string

delete/v1/users/{user_id}/channel_data/{channel_id}

Unset channel data

Identify User ->

User

put/v1/users/{user_id}

Identify user

Domain types

IdentifyUserRequest = { channel_data, created_at, preferences }

A set of parameters to identify a user with. Does not include the user ID, as that's specified elsewhere in the request. You can supply any additional properties you'd like to upsert against the user.

InlineIdentifyUserRequest = { id, channel_data, created_at, 1 more... }

A set of parameters to inline-identify a user with. Inline identifying the user will ensure that the user is available before the request is executed in Knock. It will perform an upsert against the user you're supplying, replacing any properties specified.

User = { id, __typename, updated_at, 6 more... }

A user object

Users