Skip to content

Commit 4d538d1

Browse files
Ang-dotAng-dot
committed
docs: update documentation according to latest virtuals_tweepy
1 parent 642b268 commit 4d538d1

File tree

2 files changed

+121
-69
lines changed

2 files changed

+121
-69
lines changed

‎plugins/twitter/README.md‎

Lines changed: 120 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,151 @@
11
# Twitter Plugin for GAME SDK
22

3-
The Twitter plugin is a lightweight wrapper over commonly-used twitter API calls. It can be used as a executable on its own or by combining multiple of these into an executable.
3+
The **Twitter Plugin** provides a lightweight interface for integrating Twitter (X) functionality into your GAME SDK agents. Built on top of [`virtuals_tweepy`](https://pypi.org/project/virtuals-tweepy/) by the Virtuals team — a maintained fork of [`Tweepy`](https://pypi.org/project/tweepy/)) — this plugin lets you easily post tweets, fetch data, and execute workflows through agent logic.
4+
5+
Use it standalone or compose multiple Twitter actions as part of a larger agent job.
6+
7+
---
48

59
## Installation
610

7-
From this directory (`twitter`), run the installation:
11+
You can install the plugin using either `poetry` or `pip`:
812

913
```bash
14+
# Using Poetry (from the plugin directory)
1015
poetry install
16+
17+
# Or using pip (recommended for integration projects)
18+
pip install twitter_plugin_gamesdk
19+
```
20+
21+
---
22+
23+
## Authentication Methods
24+
25+
We support two primary ways to authenticate:
26+
27+
### 1. GAME's Sponsored X Enterprise Access Token (Recommended)
28+
29+
Virtuals sponsors the community with a **Twitter Enterprise API access plan**, using OAuth 2.0 with PKCE. This provides:
30+
31+
- Higher rate limits: **35 calls / 5 minutes**
32+
- Smoother onboarding
33+
- Free usage via your `GAME_API_KEY`
34+
35+
#### a. Get Your Access Token
36+
37+
Run the following command to authenticate using your `GAME_API_KEY`:
38+
39+
```bash
40+
poetry run twitter-plugin-gamesdk auth -k <GAME_API_KEY>
41+
```
42+
43+
This will prompt:
44+
45+
```bash
46+
Waiting for authentication...
47+
48+
Visit the following URL to authenticate:
49+
https://x.com/i/oauth2/authorize?...
50+
51+
Authenticated! Here's your access token:
52+
apx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
53+
```
54+
55+
#### b. Store Your Access Token
56+
57+
We strongly recommend storing environment variables in a `.env` file:
58+
59+
```
60+
# .env
61+
62+
GAME_TWITTER_ACCESS_TOKEN=apx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
63+
```
64+
65+
Then, use `load_dotenv()` to load them:
66+
67+
```python
68+
import os
69+
from dotenv import load_dotenv
70+
from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
71+
72+
load_dotenv()
73+
74+
options = {
75+
"credentials": {
76+
"game_twitter_access_token": os.environ.get("GAME_TWITTER_ACCESS_TOKEN")
77+
}
78+
}
79+
80+
twitter_plugin = TwitterPlugin(options)
81+
client = twitter_plugin.twitter_client
82+
83+
client.create_tweet(text="Tweeting with GAME Access Token!")
1184
```
1285
13-
## Usage
86+
---
1487
15-
The Twitter plugin can be initialized in one of two ways:
88+
### 2. Use Your Own Twitter Developer Credentials
1689
17-
1. Using GAME's X enterprise API credentials (higher rate limits)
90+
Use this option if you need access to Twitter endpoints requiring a different auth level (e.g., **OAuth 1.0a User Context** or **OAuth 2.0 App Only**).
1891
19-
- To get the access token for this option, run the following command:
92+
> See [X API Auth Mapping](https://docs.x.com/resources/fundamentals/authentication/guides/v2-authentication-mapping) to determine which auth level is required for specific endpoints.
2093
21-
```bash
22-
poetry run twitter-plugin-gamesdk auth -k <GAME_API_KEY>
23-
```
94+
#### a. Get Your Developer Credentials
2495
25-
You will see the following output:
96+
1. Sign in to the [Twitter Developer Portal](https://developer.x.com/en/portal/dashboard).
97+
2. Create a project and app.
98+
3. Generate the following keys and store them in your `.env` file:
2699
27-
```bash
28-
Waiting for authentication...
100+
```
101+
# .env
29102
30-
Visit the following URL to authenticate:
31-
https://x.com/i/oauth2/authorize?response_type=code&client_id=VVdyZ0t4WFFRMjBlMzVaczZyMzU6MTpjaQ&redirect_uri=http%3A%2F%2Flocalhost%3A8714%2Fcallback&state=866c82c0-e3f6-444e-a2de-e58bcc95f08b&code_challenge=K47t-0Mcl8B99ufyqmwJYZFB56fiXiZf7f3euQ4H2_0&code_challenge_method=s256&scope=tweet.read%20tweet.write%20users.read%20offline.access
32-
```
103+
TWITTER_API_KEY=...
104+
TWITTER_API_SECRET_KEY=...
105+
TWITTER_ACCESS_TOKEN=...
106+
TWITTER_ACCESS_TOKEN_SECRET=...
107+
```
33108
34-
After authenticating, you will receive the following message:
109+
#### b. Initialize the Plugin
35110
36-
```bash
37-
Authenticated! Here's your access token:
38-
apx-<xxx>
39-
```
111+
```python
112+
import os
113+
from dotenv import load_dotenv
114+
from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
40115
41-
- Set the access token as an environment variable called `GAME_TWITTER_ACCESS_TOKEN` (e.g. using a `.bashrc` or a `.zshrc` file).
42-
- Import and initialize the plugin to use in your worker:
116+
load_dotenv()
43117
44-
```python
45-
import os
46-
from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
118+
options = {
119+
"credentials": {
120+
"api_key": os.environ.get("TWITTER_API_KEY"),
121+
"api_key_secret": os.environ.get("TWITTER_API_SECRET_KEY"),
122+
"access_token": os.environ.get("TWITTER_ACCESS_TOKEN"),
123+
"access_token_secret": os.environ.get("TWITTER_ACCESS_TOKEN_SECRET"),
124+
}
125+
}
47126
48-
# Define your options with the necessary credentials
49-
options = {
50-
"credentials": {
51-
"gameTwitterAccessToken": os.environ.get("GAME_TWITTER_ACCESS_TOKEN")
52-
},
53-
}
54-
# Initialize the TwitterPlugin with your options
55-
twitter_plugin = TwitterPlugin(options)
127+
twitter_plugin = TwitterPlugin(options)
128+
client = twitter_plugin.twitter_client
56129
57-
# Post a tweet
58-
post_tweet_fn = twitter_plugin.get_function('post_tweet')
59-
post_tweet_fn("Hello world!")
60-
```
130+
client.create_tweet(text="Tweeting with personal developer credentials!")
131+
```
61132
62-
2. Using your own X API credentials
133+
---
63134
64-
- If you don't already have one, create a X (twitter) account and navigate to the [developer portal](https://developer.x.com/en/portal/dashboard).
65-
- Create a project app, generate the following credentials and set them as environment variables (e.g. using a `.bashrc` or a `.zshrc` file):
66-
- `TWITTER_BEARER_TOKEN`
67-
- `TWITTER_API_KEY`
68-
- `TWITTER_API_SECRET_KEY`
69-
- `TWITTER_ACCESS_TOKEN`
70-
- `TWITTER_ACCESS_TOKEN_SECRET`
71-
- Import and initialize the plugin to use in your worker:
135+
## Examples
72136
73-
```python
74-
import os
75-
from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
137+
Explore the [`examples/`](./examples) directory for sample scripts demonstrating how to:
76138
77-
# Define your options with the necessary credentials
78-
options = {
79-
"credentials": {
80-
"bearerToken": os.environ.get("TWITTER_BEARER_TOKEN"),
81-
"apiKey": os.environ.get("TWITTER_API_KEY"),
82-
"apiSecretKey": os.environ.get("TWITTER_API_SECRET_KEY"),
83-
"accessToken": os.environ.get("TWITTER_ACCESS_TOKEN"),
84-
"accessTokenSecret": os.environ.get("TWITTER_ACCESS_TOKEN_SECRET"),
85-
},
86-
}
87-
# Initialize the TwitterPlugin with your options
88-
twitter_plugin = TwitterPlugin(options)
139+
- Post tweets
140+
- Reply to mentions
141+
- Quote tweets
142+
- Fetch user timelines
143+
- And more!
89144
90-
# Post a tweet
91-
post_tweet_fn = twitter_plugin.twitter_client.create_tweet
92-
post_tweet_fn(text="Hello world! This is a test tweet from the Twitter Plugin!")
93-
```
145+
---
94146
95-
For detailed documentation on each function's parameters and usage, please refer to the [Tweepy Client Documentation](https://docs.tweepy.org/en/stable/client.html).
147+
## API Reference
96148
97-
Example usage:
149+
This plugin wraps [`virtuals_tweepy`](https://pypi.org/project/virtuals-tweepy/), which is API-compatible with [Tweepy’s client interface](https://docs.tweepy.org/en/stable/client.html). Refer to their docs for supported methods and parameters.
98150
99-
You can refer to the example files in the `examples` directory for more examples on how to call the twitter functions.
151+
---

‎plugins/twitter/examples/test_twitter.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ def run_twitter_actions():
2020
# },
2121
# }
2222

23-
# Option B: Using GAME Twitter API credentials
23+
# Option B: Using GAME Twitter API Access Token (Recommended, higher rate limits: 35 calls/5 minutes)
2424
options = {
2525
"credentials": {
2626
"game_twitter_access_token": token

0 commit comments

Comments
 (0)