= Twitter Consumers


== 1. Twitter Status Update Consumer.

Updates the authenticating user's current text (e.g. Tweeting).

NOTE: For each update attempt, the update text is compared with the authenticating user's recent Tweets.
Any attempt that would result in duplication will be blocked, resulting in a 403 error.
A user cannot submit the same text twice in a row.

While not rate limited by the API, a user is limited in the number of Tweets they can create at a time.
The update limit for standard API is 300 in 3 hours windows.
If the number of updates posted by the user reaches the current allowed limit this method will return an HTTP 403 error.

You can find details for the Update API here: https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update


=== 1.1 Beans for injection

The `TwitterUpdateConsumerConfiguration` auto-configuration provides this beans:

- `Consumer<StatusUpdate> twitterUpdateStatusConsumer` - if you have an `StatusUpdate` instance you can use the `updateStatus` to apply it.

- `Function<Message<?>, StatusUpdate> messageToStatusUpdateFunction` - function that converts a `Message<?>`  text into a `StatusUpdate` instance using the `TwitterUpdateConsumerProperties` properties.

- `Consumer<Message<?>> twitterUpdateStatusConsumer` - composes `messageToStatusUpdateFunction` and `updateStatus` to update the twitter status from Message text.

Note: the Message content is expected to be in text format. Consider using the `byteArrayTextToString` utility `Function`.

You can use `twitterUpdateStatusConsumer` as a qualifier when injecting.

=== 1.2 Configuration Options

All configuration properties are prefixed with `twitter.update`.

For more information on the various options available, please see link:src/main/java/org/springframework/cloud/fn/consumer/twitter/status/update/TwitterUpdateConsumerProperties.java[TwitterUpdateConsumerProperties].

The twitter function makes uses of link:../spel-function/README.adoc[SpEL function].

=== 1.3 Other usage

See this https://github.com/spring-cloud/stream-applications/blob/master/applications/sink/twitter-update-sink/README.adoc[README] where this consumer is used to create a Spring Cloud Stream application where it makes a Twitter Update sink.

== 2. Twitter Message Consumer.

Send Direct Messages to a specified user from the authenticating user.
Requires a JSON POST body and `Content-Type` header to be set to `application/json`.

NOTE: When a message is received from a user you may send up to 5 messages in response within a 24-hour window.
Each message received resets the 24-hour window and the 5 allotted messages.
Sending a 6th message within a 24-hour window or sending a message outside a 24-hour window will count towards rate-limiting.
This behavior only applies when using the POST direct_messages/events/new endpoint.

SpEL expressions are used to compute the request parameters from the input message.

=== 2.1 Beans for injection

The `TwitterMessageConsumerConfiguration` auto-configuration provides this beans:

- `Consumer<Message<?>> twitterSendMessageConsumer`

Note: the Message content is expected to be in text format. Consider using the `byteArrayTextToString` utility `Function`.

You can use `twitterSendMessageConsumer` as a qualifier when injecting.

=== 2.2 Configuration Options

All configuration properties are prefixed with `twitter.message.update`.

For more information on the various options available, please see link:src/main/java/org/springframework/cloud/fn/consumer/twitter/message/TwitterMessageConsumerProperties.java[TwitterMessageConsumerProperties].

The twitter function makes uses of link:../spel-function/README.adoc[SpEL function].

=== 2.3 Other usage

See this https://github.com/spring-cloud/stream-applications/blob/master/applications/sink/twitter-message-sink/README.adoc[README] where this consumer is used to create a Spring Cloud Stream application where it makes a Twitter Message sink.

== 3. Twitter Friendship Consumer.

Allows creating `follow`, `unfollow` and `update` relationships with specified `userId` or `screenName`.
The `twitter.friendships.sink.type` property allows to select the desired friendship operation.

* https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create[Friendships Create API] - Allows the authenticating user to follow (friend) the user specified in the ID parameter.
Actions taken in this method are asynchronous.
Changes will be eventually consistent.
* https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-update[Friendships Update API] - Enable or disable Retweets and device notifications from the specified user.
* https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy[Friendships Destroy API] - Allows the authenticating user to unfollow the user specified in the ID parameter.

SpEL expressions are used to compute the request parameters from the input message.
Every operation type has its own parameters.

=== 3.1 Beans for injection

The `TwitterFriendshipsConsumerConfiguration` auto-configuration provides this beans:

- `Consumer<Message<?>> twitterFriendshipConsumer`

Note: the Message content is expected to be in text format. Consider using the `byteArrayTextToString` utility `Function`.

You can use `twitterFriendshipConsumer` as a qualifier when injecting.

=== 3.2 Configuration Options

All configuration properties are prefixed with `twitter.friendships.update`.

For more information on the various options available, please see link:src/main/java/org/springframework/cloud/fn/consumer/twitter/friendship/TwitterFriendshipsConsumerProperties.java[TwitterFriendshipsConsumerProperties].

The twitter function makes uses of link:../spel-function/README.adoc[SpEL function].

