Initial commit with translated description
This commit is contained in:
432
INTEGRATION_TOOLS_WORKFLOW.md
Normal file
432
INTEGRATION_TOOLS_WORKFLOW.md
Normal file
@@ -0,0 +1,432 @@
|
||||
# Integration Tools Workflow
|
||||
|
||||
Some integrations require additional data (like IDs, tags, playlists, etc.) before you can post. The CLI supports a complete workflow to discover and use these tools.
|
||||
|
||||
## The Complete Workflow
|
||||
|
||||
### Step 1: List Integrations
|
||||
|
||||
```bash
|
||||
postiz integrations:list
|
||||
```
|
||||
|
||||
Get your integration IDs.
|
||||
|
||||
### Step 2: Get Integration Settings
|
||||
|
||||
```bash
|
||||
postiz integrations:settings <integration-id>
|
||||
```
|
||||
|
||||
This returns:
|
||||
- `maxLength` - Character limit
|
||||
- `settings` - Required/optional fields
|
||||
- **`tools`** - Callable methods to fetch additional data
|
||||
|
||||
### Step 3: Trigger Tools (If Needed)
|
||||
|
||||
If settings require IDs/data you don't have, use the tools:
|
||||
|
||||
```bash
|
||||
postiz integrations:trigger <integration-id> <method-name> -d '{"key":"value"}'
|
||||
```
|
||||
|
||||
### Step 4: Create Post with Complete Settings
|
||||
|
||||
Use the data from Step 3 in your post settings.
|
||||
|
||||
## Real-World Example: Reddit
|
||||
|
||||
### 1. Get Reddit Integration Settings
|
||||
|
||||
```bash
|
||||
postiz integrations:settings reddit-abc123
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"output": {
|
||||
"maxLength": 40000,
|
||||
"settings": {
|
||||
"properties": {
|
||||
"subreddit": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"properties": {
|
||||
"subreddit": { "type": "string" },
|
||||
"title": { "type": "string" },
|
||||
"flair": {
|
||||
"properties": {
|
||||
"id": { "type": "string" } // ← Need flair ID!
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"tools": [
|
||||
{
|
||||
"methodName": "getFlairs",
|
||||
"description": "Get available flairs for a subreddit",
|
||||
"dataSchema": [
|
||||
{
|
||||
"key": "subreddit",
|
||||
"description": "The subreddit name",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"methodName": "searchSubreddits",
|
||||
"description": "Search for subreddits",
|
||||
"dataSchema": [
|
||||
{
|
||||
"key": "query",
|
||||
"description": "Search query",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Get Flairs for the Subreddit
|
||||
|
||||
```bash
|
||||
postiz integrations:trigger reddit-abc123 getFlairs -d '{"subreddit":"programming"}'
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"output": [
|
||||
{
|
||||
"id": "flair-12345",
|
||||
"name": "Discussion"
|
||||
},
|
||||
{
|
||||
"id": "flair-67890",
|
||||
"name": "Tutorial"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Create Post with Flair ID
|
||||
|
||||
```bash
|
||||
postiz posts:create \
|
||||
-c "Check out my project!" \
|
||||
-p reddit \
|
||||
--settings '{
|
||||
"subreddit": [{
|
||||
"value": {
|
||||
"subreddit": "programming",
|
||||
"title": "My Cool Project",
|
||||
"type": "text",
|
||||
"url": "",
|
||||
"is_flair_required": true,
|
||||
"flair": {
|
||||
"id": "flair-12345",
|
||||
"name": "Discussion"
|
||||
}
|
||||
}
|
||||
}]
|
||||
}' \
|
||||
-i "reddit-abc123"
|
||||
```
|
||||
|
||||
## Example: YouTube Playlists
|
||||
|
||||
### 1. Get YouTube Settings
|
||||
|
||||
```bash
|
||||
postiz integrations:settings youtube-123
|
||||
```
|
||||
|
||||
**Output includes tools:**
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"methodName": "getPlaylists",
|
||||
"description": "Get your YouTube playlists",
|
||||
"dataSchema": []
|
||||
},
|
||||
{
|
||||
"methodName": "getCategories",
|
||||
"description": "Get available video categories",
|
||||
"dataSchema": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Get Playlists
|
||||
|
||||
```bash
|
||||
postiz integrations:trigger youtube-123 getPlaylists
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"output": [
|
||||
{
|
||||
"id": "PLxxxxxx",
|
||||
"title": "My Tutorials"
|
||||
},
|
||||
{
|
||||
"id": "PLyyyyyy",
|
||||
"title": "Product Demos"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Post to Specific Playlist
|
||||
|
||||
```bash
|
||||
postiz posts:create \
|
||||
-c "Video description" \
|
||||
-p youtube \
|
||||
--settings '{
|
||||
"title": "My Video",
|
||||
"type": "public",
|
||||
"playlistId": "PLxxxxxx"
|
||||
}' \
|
||||
-i "youtube-123"
|
||||
```
|
||||
|
||||
## Example: LinkedIn Companies
|
||||
|
||||
### 1. Get LinkedIn Settings
|
||||
|
||||
```bash
|
||||
postiz integrations:settings linkedin-123
|
||||
```
|
||||
|
||||
**Output includes tools:**
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"methodName": "getCompanies",
|
||||
"description": "Get companies you can post to",
|
||||
"dataSchema": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Get Companies
|
||||
|
||||
```bash
|
||||
postiz integrations:trigger linkedin-123 getCompanies
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"output": [
|
||||
{
|
||||
"id": "company-123",
|
||||
"name": "My Company"
|
||||
},
|
||||
{
|
||||
"id": "company-456",
|
||||
"name": "Other Company"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Post as Company
|
||||
|
||||
```bash
|
||||
postiz posts:create \
|
||||
-c "Company announcement" \
|
||||
-p linkedin \
|
||||
--settings '{
|
||||
"companyId": "company-123"
|
||||
}' \
|
||||
-i "linkedin-123"
|
||||
```
|
||||
|
||||
## Understanding Tools
|
||||
|
||||
### Tool Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"methodName": "getFlairs",
|
||||
"description": "Get available flairs for a subreddit",
|
||||
"dataSchema": [
|
||||
{
|
||||
"key": "subreddit",
|
||||
"description": "The subreddit name",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- **methodName** - Use this in `integrations:trigger`
|
||||
- **description** - What the tool does
|
||||
- **dataSchema** - Required input parameters
|
||||
|
||||
### Calling Tools
|
||||
|
||||
```bash
|
||||
# No parameters
|
||||
postiz integrations:trigger <integration-id> <methodName>
|
||||
|
||||
# With parameters
|
||||
postiz integrations:trigger <integration-id> <methodName> -d '{"key":"value"}'
|
||||
```
|
||||
|
||||
## Common Tool Methods
|
||||
|
||||
### Reddit
|
||||
- `getFlairs` - Get flairs for a subreddit
|
||||
- `searchSubreddits` - Search for subreddits
|
||||
- `getSubreddits` - Get subscribed subreddits
|
||||
|
||||
### YouTube
|
||||
- `getPlaylists` - Get your playlists
|
||||
- `getCategories` - Get video categories
|
||||
- `getChannels` - Get your channels
|
||||
|
||||
### LinkedIn
|
||||
- `getCompanies` - Get companies you manage
|
||||
- `getOrganizations` - Get organizations
|
||||
|
||||
### Twitter/X
|
||||
- `getListsowned` - Get your Twitter lists
|
||||
- `getCommunities` - Get communities you're in
|
||||
|
||||
### Pinterest
|
||||
- `getBoards` - Get your Pinterest boards
|
||||
- `getBoardSections` - Get sections in a board
|
||||
|
||||
## AI Agent Workflow
|
||||
|
||||
For AI agents, this enables dynamic discovery and usage:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
INTEGRATION_ID="your-integration-id"
|
||||
|
||||
# 1. Get settings and tools
|
||||
SETTINGS=$(postiz integrations:settings "$INTEGRATION_ID")
|
||||
echo "$SETTINGS" | jq '.output.tools'
|
||||
|
||||
# 2. Get tool method names
|
||||
TOOLS=$(echo "$SETTINGS" | jq -r '.output.tools[]?.methodName')
|
||||
|
||||
# 3. Call tools to get required data
|
||||
for METHOD in $TOOLS; do
|
||||
RESULT=$(postiz integrations:trigger "$INTEGRATION_ID" "$METHOD" -d '{}')
|
||||
echo "Tool $METHOD returned: $RESULT"
|
||||
done
|
||||
|
||||
# 4. Create post with complete settings
|
||||
postiz posts:create \
|
||||
-c "Your content" \
|
||||
--settings '{"key": "value"}' \
|
||||
-i "$INTEGRATION_ID"
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Tool Not Found
|
||||
|
||||
```bash
|
||||
postiz integrations:trigger reddit-123 invalidMethod
|
||||
# ❌ Failed to trigger tool: Tool not found
|
||||
```
|
||||
|
||||
### Missing Required Data
|
||||
|
||||
```bash
|
||||
postiz integrations:trigger reddit-123 getFlairs
|
||||
# ❌ Missing required parameter: subreddit
|
||||
```
|
||||
|
||||
### Integration Not Found
|
||||
|
||||
```bash
|
||||
postiz integrations:trigger invalid-id getFlairs
|
||||
# ❌ Failed to trigger tool: Integration not found
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Always check tools first** - Run `integrations:settings` to see available tools
|
||||
2. **Read dataSchema** - Know what parameters each tool needs
|
||||
3. **Parse JSON output** - Use `jq` or similar to extract data
|
||||
4. **Cache results** - Tool results don't change often
|
||||
5. **For AI agents** - Automate the entire workflow
|
||||
|
||||
## Complete Example Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
export POSTIZ_API_KEY=your_key
|
||||
INTEGRATION_ID="reddit-abc123"
|
||||
|
||||
# 1. Get settings
|
||||
echo "📋 Getting settings..."
|
||||
SETTINGS=$(postiz integrations:settings $INTEGRATION_ID)
|
||||
echo $SETTINGS | jq '.output.tools'
|
||||
|
||||
# 2. Get flairs
|
||||
echo ""
|
||||
echo "🏷️ Getting flairs..."
|
||||
FLAIRS=$(postiz integrations:trigger $INTEGRATION_ID getFlairs -d '{"subreddit":"programming"}')
|
||||
FLAIR_ID=$(echo $FLAIRS | jq -r '.output[0].id')
|
||||
FLAIR_NAME=$(echo $FLAIRS | jq -r '.output[0].name')
|
||||
|
||||
echo "Selected flair: $FLAIR_NAME ($FLAIR_ID)"
|
||||
|
||||
# 3. Create post
|
||||
echo ""
|
||||
echo "📝 Creating post..."
|
||||
postiz posts:create \
|
||||
-c "My post content" \
|
||||
-p reddit \
|
||||
--settings "{
|
||||
\"subreddit\": [{
|
||||
\"value\": {
|
||||
\"subreddit\": \"programming\",
|
||||
\"title\": \"My Post Title\",
|
||||
\"type\": \"text\",
|
||||
\"url\": \"\",
|
||||
\"is_flair_required\": true,
|
||||
\"flair\": {
|
||||
\"id\": \"$FLAIR_ID\",
|
||||
\"name\": \"$FLAIR_NAME\"
|
||||
}
|
||||
}
|
||||
}]
|
||||
}" \
|
||||
-i "$INTEGRATION_ID"
|
||||
|
||||
echo "✅ Done!"
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
✅ **Discover available tools** with `integrations:settings`
|
||||
✅ **Call tools** to fetch required data with `integrations:trigger`
|
||||
✅ **Use tool results** in post settings
|
||||
✅ **Complete workflow** from discovery to posting
|
||||
✅ **Perfect for AI agents** - fully automated
|
||||
✅ **No guesswork** - know exactly what data you need
|
||||
|
||||
**The CLI now supports the complete integration tools workflow!** 🎉
|
||||
Reference in New Issue
Block a user