SKAI Adapters Piece

Transform messages between messaging platforms and SKAI Agents API.

Overview

The SKAI Adapters piece acts as a bridge between messaging platforms (WhatsApp, Telegram, Discord, etc.) and SKAI Agents. It provides:

• Platform-agnostic message format - GenericMessage interface
• Bidirectional transformations - Platform ↔ SKAI
• SKAI API integration - Direct communication with SKAI Agents
• Agent dropdown - Dynamic agent selection from your SKAI account

Architecture

Platform Message → Adapter (Transform) → SKAI Agent → Adapter (Transform) → Platform Message

GenericMessage Format

All platform messages are transformed to this unified format:

interface GenericMessage {
  external_id: string;          // Platform identifier (phone, chat ID, etc.)
  platform: Platform;           // 'whatsapp' | 'telegram' | 'discord'
  message: string;              // Text content
  reference_id?: string;        // Platform's message ID
  media_urls?: string[];        // Media attachments
  media_types?: MediaType[];    // Types of media
  sender_name?: string;         // Display name
  metadata?: Record<string, any>; // Platform-specific data
  timestamp?: string;           // ISO 8601 timestamp
}

Actions

WhatsApp → SKAI Agent

Transform WhatsApp message and process with SKAI agent.

Inputs:

• WhatsApp Message (JSON) - Output from WhatsApp New Message trigger
• Environment - Production/Development/Staging
• SKAI Agent - Select from dropdown
• Include Raw Metadata - Optional

Output:

{
  "success": true,
  "skaiResponse": {
    "success": true,
    "response": "Agent's reply",
    "conversationId": "conv_123"
  },
  "genericMessage": { /* Transformed message */ },
  "originalPlatform": "whatsapp"
}

SKAI → WhatsApp

Transform SKAI agent response back to WhatsApp format.

Inputs:

• SKAI Response (JSON) - Output from WhatsApp → SKAI action
• Include Conversation ID - Add as footer
• Custom Footer - Optional custom text

Output:

{
  "to": "+1234567890",
  "text": "Agent's formatted response",
  "conversationId": "conv_123",
  "metadata": { /* Additional data */ }
}

Setup

Prerequisites

1. SKAI Account - Sign up at agents.skillfulai.io
2. SKAI API Key - Generate from Settings → API Keys
3. SKAI Agent - Create at least one agent

Getting SKAI API Key

1. Log in to SKAI Agents Platform
2. Navigate to Settings → API Keys
3. Click "Create New API Key"
4. Copy the key (starts with sk_)
5. Paste into ActivePieces when configuring SKAI Adapters

Usage Examples

Example 1: WhatsApp Auto-Reply with SKAI

1. TRIGGER: WhatsApp - New Message
   └─ Output: WhatsApp message

2. ACTION: WhatsApp → SKAI Agent
   └─ Input: {{trigger.output}}
   └─ Agent: Customer Support Agent
   └─ Environment: Production
   └─ Output: SKAI response

3. ACTION: SKAI → WhatsApp
   └─ Input: {{step2.output}}
   └─ Include Conversation ID: Yes
   └─ Output: Formatted message

4. ACTION: WhatsApp - Send Message
   └─ To: {{step3.to}}
   └─ Message: {{step3.text}}

Example 2: Multi-Platform Support

Flow for WhatsApp:

WhatsApp New Message
  → WhatsApp → SKAI
  → SKAI → WhatsApp
  → WhatsApp Send Message

Flow for Telegram (coming soon):

Telegram New Message
  → Telegram → SKAI
  → SKAI → Telegram
  → Telegram Send Message

Same agent, different platforms!

Example 3: Conditional Responses

1. TRIGGER: WhatsApp - New Message

2. ACTION: Code - Check Keywords
   └─ If message contains "urgent"

3. BRANCH:
   a) If Urgent:
      WhatsApp → SKAI (Priority Agent)

   b) If Normal:
      WhatsApp → SKAI (Standard Agent)

4. ACTION: SKAI → WhatsApp
5. ACTION: WhatsApp - Send Message

Supported Platforms

Currently Supported

• ✅ WhatsApp Business

Coming Soon

• 🔜 Telegram
• 🔜 Discord
• 🔜 SMS (Twilio)
• 🔜 Slack

Message Type Support

WhatsApp

• ✅ Text messages
• ✅ Images (with captions)
• ✅ Videos (with captions)
• ✅ Audio messages
• ✅ Documents
• ✅ Voice messages

All media information is preserved in genericMessage.metadata.

API Integration

SKAI Agents API

Endpoints:

• GET /agents - List user's agents
• POST /agents/{id}/process - Process message with agent

Environments:

• Production: https://api-production.agents.skillfulai.io
• Development: https://api-development.agents.skillfulai.io
• Staging: https://api-staging.agents.skillfulai.io

Authentication

All requests use Bearer token authentication:

Authorization: Bearer sk_your_api_key_here

Error Handling

Common Errors

"SKAI API error (401)"

• Invalid API key
• API key expired
• Solution: Regenerate API key in SKAI platform

"SKAI API error (404)"

• Agent not found
• Agent ID invalid
• Solution: Verify agent exists and is minted

"Failed to fetch agents"

• Network issue
• API key missing
• Solution: Check authentication and network

"Invalid WhatsApp message: missing required fields"

• Malformed input
• Missing from or messageId
• Solution: Ensure WhatsApp trigger output is used

Debugging

Enable detailed logging by checking ActivePieces logs:

✅ Message transformed
✅ SKAI API response received
❌ SKAI API error: ...

Advanced Features

Custom Transformers

To add support for new platforms, create a transformer:

import { GenericMessage, Platform } from '../common/types/generic-message';

export class TelegramTransformer {
  transform(telegramMessage: any): GenericMessage {
    return {
      external_id: telegramMessage.chatId,
      platform: Platform.TELEGRAM,
      message: telegramMessage.text,
      // ... other fields
    };
  }
}

Metadata Preservation

All platform-specific metadata is preserved:

// WhatsApp metadata includes:
{
  type: 'image',
  timestamp: '1642511234',
  image: {
    id: 'img_123',
    mimeType: 'image/jpeg',
    caption: 'Check this out!'
  }
}

Building

# Build the piece
npx nx build pieces-skai-adapters

# Build all custom pieces
npx nx run-many -t build --projects=pieces-*

Testing

# Run unit tests (coming soon)
npx nx test pieces-skai-adapters

# Manual testing
1. Create test flow in ActivePieces
2. Send test message from platform
3. Verify transformation and SKAI response
4. Check logs for detailed output

Contributing

To add support for a new platform:

1. Create transformer in src/lib/transformers/
2. Create actions in src/lib/actions/
3. Update src/index.ts
4. Add tests
5. Update README

Version

Current version: 0.0.1

Authors

Skillful AI

Support

• Documentation: SKAI Agents Docs
• Issues: Report bugs in ActivePieces repository
• API Status: status.skillfulai.io

License

MIT