Module: Twitter::REST::DirectMessages

Includes:
UploadUtils, Utils, Utils
Included in:
API
Defined in:
lib/twitter/rest/direct_messages.rb,
lib/twitter/rest/direct_messages/welcome_messages.rb

Defined Under Namespace

Modules: WelcomeMessages

Constant Summary

Constants included from Utils

Utils::DEFAULT_CURSOR

Instance Method Summary collapse

Methods included from Utils

flat_pmap, pmap

Instance Method Details

#create_direct_message(user_id, text, options = {}) ⇒ Twitter::DirectMessage Also known as: d, m, dm

Sends a new direct message to the specified user from the authenticating user

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID

  • text (String) —

    The text of your direct message, up to 10,000 characters.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context


171
172
173
174
 
# File 'lib/twitter/rest/direct_messages.rb', line 171

def create_direct_message(user_id, text, options = {})
  event = perform_request_with_object(:json_post, '/1.1/direct_messages/events/new.json', format_json_options(user_id, text, options), Twitter::DirectMessageEvent)
  event.direct_message
end

#create_direct_message_event(*args) ⇒ Twitter::DirectMessageEvent

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Create a new direct message event to the specified user from the authenticating user

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, URI, or object.

  • text (String) —

    The text of your direct message, up to 10,000 characters.

  • options (Hash) —

    A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context


190
191
192
193
194
195
196
 
# File 'lib/twitter/rest/direct_messages.rb', line 190

def create_direct_message_event(*args)
  arguments = Twitter::Arguments.new(args)
  options = arguments.options.dup
  options[:event] = {type: 'message_create', message_create: {target: {recipient_id: extract_id(arguments[0])}, message_data: {text: arguments[1]}}} if arguments.length >= 2
  response = Twitter::REST::Request.new(self, :json_post, '/1.1/direct_messages/events/new.json', options).perform
  Twitter::DirectMessageEvent.new(response[:event])
end

#create_direct_message_event_with_media(user, text, media, options = {}) ⇒ Twitter::DirectMessageEvent

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Create a new direct message event to the specified user from the authenticating user with media

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, URI, or object.

  • text (String) —

    The text of your direct message, up to 10,000 characters.

  • media (File) —

    A media file (PNG, JPEG, GIF or MP4).

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context


211
212
213
214
215
216
217
 
# File 'lib/twitter/rest/direct_messages.rb', line 211

def create_direct_message_event_with_media(user, text, media, options = {})
  media_id = upload(media, media_category_prefix: 'dm')[:media_id]
  options = options.dup
  options[:event] = {type: 'message_create', message_create: {target: {recipient_id: extract_id(user)}, message_data: {text: text, attachment: {type: 'media', media: {id: media_id}}}}}
  response = Twitter::REST::Request.new(self, :json_post, '/1.1/direct_messages/events/new.json', options).perform
  Twitter::DirectMessageEvent.new(response[:event])
end

#destroy_direct_message(*ids) ⇒ nil

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Destroys direct messages

Parameters:

  • ids (Enumerable<Integer>) —

    A collection of direct message IDs.

Returns:

  • (nil) —

    Response body from Twitter is nil if successful

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context


154
155
156
157
158
159
 
# File 'lib/twitter/rest/direct_messages.rb', line 154

def destroy_direct_message(*ids)
  pmap(ids) do |id|
    perform_requests(:delete, '/1.1/direct_messages/events/destroy.json', id: id)
  end
  nil
end

#direct_message(id, options = {}) ⇒ Twitter::DirectMessage

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Returns a direct message

Parameters:

  • id (Integer) —

    A direct message ID.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context


88
89
90
 
# File 'lib/twitter/rest/direct_messages.rb', line 88

def direct_message(id, options = {})
  direct_message_event(id, options).direct_message
end

#direct_message_event(id, options = {}) ⇒ Twitter::DirectMessageEvent

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Returns a direct message event

Parameters:

  • id (Integer) —

    A direct message ID.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context


102
103
104
105
106
 
# File 'lib/twitter/rest/direct_messages.rb', line 102

def direct_message_event(id, options = {})
  options = options.dup
  options[:id] = id
  perform_get_with_object('/1.1/direct_messages/events/show.json', options, Twitter::DirectMessageEvent)
end

#direct_messages(*ids) ⇒ Object #direct_messages(*ids, options) ⇒ Object

@see https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/list-events @param options [Hash] A customizable set of options. @option options [Integer] :count Specifies the number of records (sent and received dms) to retrieve. Must be less than or equal to 50. Default is 50 this count does not directly correspond to the output, as we pull sent and received messages from twitter and only present received to the user @option options [String] :cursor Specifies the cursor position of results to retrieve.

Overloads:


133
134
135
136
137
138
139
140
141
142
 
# File 'lib/twitter/rest/direct_messages.rb', line 133

def direct_messages(*args)
  arguments = Twitter::Arguments.new(args)
  if arguments.empty?
    direct_messages_received(arguments.options)
  else
    pmap(arguments) do |id|
      direct_message(id, arguments.options)
    end
  end
end

#direct_messages_events(options = {}) ⇒ Array<Twitter::DirectMessageEvent>

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Returns all Direct Message events for the authenticated user (both sent and received) within the last 30 days. Sorted in reverse-chronological order.

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 50. Default is 20

  • :cursor (String) —

    Specifies the cursor position of results to retrieve.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context


26
27
28
29
 
# File 'lib/twitter/rest/direct_messages.rb', line 26

def direct_messages_events(options = {})
  limit = options.fetch(:count, 20)
  perform_get_with_cursor('/1.1/direct_messages/events/list.json', options.merge!(no_default_cursor: true, count: 50, limit: limit), :events, Twitter::DirectMessageEvent)
end

#direct_messages_list(options = {}) ⇒ Array<Twitter::DirectMessage>

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Returns all Direct Messages for the authenticated user (both sent and received) within the last 30 days. Sorted in reverse-chronological order.

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 50. Default is 20

  • :cursor (String) —

    Specifies the cursor position of results to retrieve.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context


41
42
43
 
# File 'lib/twitter/rest/direct_messages.rb', line 41

def direct_messages_list(options = {})
  direct_messages_events(options).collect(&:direct_message)
end

#direct_messages_received(options = {}) ⇒ Array<Twitter::DirectMessage>

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Returns Direct Messages received by the authenticated user within the last 30 days. Sorted in reverse-chronological order. this count does not directly correspond to the output, as we pull sent and received messages from twitter and only present received to the user

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records (sent and received dms) to retrieve. Must be less than or equal to 50. Default is 50

  • :cursor (String) —

    Specifies the cursor position of results to retrieve.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context


56
57
58
59
 
# File 'lib/twitter/rest/direct_messages.rb', line 56

def direct_messages_received(options = {})
  limit = options.fetch(:count, 20)
  direct_messages_list(options).select { |dm| dm.recipient_id == user_id }.first(limit)
end

#direct_messages_sent(options = {}) ⇒ Array<Twitter::DirectMessage>

Note:

This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Returns Direct Messages sent by the authenticated user within the last 30 days. Sorted in reverse-chronological order. this count does not directly correspond to the output, as we pull sent and received messages from twitter and only present received to the user

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records (sent and received dms) to retrieve. Must be less than or equal to 50. Default is 50

  • :cursor (String) —

    Specifies the cursor position of results to retrieve.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context


72
73
74
75
 
# File 'lib/twitter/rest/direct_messages.rb', line 72

def direct_messages_sent(options = {})
  limit = options.fetch(:count, 20)
  direct_messages_list(options).select { |dm| dm.sender_id == user_id }.first(limit)
end