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,
sig/knockapi/resources/users.rbs,
sig/knockapi/resources/users/bulk.rbs,
sig/knockapi/resources/users/feeds.rbs,
sig/knockapi/resources/users/guides.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

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:



477
478
479
480
481
482
 
# File 'lib/knockapi/resources/users.rb', line 477

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)
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

Instance Method Details

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

Permanently delete a user and all associated data.

Parameters:

Returns:

  • (nil)

See Also:



110
111
112
113
114
115
116
117
 
# File 'lib/knockapi/resources/users.rb', line 110

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:



130
131
132
133
134
135
136
137
 
# File 'lib/knockapi/resources/users.rb', line 130

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:



152
153
154
155
156
157
158
159
 
# File 'lib/knockapi/resources/users.rb', line 152

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:



177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/knockapi/resources/users.rb', line 177

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:



86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/knockapi/resources/users.rb', line 86

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:



233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/knockapi/resources/users.rb', line 233

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:



257
258
259
260
261
262
263
264
 
# File 'lib/knockapi/resources/users.rb', line 257

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:



287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'lib/knockapi/resources/users.rb', line 287

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:



322
323
324
325
326
327
328
329
330
331
332
333
 
# File 'lib/knockapi/resources/users.rb', line 322

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:



349
350
351
352
353
354
355
356
357
358
 
# File 'lib/knockapi/resources/users.rb', line 349

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:



377
378
379
380
381
382
383
384
385
386
 
# File 'lib/knockapi/resources/users.rb', line 377

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:



419
420
421
422
423
424
425
426
427
428
 
# File 'lib/knockapi/resources/users.rb', line 419

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:



443
444
445
446
447
448
449
450
 
# File 'lib/knockapi/resources/users.rb', line 443

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:



465
466
467
468
469
470
471
472
 
# File 'lib/knockapi/resources/users.rb', line 465

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:



57
58
59
60
61
62
63
64
65
66
 
# File 'lib/knockapi/resources/users.rb', line 57

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