Fortinet Document Library

Version:


Table of Contents

1.0.0
Copy Link

 

About the connector

Twitter is an online news and social networking service on which users post and interact with messages known as "tweets". Tweets are publicly visible by default, but senders can restrict message delivery to just their followers. Users can tweet using the Twitter website, compatible external applications (such as for smartphones), or by Short Message Service (SMS) available in certain countries. Users may subscribe to other users' tweets—this is known as "following" and subscribers are known as "followers" or "tweeps", a portmanteau of Twitter and peeps. Individual tweets can be forwarded by other users to their own feed, a process known as a "retweet". Users can also "like" (formerly "favorite") individual tweets.

This document provides information about the Twitter Connector, which facilitates automated interactions, with your Twitter account using FortiSOAR™ playbooks. Add the Twitter Connector, as a step in FortiSOAR™ playbooks and perform automated operations such as, posting tweets, searching tweets, and getting user details.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 4.10.3-161

Authored By: Fortinet

Certified: Yes

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

For the detailed procedure to install a connector, click here.

yum install cyops-connector-twitter

Prerequisites to configuring the connector

  • You must have a Twitter account to which you will connect and perform automated operations and the credentials, such as the Consumer Key and Access Token Secret, to access that account.
  • You must install the python-twitter==3.4.1 python module
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the Twitter connector and click Configure to configure the following parameters.

Note: To create twitter application refer to the "How to create a Twitter application document" located at: http://docs.inboundnow.com/guide/create-twitter-application/. Using this document you will learn how you can get all the configuration keys and configure your Twitter application so that you can connect to your Twitter account using which you want to perform automated operations using the Twitter connector.

 

Parameter Description
Consumer Key Consumer Key of the Twitter application that you have configured.
Consumer Secret Consumer Secret of the Twitter application that you have configured.
Access Token Key Access Token Key of the Twitter application that you have configured.
Access Token Secret Access Token Secret of the Twitter application that you have configured.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Post Tweet Posts a Twitter status message from your authenticated Twitter account.  
Send Direct Message Posts a Twitter direct message to a specified user from your authenticated Twitter account. You can specify a user using either the user's ID or the user's screen name. send_direct_message
Investigation
Search Tweets Searches for Tweets based on the term or geocode, and other input parameters you have specified. search_tweets
Investigation
Get User Retrieves details of a specified Twitter user, based on the user ID or screen name of the user you have specified. get_user
Investigation
Get User Timeline Retrieves the sequence of Public Status messages for a specified Twitter user, based on the user ID or screen name of the user, and other input parameters you have specified. get_user_timeline
Investigation

 

operation: Post Tweet

Input parameters

 

Parameter Description
Status Status message text that you want to post on Twitter. The message text must be less than or equal to 280 characters.
Attachment IRI (Optional) Attachment IRI is use to access a file directly from the FortiSOAR™ Attachments module. If you want to attach a file as media to your tweet status then specify the Attachment IRI for the file in this field.
In the playbook, this defaults to the {{vars.attachment_id}} .
In Reply To Status ID (Optional) ID of an existing status to which you are posting the status message as a reply. Implicitly this sets the in_reply_to_user_id attribute of the resulting status to the user ID of the message being replied to. Invalid or missing status IDs will be ignored.
By default, this is set to False.
Auto Populate Reply Metadata (Optional) If you select this field, then @usernames of the users mentioned in or participating in the tweet are automatically included, to which this tweet that you want to post is a reply.
By default, this is set to False.
Exclude Reply User IDs (CSV /List format) (Optional) Used to remove given user_ids (not @usernames) from the tweet's automatically generated reply metadata.
Latitude (Optional) Latitude coordinate of the tweet in degrees. Works only in conjunction with longitude argument. Both longitude and latitude will be ignored by Twitter if you do not have the geo_enabled setting enabled, i.e., geo_enabled setting is set as false.
Longitude (Optional) Longitude coordinate of the tweet in degrees. Works only in conjunction with latitude argument. Both longitude and latitude will be ignored by Twitter if you do not have the geo_enabled setting enabled, i.e., geo_enabled setting is set as false.
Place ID (Optional) ID of a place in the world. Places are specific, named locations with corresponding geo coordinates.
Display Coordinates (Optional) If you select this field, a pin that displays the exact coordinates from where the tweet has been sent is included in the tweet.
By default, this is set to True.
Trim User (Optional) If you select this field, then the returned results will contains only the user IDs, otherwise the result returns the complete user details or the complete user object.
By default, this is set to False.
Verify Status Length (Optional) If you select this field, i.e., set this as True, then the API throws an error that the status message is over 280 characters. If this is set as False, then the API attempts to post the status message.
By default, this is set to True.
Attachment URL (Optional) URL to an attachment resource. You can specify the following types of attachment resources: one to four photos, a GIF, a video, a Quote Tweet, or a DM deep link.
If you do not specify anything in this field, then this parameter is set as None.
If a bad URL is passed then Twitter raises an error.

 

Output

The JSON output contains details of the responses after you have posted the status message.

Following image displays a sample output:

Sample output of the Post Tweet operation

operation: Send Direct Message

Input parameters

 

Parameter Description
Text Twitter direct message text that you want to send to a specified user from your authenticated Twitter account. You can specify a user either by the user's ID or the users screen name.
User ID ID of the user who should receive the direct message.
Important: You must specify either the User ID or the Screen Name of the user to whom you want to sent the direct message.
Screen Name Screen name of the user who should receive the direct message.

 

Output

The JSON output contains Twitter direct message details, sender details, and recipient details.

Following image displays a sample output:

Sample output of the Send Direct Message operation

operation: Search Tweets

Input parameters

 

Parameter Description
Term Term based on which you want to search for tweets.
Important: For the Search Tweets operation, you must specify either the Term or the Geocode.
Geocode Geo location within which you want to search for tweets. You can either specify a string value for this field, in form of latitude,longitude,radius, where latitude and longitude are float values and radius is a string value such as 1mi or 1km. Radius supports only mi or km units.
For example, 37.781157,-122.398720,1mi
Since ID (Optional) If you specify the Since ID, then this operation will return results with an ID greater than, i.e. more recent than, the specified ID.
There are limits to the number of Tweets which can be accessed using the API. If the limit of Tweets has been reached since the since_id, the since_id will be forced to the oldest ID available.
Max ID (Optional) If you specify the Max ID, then this operation will return results with an ID less than, i.e. older than, or equal to the specified ID.
Until (Optional) Datetime until which this operation will return tweets, i.e this operation will return tweets that have been generated till the specified datetime.
Since (Optional) Datetime after which this operation will return tweets, i.e this operation will return tweets that have been generated since specified datetime.
Count (Optional) Number of results this operation should return. Maximum number of Tweets that Twitter returns for this operation is 100 (irrespective of what you type in this field).
By default, this is set to 15.
Language (Optional) Language in which you want the results to be retrieved. You must specify the language in the ISO 639-1 code format. For example, en for English.
By default this is set to None (all languages).
Result Type (Optional) Type of result that this operation should return. You can choose from the following options: Mixed, Recent or Popular.
By default, this is set to Mixed.
Include Entities (Optional) If you select this field, i.e., set this as True, then each tweet that are included in the returned results includes a node called entities. The entities node contains contains a variety of metadata about the tweet in a discrete structure, including user_mentions, urls, and hashtags.
By default, this is set to True.

 

Output

The JSON output contains details the tweets retrieved from Twitter based on the term or geocode, and other input parameters you have specified.

Following image displays a sample output:

Sample output of the Search Tweets operation

operation: Get User

Input parameters

 

Parameter Description
User ID ID of the user whose details you want to retrieve from Twitter.
Important: You must specify either the User ID or the Screen Name of the user whose details you want to retrieve from Twitter.
Screen Name Screen name of the user whose details you want to retrieve from Twitter.
Include Entities (Optional) If you select this field, i.e., set this as True, then each tweet that are included in the returned results includes a node called entities. The entities node contains contains a variety of metadata about the tweet in a discrete structure, including user_mentions, urls, and hashtags.
By default, this is set to True.

 

Output

The JSON output contains details of the user retrieved from Twitter based on the user ID or screen name of the user that you have specified.

Following image displays a sample output:

Sample output of the Get User operation

operation: Get User Timeline

Input parameters

 

Parameter Description
User ID ID of the user whose timeline you want to retrieve from Twitter.
Important: You must specify either the User ID or the Screen Name of the user whose timeline you want to retrieve from Twitter.
Screen Name Screen name of the timeline whose timeline you want to retrieve from Twitter.
Since ID (Optional) If you specify the Since ID, then this operation will return results with an ID greater than, i.e. more recent than, the specified ID.
Max ID (Optional) If you specify the Max ID, then this operation will return results with an ID less than, i.e. older than, or equal to the specified ID.
Count (Optional) Number of results this operation should return. Maximum number of results that Twitter returns for this operation is 200 (irrespective of what you type in this field).
Include Retweets (Optional) If you select this field, i.e., set this as True, then the timeline will contain native retweets (if they exist) in addition to the standard stream of tweets.
By default, this is set to True.
Trim User (Optional) If you select this field, then the returned results will contains only the user IDs, otherwise the result returns the complete user details or the complete user object.
By default, this is set to False.
Exclude Replies (Optional) If you select this field, then replies will be excluded in the returned timeline.
By default, this is set to False.

 

Output

The JSON output contains details of the timeline for a specified user retrieved from Twitter, based on the user ID or screen name of the user and other input parameters that you have specified.

Following image displays a sample output:

Sample output of the Get User Timeline operation

Included playbooks

The Sample - Twitter - 1.0.0 playbook collection comes bundled with the Twitter connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Twitter connector.

  • Get User
  • Get User Timeline
  • Post Tweet
  • Search Tweets
  • Send Direct Message

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.

 

 

About the connector

Twitter is an online news and social networking service on which users post and interact with messages known as "tweets". Tweets are publicly visible by default, but senders can restrict message delivery to just their followers. Users can tweet using the Twitter website, compatible external applications (such as for smartphones), or by Short Message Service (SMS) available in certain countries. Users may subscribe to other users' tweets—this is known as "following" and subscribers are known as "followers" or "tweeps", a portmanteau of Twitter and peeps. Individual tweets can be forwarded by other users to their own feed, a process known as a "retweet". Users can also "like" (formerly "favorite") individual tweets.

This document provides information about the Twitter Connector, which facilitates automated interactions, with your Twitter account using FortiSOAR™ playbooks. Add the Twitter Connector, as a step in FortiSOAR™ playbooks and perform automated operations such as, posting tweets, searching tweets, and getting user details.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 4.10.3-161

Authored By: Fortinet

Certified: Yes

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

For the detailed procedure to install a connector, click here.

yum install cyops-connector-twitter

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the Twitter connector and click Configure to configure the following parameters.

Note: To create twitter application refer to the "How to create a Twitter application document" located at: http://docs.inboundnow.com/guide/create-twitter-application/. Using this document you will learn how you can get all the configuration keys and configure your Twitter application so that you can connect to your Twitter account using which you want to perform automated operations using the Twitter connector.

 

Parameter Description
Consumer Key Consumer Key of the Twitter application that you have configured.
Consumer Secret Consumer Secret of the Twitter application that you have configured.
Access Token Key Access Token Key of the Twitter application that you have configured.
Access Token Secret Access Token Secret of the Twitter application that you have configured.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Post Tweet Posts a Twitter status message from your authenticated Twitter account.  
Send Direct Message Posts a Twitter direct message to a specified user from your authenticated Twitter account. You can specify a user using either the user's ID or the user's screen name. send_direct_message
Investigation
Search Tweets Searches for Tweets based on the term or geocode, and other input parameters you have specified. search_tweets
Investigation
Get User Retrieves details of a specified Twitter user, based on the user ID or screen name of the user you have specified. get_user
Investigation
Get User Timeline Retrieves the sequence of Public Status messages for a specified Twitter user, based on the user ID or screen name of the user, and other input parameters you have specified. get_user_timeline
Investigation

 

operation: Post Tweet

Input parameters

 

Parameter Description
Status Status message text that you want to post on Twitter. The message text must be less than or equal to 280 characters.
Attachment IRI (Optional) Attachment IRI is use to access a file directly from the FortiSOAR™ Attachments module. If you want to attach a file as media to your tweet status then specify the Attachment IRI for the file in this field.
In the playbook, this defaults to the {{vars.attachment_id}} .
In Reply To Status ID (Optional) ID of an existing status to which you are posting the status message as a reply. Implicitly this sets the in_reply_to_user_id attribute of the resulting status to the user ID of the message being replied to. Invalid or missing status IDs will be ignored.
By default, this is set to False.
Auto Populate Reply Metadata (Optional) If you select this field, then @usernames of the users mentioned in or participating in the tweet are automatically included, to which this tweet that you want to post is a reply.
By default, this is set to False.
Exclude Reply User IDs (CSV /List format) (Optional) Used to remove given user_ids (not @usernames) from the tweet's automatically generated reply metadata.
Latitude (Optional) Latitude coordinate of the tweet in degrees. Works only in conjunction with longitude argument. Both longitude and latitude will be ignored by Twitter if you do not have the geo_enabled setting enabled, i.e., geo_enabled setting is set as false.
Longitude (Optional) Longitude coordinate of the tweet in degrees. Works only in conjunction with latitude argument. Both longitude and latitude will be ignored by Twitter if you do not have the geo_enabled setting enabled, i.e., geo_enabled setting is set as false.
Place ID (Optional) ID of a place in the world. Places are specific, named locations with corresponding geo coordinates.
Display Coordinates (Optional) If you select this field, a pin that displays the exact coordinates from where the tweet has been sent is included in the tweet.
By default, this is set to True.
Trim User (Optional) If you select this field, then the returned results will contains only the user IDs, otherwise the result returns the complete user details or the complete user object.
By default, this is set to False.
Verify Status Length (Optional) If you select this field, i.e., set this as True, then the API throws an error that the status message is over 280 characters. If this is set as False, then the API attempts to post the status message.
By default, this is set to True.
Attachment URL (Optional) URL to an attachment resource. You can specify the following types of attachment resources: one to four photos, a GIF, a video, a Quote Tweet, or a DM deep link.
If you do not specify anything in this field, then this parameter is set as None.
If a bad URL is passed then Twitter raises an error.

 

Output

The JSON output contains details of the responses after you have posted the status message.

Following image displays a sample output:

Sample output of the Post Tweet operation

operation: Send Direct Message

Input parameters

 

Parameter Description
Text Twitter direct message text that you want to send to a specified user from your authenticated Twitter account. You can specify a user either by the user's ID or the users screen name.
User ID ID of the user who should receive the direct message.
Important: You must specify either the User ID or the Screen Name of the user to whom you want to sent the direct message.
Screen Name Screen name of the user who should receive the direct message.

 

Output

The JSON output contains Twitter direct message details, sender details, and recipient details.

Following image displays a sample output:

Sample output of the Send Direct Message operation

operation: Search Tweets

Input parameters

 

Parameter Description
Term Term based on which you want to search for tweets.
Important: For the Search Tweets operation, you must specify either the Term or the Geocode.
Geocode Geo location within which you want to search for tweets. You can either specify a string value for this field, in form of latitude,longitude,radius, where latitude and longitude are float values and radius is a string value such as 1mi or 1km. Radius supports only mi or km units.
For example, 37.781157,-122.398720,1mi
Since ID (Optional) If you specify the Since ID, then this operation will return results with an ID greater than, i.e. more recent than, the specified ID.
There are limits to the number of Tweets which can be accessed using the API. If the limit of Tweets has been reached since the since_id, the since_id will be forced to the oldest ID available.
Max ID (Optional) If you specify the Max ID, then this operation will return results with an ID less than, i.e. older than, or equal to the specified ID.
Until (Optional) Datetime until which this operation will return tweets, i.e this operation will return tweets that have been generated till the specified datetime.
Since (Optional) Datetime after which this operation will return tweets, i.e this operation will return tweets that have been generated since specified datetime.
Count (Optional) Number of results this operation should return. Maximum number of Tweets that Twitter returns for this operation is 100 (irrespective of what you type in this field).
By default, this is set to 15.
Language (Optional) Language in which you want the results to be retrieved. You must specify the language in the ISO 639-1 code format. For example, en for English.
By default this is set to None (all languages).
Result Type (Optional) Type of result that this operation should return. You can choose from the following options: Mixed, Recent or Popular.
By default, this is set to Mixed.
Include Entities (Optional) If you select this field, i.e., set this as True, then each tweet that are included in the returned results includes a node called entities. The entities node contains contains a variety of metadata about the tweet in a discrete structure, including user_mentions, urls, and hashtags.
By default, this is set to True.

 

Output

The JSON output contains details the tweets retrieved from Twitter based on the term or geocode, and other input parameters you have specified.

Following image displays a sample output:

Sample output of the Search Tweets operation

operation: Get User

Input parameters

 

Parameter Description
User ID ID of the user whose details you want to retrieve from Twitter.
Important: You must specify either the User ID or the Screen Name of the user whose details you want to retrieve from Twitter.
Screen Name Screen name of the user whose details you want to retrieve from Twitter.
Include Entities (Optional) If you select this field, i.e., set this as True, then each tweet that are included in the returned results includes a node called entities. The entities node contains contains a variety of metadata about the tweet in a discrete structure, including user_mentions, urls, and hashtags.
By default, this is set to True.

 

Output

The JSON output contains details of the user retrieved from Twitter based on the user ID or screen name of the user that you have specified.

Following image displays a sample output:

Sample output of the Get User operation

operation: Get User Timeline

Input parameters

 

Parameter Description
User ID ID of the user whose timeline you want to retrieve from Twitter.
Important: You must specify either the User ID or the Screen Name of the user whose timeline you want to retrieve from Twitter.
Screen Name Screen name of the timeline whose timeline you want to retrieve from Twitter.
Since ID (Optional) If you specify the Since ID, then this operation will return results with an ID greater than, i.e. more recent than, the specified ID.
Max ID (Optional) If you specify the Max ID, then this operation will return results with an ID less than, i.e. older than, or equal to the specified ID.
Count (Optional) Number of results this operation should return. Maximum number of results that Twitter returns for this operation is 200 (irrespective of what you type in this field).
Include Retweets (Optional) If you select this field, i.e., set this as True, then the timeline will contain native retweets (if they exist) in addition to the standard stream of tweets.
By default, this is set to True.
Trim User (Optional) If you select this field, then the returned results will contains only the user IDs, otherwise the result returns the complete user details or the complete user object.
By default, this is set to False.
Exclude Replies (Optional) If you select this field, then replies will be excluded in the returned timeline.
By default, this is set to False.

 

Output

The JSON output contains details of the timeline for a specified user retrieved from Twitter, based on the user ID or screen name of the user and other input parameters that you have specified.

Following image displays a sample output:

Sample output of the Get User Timeline operation

Included playbooks

The Sample - Twitter - 1.0.0 playbook collection comes bundled with the Twitter connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Twitter connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.