General description

Twitter Bot is a component responsible for providing bridge between Twitter API and SentiOne Automate. It allows to conduct conversations with Automate bots using Twitter Direct Messages.

User's messages are being delivered to the application through webhooks technology so that it is important to make sure this component is exposed in a way those webhooks can be delivered.

API

Default port: 5756

Application has got HTTP API which is secured by verification of payload signature made with secret token that is shared between Twitter and the component.

There are default endpoints for monitoring purposes. They are described in Components monitoring section.

Databases

This application connects to RabbitMQ in order to persist all incoming messages and to guarantee they will be processed even in case of temporary downtime of application.

Communication

This service communicates with the following services:

Config

Application's config:

chatbots.twitter-bot {
    auth {
        # Key generated when Twitter Application is created
        consumer-key: "AAA888aaaaabbbbb123aaa" 
        # Secret is generated together with consumer key
        consumer-secret: "AAA888aaaaabbbbb123aaaAAA888aaaaabbbbb123aaa" 
        # Once you create twitter application there's possibility to generate the Bearer token as well
        bearer-token: "AAAAAAAAAAAAAA6798798798VVVVVVDFASDWQQDcxasdaWEQWEQWEEQWEQWE" 
        # Token required for registering webhooks. 
        # It's being created during application creation. 
        # It should have following access levels: Read,Write, Direct Messages. 
        # It can be found in "Authentication Tokens" section.
        default-access-token: "654897879875-sdad1231231ADASDWAWDAS1123asdasd" 
        # It is generated together with default-access-token
        default-access-secret: "asd888pqweknqiwnei123123" 
    }

    api {
        # Name of the environment in the Twitter Developer portal.
        # It can be found in section called "Products/Premium/Dev environments"
        env-name: "DEFAULT" 
        # Public URL of the component's endpoint
        # called "/webhooks" that can be accessed by Twitter server
        webhook-url: "http://twitter-bot.public-domain.com/webhooks"         
        # Twitter API base URL
        twitter-url: "https://api.twitter.com/1.1/"
    }

    bots: [{
       # Access token of a Twitter User who acts as a bot on Twitter.
       access-token: "56479874asdawdawdSDADASdasdasdWA"
       # Access token secret of a Twitter User who acts as a bot on Twitter.
       access-secret: "Iasd123123JKLSDOASDsdasadawqeweq1312312asd" 
       # Id of the user who acts as a bot on Twitter.
       user-id: 1230981029831098231 
       # Project ID in SentiOne Automate.
       bot-id: "aaaabbbb-4444-5555-6666-ccccddddeeee" 
    }]

    webhooks-messaging {
        message-timeout: 15s
    }
}

Other required configurations:

# actual address for gateway service
chatbots.gateway-api.url: "http://host:port" 

chatbots.messaging { 
  rabbit {
    hosts: ["HOST:PORT"]
    username: "USER"
    password: "PASSWORD"
  }
}

Job execution

None

Troubleshooting

Error when subscribing ("no write access")

Make sure your Twitter Application got OAuth enabled with "read, write and DM" permissions.

Additional resources

Twitter API

These API features enable developers to build better-personalized customer experiences at scale as well as other innovative interactions. To help create more engaging customer service, marketing, and user engagement experiences in Direct Messages we’re providing developers access to endpoints to start conversations with a welcome message, publish messages with quick replies and media, and more.

The Account Activity API provides you the ability to subscribe to realtime activities related to a user account via webhooks. This means that you can receive realtime Tweets, Direct Messages, and other account events from one or more of your owned or subscribed accounts through a single connection.

Quotes from official Twitter documentation.

Resources

https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/api-features
https://developer.twitter.com/en/docs/twitter-api/premium/account-activity-api/overview