module Twitter::REST::DirectMessages

Public Instance Methods

create_direct_message(user_id, text, options = {}) click to toggle source

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

@see developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/new-event @rate_limited Yes @authentication Requires user context @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid. @return [Twitter::DirectMessage] The sent message. @param user [Integer, String, Twitter::User] A Twitter user ID @param text [String] The text of your direct message, up to 10,000 characters. @param options [Hash] A customizable set of options.

# 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
Also aliased as: d, m, dm
create_direct_message_event(*args) click to toggle source

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

@see developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/new-event @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information. @rate_limited Yes @authentication Requires user context @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid. @return [Twitter::DirectMessageEvent] The created direct message event. @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object. @param text [String] The text of your direct message, up to 10,000 characters. @param options [Hash] A customizable set of options.

# 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 = {}) click to toggle source

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

@see developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/new-event @see developer.twitter.com/en/docs/direct-messages/message-attachments/guides/attaching-media @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information. @rate_limited Yes @authentication Requires user context @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid. @return [Twitter::DirectMessageEvent] The created direct message event. @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object. @param text [String] The text of your direct message, up to 10,000 characters. @param media [File] A media file (PNG, JPEG, GIF or MP4). @param options [Hash] A customizable set of options.

# 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
d(user_id, text, options = {})
destroy_direct_message(*ids) click to toggle source

Destroys direct messages

@see developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/delete-message-event @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information. @rate_limited Yes @authentication Requires user context @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid. @return [nil] Response body from Twitter is nil if successful @overload destroy_direct_message(*ids)

@param ids [Enumerable<Integer>] A collection of direct message IDs.
# 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 = {}) click to toggle source

Returns a direct message

@see developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-event @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information. @rate_limited Yes @authentication Requires user context @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid. @return [Twitter::DirectMessage] The requested message. @param id [Integer] A direct message ID. @param options [Hash] A customizable set of options.

# 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 = {}) click to toggle source

Returns a direct message event

@see developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-event @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information. @rate_limited Yes @authentication Requires user context @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid. @return [Twitter::DirectMessageEvent] The requested message. @param id [Integer] A direct message ID. @param options [Hash] A customizable set of options.

# 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(*args) click to toggle source
@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.

@overload direct_messages(*ids)

Returns direct messages

@see https://dev.twitter.com/rest/reference/get/direct_messages/show
@param ids [Enumerable<Integer>] A collection of direct message IDs.

@overload direct_messages(*ids, options)

Returns direct messages

@see https://dev.twitter.com/rest/reference/get/direct_messages/show
@param ids [Enumerable<Integer>] A collection of direct message IDs.
@param options [Hash] A customizable set of options.
# 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 = {}) click to toggle source

Returns all Direct Message events for the authenticated user (both sent and received) within the last 30 days. Sorted in reverse-chronological order. @see developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/list-events @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information. @rate_limited Yes @authentication Requires user context @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid. @return [Array<Twitter::DirectMessageEvent>] Direct message events sent by and received by the authenticating user. @param options [Hash] A customizable set of options. @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 50. Default is 20 @option options [String] :cursor Specifies the cursor position of results to retrieve.

# 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 = {}) click to toggle source

Returns all Direct Messages for the authenticated user (both sent and received) within the last 30 days. Sorted in reverse-chronological order. @see developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/list-events @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information. @rate_limited Yes @authentication Requires user context @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid. @return [Array<Twitter::DirectMessage>] Direct messages sent by and received by the authenticating user. @param options [Hash] A customizable set of options. @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 50. Default is 20 @option options [String] :cursor Specifies the cursor position of results to retrieve.

# 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 = {}) click to toggle source

Returns Direct Messages received by the authenticated user within the last 30 days. Sorted in reverse-chronological order. @see developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/list-events @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information. @rate_limited Yes @authentication Requires user context @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid. @return [Array<Twitter::DirectMessage>] Direct messages received by the authenticating user. @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.

# 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 = {}) click to toggle source

Returns Direct Messages sent by the authenticated user within the last 30 days. Sorted in reverse-chronological order. @see developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/list-events @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information. @rate_limited Yes @authentication Requires user context @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid. @return [Array<Twitter::DirectMessage>] Direct messages sent by the authenticating user. @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.

# 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
dm(user_id, text, options = {})
m(user_id, text, options = {})

Private Instance Methods

format_json_options(user_id, text, options) click to toggle source
# File lib/twitter/rest/direct_messages.rb, line 221
def format_json_options(user_id, text, options)
  {'event': {'type': 'message_create', 'message_create': {'target': {'recipient_id': user_id}, 'message_data': {'text': text}.merge(options)}}}
end