@skillful-ai/piece-skai-adapters 0.0.3 → 0.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,325 +1,325 @@
|
|
|
1
|
-
# SKAI Adapters Piece
|
|
2
|
-
|
|
3
|
-
Transform messages between messaging platforms and SKAI Agents API.
|
|
4
|
-
|
|
5
|
-
## Overview
|
|
6
|
-
|
|
7
|
-
The SKAI Adapters piece acts as a bridge between messaging platforms (WhatsApp, Telegram, Discord, etc.) and SKAI Agents. It provides:
|
|
8
|
-
|
|
9
|
-
- **Platform-agnostic message format** - GenericMessage interface
|
|
10
|
-
- **Bidirectional transformations** - Platform ↔ SKAI
|
|
11
|
-
- **SKAI API integration** - Direct communication with SKAI Agents
|
|
12
|
-
- **Agent dropdown** - Dynamic agent selection from your SKAI account
|
|
13
|
-
|
|
14
|
-
## Architecture
|
|
15
|
-
|
|
16
|
-
```
|
|
17
|
-
Platform Message → Adapter (Transform) → SKAI Agent → Adapter (Transform) → Platform Message
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
### GenericMessage Format
|
|
21
|
-
|
|
22
|
-
All platform messages are transformed to this unified format:
|
|
23
|
-
|
|
24
|
-
```typescript
|
|
25
|
-
interface GenericMessage {
|
|
26
|
-
external_id: string; // Platform identifier (phone, chat ID, etc.)
|
|
27
|
-
platform: Platform; // 'whatsapp' | 'telegram' | 'discord'
|
|
28
|
-
message: string; // Text content
|
|
29
|
-
reference_id?: string; // Platform's message ID
|
|
30
|
-
media_urls?: string[]; // Media attachments
|
|
31
|
-
media_types?: MediaType[]; // Types of media
|
|
32
|
-
sender_name?: string; // Display name
|
|
33
|
-
metadata?: Record<string, any>; // Platform-specific data
|
|
34
|
-
timestamp?: string; // ISO 8601 timestamp
|
|
35
|
-
}
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
## Actions
|
|
39
|
-
|
|
40
|
-
### WhatsApp → SKAI Agent
|
|
41
|
-
|
|
42
|
-
Transform WhatsApp message and process with SKAI agent.
|
|
43
|
-
|
|
44
|
-
**Inputs:**
|
|
45
|
-
- WhatsApp Message (JSON) - Output from WhatsApp New Message trigger
|
|
46
|
-
- Environment - Production/Development/Staging
|
|
47
|
-
- SKAI Agent - Select from dropdown
|
|
48
|
-
- Include Raw Metadata - Optional
|
|
49
|
-
|
|
50
|
-
**Output:**
|
|
51
|
-
```json
|
|
52
|
-
{
|
|
53
|
-
"success": true,
|
|
54
|
-
"skaiResponse": {
|
|
55
|
-
"success": true,
|
|
56
|
-
"response": "Agent's reply",
|
|
57
|
-
"conversationId": "conv_123"
|
|
58
|
-
},
|
|
59
|
-
"genericMessage": { /* Transformed message */ },
|
|
60
|
-
"originalPlatform": "whatsapp"
|
|
61
|
-
}
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
### SKAI → WhatsApp
|
|
65
|
-
|
|
66
|
-
Transform SKAI agent response back to WhatsApp format.
|
|
67
|
-
|
|
68
|
-
**Inputs:**
|
|
69
|
-
- SKAI Response (JSON) - Output from WhatsApp → SKAI action
|
|
70
|
-
- Include Conversation ID - Add as footer
|
|
71
|
-
- Custom Footer - Optional custom text
|
|
72
|
-
|
|
73
|
-
**Output:**
|
|
74
|
-
```json
|
|
75
|
-
{
|
|
76
|
-
"to": "+1234567890",
|
|
77
|
-
"text": "Agent's formatted response",
|
|
78
|
-
"conversationId": "conv_123",
|
|
79
|
-
"metadata": { /* Additional data */ }
|
|
80
|
-
}
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
## Setup
|
|
84
|
-
|
|
85
|
-
### Prerequisites
|
|
86
|
-
|
|
87
|
-
1. **SKAI Account** - Sign up at [agents.skillfulai.io](https://agents.skillfulai.io)
|
|
88
|
-
2. **SKAI API Key** - Generate from Settings → API Keys
|
|
89
|
-
3. **SKAI Agent** - Create at least one agent
|
|
90
|
-
|
|
91
|
-
### Getting SKAI API Key
|
|
92
|
-
|
|
93
|
-
1. Log in to [SKAI Agents Platform](https://agents.skillfulai.io)
|
|
94
|
-
2. Navigate to Settings → API Keys
|
|
95
|
-
3. Click "Create New API Key"
|
|
96
|
-
4. Copy the key (starts with `sk_`)
|
|
97
|
-
5. Paste into ActivePieces when configuring SKAI Adapters
|
|
98
|
-
|
|
99
|
-
## Usage Examples
|
|
100
|
-
|
|
101
|
-
### Example 1: WhatsApp Auto-Reply with SKAI
|
|
102
|
-
|
|
103
|
-
```
|
|
104
|
-
1. TRIGGER: WhatsApp - New Message
|
|
105
|
-
└─ Output: WhatsApp message
|
|
106
|
-
|
|
107
|
-
2. ACTION: WhatsApp → SKAI Agent
|
|
108
|
-
└─ Input: {{trigger.output}}
|
|
109
|
-
└─ Agent: Customer Support Agent
|
|
110
|
-
└─ Environment: Production
|
|
111
|
-
└─ Output: SKAI response
|
|
112
|
-
|
|
113
|
-
3. ACTION: SKAI → WhatsApp
|
|
114
|
-
└─ Input: {{step2.output}}
|
|
115
|
-
└─ Include Conversation ID: Yes
|
|
116
|
-
└─ Output: Formatted message
|
|
117
|
-
|
|
118
|
-
4. ACTION: WhatsApp - Send Message
|
|
119
|
-
└─ To: {{step3.to}}
|
|
120
|
-
└─ Message: {{step3.text}}
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
### Example 2: Multi-Platform Support
|
|
124
|
-
|
|
125
|
-
**Flow for WhatsApp:**
|
|
126
|
-
```
|
|
127
|
-
WhatsApp New Message
|
|
128
|
-
→ WhatsApp → SKAI
|
|
129
|
-
→ SKAI → WhatsApp
|
|
130
|
-
→ WhatsApp Send Message
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
**Flow for Telegram** (coming soon):
|
|
134
|
-
```
|
|
135
|
-
Telegram New Message
|
|
136
|
-
→ Telegram → SKAI
|
|
137
|
-
→ SKAI → Telegram
|
|
138
|
-
→ Telegram Send Message
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
**Same agent, different platforms!**
|
|
142
|
-
|
|
143
|
-
### Example 3: Conditional Responses
|
|
144
|
-
|
|
145
|
-
```
|
|
146
|
-
1. TRIGGER: WhatsApp - New Message
|
|
147
|
-
|
|
148
|
-
2. ACTION: Code - Check Keywords
|
|
149
|
-
└─ If message contains "urgent"
|
|
150
|
-
|
|
151
|
-
3. BRANCH:
|
|
152
|
-
a) If Urgent:
|
|
153
|
-
WhatsApp → SKAI (Priority Agent)
|
|
154
|
-
|
|
155
|
-
b) If Normal:
|
|
156
|
-
WhatsApp → SKAI (Standard Agent)
|
|
157
|
-
|
|
158
|
-
4. ACTION: SKAI → WhatsApp
|
|
159
|
-
5. ACTION: WhatsApp - Send Message
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
## Supported Platforms
|
|
163
|
-
|
|
164
|
-
### Currently Supported
|
|
165
|
-
- ✅ WhatsApp Business
|
|
166
|
-
|
|
167
|
-
### Coming Soon
|
|
168
|
-
- 🔜 Telegram
|
|
169
|
-
- 🔜 Discord
|
|
170
|
-
- 🔜 SMS (Twilio)
|
|
171
|
-
- 🔜 Slack
|
|
172
|
-
|
|
173
|
-
## Message Type Support
|
|
174
|
-
|
|
175
|
-
### WhatsApp
|
|
176
|
-
- ✅ Text messages
|
|
177
|
-
- ✅ Images (with captions)
|
|
178
|
-
- ✅ Videos (with captions)
|
|
179
|
-
- ✅ Audio messages
|
|
180
|
-
- ✅ Documents
|
|
181
|
-
- ✅ Voice messages
|
|
182
|
-
|
|
183
|
-
All media information is preserved in `genericMessage.metadata`.
|
|
184
|
-
|
|
185
|
-
## API Integration
|
|
186
|
-
|
|
187
|
-
### SKAI Agents API
|
|
188
|
-
|
|
189
|
-
**Endpoints:**
|
|
190
|
-
- `GET /agents` - List user's agents
|
|
191
|
-
- `POST /agents/{id}/process` - Process message with agent
|
|
192
|
-
|
|
193
|
-
**Environments:**
|
|
194
|
-
- Production: `https://api-production.agents.skillfulai.io`
|
|
195
|
-
- Development: `https://api-development.agents.skillfulai.io`
|
|
196
|
-
- Staging: `https://api-staging.agents.skillfulai.io`
|
|
197
|
-
|
|
198
|
-
### Authentication
|
|
199
|
-
|
|
200
|
-
All requests use Bearer token authentication:
|
|
201
|
-
```
|
|
202
|
-
Authorization: Bearer sk_your_api_key_here
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
## Error Handling
|
|
206
|
-
|
|
207
|
-
### Common Errors
|
|
208
|
-
|
|
209
|
-
**"SKAI API error (401)"**
|
|
210
|
-
- Invalid API key
|
|
211
|
-
- API key expired
|
|
212
|
-
- Solution: Regenerate API key in SKAI platform
|
|
213
|
-
|
|
214
|
-
**"SKAI API error (404)"**
|
|
215
|
-
- Agent not found
|
|
216
|
-
- Agent ID invalid
|
|
217
|
-
- Solution: Verify agent exists and is minted
|
|
218
|
-
|
|
219
|
-
**"Failed to fetch agents"**
|
|
220
|
-
- Network issue
|
|
221
|
-
- API key missing
|
|
222
|
-
- Solution: Check authentication and network
|
|
223
|
-
|
|
224
|
-
**"Invalid WhatsApp message: missing required fields"**
|
|
225
|
-
- Malformed input
|
|
226
|
-
- Missing `from` or `messageId`
|
|
227
|
-
- Solution: Ensure WhatsApp trigger output is used
|
|
228
|
-
|
|
229
|
-
### Debugging
|
|
230
|
-
|
|
231
|
-
Enable detailed logging by checking ActivePieces logs:
|
|
232
|
-
```
|
|
233
|
-
✅ Message transformed
|
|
234
|
-
✅ SKAI API response received
|
|
235
|
-
❌ SKAI API error: ...
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
## Advanced Features
|
|
239
|
-
|
|
240
|
-
### Custom Transformers
|
|
241
|
-
|
|
242
|
-
To add support for new platforms, create a transformer:
|
|
243
|
-
|
|
244
|
-
```typescript
|
|
245
|
-
import { GenericMessage, Platform } from '../common/types/generic-message';
|
|
246
|
-
|
|
247
|
-
export class TelegramTransformer {
|
|
248
|
-
transform(telegramMessage: any): GenericMessage {
|
|
249
|
-
return {
|
|
250
|
-
external_id: telegramMessage.chatId,
|
|
251
|
-
platform: Platform.TELEGRAM,
|
|
252
|
-
message: telegramMessage.text,
|
|
253
|
-
// ... other fields
|
|
254
|
-
};
|
|
255
|
-
}
|
|
256
|
-
}
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
### Metadata Preservation
|
|
260
|
-
|
|
261
|
-
All platform-specific metadata is preserved:
|
|
262
|
-
|
|
263
|
-
```javascript
|
|
264
|
-
// WhatsApp metadata includes:
|
|
265
|
-
{
|
|
266
|
-
type: 'image',
|
|
267
|
-
timestamp: '1642511234',
|
|
268
|
-
image: {
|
|
269
|
-
id: 'img_123',
|
|
270
|
-
mimeType: 'image/jpeg',
|
|
271
|
-
caption: 'Check this out!'
|
|
272
|
-
}
|
|
273
|
-
}
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
## Building
|
|
277
|
-
|
|
278
|
-
```bash
|
|
279
|
-
# Build the piece
|
|
280
|
-
npx nx build pieces-skai-adapters
|
|
281
|
-
|
|
282
|
-
# Build all custom pieces
|
|
283
|
-
npx nx run-many -t build --projects=pieces-*
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
## Testing
|
|
287
|
-
|
|
288
|
-
```bash
|
|
289
|
-
# Run unit tests (coming soon)
|
|
290
|
-
npx nx test pieces-skai-adapters
|
|
291
|
-
|
|
292
|
-
# Manual testing
|
|
293
|
-
1. Create test flow in ActivePieces
|
|
294
|
-
2. Send test message from platform
|
|
295
|
-
3. Verify transformation and SKAI response
|
|
296
|
-
4. Check logs for detailed output
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
## Contributing
|
|
300
|
-
|
|
301
|
-
To add support for a new platform:
|
|
302
|
-
|
|
303
|
-
1. Create transformer in `src/lib/transformers/`
|
|
304
|
-
2. Create actions in `src/lib/actions/`
|
|
305
|
-
3. Update `src/index.ts`
|
|
306
|
-
4. Add tests
|
|
307
|
-
5. Update README
|
|
308
|
-
|
|
309
|
-
## Version
|
|
310
|
-
|
|
311
|
-
Current version: 0.0.1
|
|
312
|
-
|
|
313
|
-
## Authors
|
|
314
|
-
|
|
315
|
-
Skillful AI
|
|
316
|
-
|
|
317
|
-
## Support
|
|
318
|
-
|
|
319
|
-
- **Documentation**: [SKAI Agents Docs](https://docs.skillfulai.io)
|
|
320
|
-
- **Issues**: Report bugs in ActivePieces repository
|
|
321
|
-
- **API Status**: [status.skillfulai.io](https://status.skillfulai.io)
|
|
322
|
-
|
|
323
|
-
## License
|
|
324
|
-
|
|
325
|
-
MIT
|
|
1
|
+
# SKAI Adapters Piece
|
|
2
|
+
|
|
3
|
+
Transform messages between messaging platforms and SKAI Agents API.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
The SKAI Adapters piece acts as a bridge between messaging platforms (WhatsApp, Telegram, Discord, etc.) and SKAI Agents. It provides:
|
|
8
|
+
|
|
9
|
+
- **Platform-agnostic message format** - GenericMessage interface
|
|
10
|
+
- **Bidirectional transformations** - Platform ↔ SKAI
|
|
11
|
+
- **SKAI API integration** - Direct communication with SKAI Agents
|
|
12
|
+
- **Agent dropdown** - Dynamic agent selection from your SKAI account
|
|
13
|
+
|
|
14
|
+
## Architecture
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
Platform Message → Adapter (Transform) → SKAI Agent → Adapter (Transform) → Platform Message
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### GenericMessage Format
|
|
21
|
+
|
|
22
|
+
All platform messages are transformed to this unified format:
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
interface GenericMessage {
|
|
26
|
+
external_id: string; // Platform identifier (phone, chat ID, etc.)
|
|
27
|
+
platform: Platform; // 'whatsapp' | 'telegram' | 'discord'
|
|
28
|
+
message: string; // Text content
|
|
29
|
+
reference_id?: string; // Platform's message ID
|
|
30
|
+
media_urls?: string[]; // Media attachments
|
|
31
|
+
media_types?: MediaType[]; // Types of media
|
|
32
|
+
sender_name?: string; // Display name
|
|
33
|
+
metadata?: Record<string, any>; // Platform-specific data
|
|
34
|
+
timestamp?: string; // ISO 8601 timestamp
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Actions
|
|
39
|
+
|
|
40
|
+
### WhatsApp → SKAI Agent
|
|
41
|
+
|
|
42
|
+
Transform WhatsApp message and process with SKAI agent.
|
|
43
|
+
|
|
44
|
+
**Inputs:**
|
|
45
|
+
- WhatsApp Message (JSON) - Output from WhatsApp New Message trigger
|
|
46
|
+
- Environment - Production/Development/Staging
|
|
47
|
+
- SKAI Agent - Select from dropdown
|
|
48
|
+
- Include Raw Metadata - Optional
|
|
49
|
+
|
|
50
|
+
**Output:**
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"success": true,
|
|
54
|
+
"skaiResponse": {
|
|
55
|
+
"success": true,
|
|
56
|
+
"response": "Agent's reply",
|
|
57
|
+
"conversationId": "conv_123"
|
|
58
|
+
},
|
|
59
|
+
"genericMessage": { /* Transformed message */ },
|
|
60
|
+
"originalPlatform": "whatsapp"
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### SKAI → WhatsApp
|
|
65
|
+
|
|
66
|
+
Transform SKAI agent response back to WhatsApp format.
|
|
67
|
+
|
|
68
|
+
**Inputs:**
|
|
69
|
+
- SKAI Response (JSON) - Output from WhatsApp → SKAI action
|
|
70
|
+
- Include Conversation ID - Add as footer
|
|
71
|
+
- Custom Footer - Optional custom text
|
|
72
|
+
|
|
73
|
+
**Output:**
|
|
74
|
+
```json
|
|
75
|
+
{
|
|
76
|
+
"to": "+1234567890",
|
|
77
|
+
"text": "Agent's formatted response",
|
|
78
|
+
"conversationId": "conv_123",
|
|
79
|
+
"metadata": { /* Additional data */ }
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Setup
|
|
84
|
+
|
|
85
|
+
### Prerequisites
|
|
86
|
+
|
|
87
|
+
1. **SKAI Account** - Sign up at [agents.skillfulai.io](https://agents.skillfulai.io)
|
|
88
|
+
2. **SKAI API Key** - Generate from Settings → API Keys
|
|
89
|
+
3. **SKAI Agent** - Create at least one agent
|
|
90
|
+
|
|
91
|
+
### Getting SKAI API Key
|
|
92
|
+
|
|
93
|
+
1. Log in to [SKAI Agents Platform](https://agents.skillfulai.io)
|
|
94
|
+
2. Navigate to Settings → API Keys
|
|
95
|
+
3. Click "Create New API Key"
|
|
96
|
+
4. Copy the key (starts with `sk_`)
|
|
97
|
+
5. Paste into ActivePieces when configuring SKAI Adapters
|
|
98
|
+
|
|
99
|
+
## Usage Examples
|
|
100
|
+
|
|
101
|
+
### Example 1: WhatsApp Auto-Reply with SKAI
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
1. TRIGGER: WhatsApp - New Message
|
|
105
|
+
└─ Output: WhatsApp message
|
|
106
|
+
|
|
107
|
+
2. ACTION: WhatsApp → SKAI Agent
|
|
108
|
+
└─ Input: {{trigger.output}}
|
|
109
|
+
└─ Agent: Customer Support Agent
|
|
110
|
+
└─ Environment: Production
|
|
111
|
+
└─ Output: SKAI response
|
|
112
|
+
|
|
113
|
+
3. ACTION: SKAI → WhatsApp
|
|
114
|
+
└─ Input: {{step2.output}}
|
|
115
|
+
└─ Include Conversation ID: Yes
|
|
116
|
+
└─ Output: Formatted message
|
|
117
|
+
|
|
118
|
+
4. ACTION: WhatsApp - Send Message
|
|
119
|
+
└─ To: {{step3.to}}
|
|
120
|
+
└─ Message: {{step3.text}}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Example 2: Multi-Platform Support
|
|
124
|
+
|
|
125
|
+
**Flow for WhatsApp:**
|
|
126
|
+
```
|
|
127
|
+
WhatsApp New Message
|
|
128
|
+
→ WhatsApp → SKAI
|
|
129
|
+
→ SKAI → WhatsApp
|
|
130
|
+
→ WhatsApp Send Message
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
**Flow for Telegram** (coming soon):
|
|
134
|
+
```
|
|
135
|
+
Telegram New Message
|
|
136
|
+
→ Telegram → SKAI
|
|
137
|
+
→ SKAI → Telegram
|
|
138
|
+
→ Telegram Send Message
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
**Same agent, different platforms!**
|
|
142
|
+
|
|
143
|
+
### Example 3: Conditional Responses
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
1. TRIGGER: WhatsApp - New Message
|
|
147
|
+
|
|
148
|
+
2. ACTION: Code - Check Keywords
|
|
149
|
+
└─ If message contains "urgent"
|
|
150
|
+
|
|
151
|
+
3. BRANCH:
|
|
152
|
+
a) If Urgent:
|
|
153
|
+
WhatsApp → SKAI (Priority Agent)
|
|
154
|
+
|
|
155
|
+
b) If Normal:
|
|
156
|
+
WhatsApp → SKAI (Standard Agent)
|
|
157
|
+
|
|
158
|
+
4. ACTION: SKAI → WhatsApp
|
|
159
|
+
5. ACTION: WhatsApp - Send Message
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## Supported Platforms
|
|
163
|
+
|
|
164
|
+
### Currently Supported
|
|
165
|
+
- ✅ WhatsApp Business
|
|
166
|
+
|
|
167
|
+
### Coming Soon
|
|
168
|
+
- 🔜 Telegram
|
|
169
|
+
- 🔜 Discord
|
|
170
|
+
- 🔜 SMS (Twilio)
|
|
171
|
+
- 🔜 Slack
|
|
172
|
+
|
|
173
|
+
## Message Type Support
|
|
174
|
+
|
|
175
|
+
### WhatsApp
|
|
176
|
+
- ✅ Text messages
|
|
177
|
+
- ✅ Images (with captions)
|
|
178
|
+
- ✅ Videos (with captions)
|
|
179
|
+
- ✅ Audio messages
|
|
180
|
+
- ✅ Documents
|
|
181
|
+
- ✅ Voice messages
|
|
182
|
+
|
|
183
|
+
All media information is preserved in `genericMessage.metadata`.
|
|
184
|
+
|
|
185
|
+
## API Integration
|
|
186
|
+
|
|
187
|
+
### SKAI Agents API
|
|
188
|
+
|
|
189
|
+
**Endpoints:**
|
|
190
|
+
- `GET /agents` - List user's agents
|
|
191
|
+
- `POST /agents/{id}/process` - Process message with agent
|
|
192
|
+
|
|
193
|
+
**Environments:**
|
|
194
|
+
- Production: `https://api-production.agents.skillfulai.io`
|
|
195
|
+
- Development: `https://api-development.agents.skillfulai.io`
|
|
196
|
+
- Staging: `https://api-staging.agents.skillfulai.io`
|
|
197
|
+
|
|
198
|
+
### Authentication
|
|
199
|
+
|
|
200
|
+
All requests use Bearer token authentication:
|
|
201
|
+
```
|
|
202
|
+
Authorization: Bearer sk_your_api_key_here
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## Error Handling
|
|
206
|
+
|
|
207
|
+
### Common Errors
|
|
208
|
+
|
|
209
|
+
**"SKAI API error (401)"**
|
|
210
|
+
- Invalid API key
|
|
211
|
+
- API key expired
|
|
212
|
+
- Solution: Regenerate API key in SKAI platform
|
|
213
|
+
|
|
214
|
+
**"SKAI API error (404)"**
|
|
215
|
+
- Agent not found
|
|
216
|
+
- Agent ID invalid
|
|
217
|
+
- Solution: Verify agent exists and is minted
|
|
218
|
+
|
|
219
|
+
**"Failed to fetch agents"**
|
|
220
|
+
- Network issue
|
|
221
|
+
- API key missing
|
|
222
|
+
- Solution: Check authentication and network
|
|
223
|
+
|
|
224
|
+
**"Invalid WhatsApp message: missing required fields"**
|
|
225
|
+
- Malformed input
|
|
226
|
+
- Missing `from` or `messageId`
|
|
227
|
+
- Solution: Ensure WhatsApp trigger output is used
|
|
228
|
+
|
|
229
|
+
### Debugging
|
|
230
|
+
|
|
231
|
+
Enable detailed logging by checking ActivePieces logs:
|
|
232
|
+
```
|
|
233
|
+
✅ Message transformed
|
|
234
|
+
✅ SKAI API response received
|
|
235
|
+
❌ SKAI API error: ...
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## Advanced Features
|
|
239
|
+
|
|
240
|
+
### Custom Transformers
|
|
241
|
+
|
|
242
|
+
To add support for new platforms, create a transformer:
|
|
243
|
+
|
|
244
|
+
```typescript
|
|
245
|
+
import { GenericMessage, Platform } from '../common/types/generic-message';
|
|
246
|
+
|
|
247
|
+
export class TelegramTransformer {
|
|
248
|
+
transform(telegramMessage: any): GenericMessage {
|
|
249
|
+
return {
|
|
250
|
+
external_id: telegramMessage.chatId,
|
|
251
|
+
platform: Platform.TELEGRAM,
|
|
252
|
+
message: telegramMessage.text,
|
|
253
|
+
// ... other fields
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
### Metadata Preservation
|
|
260
|
+
|
|
261
|
+
All platform-specific metadata is preserved:
|
|
262
|
+
|
|
263
|
+
```javascript
|
|
264
|
+
// WhatsApp metadata includes:
|
|
265
|
+
{
|
|
266
|
+
type: 'image',
|
|
267
|
+
timestamp: '1642511234',
|
|
268
|
+
image: {
|
|
269
|
+
id: 'img_123',
|
|
270
|
+
mimeType: 'image/jpeg',
|
|
271
|
+
caption: 'Check this out!'
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
## Building
|
|
277
|
+
|
|
278
|
+
```bash
|
|
279
|
+
# Build the piece
|
|
280
|
+
npx nx build pieces-skai-adapters
|
|
281
|
+
|
|
282
|
+
# Build all custom pieces
|
|
283
|
+
npx nx run-many -t build --projects=pieces-*
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
## Testing
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
# Run unit tests (coming soon)
|
|
290
|
+
npx nx test pieces-skai-adapters
|
|
291
|
+
|
|
292
|
+
# Manual testing
|
|
293
|
+
1. Create test flow in ActivePieces
|
|
294
|
+
2. Send test message from platform
|
|
295
|
+
3. Verify transformation and SKAI response
|
|
296
|
+
4. Check logs for detailed output
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
## Contributing
|
|
300
|
+
|
|
301
|
+
To add support for a new platform:
|
|
302
|
+
|
|
303
|
+
1. Create transformer in `src/lib/transformers/`
|
|
304
|
+
2. Create actions in `src/lib/actions/`
|
|
305
|
+
3. Update `src/index.ts`
|
|
306
|
+
4. Add tests
|
|
307
|
+
5. Update README
|
|
308
|
+
|
|
309
|
+
## Version
|
|
310
|
+
|
|
311
|
+
Current version: 0.0.1
|
|
312
|
+
|
|
313
|
+
## Authors
|
|
314
|
+
|
|
315
|
+
Skillful AI
|
|
316
|
+
|
|
317
|
+
## Support
|
|
318
|
+
|
|
319
|
+
- **Documentation**: [SKAI Agents Docs](https://docs.skillfulai.io)
|
|
320
|
+
- **Issues**: Report bugs in ActivePieces repository
|
|
321
|
+
- **API Status**: [status.skillfulai.io](https://status.skillfulai.io)
|
|
322
|
+
|
|
323
|
+
## License
|
|
324
|
+
|
|
325
|
+
MIT
|
package/package.json
CHANGED
|
Binary file
|
|
@@ -62,10 +62,11 @@ exports.skaiResponseWebhook = (0, pieces_framework_1.createTrigger)({
|
|
|
62
62
|
const baseUrl = serverUrl.endsWith('/') ? serverUrl : serverUrl + '/';
|
|
63
63
|
console.log('Validating token against:', baseUrl);
|
|
64
64
|
// Make a lightweight API call to verify the token
|
|
65
|
-
// Using /
|
|
65
|
+
// Using /v1/users/me as a fast auth verification endpoint
|
|
66
|
+
// Note: publicUrl already includes /api/, so we don't need to add it again
|
|
66
67
|
const response = yield pieces_common_1.httpClient.sendRequest({
|
|
67
68
|
method: pieces_common_1.HttpMethod.GET,
|
|
68
|
-
url: `${baseUrl}
|
|
69
|
+
url: `${baseUrl}v1/users/me`,
|
|
69
70
|
authentication: {
|
|
70
71
|
type: pieces_common_1.AuthenticationType.BEARER_TOKEN,
|
|
71
72
|
token: token,
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"skai-response-webhook.js","sourceRoot":"","sources":["../../../../../../../../packages/pieces/custom/skai-adapters/src/lib/triggers/skai-response-webhook.ts"],"names":[],"mappings":";;;;AAAA,qEAA0F;AAC1F,+DAAyF;AACzF,iDAAuD;AAe1C,QAAA,mBAAmB,GAAG,IAAA,gCAAa,EAAC;IAChD,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EAAE,uBAAuB;IACpC,WAAW,EAAE,uFAAuF;IAEpG,IAAI,EAAE,kCAAe,CAAC,OAAO;IAE7B,KAAK,EAAE;QACN,UAAU,EAAE,2BAAQ,CAAC,QAAQ,CAAC;YAC7B,KAAK,EAAE;;;;CAIT;YACE,OAAO,EAAE,wBAAe,CAAC,IAAI;SAC7B,CAAC;KACF;IAEK,QAAQ,CAAC,OAAO;;YACrB,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;YAC3D,OAAO;QACR,CAAC;KAAA;IAEK,SAAS,CAAC,OAAO;;YACtB,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,CAAS,aAAa,CAAC,CAAC;YAClE,IAAI,UAAU,EAAE,CAAC;gBAChB,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,UAAU,CAAC,CAAC;YACtD,CAAC;YACD,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;YAE7C,OAAO;QACR,CAAC;KAAA;IAEK,GAAG,CAAC,OAAO;;;YAChB,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;YAEjD,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAE9C,CAAC;YAEb,IAAI,CAAC,UAAU,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CACd,6EAA6E,CAC7E,CAAC;YACH,CAAC;YAED,+BAA+B;YAC/B,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;gBACrD,MAAM,IAAI,KAAK,CACd,iEAAiE,CACjE,CAAC;YACH,CAAC;YAED,0CAA0C;YAC1C,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAE7C,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAClC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAC/D,CAAC;YAED,OAAO,CAAC,GAAG,CAAC,oDAAoD,CAAC,CAAC;YAElE,6CAA6C;YAC7C,IAAI,CAAC;gBACJ,kCAAkC;gBAClC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC;gBAE3C,yBAAyB;gBACzB,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC;gBAEtE,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,OAAO,CAAC,CAAC;gBAElD,kDAAkD;gBAClD,2EAA2E;gBAC3E,MAAM,QAAQ,GAAG,MAAM,0BAAU,CAAC,WAAW,CAAC;oBAC7C,MAAM,EAAE,0BAAU,CAAC,GAAG;oBACtB,GAAG,EAAE,GAAG,OAAO,
|
|
1
|
+
{"version":3,"file":"skai-response-webhook.js","sourceRoot":"","sources":["../../../../../../../../packages/pieces/custom/skai-adapters/src/lib/triggers/skai-response-webhook.ts"],"names":[],"mappings":"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"}
|
|
Binary file
|