Class: Knockapi::Resources::Users

Inherits:
Object
  • Object
show all
Defined in:
lib/knockapi/resources/users.rb,
lib/knockapi/resources/users/bulk.rb,
lib/knockapi/resources/users/feeds.rb,
lib/knockapi/resources/users/guides.rb,
lib/knockapi/resources/users/preference_center.rb,
sig/knockapi/resources/users.rbs,
sig/knockapi/resources/users/bulk.rbs,
sig/knockapi/resources/users/feeds.rbs,
sig/knockapi/resources/users/guides.rbs,
sig/knockapi/resources/users/preference_center.rbs

Overview

A user is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.

Defined Under Namespace

Classes: Bulk, Feeds, Guides, PreferenceCenter

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Users

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Users.

Parameters:



482
483
484
485
486
487
488
 
# File 'lib/knockapi/resources/users.rb', line 482

def initialize(client:)
  @client = client
  @feeds = Knockapi::Resources::Users::Feeds.new(client: client)
  @guides = Knockapi::Resources::Users::Guides.new(client: client)
  @bulk = Knockapi::Resources::Users::Bulk.new(client: client)
  @preference_center = Knockapi::Resources::Users::PreferenceCenter.new(client: client)
end

Instance Attribute Details

#bulk ⇒ Knockapi::Resources::Users::Bulk (readonly)

A bulk operation is a set of changes applied across zero or more records triggered via a call to the Knock API and performed asynchronously.

Returns:



21
22
23
 
# File 'lib/knockapi/resources/users.rb', line 21

def bulk
  @bulk
end

#feeds ⇒ Knockapi::Resources::Users::Feeds (readonly)

A user is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.

Returns:



11
12
13
 
# File 'lib/knockapi/resources/users.rb', line 11

def feeds
  @feeds
end

#guides ⇒ Knockapi::Resources::Users::Guides (readonly)

A user is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.

Returns:



16
17
18
 
# File 'lib/knockapi/resources/users.rb', line 16

def guides
  @guides
end

#preference_center ⇒ Knockapi::Resources::Users::PreferenceCenter (readonly)

The preference center is a hosted page where users can manage their notification preferences.

Returns:



26
27
28
 
# File 'lib/knockapi/resources/users.rb', line 26

def preference_center
  @preference_center
end

Instance Method Details

#delete(user_id, request_options: {}) ⇒ nil

Permanently delete a user and all associated data.

Parameters:

Returns:

  • (nil)

See Also:



115
116
117
118
119
120
121
122
 
# File 'lib/knockapi/resources/users.rb', line 115

def delete(user_id, params = {})
  @client.request(
    method: :delete,
    path: ["v1/users/%1$s", user_id],
    model: NilClass,
    options: params[:request_options]
  )
end

#get(user_id, request_options: {}) ⇒ Knockapi::Models::User

Retrieve a specific user by their ID.

Parameters:

Returns:

See Also:



135
136
137
138
139
140
141
142
 
# File 'lib/knockapi/resources/users.rb', line 135

def get(user_id, params = {})
  @client.request(
    method: :get,
    path: ["v1/users/%1$s", user_id],
    model: Knockapi::User,
    options: params[:request_options]
  )
end

#get_channel_data(user_id, channel_id, request_options: {}) ⇒ Knockapi::Models::Recipients::RecipientsChannelData

Retrieves the channel data for a specific user and channel ID.

Parameters:

  • user_id (String) —

    The unique identifier of the user.

  • channel_id (String) —

    The unique identifier for the channel.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



157
158
159
160
161
162
163
164
 
# File 'lib/knockapi/resources/users.rb', line 157

def get_channel_data(user_id, channel_id, params = {})
  @client.request(
    method: :get,
    path: ["v1/users/%1$s/channel_data/%2$s", user_id, channel_id],
    model: Knockapi::Recipients::RecipientsChannelData,
    options: params[:request_options]
  )
end

#get_preferences(user_id, id, tenant: nil, request_options: {}) ⇒ Knockapi::Models::Recipients::PreferenceSet

Retrieves a specific preference set for a user identified by the preference set ID.

Parameters:

  • user_id (String) —

    The unique identifier of the user.

  • id (String) —

    Unique identifier for the preference set.

  • tenant (String) —

    The unique identifier for the tenant.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/knockapi/resources/users.rb', line 182

def get_preferences(user_id, id, params = {})
  parsed, options = Knockapi::UserGetPreferencesParams.dump_request(params)
  query = Knockapi::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["v1/users/%1$s/preferences/%2$s", user_id, id],
    query: query,
    model: Knockapi::Recipients::PreferenceSet,
    options: options
  )
end

#list(after: nil, before: nil, include: nil, page_size: nil, request_options: {}) ⇒ Knockapi::Internal::EntriesCursor<Knockapi::Models::User>

Retrieve a paginated list of users in the environment. Defaults to 50 users per page.

Parameters:

  • after (String) —

    The cursor to fetch entries after.

  • before (String) —

    The cursor to fetch entries before.

  • include (Array<Symbol, Knockapi::Models::UserListParams::Include>) —

    Associated resources to include in the response.

  • page_size (Integer) —

    The number of items per page (defaults to 50).

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/knockapi/resources/users.rb', line 91

def list(params = {})
  parsed, options = Knockapi::UserListParams.dump_request(params)
  query = Knockapi::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "v1/users",
    query: query,
    page: Knockapi::Internal::EntriesCursor,
    model: Knockapi::User,
    options: options
  )
end

#list_messages(user_id, after: nil, before: nil, channel_id: nil, engagement_status: nil, inserted_at: nil, message_ids: nil, page_size: nil, source: nil, status: nil, tenant: nil, trigger_data: nil, workflow_categories: nil, workflow_recipient_run_id: nil, workflow_run_id: nil, request_options: {}) ⇒ Knockapi::Internal::ItemsCursor<Knockapi::Models::Message>

Some parameter documentations has been truncated, see Models::UserListMessagesParams for more details.

Returns a paginated list of messages for a specific user. Messages are sorted with the most recent ones appearing first. Messages outside the account's retention window will not be included in the results.

Parameters:

  • user_id (String) —

    The user ID to list messages for.

  • after (String) —

    The cursor to fetch entries after.

  • before (String) —

    The cursor to fetch entries before.

  • channel_id (String) —

    Limits the results to items with the corresponding channel ID.

  • engagement_status (Array<Symbol, Knockapi::Models::UserListMessagesParams::EngagementStatus>) —

    Limits the results to messages with the given engagement status.

  • inserted_at (Knockapi::Models::UserListMessagesParams::InsertedAt)
  • message_ids (Array<String>) —

    Limits the results to only the message IDs given (max 50). Note: when using this

  • page_size (Integer) —

    The number of items per page (defaults to 50).

  • source (String) —

    Limits the results to messages triggered by the given workflow key.

  • status (Array<Symbol, Knockapi::Models::UserListMessagesParams::Status>) —

    Limits the results to messages with the given delivery status.

  • tenant (String) —

    Limits the results to items with the corresponding tenant.

  • trigger_data (String) —

    Limits the results to only messages that were generated with the given data. See

  • workflow_categories (Array<String>) —

    Limits the results to messages related to any of the provided categories.

  • workflow_recipient_run_id (String) —

    Limits the results to messages for a specific recipient's workflow run.

  • workflow_run_id (String) —

    Limits the results to messages associated with the top-level workflow run ID ret

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/knockapi/resources/users.rb', line 238

def list_messages(user_id, params = {})
  parsed, options = Knockapi::UserListMessagesParams.dump_request(params)
  query = Knockapi::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["v1/users/%1$s/messages", user_id],
    query: query,
    page: Knockapi::Internal::ItemsCursor,
    model: Knockapi::Message,
    options: options
  )
end

#list_preferences(user_id, request_options: {}) ⇒ Array<Knockapi::Models::Recipients::PreferenceSet>

Retrieves a list of all preference sets for a specific user.

Parameters:

Returns:

See Also:



262
263
264
265
266
267
268
269
 
# File 'lib/knockapi/resources/users.rb', line 262

def list_preferences(user_id, params = {})
  @client.request(
    method: :get,
    path: ["v1/users/%1$s/preferences", user_id],
    model: Knockapi::Internal::Type::ArrayOf[Knockapi::Recipients::PreferenceSet],
    options: params[:request_options]
  )
end

#list_schedules(user_id, after: nil, before: nil, page_size: nil, tenant: nil, workflow: nil, request_options: {}) ⇒ Knockapi::Internal::EntriesCursor<Knockapi::Models::Schedule>

Returns a paginated list of schedules for a specific user, in descending order.

Parameters:

  • user_id (String) —

    The user ID to list schedules for.

  • after (String) —

    The cursor to fetch entries after.

  • before (String) —

    The cursor to fetch entries before.

  • page_size (Integer) —

    The number of items per page (defaults to 50).

  • tenant (String) —

    The tenant ID to filter schedules for.

  • workflow (String) —

    The workflow key to filter schedules for.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/knockapi/resources/users.rb', line 292

def list_schedules(user_id, params = {})
  parsed, options = Knockapi::UserListSchedulesParams.dump_request(params)
  query = Knockapi::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["v1/users/%1$s/schedules", user_id],
    query: query,
    page: Knockapi::Internal::EntriesCursor,
    model: Knockapi::Schedule,
    options: options
  )
end

#list_subscriptions(user_id, after: nil, before: nil, include: nil, objects: nil, page_size: nil, request_options: {}) ⇒ Knockapi::Internal::EntriesCursor<Knockapi::Models::Recipients::Subscription>

Retrieves a paginated list of subscriptions for a specific user, in descending order.

Parameters:

Returns:

See Also:



327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/knockapi/resources/users.rb', line 327

def list_subscriptions(user_id, params = {})
  parsed, options = Knockapi::UserListSubscriptionsParams.dump_request(params)
  query = Knockapi::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["v1/users/%1$s/subscriptions", user_id],
    query: query,
    page: Knockapi::Internal::EntriesCursor,
    model: Knockapi::Recipients::Subscription,
    options: options
  )
end

#merge(user_id, from_user_id:, request_options: {}) ⇒ Knockapi::Models::User

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

Parameters:

  • user_id (String) —

    The id of the user to merge into.

  • from_user_id (String) —

    The user ID to merge from.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



354
355
356
357
358
359
360
361
362
363
 
# File 'lib/knockapi/resources/users.rb', line 354

def merge(user_id, params)
  parsed, options = Knockapi::UserMergeParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["v1/users/%1$s/merge", user_id],
    body: parsed,
    model: Knockapi::User,
    options: options
  )
end

#set_channel_data(user_id, channel_id, data:, request_options: {}) ⇒ Knockapi::Models::Recipients::RecipientsChannelData

Updates or creates channel data for a specific user and channel ID. If no user exists in the current environment for the given user_id, Knock will create the user entry as part of this request.

Parameters:

Returns:

See Also:



382
383
384
385
386
387
388
389
390
391
 
# File 'lib/knockapi/resources/users.rb', line 382

def set_channel_data(user_id, channel_id, params)
  parsed, options = Knockapi::UserSetChannelDataParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["v1/users/%1$s/channel_data/%2$s", user_id, channel_id],
    body: parsed,
    model: Knockapi::Recipients::RecipientsChannelData,
    options: options
  )
end

#set_preferences(user_id, id, _persistence_strategy: nil, categories: nil, channel_types: nil, channels: nil, commercial_subscribed: nil, workflows: nil, request_options: {}) ⇒ Knockapi::Models::Recipients::PreferenceSet

Some parameter documentations has been truncated, see Models::UserSetPreferencesParams for more details.

Updates a complete preference set for a user. By default, this is a destructive operation and will replace any existing preferences with the preferences given. Use 'persistence_strategy': 'merge' to merge with existing preferences instead.

Parameters:

Returns:

See Also:



424
425
426
427
428
429
430
431
432
433
 
# File 'lib/knockapi/resources/users.rb', line 424

def set_preferences(user_id, id, params = {})
  parsed, options = Knockapi::UserSetPreferencesParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["v1/users/%1$s/preferences/%2$s", user_id, id],
    body: parsed,
    model: Knockapi::Recipients::PreferenceSet,
    options: options
  )
end

#unset_channel_data(user_id, channel_id, request_options: {}) ⇒ nil

Deletes channel data for a specific user and channel ID.

Parameters:

  • user_id (String) —

    The unique identifier of the user.

  • channel_id (String) —

    The unique identifier for the channel.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



448
449
450
451
452
453
454
455
 
# File 'lib/knockapi/resources/users.rb', line 448

def unset_channel_data(user_id, channel_id, params = {})
  @client.request(
    method: :delete,
    path: ["v1/users/%1$s/channel_data/%2$s", user_id, channel_id],
    model: NilClass,
    options: params[:request_options]
  )
end

#unset_preferences(user_id, id, request_options: {}) ⇒ nil

Unsets the preference set for the user, removing it entirely.

Parameters:

  • user_id (String) —

    The unique identifier of the user.

  • id (String) —

    Unique identifier for the preference set.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



470
471
472
473
474
475
476
477
 
# File 'lib/knockapi/resources/users.rb', line 470

def unset_preferences(user_id, id, params = {})
  @client.request(
    method: :delete,
    path: ["v1/users/%1$s/preferences/%2$s", user_id, id],
    model: NilClass,
    options: params[:request_options]
  )
end

#update(user_id, avatar: nil, channel_data: nil, created_at: nil, email: nil, locale: nil, name: nil, phone_number: nil, preferences: nil, timezone: nil, request_options: {}) ⇒ Knockapi::Models::User

Some parameter documentations has been truncated, see Models::UserUpdateParams for more details.

Create or update a user with the provided identification data. When you identify an existing user, the system merges the properties you specific with what is currently set on the user, updating only the fields included in your requests.

Parameters:

Returns:

See Also:



62
63
64
65
66
67
68
69
70
71
 
# File 'lib/knockapi/resources/users.rb', line 62

def update(user_id, params = {})
  parsed, options = Knockapi::UserUpdateParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["v1/users/%1$s", user_id],
    body: parsed,
    model: Knockapi::User,
    options: options
  )
end