

Twitter Connector Reference¶

The following operations allow you to work with the Twitter Connector. Click an operation name to see parameter details and samples on how to use it.

Initialize the connector¶

To use the Twitter connector, add the <twitter.init> element in your configuration before carrying out any other Twitter operations.

twitter.init

The twitter.init operation initializes the connector to interact with the Twitter API. See the related API documentation for more information.

Parameter Name	Type	Required	Description
accessToken	String	Yes if the refresh token is not present	The access token of the OAuth 2.0 Twitter app. Not to be mistaken with the OAuth 1.0 access token.
refreshToken	String	Yes if the access token is not present	The refresh token of the OAuth 2.0 Twitter app. Not to be mistaken with the OAuth 1.0 refresh token.
clientId	String	Yes	User Id that allows you to use OAuth 2.0 as an authentication method.
apiUrl	String	No, the default value is https://api.twitter.com	The URL of the Twitter REST API.
timeout	Integer	No, the default value is 5000	Timeout duration of the API request.

Sample configuration

<twitter.init>
    <clientId>{$ctx:clientId}</clientId>
    <accessToken>{$ctx:accessToken}</accessToken>
    <refreshToken>{$ctx:refreshToken}</refreshToken>
    <apiUrl>{$ctx:apiUrl}</apiUrl>
    <timeout>{$ctx:timeout}</timeout>
</twitter.init>

Sample request

<twitter.init>
    <clientId>"rG9n6402A3dbUJKzXTNX4oWHJ"</clientId>
    <accessToken>"MFpJRmFlbGJTZHVDdkNIbDN4WURTYTFiUmZtRV9HckdsUmlmd1ZxVjRvWHVUOjE2ODY1NDIwMjM5MTk6MTowOmF0OjE"</accessToken>
    <refreshToken>"bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE"</refreshToken>
</twitter.init>

Working with Tweets¶

The following operations allow you to work with tweets. To be authorized for the following endpoints, you will need an access token with the correct scopes. Please refer the Twitter authentication map to get the required scopes for the access token.

createTweet

The twitter.createTweet method creates a Tweet. See the related API documentation for more information.

Parameter Name	Type	Required	Description
text	String	Yes if media field is not present	The text of your Tweet. Up to 280 characters are permitted.
direct_message_deep_link	String	No	Tweets a link directly to a Direct Message conversation with an account.
for_super_followers_only	Boolean	No	Allows you to Tweet exclusively for Super Followers.
geo	JSON Object	No	A JSON object that contains location information for a Tweet. You can only add a location to Tweets if you have geo enabled in your profile settings. If you don't have geo enabled, you can still add a location parameter in your request body, but it won't get attached to your Tweet.
media	JSON Object	No	A JSON object that contains media information being attached to created Tweet. This is mutually exclusive from Quote Tweet ID and Poll.
poll	JSON Object	No	A JSON object that contains options for a Tweet with a poll. This is mutually exclusive from Media and Quote Tweet ID.
quote_tweet_id	String	No	Link to the Tweet being quoted.
reply	JSON Object	No	A JSON object that contains information of the Tweet being replied to.
reply_settings	String	No	Settings to indicate who can reply to the Tweet. Valid values are: `mentionedUsers, following`. If the field isn’t specified, it will default to everyone.

Sample configuration

<twitter.createTweet>
    <text>{$ctx:text}</text>
    <direct_message_deep_link>{$ctx:direct_message_deep_link}</direct_message_deep_link>
    <for_super_followers_only>{$ctx:for_super_followers_only}</for_super_followers_only>
    <geo>{$ctx:geo}</geo>
    <media>{$ctx:media}</media>
    <poll>{$ctx:poll}</poll>
    <quote_tweet_id>{$ctx:quote_tweet_id}</quote_tweet_id>
    <reply>{$ctx:reply}</reply>
    <reply_settings>{$ctx:reply_settings}</reply_settings>
</twitter.createTweet>

Sample request

Given below is a sample request that can be handled by the createTweet operation.

<twitter.createTweet>
    <text>"Hello World!"</text>
    <for_super_followers_only>true</for_super_followers_only>
    <poll>{"options": ["yes", "maybe", "no"], "duration_minutes": 120}</poll>
    <reply>{"in_reply_to_tweet_id": "1455953449422516226", "exclude_reply_user_ids": ["6253282"]}</reply>
    <reply_settings>"mentionedUsers"</reply_settings>
</twitter.createTweet>

Sample response

Given below is a sample response for the createTweet operation.

{
   "data": {
      "edit_history_tweet_ids": [
         "1667035675894640640"
      ],
      "id": "1667035675894640640",
      "text": "Hello World!"
   }
}

deleteTweet

The twitter.deleteTweet method deletes a Tweet when given the Tweet ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The Tweet ID you are deleting.

Sample configuration

<twitter.deleteTweet>
    <id>{$ctx:id}</id>
</twitter.deleteTweet>

Sample request

Given below is a sample request that can be handled by the deleteTweet operation.

<twitter.deleteTweet>
    <id>"1667035675894640640"</id>
</twitter.deleteTweet>

Sample response

Given below is a sample response for the deleteTweet operation.

{
    "data": {
        "deleted": true
    }
}

getTweetById

The twitter.getTweetById method retrieves information about a single Tweet specified by the requested ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	Unique identifier of the Tweet to request.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned Tweets. Submit a list of desired expansions in a comma-separated list without spaces. The ID that represents the expanded data object will be included directly in the Tweet data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `attachments.poll_ids, attachments.media_keys, author_id, edit_history_tweet_ids, entities.mentions.username, geo.place_id, in_reply_to_user_id, referenced_tweets.id, referenced_tweets.id.author_id`.
media_fields	String	No	This fields parameter enables you to select which specific media fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return media fields if the Tweet contains media and if you've also included the expansions=attachments.media_keys query parameter in your request. While the media ID will be located in the Tweet object, you will find this ID and all additional media fields in the includes data object. Valid values for this parameter are: `duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, non_public_metrics, organic_metrics, promoted_metrics, alt_text, variants`
place_fields	String	No	This fields parameter enables you to select which specific place fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The response will contain the selected fields only if you've also included the expansions=geo.place_id query parameter in your request. Valid values for this parameter are: `contained_within, country, country_code, full_name, geo, id, name, place_type`.
poll_fields	String	No	This fields parameter enables you to select which specific poll fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return poll fields if the Tweet contains a poll and if you've also included the expansions=attachments.poll_ids query parameter in your request. While the poll ID will be located in the Tweet object, you will find this ID and all additional poll fields in the includes data object. Valid values for this parameter are: `duration_minutes, end_datetime, id, options, voting_status`.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned Tweet object. Specify the desired fields in a comma-separated list without spaces between commas and fields. You can also pass the expansions=referenced_tweets.id expansion to return the specified fields for both the original Tweet and any included referenced Tweets. The requested Tweet fields will display in both the original Tweet data object, as well as in the referenced Tweet expanded data object that will be located in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the user ID will be located in the original Tweet object, you will find this ID and all additional user fields in the includes data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getTweetById>
    <id>{$ctx:id}</id>
    <expansions>{$ctx:expansions}</expansions>
    <media_fields>{$ctx:media_fields}</media_fields>
    <place_fields>{$ctx:place_fields}</place_fields>
    <poll_fields>{$ctx:poll_fields}</poll_fields>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getTweetById>

Sample request

Given below is a sample request that can be handled by the getTweetById operation.

<twitter.getTweetById>
    <id>"1460323737035677698"</id>
    <expansions>"attachments.media_keys,author_id"</expansions>
    <media_fields>"duration_ms,media_key"</media_fields>
    <tweet_fields>"lang"</tweet_fields>
</twitter.getTweetById>

Sample response

Given below is a sample response for the getTweetById operation.

{
    "data": {
        "lang": "en",
        "author_id": "2244994945",
        "text": "Introducing a new era for the Twitter Developer Platform! \n\n The Twitter API v2 is now the primary API and full of new features\n⏱Immediate access for most use cases, or apply to get more access for free",
        "attachments": {
            "media_keys": [
                "7_1460322142680072196"
            ]
        },
        "id": "1460323737035677698",
        "edit_history_tweet_ids": [
            "1460323737035677698"
        ]
    }
}

getTweetsLookup

The twitter.getTweetsLookup method retrieves information about one or more Tweets specified by the requested IDs. See the related API documentation for more information.

Parameter Name	Type	Required	Description
ids	String	Yes	A comma separated list of Tweet IDs. Up to 100 are allowed in a single request. Make sure to not include a space between commas and fields.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned Tweets. Submit a list of desired expansions in a comma-separated list without spaces. The ID that represents the expanded data object will be included directly in the Tweet data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `attachments.poll_ids, attachments.media_keys, author_id, edit_history_tweet_ids, entities.mentions.username, geo.place_id, in_reply_to_user_id, referenced_tweets.id, referenced_tweets.id.author_id`.
media_fields	String	No	This fields parameter enables you to select which specific media fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return media fields if the Tweet contains media and if you've also included the expansions=attachments.media_keys query parameter in your request. While the media ID will be located in the Tweet object, you will find this ID and all additional media fields in the includes data object. Valid values for this parameter are: `duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, non_public_metrics, organic_metrics, promoted_metrics, alt_text, variants`
place_fields	String	No	This fields parameter enables you to select which specific place fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The response will contain the selected fields only if you've also included the expansions=geo.place_id query parameter in your request. Valid values for this parameter are: `contained_within, country, country_code, full_name, geo, id, name, place_type`.
poll_fields	String	No	This fields parameter enables you to select which specific poll fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return poll fields if the Tweet contains a poll and if you've also included the expansions=attachments.poll_ids query parameter in your request. While the poll ID will be located in the Tweet object, you will find this ID and all additional poll fields in the includes data object. Valid values for this parameter are: `duration_minutes, end_datetime, id, options, voting_status`.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned Tweet object. Specify the desired fields in a comma-separated list without spaces between commas and fields. You can also pass the expansions=referenced_tweets.id expansion to return the specified fields for both the original Tweet and any included referenced Tweets. The requested Tweet fields will display in both the original Tweet data object, as well as in the referenced Tweet expanded data object that will be located in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the user ID will be located in the original Tweet object, you will find this ID and all additional user fields in the includes data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getTweetsLookup>
    <ids>{$ctx:ids}</ids>
    <expansions>{$ctx:expansions}</expansions>
    <media_fields>{$ctx:media_fields}</media_fields>
    <place_fields>{$ctx:place_fields}</place_fields>
    <poll_fields>{$ctx:poll_fields}</poll_fields>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getTweetsLookup>

Sample request

Given below is a sample request that can be handled by the getTweetsLookup operation.

<twitter.getTweetsLookup>
    <ids>"1460323737035677698,1519781379172495360,1519781381693353984"</ids>
    <expansions>"attachments.poll_ids,author_id"</expansions>
    <poll_fields>"duration_minutes"</poll_fields>
</twitter.getTweetsLookup>

Sample response

Given below is a sample response for the getTweetsLookup operation.

{
    "data": [
        {
            "text": "Introducing a new era for the Twitter Developer Platform! \n\n📣The Twitter API v2 is now the primary API and full of new features\n⏱Immediate access for most use cases, or apply to get more access for free\n📖Removed certain restrictions in the Policy\nhttps://t.co/Hrm15bkBWJ https://t.co/YFfCDErHsg",
            "edit_history_tweet_ids": [
                "1460323737035677698"
            ],
            "id": "1460323737035677698",
            "lang": "en",
            "author_id": "2244994945"
        },
        {
            "text": "Our mission remains just as important as ever: to deliver an open platform that serves the public conversation. We’re continuing to innovate on the Twitter API v2 and invest in our developer community 🧵\n\nhttps://t.co/Rug1l46sUc",
            "edit_history_tweet_ids": [
                "1519781379172495360"
            ],
            "id": "1519781379172495360",
            "lang": "en",
            "author_id": "2244994945"
        },
        {
            "text": "Catch up on recent launches and build with the core elements of the Twitter experience:\n🔖 New Bookmarks endpoints\n💬 New Quote Tweets lookup endpoints\n🔼 New sort_order parameter on search endpoints, and improvements to the Likes and Retweets endpoints",
            "edit_history_tweet_ids": [
                "1519781381693353984"
            ],
            "id": "1519781381693353984",
            "lang": "en",
            "author_id": "2244994945"
        }
    ]
}

searchTweets

The twitter.searchTweets method retrieves a collection of tweets that meet the specified search criteria. See the related API documentation for more information.

Parameter Name	Type	Required	Description
query	String	Yes	Query for matching Tweets. For more info check Twitter query guide.
start_time	String	No	`YYYY-MM-DDTHH:mm:ssZ` (ISO 8601/RFC 3339). The oldest UTC timestamp (from most recent seven days) from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). If included with the same request as a since_id parameter, only since_id will be used. By default, a request will return Tweets from up to seven days ago if you do not include this parameter.
end_time	String	No	`YYYY-MM-DDTHH:mm:ssZ` (ISO 8601/RFC 3339). The newest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in second granularity and is exclusive (for example, 12:00:01 excludes the first second of the minute). By default, a request will return Tweets from as recent as 30 seconds ago if you do not include this parameter.
since_id	String	No	Returns results with a Tweet ID greater than (that is, more recent than) the specified ID. The ID specified is exclusive and responses will not include it. If included with the same request as a start_time parameter, only since_id will be used.
sort_order	String	No	This parameter is used to specify the order in which you want the Tweets returned. By default, a request will return the most recent Tweets first (sorted by recency). se object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `recency, relevancy`
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
next_token	String	No	This parameter is used to get the next 'page' of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned Tweets. Submit a list of desired expansions in a comma-separated list without spaces. The ID that represents the expanded data object will be included directly in the Tweet data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `attachments.poll_ids, attachments.media_keys, author_id, edit_history_tweet_ids, entities.mentions.username, geo.place_id, in_reply_to_user_id, referenced_tweets.id, referenced_tweets.id.author_id`.
media_fields	String	No	This fields parameter enables you to select which specific media fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return media fields if the Tweet contains media and if you've also included the expansions=attachments.media_keys query parameter in your request. While the media ID will be located in the Tweet object, you will find this ID and all additional media fields in the includes data object. Valid values for this parameter are: `duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, non_public_metrics, organic_metrics, promoted_metrics, alt_text, variants`
place_fields	String	No	This fields parameter enables you to select which specific place fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The response will contain the selected fields only if you've also included the expansions=geo.place_id query parameter in your request. Valid values for this parameter are: `contained_within, country, country_code, full_name, geo, id, name, place_type`.
poll_fields	String	No	This fields parameter enables you to select which specific poll fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return poll fields if the Tweet contains a poll and if you've also included the expansions=attachments.poll_ids query parameter in your request. While the poll ID will be located in the Tweet object, you will find this ID and all additional poll fields in the includes data object. Valid values for this parameter are: `duration_minutes, end_datetime, id, options, voting_status`.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned Tweet object. Specify the desired fields in a comma-separated list without spaces between commas and fields. You can also pass the expansions=referenced_tweets.id expansion to return the specified fields for both the original Tweet and any included referenced Tweets. The requested Tweet fields will display in both the original Tweet data object, as well as in the referenced Tweet expanded data object that will be located in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the user ID will be located in the original Tweet object, you will find this ID and all additional user fields in the includes data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.searchTweets>
    <query>{$ctx:query}</query>
    <start_time>{$ctx:start_time}</start_time>
    <end_time>{$ctx:end_time}</end_time>
    <since_id>{$ctx:since_id}</since_id>
    <until_id>{$ctx:until_id}</until_id>
    <sort_order>{$ctx:sort_order}</sort_order>
    <max_results>{$ctx:max_results}</max_results>
    <next_token>{$ctx:next_token}</next_token>
    <expansions>{$ctx:expansions}</expansions>
    <media_fields>{$ctx:media_fields}</media_fields>
    <place_fields>{$ctx:place_fields}</place_fields>
    <poll_fields>{$ctx:poll_fields}</poll_fields>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.searchTweets>

Sample request

Given below is a sample request that can be handled by the searchTweets operation.

<twitter.searchTweets>
    <query>"(from:TwitterDev) new -is:retweet"</query>
    <start_time>"2020-01-01T00:00:00Z"</start_time>
    <sort_order>"recency"</sort_order>
    <max_results>10</max_results>
    <tweet_fields>"created_at,lang,conversation_id"</tweet_fields>
</twitter.searchTweets>

Sample response

Given below is a sample response for the searchTweets operation.

{
    "data": [
        {
            "text": "Looking to get started with the Twitter API but new to APIs in general? @jessicagarson will walk you through everything you need to know in APIs 101 session. She’ll use examples using our v2 endpoints, Tuesday, March 23rd at 1 pm EST.",
            "author_id": "2244994945",
            "id": "1373001119480344583",
            "edit_history_tweet_ids": [
                "1373001119480344583"
            ],
            "lang": "en",
            "conversation_id": "1373001119480344583",
            "created_at": "2021-03-19T19:59:10.000Z"
        }
    ],
}

likeTweet

The twitter.likeTweet method likes a tweet. See the related API documentation for more information.

Parameter Name	Type	Required	Description
user_id	String	Yes	The user ID who you are liking a Tweet on behalf of.
tweet_id	String	Yes	The ID of the Tweet that you would give a Like.

Sample configuration

<twitter.likeTweet>
    <user_id>{$ctx:user_id}</user_id>
    <tweet_id>{$ctx:tweet_id}</tweet_id>
</twitter.likeTweet>

Sample request

Given below is a sample request that can be handled by the likeTweet operation.

<twitter.likeTweet>
    <user_id>"1655515285577936899"</user_id>
    <tweet_id>"1521887626935947265"</tweet_id>
</twitter.likeTweet>

Sample response

Given below is a sample response for the likeTweet operation.

{
    "data": {
        "liked": true
    }
}

unlikeTweet

The twitter.unlikeTweet method unlikes a tweet. See the related API documentation for more information.

Parameter Name	Type	Required	Description
user_id	String	Yes	The user ID who you are unliking a Tweet on behalf of.
tweet_id	String	Yes	The ID of the Tweet that you would unlike.

Sample configuration

<twitter.unlikeTweet>
    <user_id>{$ctx:user_id}</user_id>
    <tweet_id>{$ctx:tweet_id}</tweet_id>
</twitter.unlikeTweet>

Sample request

Given below is a sample request that can be handled by the unlikeTweet operation.

<twitter.unlikeTweet>
    <user_id>"1655515285577936899"</user_id>
    <tweet_id>"1521887626935947265"</tweet_id>
</twitter.unlikeTweet>

Sample response

Given below is a sample response for the unlikeTweet operation.

{
    "data": {
        "liked": false
    }
}

getLikedTweetsList

The twitter.getLikedTweetsList method retrieves a list of liked Tweets of the specified user ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	User ID of the user to request liked Tweets for.
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token	String	No	Used to request the next page of results if all results weren't returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned Tweets. Submit a list of desired expansions in a comma-separated list without spaces. The ID that represents the expanded data object will be included directly in the Tweet data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `attachments.poll_ids, attachments.media_keys, author_id, edit_history_tweet_ids, entities.mentions.username, geo.place_id, in_reply_to_user_id, referenced_tweets.id, referenced_tweets.id.author_id`.
media_fields	String	No	This fields parameter enables you to select which specific media fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return media fields if the Tweet contains media and if you've also included the expansions=attachments.media_keys query parameter in your request. While the media ID will be located in the Tweet object, you will find this ID and all additional media fields in the includes data object. Valid values for this parameter are: `duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, non_public_metrics, organic_metrics, promoted_metrics, alt_text, variants`
place_fields	String	No	This fields parameter enables you to select which specific place fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The response will contain the selected fields only if you've also included the expansions=geo.place_id query parameter in your request. Valid values for this parameter are: `contained_within, country, country_code, full_name, geo, id, name, place_type`.
poll_fields	String	No	This fields parameter enables you to select which specific poll fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return poll fields if the Tweet contains a poll and if you've also included the expansions=attachments.poll_ids query parameter in your request. While the poll ID will be located in the Tweet object, you will find this ID and all additional poll fields in the includes data object. Valid values for this parameter are: `duration_minutes, end_datetime, id, options, voting_status`.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned Tweet object. Specify the desired fields in a comma-separated list without spaces between commas and fields. You can also pass the expansions=referenced_tweets.id expansion to return the specified fields for both the original Tweet and any included referenced Tweets. The requested Tweet fields will display in both the original Tweet data object, as well as in the referenced Tweet expanded data object that will be located in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the user ID will be located in the original Tweet object, you will find this ID and all additional user fields in the includes data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getLikedTweetsList>
    <id>{$ctx:id}</id>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <expansions>{$ctx:expansions}</expansions>
    <media_fields>{$ctx:media_fields}</media_fields>
    <place_fields>{$ctx:place_fields}</place_fields>
    <poll_fields>{$ctx:poll_fields}</poll_fields>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getLikedTweetsList>

Sample request

Given below is a sample request that can be handled by the getLikedTweetsList operation.

<twitter.getLikedTweetsList>
    <id>"1655515285577936899"</id>
    <max_results>10</max_results>
</twitter.getLikedTweetsList>

Sample response

Given below is a sample response for the getLikedTweetsList operation.

{
    "data": [
        {
            "edit_history_tweet_ids": [
                "1519781381693353984"
            ],
            "id": "1519781381693353984",
            "text": "Catch up on recent launches and build with the core elements of the Twitter experience:\nð New Bookmarks endpoints\nð¬ New Quote Tweets lookup endpoints\nð¼ New sort_order parameter on search endpoints, and improvements to the Likes and Retweets endpoints"
        },
        {
            "edit_history_tweet_ids": [
                "1519781379172495360"
            ],
            "id": "1519781379172495360",
            "text": "Our mission remains just as important as ever: to deliver an open platform that serves the public conversation. Weâre continuing to innovate on the Twitter API v2 and invest in our developer community ð§µ\n\nhttps://t.co/Rug1l46sUc"
        },
        {
            "edit_history_tweet_ids": [
                "1460323737035677698"
            ],
            "id": "1460323737035677698",
            "text": "Introducing a new era for the Twitter Developer Platform! \n\nð£The Twitter API v2 is now the primary API and full of new features\nâ±Immediate access for most use cases, or apply to get more access for free\nðRemoved certain restrictions in the Policy\nhttps://t.co/Hrm15bkBWJ https://t.co/YFfCDErHsg"
        }
    ],
    "meta": {
        "result_count": 3,
        "next_token": "7140dibdnow9c7btw482mq8hweo1bqos2tvjtvo5vftx2"
    }
}

createRetweet

The twitter.createRetweet method retweets a Tweet. See the related API documentation for more information.

Parameter Name	Type	Required	Description
user_id	String	Yes	The user ID who you are Retweeting a Tweet on behalf of.
tweet_id	String	Yes	The ID of the Tweet that you would like to Retweet.

Sample configuration

<twitter.createRetweet>
    <user_id>{$ctx:user_id}</user_id>
    <tweet_id>{$ctx:tweet_id}</tweet_id>
</twitter.createRetweet>

Sample request

Given below is a sample request that can be handled by the createRetweet operation.

<twitter.createRetweet>
    <user_id>"1655515285577936899"</user_id>
    <tweet_id>"1519781381693353984"</tweet_id>
</twitter.createRetweet>

Sample response

Given below is a sample response for the createRetweet operation.

{
    "data": {
        "retweeted": true
    }
}

getUserHomeTimeline

The twitter.getUserHomeTimeline method retrieves a collection of the most recent Tweets and Retweets posted by you and users you follow. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	Unique identifier of the user that is requesting their chronological home timeline.
start_time	String	No	`YYYY-MM-DDTHH:mm:ssZ` (ISO 8601/RFC 3339). The oldest UTC timestamp (from most recent seven days) from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). If included with the same request as a since_id parameter, only since_id will be used. By default, a request will return Tweets from up to seven days ago if you do not include this parameter.
end_time	String	No	`YYYY-MM-DDTHH:mm:ssZ` (ISO 8601/RFC 3339). The newest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in second granularity and is exclusive (for example, 12:00:01 excludes the first second of the minute). By default, a request will return Tweets from as recent as 30 seconds ago if you do not include this parameter.
since_id	String	No	Returns results with a Tweet ID greater than (that is, more recent than) the specified ID. The ID specified is exclusive and responses will not include it. If included with the same request as a start_time parameter, only since_id will be used.
until_id	String	No	Returns results with a Tweet ID less than (that is, older than) the specified 'until' Tweet ID. There are limits to the number of Tweets that can be accessed through the API. If the limit of Tweets has occurred since the until_id, the until_id will be forced to the most recent ID available.
sort_order	String	No	This parameter is used to specify the order in which you want the Tweets returned. By default, a request will return the most recent Tweets first (sorted by recency). se object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `recency, relevancy`
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token	String	No	This parameter is used to move forwards or backwards through 'pages' of results, based on the value of the next_token or previous_token in the response. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
exclude	String	No	Comma-separated list of the types of Tweets to exclude from the response. Valid values for this parameter are: `retweets, replies`
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned Tweets. Submit a list of desired expansions in a comma-separated list without spaces. The ID that represents the expanded data object will be included directly in the Tweet data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `attachments.poll_ids, attachments.media_keys, author_id, edit_history_tweet_ids, entities.mentions.username, geo.place_id, in_reply_to_user_id, referenced_tweets.id, referenced_tweets.id.author_id`.
media_fields	String	No	This fields parameter enables you to select which specific media fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return media fields if the Tweet contains media and if you've also included the expansions=attachments.media_keys query parameter in your request. While the media ID will be located in the Tweet object, you will find this ID and all additional media fields in the includes data object. Valid values for this parameter are: `duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, non_public_metrics, organic_metrics, promoted_metrics, alt_text, variants`
place_fields	String	No	This fields parameter enables you to select which specific place fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The response will contain the selected fields only if you've also included the expansions=geo.place_id query parameter in your request. Valid values for this parameter are: `contained_within, country, country_code, full_name, geo, id, name, place_type`.
poll_fields	String	No	This fields parameter enables you to select which specific poll fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return poll fields if the Tweet contains a poll and if you've also included the expansions=attachments.poll_ids query parameter in your request. While the poll ID will be located in the Tweet object, you will find this ID and all additional poll fields in the includes data object. Valid values for this parameter are: `duration_minutes, end_datetime, id, options, voting_status`.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned Tweet object. Specify the desired fields in a comma-separated list without spaces between commas and fields. You can also pass the expansions=referenced_tweets.id expansion to return the specified fields for both the original Tweet and any included referenced Tweets. The requested Tweet fields will display in both the original Tweet data object, as well as in the referenced Tweet expanded data object that will be located in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the user ID will be located in the original Tweet object, you will find this ID and all additional user fields in the includes data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getUserHomeTimeline>
    <id>{$ctx:id}</id>
    <start_time>{$ctx:start_time}</start_time>
    <end_time>{$ctx:end_time}</end_time>
    <since_id>{$ctx:since_id}</since_id>
    <until_id>{$ctx:until_id}</until_id>
    <sort_order>{$ctx:sort_order}</sort_order>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <exclude>{$ctx:exclude}</exclude>
    <expansions>{$ctx:expansions}</expansions>
    <media_fields>{$ctx:media_fields}</media_fields>
    <place_fields>{$ctx:place_fields}</place_fields>
    <poll_fields>{$ctx:poll_fields}</poll_fields>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getUserHomeTimeline>

Sample request

Given below is a sample request that can be handled by the getUserHomeTimeline operation.

<twitter.getUserHomeTimeline>
    <id>"1655515285577936899"</id>
    <start_time>"2020-01-01T00:00:00Z"</start_time>
    <max_results>10</max_results>
    <tweet_fields>"created_at,lang,conversation_id"</tweet_fields>
</twitter.getUserHomeTimeline>

Sample response

Given below is a sample response for the getUserHomeTimeline operation.

{
    "data": [
        {
            "created_at": "2022-05-12T17:00:00.000Z",
            "text": "Today marks the launch of Devs in the Details, a technical video series made for developers by developers building with the Twitter API.  ðnnIn this premiere episode, @jessicagarson walks us through how she built @FactualCat #WelcomeToOurTechTalknâ¬ï¸nnhttps://t.co/nGa8JTQVBJ",
            "author_id": "2244994945",
            "edit_history_tweet_ids": [
                "1524796546306478083"
            ],
            "id": "1524796546306478083"
        },
        {
            "created_at": "2022-05-11T19:16:40.000Z",
            "text": "ð¢ Join @jessicagarson @alanbenlee and @i_am_daniele tomorrow, May 12  | 5:30 ET / 2:30pm PT as they discuss the future of bots https://t.co/sQ2bIO1fz6",
            "author_id": "2244994945",
            "edit_history_tweet_ids": [
                "1524468552404668416"
            ],
            "id": "1524468552404668416"
        },
        {
            "created_at": "2022-05-09T20:12:01.000Z",
            "text": "Do you make bots with the Twitter API? ð¤nnJoin @jessicagarson @alanbenlee and @iamdaniele on Thursday, May 12  | 5:30 ET / 2:30pm PT as they discuss the future of bots and answer any questions you might have. ððâ¬ï¸nnhttps://t.co/2uVt7hCcdG",
            "author_id": "2244994945",
            "edit_history_tweet_ids": [
                "1523757705436958720"
            ],
            "id": "1523757705436958720"
        },
        {
            "created_at": "2022-05-06T18:19:54.000Z",
            "text": "If youâd like to apply, or would like to nominate someone else for the program, please feel free to fill out the following form:nnhttps://t.co/LUuWj24HLu",
            "author_id": "2244994945",
            "edit_history_tweet_ids": [
                "1522642324781633536"
            ],
            "id": "1522642324781633536"
        },
        {
            "created_at": "2022-05-06T18:19:53.000Z",
            "text": "Weâve gone into more detail on each Insider in our forum post. nnJoin us in congratulating the new additions! ð¥³nnhttps://t.co/0r5maYEjPJ",
            "author_id": "2244994945",
            "edit_history_tweet_ids": [
                "1522642323535847424"
            ],
            "id": "1522642323535847424"
        }
    ],
    "includes": {
        "users": [
            {
                "created_at": "2013-12-14T04:35:55.000Z",
                "name": "Twitter Dev",
                "username": "TwitterDev",
                "id": "2244994945"
            }
        ]
    },
    "meta": {
        "result_count": 5,
        "newest_id": "1524796546306478083",
        "oldest_id": "1522642323535847424",
        "next_token": "7140dibdnow9c7btw421dyz6jism75z99gyxd8egarsc4"
    }
}

getUserMentionsTimeline

The twitter.getUserMentionsTimeline method retrieves Tweets mentioning a single user specified by the requested user ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	Unique identifier of the user for whom to return Tweets mentioning the user.
start_time	String	No	`YYYY-MM-DDTHH:mm:ssZ` (ISO 8601/RFC 3339). The oldest UTC timestamp (from most recent seven days) from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). If included with the same request as a since_id parameter, only since_id will be used. By default, a request will return Tweets from up to seven days ago if you do not include this parameter.
end_time	String	No	`YYYY-MM-DDTHH:mm:ssZ` (ISO 8601/RFC 3339). The newest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in second granularity and is exclusive (for example, 12:00:01 excludes the first second of the minute). By default, a request will return Tweets from as recent as 30 seconds ago if you do not include this parameter.
since_id	String	No	Returns results with a Tweet ID greater than (that is, more recent than) the specified ID. The ID specified is exclusive and responses will not include it. If included with the same request as a start_time parameter, only since_id will be used.
until_id	String	No	Returns results with a Tweet ID less than (that is, older than) the specified 'until' Tweet ID. There are limits to the number of Tweets that can be accessed through the API. If the limit of Tweets has occurred since the until_id, the until_id will be forced to the most recent ID available.
sort_order	String	No	This parameter is used to specify the order in which you want the Tweets returned. By default, a request will return the most recent Tweets first (sorted by recency). se object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `recency, relevancy`
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token	String	No	This parameter is used to move forwards or backwards through 'pages' of results, based on the value of the next_token or previous_token in the response. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned Tweets. Submit a list of desired expansions in a comma-separated list without spaces. The ID that represents the expanded data object will be included directly in the Tweet data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `attachments.poll_ids, attachments.media_keys, author_id, edit_history_tweet_ids, entities.mentions.username, geo.place_id, in_reply_to_user_id, referenced_tweets.id, referenced_tweets.id.author_id`.
media_fields	String	No	This fields parameter enables you to select which specific media fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return media fields if the Tweet contains media and if you've also included the expansions=attachments.media_keys query parameter in your request. While the media ID will be located in the Tweet object, you will find this ID and all additional media fields in the includes data object. Valid values for this parameter are: `duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, non_public_metrics, organic_metrics, promoted_metrics, alt_text, variants`
place_fields	String	No	This fields parameter enables you to select which specific place fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The response will contain the selected fields only if you've also included the expansions=geo.place_id query parameter in your request. Valid values for this parameter are: `contained_within, country, country_code, full_name, geo, id, name, place_type`.
poll_fields	String	No	This fields parameter enables you to select which specific poll fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return poll fields if the Tweet contains a poll and if you've also included the expansions=attachments.poll_ids query parameter in your request. While the poll ID will be located in the Tweet object, you will find this ID and all additional poll fields in the includes data object. Valid values for this parameter are: `duration_minutes, end_datetime, id, options, voting_status`.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned Tweet object. Specify the desired fields in a comma-separated list without spaces between commas and fields. You can also pass the expansions=referenced_tweets.id expansion to return the specified fields for both the original Tweet and any included referenced Tweets. The requested Tweet fields will display in both the original Tweet data object, as well as in the referenced Tweet expanded data object that will be located in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the user ID will be located in the original Tweet object, you will find this ID and all additional user fields in the includes data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getUserMentionsTimeline>
    <id>{$ctx:id}</id>
    <start_time>{$ctx:start_time}</start_time>
    <end_time>{$ctx:end_time}</end_time>
    <since_id>{$ctx:since_id}</since_id>
    <until_id>{$ctx:until_id}</until_id>
    <sort_order>{$ctx:sort_order}</sort_order>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <expansions>{$ctx:expansions}</expansions>
    <media_fields>{$ctx:media_fields}</media_fields>
    <place_fields>{$ctx:place_fields}</place_fields>
    <poll_fields>{$ctx:poll_fields}</poll_fields>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getUserMentionsTimeline>

Sample request

Given below is a sample request that can be handled by the getUserMentionsTimeline operation.

<twitter.getUserMentionsTimeline>
    <id>"1655515285577936899"</id>
    <start_time>"2020-01-01T00:00:00Z"</start_time>
    <max_results>10</max_results>
    <tweet_fields>"created_at,lang,conversation_id"</tweet_fields>
</twitter.getUserMentionsTimeline>

Sample response

Given below is a sample response for the getUserMentionsTimeline operation.

{
    "data": [
        {
            "public_metrics": {
                "retweet_count": 5,
                "reply_count": 2,
                "like_count": 22,
                "quote_count": 0
            },
            "text": "Live now! https://t.co/9BbWekeWq2",
            "author_id": "2244994945",
            "id": "1374405406261268481",
            "edit_history_tweet_ids": [
                "1374405406261268481"
            ],
            "created_at": "2021-03-23T16:59:18.000Z",
            "context_annotations": [
                {
                "domain": {
                    "id": "46",
                    "name": "Brand Category",
                    "description": "Categories within Brand Verticals that narrow down the scope of Brands"
                },
                "entity": {
                    "id": "781974596752842752",
                    "name": "Services"
                }
                },
                {
                "domain": {
                    "id": "47",
                    "name": "Brand",
                    "description": "Brands and Companies"
                },
                "entity": {
                    "id": "10045225402",
                    "name": "Twitter"
                }
                }
            ],
            "conversation_id": "1374405406261268481"
        },
        {
            "public_metrics": {
                "retweet_count": 7,
                "reply_count": 1,
                "like_count": 21,
                "quote_count": 2
            },
            "text": "Hope to see you tomorrow at 1 pm EST for APIs 101! nhttps://t.co/GrtBOXyHmB https://t.co/YyQfmgiLlL",
            "author_id": "2244994945",
            "id": "1374104599456534531",
            "edit_history_tweet_ids": [
                "1374104599456534531"
            ],
            "created_at": "2021-03-22T21:04:00.000Z",
            "context_annotations": [
                {
                "domain": {
                    "id": "46",
                    "name": "Brand Category",
                    "description": "Categories within Brand Verticals that narrow down the scope of Brands"
                },
                "entity": {
                    "id": "781974596752842752",
                    "name": "Services"
                }
                },
                {
                "domain": {
                    "id": "47",
                    "name": "Brand",
                    "description": "Brands and Companies"
                },
                "entity": {
                    "id": "10045225402",
                    "name": "Twitter"
                }
                }
            ],
            "conversation_id": "1374104599456534531"
        }
    ]
}

getUserTweetsTimeline

The twitter.getUserTweetsTimeline method retrieves Tweets composed by a single user, specified by the requested user ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	Unique identifier of the user who composed the Tweets.
start_time	String	No	`YYYY-MM-DDTHH:mm:ssZ` (ISO 8601/RFC 3339). The oldest UTC timestamp (from most recent seven days) from which the Tweets will be provided. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). If included with the same request as a since_id parameter, only since_id will be used. By default, a request will return Tweets from up to seven days ago if you do not include this parameter.
end_time	String	No	`YYYY-MM-DDTHH:mm:ssZ` (ISO 8601/RFC 3339). The newest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in second granularity and is exclusive (for example, 12:00:01 excludes the first second of the minute). By default, a request will return Tweets from as recent as 30 seconds ago if you do not include this parameter.
since_id	String	No	Returns results with a Tweet ID greater than (that is, more recent than) the specified ID. The ID specified is exclusive and responses will not include it. If included with the same request as a start_time parameter, only since_id will be used.
until_id	String	No	Returns results with a Tweet ID less than (that is, older than) the specified 'until' Tweet ID. There are limits to the number of Tweets that can be accessed through the API. If the limit of Tweets has occurred since the until_id, the until_id will be forced to the most recent ID available.
sort_order	String	No	This parameter is used to specify the order in which you want the Tweets returned. By default, a request will return the most recent Tweets first (sorted by recency). se object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `recency, relevancy`
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token	String	No	This parameter is used to move forwards or backwards through 'pages' of results, based on the value of the next_token or previous_token in the response. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned Tweets. Submit a list of desired expansions in a comma-separated list without spaces. The ID that represents the expanded data object will be included directly in the Tweet data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. Valid values for this parameter are: `attachments.poll_ids, attachments.media_keys, author_id, edit_history_tweet_ids, entities.mentions.username, geo.place_id, in_reply_to_user_id, referenced_tweets.id, referenced_tweets.id.author_id`.
media_fields	String	No	This fields parameter enables you to select which specific media fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return media fields if the Tweet contains media and if you've also included the expansions=attachments.media_keys query parameter in your request. While the media ID will be located in the Tweet object, you will find this ID and all additional media fields in the includes data object. Valid values for this parameter are: `duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, non_public_metrics, organic_metrics, promoted_metrics, alt_text, variants`
place_fields	String	No	This fields parameter enables you to select which specific place fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The response will contain the selected fields only if you've also included the expansions=geo.place_id query parameter in your request. Valid values for this parameter are: `contained_within, country, country_code, full_name, geo, id, name, place_type`.
poll_fields	String	No	This fields parameter enables you to select which specific poll fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet will only return poll fields if the Tweet contains a poll and if you've also included the expansions=attachments.poll_ids query parameter in your request. While the poll ID will be located in the Tweet object, you will find this ID and all additional poll fields in the includes data object. Valid values for this parameter are: `duration_minutes, end_datetime, id, options, voting_status`.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned Tweet object. Specify the desired fields in a comma-separated list without spaces between commas and fields. You can also pass the expansions=referenced_tweets.id expansion to return the specified fields for both the original Tweet and any included referenced Tweets. The requested Tweet fields will display in both the original Tweet data object, as well as in the referenced Tweet expanded data object that will be located in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the user ID will be located in the original Tweet object, you will find this ID and all additional user fields in the includes data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getUserTweetsTimeline>
    <id>{$ctx:id}</id>
    <start_time>{$ctx:start_time}</start_time>
    <end_time>{$ctx:end_time}</end_time>
    <since_id>{$ctx:since_id}</since_id>
    <until_id>{$ctx:until_id}</until_id>
    <sort_order>{$ctx:sort_order}</sort_order>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <expansions>{$ctx:expansions}</expansions>
    <media_fields>{$ctx:media_fields}</media_fields>
    <place_fields>{$ctx:place_fields}</place_fields>
    <poll_fields>{$ctx:poll_fields}</poll_fields>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getUserTweetsTimeline>

Sample request

Given below is a sample request that can be handled by the getUserTweetsTimeline operation.

<twitter.getUserTweetsTimeline>
    <id>"1655515285577936899"</id>
    <start_time>"2020-01-01T00:00:00Z"</start_time>
    <max_results>10</max_results>
    <tweet_fields>"created_at,lang,conversation_id"</tweet_fields>
</twitter.getUserTweetsTimeline>

Sample response

Given below is a sample response for the getUserTweetsTimeline operation.

{
    "data": [
        {
            "public_metrics": {
                "retweet_count": 5,
                "reply_count": 2,
                "like_count": 22,
                "quote_count": 0
            },
            "text": "Live now! https://t.co/9BbWekeWq2",
            "author_id": "2244994945",
            "id": "1374405406261268481",
            "edit_history_tweet_ids": [
                "1374405406261268481"
            ],
            "created_at": "2021-03-23T16:59:18.000Z",
            "context_annotations": [
                {
                "domain": {
                    "id": "46",
                    "name": "Brand Category",
                    "description": "Categories within Brand Verticals that narrow down the scope of Brands"
                },
                "entity": {
                    "id": "781974596752842752",
                    "name": "Services"
                }
                },
                {
                "domain": {
                    "id": "47",
                    "name": "Brand",
                    "description": "Brands and Companies"
                },
                "entity": {
                    "id": "10045225402",
                    "name": "Twitter"
                }
                }
            ],
            "conversation_id": "1374405406261268481"
        }
    ]
}

Working with Users¶

The following operations allow you to work with users in Twitter. To be authorized for the following endpoints, you will need an access token with the correct scopes. Please refer the Twitter authentication map to get the required scopes for the access token.

getMe

The twitter.getMe method retrieves information about the authorized user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned users. The ID that represents the expanded data object will be included directly in the user data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. At this time, the only expansion available to endpoints that primarily return user objects is expansions=`pinned_tweet_id`. You will find the expanded Tweet data object living in the includes response object.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned pinned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet fields will only return if the user has a pinned Tweet and if you've also included the expansions=pinned_tweet_id query parameter in your request. While the referenced Tweet ID will be located in the original Tweet object, you will find this ID and all additional Tweet fields in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with each returned users objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified user fields will display directly in the user data objects. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getMe>
    <expansions>{$ctx:expansions}</expansions>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getMe>

Sample request

Given below is a sample request that can be handled by the getMe operation.

<twitter.getMe>
    <expansions>"pinned_tweet_id"</expansions>
    <user_fields>"created_at,username,id,name"</user_fields>
</twitter.getMe>

Sample response

Given below is a sample response for the getMe operation.

{
    "data": {
        "name": "GrawKraken",
        "username": "GrawKraken",
        "pinned_tweet_id": "1667091290889256961",
        "id": "1655515285577936899",
        "created_at": "2023-05-08T10:09:55.000Z"
    },
    "includes": {
        "tweets": [
            {
                "public_metrics": {
                "retweet_count": 0,
                "reply_count": 0,
                "like_count": 0,
                "quote_count": 0,
                "bookmark_count": 0,
                "impression_count": 0
                },
                "edit_history_tweet_ids": [
                "1667091290889256961"
                ],
                "text": "Hi",
                "id": "1667091290889256961"
            }
        ]
    }
}

getUserById

The twitter.getUserById method retrieves information about a single user specified by the requested ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The ID of the user to lookup.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned users. The ID that represents the expanded data object will be included directly in the user data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. At this time, the only expansion available to endpoints that primarily return user objects is expansions=`pinned_tweet_id`. You will find the expanded Tweet data object living in the includes response object.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned pinned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet fields will only return if the user has a pinned Tweet and if you've also included the expansions=pinned_tweet_id query parameter in your request. While the referenced Tweet ID will be located in the original Tweet object, you will find this ID and all additional Tweet fields in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with each returned users objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified user fields will display directly in the user data objects. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getUserById>
    <id>{$ctx:id}</id>
    <expansions>{$ctx:expansions}</expansions>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getUserById>

Sample request

Given below is a sample request that can be handled by the getUserById operation.

<twitter.getUserById>
    <id>"1655515285577936899"</id>
    <user_fields>"created_at,username,id,name"</user_fields>
</twitter.getUserById>

Sample response

Given below is a sample response for the getUserById operation.

{
    "data": {
        "pinned_tweet_id": "1667091290889256961",
        "name": "GrawKraken",
        "id": "1655515285577936899",
        "created_at": "2023-05-08T10:09:55.000Z",
        "username": "GrawKraken"
    },
    "includes": {
        "tweets": [
            {
                "id": "1667091290889256961",
                "edit_history_tweet_ids": [
                "1667091290889256961"
                ],
                "public_metrics": {
                "retweet_count": 0,
                "reply_count": 0,
                "like_count": 0,
                "quote_count": 0,
                "bookmark_count": 0,
                "impression_count": 0
                },
                "text": "Hi"
            }
        ]
    }
}

getUserByUsername

The twitter.getUserByUsername method retrieves information about a single user specified by the requested username. See the related API documentation for more information.

Parameter Name	Type	Required	Description
username	String	Yes	The Twitter username (handle) of the user.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned users. The ID that represents the expanded data object will be included directly in the user data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. At this time, the only expansion available to endpoints that primarily return user objects is expansions=`pinned_tweet_id`. You will find the expanded Tweet data object living in the includes response object.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned pinned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet fields will only return if the user has a pinned Tweet and if you've also included the expansions=pinned_tweet_id query parameter in your request. While the referenced Tweet ID will be located in the original Tweet object, you will find this ID and all additional Tweet fields in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with each returned users objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified user fields will display directly in the user data objects. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getUserByUsername>
    <username>{$ctx:username}</username>
    <expansions>{$ctx:expansions}</expansions>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getUserByUsername>

Sample request

Given below is a sample request that can be handled by the getUserByUsername operation.

<twitter.getUserByUsername>
    <username>"GrawKraken"</username>
    <tweet_fields>"public_metrics"</tweet_fields>
</twitter.getUserByUsername>

Sample response

Given below is a sample response for the getUserByUsername operation.

{
    "data": {
        "name": "GrawKraken",
        "username": "GrawKraken",
        "pinned_tweet_id": "1667091290889256961",
        "id": "1655515285577936899",
        "created_at": "2023-05-08T10:09:55.000Z"
    },
    "includes": {
        "tweets": [
            {
                "public_metrics": {
                "retweet_count": 0,
                "reply_count": 0,
                "like_count": 0,
                "quote_count": 0,
                "bookmark_count": 0,
                "impression_count": 0
                },
                "edit_history_tweet_ids": [
                "1667091290889256961"
                ],
                "text": "Hi",
                "id": "1667091290889256961"
            }
        ]
    }
}

getUsersLookup

The twitter.getUsersLookup method retrieves information about one or more users specified by the requested IDs. See the related API documentation for more information.

Parameter Name	Type	Required	Description
ids	String	Yes	A comma separated list of user IDs. Up to 100 are allowed in a single request. Make sure to not include a space between commas and fields.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned users. The ID that represents the expanded data object will be included directly in the user data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. At this time, the only expansion available to endpoints that primarily return user objects is expansions=`pinned_tweet_id`. You will find the expanded Tweet data object living in the includes response object.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned pinned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet fields will only return if the user has a pinned Tweet and if you've also included the expansions=pinned_tweet_id query parameter in your request. While the referenced Tweet ID will be located in the original Tweet object, you will find this ID and all additional Tweet fields in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with each returned users objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified user fields will display directly in the user data objects. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getUsersLookup>
    <ids>{$ctx:ids}</ids>
    <expansions>{$ctx:expansions}</expansions>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getUsersLookup>

Sample request

Given below is a sample request that can be handled by the getUsersLookup operation.

<twitter.getUsersLookup>
    <ids>"1655515285577936899,15594932"</ids>
    <expansions>"pinned_tweet_id"</expansions>
    <tweet_fields>"created_at"</tweet_fields>
</twitter.getUsersLookup>

Sample response

Given below is a sample response for the getUsersLookup operation.

{
    "data": [
        {
            "pinned_tweet_id": "1667091290889256961",
            "username": "GrawKraken",
            "name": "GrawKraken",
            "id": "1655515285577936899"
        },
        {
            "username": "wso2",
            "name": "WSO2",
            "id": "15594932"
        }
    ],
    "includes": {
        "tweets": [
            {
                "edit_history_tweet_ids": [
                "1667091290889256961"
                ],
                "text": "Hi",
                "created_at": "2023-06-09T08:48:31.000Z",
                "id": "1667091290889256961"
            }
        ]
    }
}

followUser

The twitter.followUser method follows a specified user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The authenticated user ID of whom you would like to initiate the following on behalf. You must pass the Access Tokens that relate to this user when authenticating the request.
target_user_id	String	Yes	The user ID of the user that you would like to follow.

Sample configuration

<twitter.followUser>
    <id>{$ctx:id}</id>
    <target_user_id>{$ctx:target_user_id}</target_user_id>
</twitter.followUser>

Sample request

Given below is a sample request that can be handled by the followUser operation.

<twitter.followUser>
    <id>"1655515285577936899"</id>
    <target_user_id>"15594932"</target_user_id>
</twitter.followUser>

Sample response

Given below is a sample response for the followUser operation.

{
    "data": {
        "following": true,
        "pending_follow": false
    }
}

getFollowingUsers

The twitter.getFollowingUsers method retrieves a list of users who are followed by the specified user ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The user ID whose following you would like to retrieve.
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token	String	No	Used to request the next page of results if all results weren't returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned users. The ID that represents the expanded data object will be included directly in the user data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. At this time, the only expansion available to endpoints that primarily return user objects is expansions=`pinned_tweet_id`. You will find the expanded Tweet data object living in the includes response object.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned pinned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet fields will only return if the user has a pinned Tweet and if you've also included the expansions=pinned_tweet_id query parameter in your request. While the referenced Tweet ID will be located in the original Tweet object, you will find this ID and all additional Tweet fields in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with each returned users objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified user fields will display directly in the user data objects. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getFollowingUsers>
    <id>{$ctx:id}</id>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <expansions>{$ctx:expansions}</expansions>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getFollowingUsers>

Sample request

Given below is a sample request that can be handled by the getFollowingUsers operation.

<twitter.getFollowingUsers>
    <id>"1655515285577936899"</id>
</twitter.getFollowingUsers>

Sample response

Given below is a sample response for the getFollowingUsers operation.

{
    "data": [
        {
            "pinned_tweet_id": "1293595870563381249",
            "id": "6253282",
            "username": "TwitterAPI",
            "name": "Twitter API"
        },
        {
            "pinned_tweet_id": "1293593516040269825",
            "id": "2244994945",
            "username": "TwitterDev",
            "name": "Twitter Dev"
        },
        {
            "id": "783214",
            "username": "Twitter",
            "name": "Twitter"
        },
        {
            "pinned_tweet_id": "1271186240323432452",
            "id": "95731075",
            "username": "TwitterSafety",
            "name": "Twitter Safety"
        },
        {
            "id": "3260518932",
            "username": "TwitterMoments",
            "name": "Twitter Moments"
        },
        {
            "pinned_tweet_id": "1293216056274759680",
            "id": "373471064",
            "username": "TwitterMusic",
            "name": "Twitter Music"
        },
        {
            "id": "791978718",
            "username": "OfficialPartner",
            "name": "Twitter Official Partner"
        },
        {
            "pinned_tweet_id": "1289000334497439744",
            "id": "17874544",
            "username": "TwitterSupport",
            "name": "Twitter Support"
        },
        {
            "pinned_tweet_id": "1283543147444711424",
            "id": "234489024",
            "username": "TwitterComms",
            "name": "Twitter Comms"
        },
        {
            "id": "1526228120",
            "username": "TwitterData",
            "name": "Twitter Data"
        }
    ]
}

getFollowers

The twitter.getFollowers method retrieves a list of users who are followers of the specified user ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The user ID whose followers you would like to retrieve.
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token	String	No	Used to request the next page of results if all results weren't returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned users. The ID that represents the expanded data object will be included directly in the user data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. At this time, the only expansion available to endpoints that primarily return user objects is expansions=`pinned_tweet_id`. You will find the expanded Tweet data object living in the includes response object.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned pinned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet fields will only return if the user has a pinned Tweet and if you've also included the expansions=pinned_tweet_id query parameter in your request. While the referenced Tweet ID will be located in the original Tweet object, you will find this ID and all additional Tweet fields in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with each returned users objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified user fields will display directly in the user data objects. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getFollowers>
    <id>{$ctx:id}</id>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <expansions>{$ctx:expansions}</expansions>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getFollowers>

Sample request

Given below is a sample request that can be handled by the getFollowers operation.

<twitter.getFollowers>
    <id>"1655515285577936899"</id>
</twitter.getFollowers>

Sample response

Given below is a sample response for the getFollowers operation.

{
    "data": [
        {
            "pinned_tweet_id": "1293595870563381249",
            "id": "6253282",
            "username": "TwitterAPI",
            "name": "Twitter API"
        },
        {
            "pinned_tweet_id": "1293593516040269825",
            "id": "2244994945",
            "username": "TwitterDev",
            "name": "Twitter Dev"
        },
        {
            "id": "783214",
            "username": "Twitter",
            "name": "Twitter"
        },
        {
            "pinned_tweet_id": "1271186240323432452",
            "id": "95731075",
            "username": "TwitterSafety",
            "name": "Twitter Safety"
        },
        {
            "id": "3260518932",
            "username": "TwitterMoments",
            "name": "Twitter Moments"
        },
        {
            "pinned_tweet_id": "1293216056274759680",
            "id": "373471064",
            "username": "TwitterMusic",
            "name": "Twitter Music"
        },
        {
            "id": "791978718",
            "username": "OfficialPartner",
            "name": "Twitter Official Partner"
        },
        {
            "pinned_tweet_id": "1289000334497439744",
            "id": "17874544",
            "username": "TwitterSupport",
            "name": "Twitter Support"
        },
        {
            "pinned_tweet_id": "1283543147444711424",
            "id": "234489024",
            "username": "TwitterComms",
            "name": "Twitter Comms"
        },
        {
            "id": "1526228120",
            "username": "TwitterData",
            "name": "Twitter Data"
        }
    ]
}

unfollowUser

The twitter.unfollowUser method unfollows a specified user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The authenticated user ID of whom you would like to initiate the unfollowing on behalf. You must pass the Access Tokens that relate to this user when authenticating the request.
target_user_id	String	Yes	The user ID of the user that you would like to unfollow.

Sample configuration

<twitter.unfollowUser>
    <id>{$ctx:id}</id>
    <target_user_id>{$ctx:target_user_id}</target_user_id>
</twitter.unfollowUser>

Sample request

Given below is a sample request that can be handled by the unfollowUser operation.

<twitter.unfollowUser>
    <id>"1655515285577936899"</id>
    <target_user_id>"15594932"</target_user_id>
</twitter.unfollowUser>

Sample response

Given below is a sample response for the unfollowUser operation.

{
    "data": {
        "following": false
    }
}

blockUser

The twitter.blockUser method blocks a specified user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The authenticated user ID of whom you would like to initiate the blocking on behalf. You must pass the Access Tokens that relate to this user when authenticating the request.
target_user_id	String	Yes	The user ID of the user that you would like to block.

Sample configuration

<twitter.blockUser>
    <id>{$ctx:id}</id>
    <target_user_id>{$ctx:target_user_id}</target_user_id>
</twitter.blockUser>

Sample request

Given below is a sample request that can be handled by the blockUser operation.

<twitter.blockUser>
    <id>"1655515285577936899"</id>
    <target_user_id>"15594932"</target_user_id>
</twitter.blockUser>

Sample response

Given below is a sample response for the blockUser operation.

{
    "data": {
        "blocking": true
    }
}

getBlockedUsers

The twitter.getBlockedUsers method retrieves a list of users who are blocked by the specified user ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The user ID whose blocked users you would like to retrieve.
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token	String	No	Used to request the next page of results if all results weren't returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned users. The ID that represents the expanded data object will be included directly in the user data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. At this time, the only expansion available to endpoints that primarily return user objects is expansions=`pinned_tweet_id`. You will find the expanded Tweet data object living in the includes response object.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned pinned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet fields will only return if the user has a pinned Tweet and if you've also included the expansions=pinned_tweet_id query parameter in your request. While the referenced Tweet ID will be located in the original Tweet object, you will find this ID and all additional Tweet fields in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with each returned users objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified user fields will display directly in the user data objects. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getBlockedUsers>
    <id>{$ctx:id}</id>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <expansions>{$ctx:expansions}</expansions>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getBlockedUsers>

Sample request

Given below is a sample request that can be handled by the getBlockedUsers operation.

<twitter.getBlockedUsers>
    <id>"1655515285577936899"</id>
</twitter.getBlockedUsers>

Sample response

Given below is a sample response for the getBlockedUsers operation.

{
    "data": [
        {
            "pinned_tweet_id": "1293595870563381249",
            "id": "6253282",
            "username": "TwitterAPI",
            "name": "Twitter API"
        },
        {
            "pinned_tweet_id": "1293593516040269825",
            "id": "2244994945",
            "username": "TwitterDev",
            "name": "Twitter Dev"
        },
        {
            "id": "783214",
            "username": "Twitter",
            "name": "Twitter"
        },
        {
            "pinned_tweet_id": "1271186240323432452",
            "id": "95731075",
            "username": "TwitterSafety",
            "name": "Twitter Safety"
        },
        {
            "id": "3260518932",
            "username": "TwitterMoments",
            "name": "Twitter Moments"
        },
        {
            "pinned_tweet_id": "1293216056274759680",
            "id": "373471064",
            "username": "TwitterMusic",
            "name": "Twitter Music"
        },
        {
            "id": "791978718",
            "username": "OfficialPartner",
            "name": "Twitter Official Partner"
        },
        {
            "pinned_tweet_id": "1289000334497439744",
            "id": "17874544",
            "username": "TwitterSupport",
            "name": "Twitter Support"
        },
        {
            "pinned_tweet_id": "1283543147444711424",
            "id": "234489024",
            "username": "TwitterComms",
            "name": "Twitter Comms"
        },
        {
            "id": "1526228120",
            "username": "TwitterData",
            "name": "Twitter Data"
        }
    ]
}

unblockUser

The twitter.unblockUser method unblocks a specified user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The authenticated user ID of whom you would like to initiate the unblocking on behalf. You must pass the Access Tokens that relate to this user when authenticating the request.
target_user_id	String	Yes	The user ID of the user that you would like to unblock.

Sample configuration

<twitter.unblockUser>
    <id>{$ctx:id}</id>
    <target_user_id>{$ctx:target_user_id}</target_user_id>
</twitter.unblockUser>

Sample request

Given below is a sample request that can be handled by the unblockUser operation.

<twitter.unblockUser>
    <id>"1655515285577936899"</id>
    <target_user_id>"15594932"</target_user_id>
</twitter.unblockUser>

Sample response

Given below is a sample response for the unblockUser operation.

{
    "data": {
        "blocking": false
    }
}

muteUser

The twitter.muteUser method mutes a specified user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The authenticated user ID of whom you would like to initiate the muting on behalf. You must pass the Access Tokens that relate to this user when authenticating the request.
target_user_id	String	Yes	The user ID of the user that you would like to mute.

Sample configuration

<twitter.muteUser>
    <id>{$ctx:id}</id>
    <target_user_id>{$ctx:target_user_id}</target_user_id>
</twitter.muteUser>

Sample request

Given below is a sample request that can be handled by the muteUser operation.

<twitter.muteUser>
    <id>"1655515285577936899"</id>
    <target_user_id>"15594932"</target_user_id>
</twitter.muteUser>

Sample response

Given below is a sample response for the muteUser operation.

{
    "data": {
        "muting": true
    }
}

getMutedUsers

The twitter.getMutedUsers method retrieves a list of users who are muted by the specified user ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The user ID whose muted users you would like to retrieve.
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token	String	No	Used to request the next page of results if all results weren't returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned users. The ID that represents the expanded data object will be included directly in the user data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Tweet object. At this time, the only expansion available to endpoints that primarily return user objects is expansions=`pinned_tweet_id`. You will find the expanded Tweet data object living in the includes response object.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will deliver in each returned pinned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. The Tweet fields will only return if the user has a pinned Tweet and if you've also included the expansions=pinned_tweet_id query parameter in your request. While the referenced Tweet ID will be located in the original Tweet object, you will find this ID and all additional Tweet fields in the includes data object. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with each returned users objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified user fields will display directly in the user data objects. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld`.

Sample configuration

<twitter.getMutedUsers>
    <id>{$ctx:id}</id>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <expansions>{$ctx:expansions}</expansions>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getMutedUsers>

Sample request

Given below is a sample request that can be handled by the getMutedUsers operation.

<twitter.getMutedUsers>
    <id>"1655515285577936899"</id>
</twitter.getMutedUsers>

Sample response

Given below is a sample response for the getMutedUsers operation.

{
    "data": [
        {
            "pinned_tweet_id": "1293595870563381249",
            "id": "6253282",
            "username": "TwitterAPI",
            "name": "Twitter API"
        },
        {
            "pinned_tweet_id": "1293593516040269825",
            "id": "2244994945",
            "username": "TwitterDev",
            "name": "Twitter Dev"
        },
        {
            "id": "783214",
            "username": "Twitter",
            "name": "Twitter"
        },
        {
            "pinned_tweet_id": "1271186240323432452",
            "id": "95731075",
            "username": "TwitterSafety",
            "name": "Twitter Safety"
        },
        {
            "id": "3260518932",
            "username": "TwitterMoments",
            "name": "Twitter Moments"
        },
        {
            "pinned_tweet_id": "1293216056274759680",
            "id": "373471064",
            "username": "TwitterMusic",
            "name": "Twitter Music"
        },
        {
            "id": "791978718",
            "username": "OfficialPartner",
            "name": "Twitter Official Partner"
        },
        {
            "pinned_tweet_id": "1289000334497439744",
            "id": "17874544",
            "username": "TwitterSupport",
            "name": "Twitter Support"
        },
        {
            "pinned_tweet_id": "1283543147444711424",
            "id": "234489024",
            "username": "TwitterComms",
            "name": "Twitter Comms"
        },
        {
            "id": "1526228120",
            "username": "TwitterData",
            "name": "Twitter Data"
        }
    ]
}

unmuteUser

The twitter.unmuteUser method unmutes a specified user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The authenticated user ID of whom you would like to initiate the unmuting on behalf. You must pass the Access Tokens that relate to this user when authenticating the request.
target_user_id	String	Yes	The user ID of the user that you would like to unmute.

Sample configuration

<twitter.unmuteUser>
    <id>{$ctx:id}</id>
    <target_user_id>{$ctx:target_user_id}</target_user_id>
</twitter.unmuteUser>

Sample request

Given below is a sample request that can be handled by the unmuteUser operation.

<twitter.unmuteUser>
    <id>"1655515285577936899"</id>
    <target_user_id>"15594932"</target_user_id>
</twitter.unmuteUser>

Sample response

Given below is a sample response for the unmuteUser operation.

{
    "data": {
        "muting": false
    }
}

Working with Lists¶

The following operations allow you to work with lists in Twitter. To be authorized for the following endpoints, you will need an access token with the correct scopes. Please refer the Twitter authentication map to get the required scopes for the access token.

createList

The twitter.createList method creates a new list for the authenticated user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
name	String	Yes	The name of the List you wish to create.
description	String	No	Description of the List.
private	Boolean	No	Determine whether the List should be private.

Sample configuration

<twitter.createList>
    <name>{$ctx:name}</name>
    <description>{$ctx:description}</description>
    <private>{$ctx:private}</private>
</twitter.createList>

Sample request

Given below is a sample request that can be handled by the createList operation.

<twitter.createList>
    <name>"test list"</name>
    <description>"list for testing"</description>
    <private>true</private>
</twitter.createList>

Sample response

Given below is a sample response for the createList operation.

{
    "data": {
        "id": "1667124005638397955",
        "name": "test list"
    }
}

updateList

The twitter.updateList method updates an existing list for the authenticated user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The ID of the List to be updated.
name	String	No	The new name of the List you wish to update.
description	String	No	Description of the List.
private	Boolean	No	Determine whether the List should be private.

Sample configuration

<twitter.updateList>
    <id>{$ctx:id}</id>
    <name>{$ctx:name}</name>
    <description>{$ctx:description}</description>
    <private>{$ctx:private}</private>
</twitter.updateList>

Sample request

Given below is a sample request that can be handled by the updateList operation.

<twitter.updateList>
    <id>"1669209684962865153"</id>
    <description>"list for testing"</description>
    <private>true</private>
</twitter.updateList>

Sample response

Given below is a sample response for the updateList operation.

{
    "data": {
        "updated": true
    }
}

deleteList

The twitter.deleteList method deletes a list for the authenticated user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The ID of the List you wish to delete.

Sample configuration

<twitter.deleteList>
    <id>{$ctx:id}</id>
</twitter.deleteList>

Sample request

Given below is a sample request that can be handled by the deleteList operation.

<twitter.deleteList>
    <id>"1669209684962865153"</id>
</twitter.deleteList>

Sample response

Given below is a sample response for the deleteList operation.

{
    "data": {
        "deleted": true
    }
}

getListById

The twitter.getListById method retrieves information about a single list specified by the requested ID. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The ID of the list to lookup.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned List. The ID that represents the expanded data object will be included directly in the List data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original user object. At this time, the only expansion available to endpoints that primarily return List objects is expansions=`owner_id`. You will find the expanded user data object living in the includes response object.
list_fields	String	No	This fields parameter enables you to select which specific List fields will deliver with each returned List objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified List fields will display directly in the List data objects. Valid values for this parameter are: `created_at, follower_count, member_count, private, description, owner_id`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with the users object. Specify the desired fields in a comma-separated list without spaces between commas and fields. The user fields will only be returned if you have included expansions=owner_id query parameter in your request. You will find this ID and all additional user fields in the included data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, withheld`.

Sample configuration

<twitter.getListById>
    <id>{$ctx:id}</id>
    <expansions>{$ctx:expansions}</expansions>
    <list_fields>{$ctx:list_fields}</list_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getListById>

Sample request

Given below is a sample request that can be handled by the getListById operation.

<twitter.getListById>
    <id>"1667124005638397955"</id>
    <user_fields>"created_at,username,id,name"</user_fields>
</twitter.getListById>

Sample response

Given below is a sample response for the getListById operation.

getFollowingLists

The twitter.getFollowingLists method retrieves all lists the authenticating or specified user is following, including their own. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The user ID whose followed Lists you would like to retrieve.
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
pagination_token	String	No	Used to request the next page of results if all results weren't returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned List. The ID that represents the expanded data object will be included directly in the List data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original user object. At this time, the only expansion available to endpoints that primarily return List objects is expansions=`owner_id`. You will find the expanded user data object living in the includes response object.
list_fields	String	No	This fields parameter enables you to select which specific List fields will deliver with each returned List objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified List fields will display directly in the List data objects. Valid values for this parameter are: `created_at, follower_count, member_count, private, description, owner_id`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with the users object. Specify the desired fields in a comma-separated list without spaces between commas and fields. The user fields will only be returned if you have included expansions=owner_id query parameter in your request. You will find this ID and all additional user fields in the included data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, withheld`.

Sample configuration

<twitter.getFollowingLists>
    <id>{$ctx:id}</id>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <expansions>{$ctx:expansions}</expansions>
    <list_fields>{$ctx:list_fields}</list_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getFollowingLists>

Sample request

Given below is a sample request that can be handled by the getFollowingLists operation.

<twitter.getFollowingLists>
    <id>"1655515285577936899"</id>
    <user_fields>"created_at,username,id,name"</user_fields>
</twitter.getFollowingLists>

Sample response

Given below is a sample response for the getFollowingLists operation.

{
    "data": [
        {
            "follower_count": 123,
            "id": "1630685563471",
            "name": "Test List",
            "owner_id": "1324848235714736129"
        }
    ],
    "includes": {
        "users": [
            {
                "username": "alanbenlee",
                "id": "1324848235714736129",
                "created_at": "2009-08-28T18:30:45.000Z",
                "name": "Alan Lee"
            }
        ]
    },
    "meta": {
        "result_count": 1
    }
}

getListsMemberships

The twitter.getListsMemberships method retrieves all Lists a specified user is a member of. See the related API documentation for more information.

Parameter Name	Type	Required	Description
id	String	Yes	The user ID whose List memberships you would like to retrieve.
max_results	Integer	No	The maximum number of results to be returned per page. This can be a number between 1 and 100. By default, each page will return 100 results.
pagination_token	String	No	Used to request the next page of results if all results weren't returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
expansions	String	No	Expansions enable you to request additional data objects that relate to the originally returned List. The ID that represents the expanded data object will be included directly in the List data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original user object. At this time, the only expansion available to endpoints that primarily return List objects is expansions=`owner_id`. You will find the expanded user data object living in the includes response object.
list_fields	String	No	This fields parameter enables you to select which specific List fields will deliver with each returned List objects. Specify the desired fields in a comma-separated list without spaces between commas and fields. These specified List fields will display directly in the List data objects. Valid values for this parameter are: `created_at, follower_count, member_count, private, description, owner_id`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will deliver with the users object. Specify the desired fields in a comma-separated list without spaces between commas and fields. The user fields will only be returned if you have included expansions=owner_id query parameter in your request. You will find this ID and all additional user fields in the included data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, withheld`.

Sample configuration

<twitter.getListsMemberships>
    <id>{$ctx:id}</id>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <expansions>{$ctx:expansions}</expansions>
    <list_fields>{$ctx:list_fields}</list_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getListsMemberships>

Sample request

Given below is a sample request that can be handled by the getListsMemberships operation.

<twitter.getListsMemberships>
    <id>"1655515285577936899"</id>
    <user_fields>"created_at,username,id,name"</user_fields>
</twitter.getListsMemberships>

Sample response

Given below is a sample response for the getListsMemberships operation.

{
    "data": [
        {
            "description": "list for editing and testing",
            "id": "1667130158023860224",
            "name": "test listss",
            "owner_id": "1655515285577936899"
        }
    ],
    "includes": {
        "users": [
            {
                "id": "1655515285577936899",
                "name": "GrawKraken",
                "username": "GrawKraken",
                "created_at": "2023-05-08T10:09:55.000Z"
            }
        ]
    },
    "meta": {
        "result_count": 1
    }
}

Working with Direct Messages¶

The following operations allow you to work with direct messages in Twitter. To be authorized for the following endpoints, you will need an access token with the correct scopes. Please refer the Twitter authentication map to get the required scopes for the access token.

sendNewDirectMessage

The twitter.sendNewDirectMessage method sends a new direct message to the specified user from the authenticating user. See the related API documentation for more information.

Parameter Name	Type	Required	Description
participant_id	String	Yes	The User ID of the account this one-to-one Direct Message is to be sent to.
attachments	String	Yes if text is not present	A single Media ID being attached to the Direct Message. Currently, Twitter supports only 1 attachment.
text	String	Yes if attachments is not present	Text of the Direct Message being created. Text messages support up to 10,000 characters.

Sample configuration

<twitter.sendNewDirectMessage>
    <participant_id>{$ctx:participant_id}</participant_id>
    <attachments>{$ctx:attachments}</attachments>
    <text>{$ctx:text}</text>
</twitter.sendNewDirectMessage>

Sample request

Given below is a sample request that can be handled by the sendNewDirectMessage operation.

<twitter.sendNewDirectMessage>
    <participant_id>"1668111685234708487"</participant_id>
    <text>"Test message!"</text>
</twitter.sendNewDirectMessage>

Sample response

Given below is a sample response for the sendNewDirectMessage operation.

{
    "data": {
        "dm_conversation_id": "1655515285577936899-1668111685234708487",
        "dm_event_id": "1668112397700067333"
    }
}

addDirectMessage

The twitter.addDirectMessage method creates a Direct Message on behalf of an authenticated user, and adds it to the specified conversation. See the related API documentation for more information.

Parameter Name	Type	Required	Description
dm_conversation_id	String	Yes	The dm_conversation_id of the conversation to add the Direct Message to. Supports both 1-1 and group conversations.
attachments	String	Yes if text is not present	A single Media ID being attached to the Direct Message. Currently, Twitter supports only 1 attachment.
text	String	Yes if attachments is not present	Text of the Direct Message being created. Text messages support up to 10,000 characters.

Sample configuration

<twitter.addDirectMessage>
    <dm_conversation_id>{$ctx:dm_conversation_id}</dm_conversation_id>
    <attachments>{$ctx:attachments}</attachments>
    <text>{$ctx:text}</text>
</twitter.addDirectMessage>

Sample request

Given below is a sample request that can be handled by the addDirectMessage operation.

<twitter.addDirectMessage>
    <dm_conversation_id>"1655515285577936899-1668111685234708487"</dm_conversation_id>
    <text>"Second Test message!"</text>
</twitter.addDirectMessage>

Sample response

Given below is a sample response for the addDirectMessage operation.

{
    "data": {
        "dm_conversation_id": "1655515285577936899-1668111685234708487",
        "dm_event_id": "1668112397700067333"
    }
}

getDirectMessages

The twitter.getDirectMessages method retrives a list of Direct Messages for the authenticated user, both sent and received. See the related API documentation for more information.

Parameter Name	Type	Required	Description
event_types	String	No	The type of Direct Message event to return. If not included, all types are returned. Valid values for this parameter are: `MessageCreate, ParticipantsJoin, ParticipantsLeave`.
max_results	Integer	No	The maximum number of results to be returned in a page. Must be between 1 and 100. The default is 100.
pagination_token	String	No	Contains either the next_token or previous_token value.
expansions	String	No	Expansions enable you to request additional data objects that relate to the returned Direct Message conversation events. Submit a list of desired expansions in a comma-separated list without spaces. The IDs that represents the expanded data objects will be included directly in the event data object, and the expanded object metadata will be returned within the includes response object. Valid values for this parameter are: `attachments.media_keys, referenced_tweets.id, sender_id, participant_ids`.
dm_event_fields	String	No	Extra fields to include in the event payload. id, and event_type are returned by default. The text value isn't included for ParticipantsJoin and ParticipantsLeave events. Valid values for this parameter are: `id, text, event_type, created_at, dm_conversation_id, sender_id, participant_ids, referenced_tweets, attachments`.
media_fields	String	No	This fields parameter enables you to select which specific media fields will be delivered in Direct Message 'MessageCreate' events. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the media ID will be located in the event object, you will find this ID and all additional media fields in the includes data object. The event object will only include media fields if the Direct Message contains media and if you've also included the expansions=attachments.media_keys query parameter in your request. Valid values for this parameter are: `duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, alt_text, variants`.
tweet_fields	String	No	This fields parameter enables you to select which specific Tweet fields will be delivered in each returned Direct Message 'MessageCreate' event object that contains a Tweet reference. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the Tweet ID will be in the event object, you will find this ID and all additional Tweet fields in the includes data object. The event object will include Tweet fields only if the Direct Message references a Tweet and the expansions=referenced_tweet.id query parameter is included in the request. Valid values for this parameter are: `attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, entities, geo, id, in_reply_to_user_id, lang, public_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld`.
user_fields	String	No	This fields parameter enables you to select which specific user fields will be delivered for Direct Message conversation events that reference a sender or participant ID. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the user ID will be located in the event object, you will find this ID and all additional user fields in the includes data object. Valid values for this parameter are: `created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, withheld`.

Sample configuration

<twitter.getDirectMessages>
    <event_types>{$ctx:event_types}</event_types>
    <max_results>{$ctx:max_results}</max_results>
    <pagination_token>{$ctx:pagination_token}</pagination_token>
    <expansions>{$ctx:expansions}</expansions>
    <dm_event_fields>{$ctx:dm_event_fields}</dm_event_fields>
    <media_fields>{$ctx:media_fields}</media_fields>
    <tweet_fields>{$ctx:tweet_fields}</tweet_fields>
    <user_fields>{$ctx:user_fields}</user_fields>
</twitter.getDirectMessages>

Sample request

Given below is a sample request that can be handled by the getDirectMessages operation.

<twitter.getDirectMessages>
    <dm_event_fields>"event_type,sender_id"</dm_event_fields>
    <user_fields>"created_at,username,id,name"</user_fields>
</twitter.getDirectMessages>

Sample response

Given below is a sample response for the getDirectMessages operation.

{
    "data": [
        {
            "text": "Test message!",
            "id": "1668113164393672708",
            "sender_id": "1655515285577936899",
            "event_type": "MessageCreate"
        },
        {
            "text": "Test DM",
            "id": "1668112842107547653",
            "sender_id": "1655515285577936899",
            "event_type": "MessageCreate"
        }
    ],
    "meta": {
        "result_count": 2
    }
}

Top