Twitter

Let your Teneo bot respond to tweets and DM's on Twitter using the Teneo Twitter connector.

Twitter logo

The connector uses Twitter's Account Activity API to detect and react to incoming Direct Messages and Tweets, without quickly exhausting Twitter's Rate Limit. This connector is partially based on the account-activity-dashboard created by Gareja Mahesh.

You can find the source code for this connector on Github.

Prerequisites

Teneo Engine

Your bot needs to be published and you need to know the Engine URL.

Twitter account

You will need to apply for a Twitter Developer Account and then create a Twitter App, as described ahead.

HTTPS

A Heroku account is required to deploy the connector online.

Or, to run the connector locally, ngrok is preferred to make the connector available via HTTPS.

Getting started

Create a Twitter app

  1. Apply for a Twitter Developer account on developer.twitter.com, select "Making a Bot", and fill in all required fields.
    • On the Specifics section, set "Will your app use Tweet, Retweet, like, follow, or Direct Message functionality?" to YES. You may set all other options to No. Continue filling in required descriptions and validate Twitter's activation email.
  2. Create a Twitter App here. Fill all required fields and tap "Create"

Create a Twitter Account Activity API

In the Account Activity API/Sandbox section, click Setup Dev Environment. Link this new environment to the App you created in the previous step and take note of the environment_label for later use.

Configure the Twitter App

  1. Open your app's details
  2. Navigate into Permissions > Edit > Access permission section > Enable Read, Write and direct messages.
  3. On the Keys and Tokens tab > click Create button. Take note of all four keys and tokens.

Connector Setup Instructions

Two ways of running this connector are described ahead. The first metod, is Running the connector online with Heroku. This is the easiest to get the connector running for non-developers since it does not require you to run Node.js or download or modify any code.

The second way is Running the connector locally or deploying it on a server of your choice. This is preferred if you're familiar with Node.js development and want to have a closer look at the code, or to implement modifications and enhancements.

Running the connector on Heroku

  1. Click the button below to deploy the connector to Heroku:

    Deploy

  2. In the 'Config Vars' section, fill the following values:
    • TWITTER_CONSUMER_KEY: The 'API key' from the 'Keys and Tokens' tab of your twitter app.
    • TWITTER_CONSUMER_SECRET: The 'API secret key' from the 'Keys and Tokens' tab of your twitter app.
    • TWITTER_ACCESS_TOKEN: The 'Access token' from thev'Keys and Tokens' tab of your twitter app.
    • TWITTER_ACCESS_TOKEN_SECRET: The 'Access token secret' from the 'Keys and Tokens' tab of your twitter app.
    • TWITTER_WEBHOOK_ENV: The 'environment_label' you entered when you created your twitter dev environment here.
    • TENEO_ENGINE_URL: The Engine URL of your bot.

  3. Click on 'Deploy App', and wait for Heroku to complete the deployment. Click 'View' to see your new Heroku's app URL. Copy it, we will use it as a webhook_url in the next step.

  4. Revisit your app's details, click 'Edit', and add the following URL values as whitelisted Callback URLs:

    https://your.herokuapp.com/webhook/twitter
https://your.herokuapp.com/callbacks/addsub
https://your.herokuapp.com/callbacks/removesub

Create a Twitter Webhook Configuration

Open Heroku's command console by tapping "More > Run Console", from the upper right area in the Dashboard. Set up a webhook to receive user events on the web app by running this command on Heroku´s console:

node example_scripts/webhook_management/create-webhook-config.js -e <environment_label> -u <https://your.herokuapp.com/webhook/twitter>

When succesful, the create-webhook-config command should return a webhook_id (you don't actually need to use this webhook_id).

Subscribe to App Owner

To listen to events such as Tweet mentions and Direct messages, subscribe to the Account Activity API Environment by running the following command on Heroku's command line:

node example_scripts/subscription_management/add-subscription-app-owner.js -e <environment_label>

That's it! You can now interact with your Teneo solution powered bot with Direct Messages, Tweet mentions, and Tweet replies.

Note: The free tier of Heroku will put your app to sleep after 30 minutes. On cold start, you app will have very high latency which may result in a CRC failure that deactivates your webhook. To trigger a challenge response request and re-validate, run the following script.

node example_scripts/webhook_management/validate-webhook-config.js -e <environment> -i <webhook_id>

Running the connector locally

Next, we need to make the connector available via https. We'll use ngrok for this.

  1. Start ngrok. The connector runs on port 5000 by default, so we need to start ngrok like this: 
    ngrok http 5000

  2. Running the command above will display a public forwarding https URL. Copy it, we will use it as a webhook_url in the final step below.

  3. Revisit your app's details, click 'Edit', and use webhook_url to form the following URL values and add them as whitelisted Callback URLs:

    https://yoururl.ngrok.io/webhook/twitter
https://yoururl.ngrok.io/callbacks/addsub
https://yoururl.ngrok.io/callbacks/removesub

Setup & run a Node.js web app

  1. Clone this repository:

    git clone https://github.com/artificialsolutions/tie-api-example-twitter.git

  2. Install Node.js dependencies:

    npm install

  3. Create a new file called .env (there is a file called .env.sample in the repository that you can use as a basis) and fill in your Twitter 'API key', 'API secret key', 'Access token', 'Access token secret', the 'environment_label' you entered when you created your twitter dev environment and the Teneo Engine URL. The keys and access tokens can be found on your app page on developer.twitter.com/en/apps. 

    TWITTER_CONSUMER_KEY=
TWITTER_CONSUMER_SECRET=
TWITTER_ACCESS_TOKEN=
TWITTER_ACCESS_TOKEN_SECRET=
TWITTER_WEBHOOK_ENV=
TENEO_ENGINE_URL=

  4. Run locally:

    npm start

Create a Twitter Webhook Configuration

A Free Twitter Developer account allows configuring one webhook_url, to receive user events on a web app. Keep the web app from the previous step running in one console window, and then open a second console window to create a webhook, with the following command:

node example_scripts/webhook_management/create-webhook-config.js -e <environment_label> -u <https://yoururl.ngrok.io/webhook/twitter>

When succesful, the create-webhook-config command should return a webhook_id.

Subscribe to App Owner

Subscribe the Account Activity API Environment to listen to activity that happens on the Twitter account that owns the app, such as incoming DMs, tweets, and mentions. 

node example_scripts/subscription_management/add-subscription-app-owner.js -e <environment_label>

That's it! You can now interact with your Teneo solution powered bot with Direct Messages, Tweet mentions, and Tweet replies.

Production considerations

This connector can handle light usage, but you may experience API rate limit issues under heavier load. For production use, consider storing data locally in a secure database, caching requests, or applying for a business account for increased Rate Limits.

Was this page helpful?