Twitter-webhooks NPM

Twitter Webhooks

This module provide a simple way to implement twitter webhooks with ExpressJs.

This module is very new, feel free to make requests or to give some feedbacks in the github issues.

Requirements

You need to create an app on the twitter's developer portal and apply for Account Activity API access
Your Twitter app must have the Read, write, and direct messages permission
Your server must be reachable with https because twitter doesn't accept unsecured webhooks.
This is an ExpressJS middleware so Express must be installed with your app
body-parser JSON middleware must be added to mount your Express app

Install

npm i -s twitter-webhooks

Usage

const express = require ('express');
const bodyParser = require ('body-parser');
const twitterWebhooks = require('twitter-webhooks');
const https = require ('https');

const app = express();
app.use(bodyParser.json());

const userActivityWebhook = twitterWebhooks.userActivity({
    serverUrl: 'https://yourdomain.com',
    route: '/your/webhook/route', //default : '/'
    consumerKey: '[YOUR CONSUMER KEY]',
    consumerSecret: '[YOUR CONSUMER SECRET]',
    accessToken: '[YOUR APP ACCESS TOKEN]',
    accessTokenSecret: '[YOUR APP ACCESS TOKEN SECRET]',
    environment: '[your-env]', //default : 'env-beta'
    app
});

//Register your webhook url - just needed once per URL
userActivityWebhook.register();

//Subscribe for a particular user activity
userActivityWebhook.subscribe({
    userId: '[TWITTER USER ID]',
    accessToken: '[TWITTER USER ACCESS TOKEN]',
    accessTokenSecret: '[TWITTER USER ACCESS TOKEN SECRET]'
})
.then(function (userActivity) {
    userActivity
    .on('favorite', (data) => console.log (userActivity.id + ' - favorite'))
    .on ('tweet_create', (data) => console.log (userActivity.id + ' - tweet_create'))
    .on ('follow', (data) => console.log (userActivity.id + ' - follow'))
    .on ('mute', (data) => console.log (userActivity.id + ' - mute'))
    .on ('revoke', (data) => console.log (userActivity.id + ' - revoke'))
    .on ('direct_message', (data) => console.log (userActivity.id + ' - direct_message'))
    .on ('direct_message_indicate_typing', (data) => console.log (userActivity.id + ' - direct_message_indicate_typing'))
    .on ('direct_message_mark_read', (data) => console.log (userActivity.id + ' - direct_message_mark_read'))
    .on ('tweet_delete', (data) => console.log (userActivity.id + ' - tweet_delete'))
});

//listen to any user activity
userActivityWebhook.on ('event', (event, userId, data) => console.log (userId + ' - favorite'));

//listen to unknown payload (in case of api new features)
userActivityWebhook.on ('unknown-event', (rawData) => console.log (rawData));

const server = https.createServer({
    ...yourHttpsConfig
});

server.listen(443);

Check your webhook

You can check that your webhook is working by hitting it with a web browser :

https://yourdomain.com/your/webhook/route?crc_token=123456

If your webhook is properly working you'll see this kind of response :

{"response_token":"sha256=3d5U20ieYMPd/+sofKdOeSE6BkVKMqFiq+acNgeUGrYg"}

Reference

TwitterWebhooks
- userActivity(config)
Middleware: UserActivity
Class: UserActivityEmitter
TwitterWebhooks
This is the root module when your require twitter-webhooks.
```
const twitterWebhooks = require ('twitter-webhooks');
```
- userActivity(config)
  Create an UserActivity middleware and automatically mount it on an express app if config.app is provided.
  arguments
  - config - Object: config.serverUrl - string: The server URL where twitter can reach the webhook app (eg: 'https://my.aweso.me/service') config.route - string: the route of the middleware in the app (eg: '/user-activity-webhook') config.consumerKey - string: Your Twitter app consumerKey config.consumerSecret - string: Your Twitter app consumerSecret config.accessToken - string: Your Twitter app accessToken config.accessTokenSecret - string: Your Twitter app accessTokenSecret config.environment - string: The environment name of the webhook. You can find it in your twitter dashboard config.app - Express App (optional): The express app on which to mount the middleware. If not provided, don't forget to mount the middleware (eg : app.use(userActivity.route, userActivity) ) config.appBearerToken - string (optional)*: Your Twitter app bearer token. If not provided a request will be made to twitter's API to get the token.
    return value UserActivity
    This method returns a UserActivity middleware.
Middleware: UserActivity
An UserActivity middleware is created using the twitterWebhooks.userActivity(config) method. This middleware can be mounted on an ExpressJs app. Each middleware is associated with one User Activity webhook. UserActivity middlewares has a set of methods that helps to configure the webhook by sending calls to the twitter API.
The UserActivity middlewares implements EventEmitters.
- Event: 'event':
  - eventName - string : The name of the event. This can be any event documented in UserActivityEmitter
  - userId - string : The id of the user who triggered this event.
    This event is sent for each message received on the webhook.
- Event: 'unknown-event':
  - payload - Object : The raw object sent by the Twitter API.
    This event is sent for each unknown message received on the webhook. This is useful in case of Twitter's API change not implemented on this module.
- getSubscriptionsCount()
  Get the subscriptions count of your Twitter app.
  return value Promise<Object>
  This method returns a promise that is resolved with a javascript Object provided by the Twitter API :
```
{
    "subscriptions_count_all": "2",
    "subscriptions_count_direct_messages": "1"
}
```
- getWebhook()
  Warning : This method will certainly be modified.
  Get information about the current registered webhooks of an environment.
  return value Promise<Array>
  This method returns a promise that is resolved with a javascript Array provided by the Twitter API.
```
[
  {
    "id": "1234567890",
    "url": "https://my.aweso.me/service/user-activity-webhook",
    "valid": true,
    "created_at": "2016-06-02T23:54:02Z"
  }
]
```
- getWebhooks()
  Get information about webhooks for all the environments of your twitter app.
  return value return Promise<Array>
  This method returns a promise that is resolved with a javascript Array provided by the Twitter API. For more information about the response, please read Twitter's doc.
- isSubscribed(options)
  Check if a subscription exists for a twitter account.
  arguments
  - options - Object options.accessToken - string : The twitter account accessToken options.accessTokenSecret - string : The twitter account accessTokenSecret * options.userId - string : The twitter account Id
    return value Promise<Boolean>
    This method returns a promise that is resolved to true if the account is subscribed to this middleware's webhook. Otherwise the resolve value is false.
- register()
  Registers the webhook with the parameters given in the config of the middleware constructor. Read Twitter's doc
  return value Promise<Object>
  This method returns a promise that is resolved with a javascript Object provided by the Twitter API :
```
{
  "id": "1234567890",
  "url": "https://my.aweso.me/service/user-activity-webhook",
  "valid": true,
  "created_at": "2016-06-02T23:54:02Z"
}
```
- subscribe(options)
  Subscribes to all events of a twitter account.
  arguments
  - options - Object options.accessToken - string : The twitter account accessToken options.accessTokenSecret - string : The twitter account accessTokenSecret * options.userId - string : The twitter account Id
    return value Promise<UserActivityEmitter>
    This method returns a promise that is resolved to a UserActivityEmitter instance that will emit all the events received for this account on the webhook.
- triggerChallengeResponseCheck(options)
  Manually trigger a CRC request on the webhook. Read Twitter's doc
  arguments
  - options.webhookId - string : The webhook id
- unregister(options)
  Unregisters the webhook with the parameters given in the config of the middleware constructor. Read Twitter's doc
  arguments
  - options - Object
    - options.webhookId - string : The webhook id that you wan't to unregister
  return value Promise
  The promise is resolved if the webhook was unregistered with success and is rejected if not.
- unsubscribe(options)
  Deletes a subscription for the specified account.
  arguments
  - options Object: options.accessToken - string : The twitter account accessToken options.accessTokenSecret - string : The twitter account accessTokenSecret * options.userId - string : The twitter account Id
    return value Promise
    The promise is resolved if the subscription was deleted with success and is rejected if not.
- getCrcCheckTiming()
```
Utility function that perform a CRC check request in order to estimate a the server timing.

#### return value `Promise<int>`
The promise is resolved with the timing of the request in milliseconds.
```
  Class: UserActivityEmitter
  Instances of the UserActivityEmitter class are EventEmitters that represent activity of one twitter account. You can get an instance of UserActivityEmitter by using the subscribe method of an UserActivity middleware.
- Event: 'block'
  - blockEvent - Object : id - string : ID of the event created_timestamp - string: Timestamp of when the event happened target - <Tweet Object>: The blocked User. For more details on User Objects : Read Twitter's doc source - <User Object>: The blocking User. For more details on User Objects : Read Twitter's doc
```
{
    "type": "follow",
    "created_timestamp": "1517588749178",
    "target": "<User Object>",
    "source": "<User Object>"
}
```
- Event: 'favorite'
  - favoriteEvent - Object : id - string : ID of the event created_at - string : Date string of when the event happened timestamp_ms - number: Timestamp of when the event happened favorited_status - <Tweet Object>: The favorited tweet object. For more details on Tweet Objects : Read Twitter's doc * user - <User Object>: The user object of the account who favorited the tweet. For more details on User Objects : Read Twitter's doc
```
{
    "id": "a7ba59eab0bfcba386f7acedac279542",
    "created_at": "Mon Mar 26 16:33:26 +0000 2018",
    "timestamp_ms": 1522082006140,
    "favorited_status": "<Tweet Object>",
    "user": "<User Object>"
}
```
- Event: 'follow'
  - followEvent - Object : id - string : ID of the event created_timestamp - string: Timestamp of when the event happened target - <Tweet Object>: The followed User. For more details on User Objects : Read Twitter's doc source - <User Object>: The following User. For more details on User Objects : Read Twitter's doc
```
{
    "type": "follow",
    "created_timestamp": "1517588749178",
    "target": "<User Object>",
    "source": "<User Object>"
}
```
- Event: 'mute'
  - muteEvent - Object : id - string : ID of the event created_timestamp - string: Timestamp of when the event happened target - <Tweet Object>: The muted User. For more details on User Objects : Read Twitter's doc source - <User Object>: The muting User. For more details on User Objects : Read Twitter's doc
```
{
    "type": "follow",
    "created_timestamp": "1517588749178",
    "target": "<User Object>",
    "source": "<User Object>"
}
```
- Event: 'direct_message'
  Not tested yet. Please provide feedback if you are using this.
- Event: 'direct_message_indicate_typing'
  Not tested yet. Please provide feedback if you are using this.
- Event: 'direct_message_mark_read'
  Not tested yet. Please provide feedback if you are using this.
- Event: 'revoke'
  - userId - string : Id of the user who revoked the subscription. This is the same id as the UserActivityEmitter instance id.
    Emitted when the user revokes the subscription.
- Event: 'tweet_create'
  - tweet - <Tweet Object> : The created tweet object. For more details on Tweet Objects : Read Twitter's doc
- Event: 'tweet_delete'
```
* tweetDeleteEvent - `Object`:
    * status - `object`:
        * id - `string`: id of the deleted tweet
        * user_id - `string`: id of the user who deleted the tweet
    * timestamp_ms - `string`: Timestamp of when the event happened
```json
  {
      "status": {
          "id": "601430178305220608",
          "user_id": "3198576760"
      },
      "timestamp_ms": "1432228155593"
  }
```
```
  For more details on each event : Read Twitter's doc

TODO

Finish documentation
Improve direct message events the emitted data object is incomplete
Add tests
Add a working example

LICENSE

MIT License

Copyright (c) 2018 Vivien Anglesio

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

twitter webhook account middleware user activity express

request

@everything-registry/sub-chunk-2990 @cryptology.hk/pay-twitter @infinitebrahmanuniverse/nolb-twit

1 year ago

4 years ago

5 years ago

5 years ago