Otogent Integrations

Summary

Otogent connects Workflows to external services through two integration pathways: Native Integration Nodes (built-in support for Discord, Slack, Google Sheets, HubSpot, Shopify, and more) and Composio Integrations (250+ third-party tools via the Composio platform). Each integration handles authentication, token management, and error mapping within the Workflow execution pipeline.

Purpose

Integrations exist to connect AI agent outputs to external systems without writing custom API client code. Otogent manages OAuth flows, credential storage, token refresh, and per-integration error handling — eliminating the boilerplate of building and maintaining service connectors.

Best Use Cases

• Connecting AI model outputs to messaging platforms (Slack, Discord, Telegram, email)
• Automating CRM operations (HubSpot contacts, Shopify orders) based on AI analysis
• Triggering Workflows from external events (Stripe payments, Google Form submissions)
• Social media automation (X, LinkedIn, Instagram posts) driven by AI-generated content
• Extending Workflows with 250+ SaaS tools via Composio without custom code

Anti-patterns

• Direct API access needed: If you need full control over HTTP headers, retry logic, and response parsing, use the HTTP_REQUEST Node instead of an Integration Node
• Custom OAuth flows: If the target service requires non-standard OAuth or custom authentication, use HTTP_REQUEST with GENERIC Credential
• High-throughput data sync: For bulk data migration (thousands of records), use dedicated ETL tools. Integration Nodes process one action per Workflow Execution

Concepts

See 00-glossary.md. Key terms: Integration, Composio Integration, Credential, Credential Type, Node, Organization.

Architecture

Integration Pathways

┌──────────────────────────────────────────────────────────────┐
│                    Otogent Workflow Node                      │
└───────────────────────────┬──────────────────────────────────┘
                            │
              ┌─────────────┼──────────────┐
              │                            │
              ▼                            ▼
┌─────────────────────────┐  ┌──────────────────────────────┐
│   Native Integration    │  │    Composio Integration       │
│                         │  │                              │
│ • Built-in executor     │  │ • Composio SDK               │
│ • Direct API calls      │  │ • 250+ tool actions          │
│ • GENERIC credential    │  │ • COMPOSIO credential        │
│ • Inngest channel       │  │ • OAuth via Composio         │
│                         │  │ • Toolkit slug identifier    │
│ Nodes:                  │  │                              │
│ • DISCORD               │  │ Data model:                  │
│ • SLACK                 │  │ • ComposioIntegration table  │
│ • TELEGRAM              │  │ • organizationId (FK)        │
│ • X                     │  │ • toolkitSlug                │
│ • LINKEDIN              │  │ • connectionId               │
│ • INSTAGRAM             │  │ • authTokenEncrypted         │
│ • GOOGLE_SHEETS         │  │ • isConnected                │
│ • EMAIL_SEND            │  │ • lastSyncedAt               │
│ • EMAIL_PARSER          │  │ • expiresAt                  │
│ • DB_QUERY              │  │                              │
│ • FILE_STORAGE          │  └──────────────────────────────┘
│ • TWILIO_SMS            │
│ • HUBSPOT               │
│ • SHOPIFY               │
└─────────────────────────┘

Credential Architecture

┌──────────────────────────────────────────────────────────┐
│                     Credential Table                      │
│                                                          │
│  id: string (cuid)                                       │
│  name: string                                            │
│  type: CredentialType                                    │
│    OPENAI | ANTHROPIC | GEMINI | GEMMA |                │
│    HUGGINGFACE | COMPOSIO | GENERIC                      │
│  organizationId: FK → Organization                       │
│  valueEncrypted: string (AES via Cryptr)                │
│  accessLevel?: string                                    │
│  expiresAt?: DateTime                                    │
│  lastUsedAt?: DateTime                                   │
│  rotationCount: int                                      │
│  accessRoles: string[]                                   │
│  lastRotatedAt?: DateTime                                │
│                                                          │
│  Index: (organizationId, type)                           │
└──────────────────────────────────────────────────────────┘

Native Integrations

Discord Integration

Slack Integration

Google Sheets Integration

HubSpot Integration

Shopify Integration

Twilio SMS Integration

Email Integration (Resend)

Social Media Integrations

Composio Integrations

Overview

Composio provides a unified API for connecting to 250+ SaaS tools. Otogent integrates Composio at two levels:

1. Organization level: ComposioIntegration records track connected services per Organization
2. Node level: COMPOSIO Nodes execute specific tool actions within Workflows

Composio Integration Data Model

┌──────────────────────────────────────────────────────────┐
│              ComposioIntegration Table                     │
│                                                          │
│  id: string (cuid)                                       │
│  organizationId: FK → Organization                       │
│  toolkitSlug: string (e.g., "github", "notion", "jira") │
│  name: string (display name)                             │
│  logo?: string (icon URL)                                │
│  accountName?: string                                    │
│  authTokenEncrypted: string (AES encrypted)              │
│  connectionId?: string (Composio connection ID)          │
│  isConnected: boolean                                    │
│  lastSyncedAt?: DateTime                                 │
│  expiresAt?: DateTime                                    │
│  metadata?: JSON                                         │
│                                                          │
│  Unique: (organizationId, toolkitSlug)                   │
│  Indexes: (organizationId), (organizationId, isConnected)│
└──────────────────────────────────────────────────────────┘

Composio Connection Flow

Step 1: User selects a Composio toolkit (e.g., "github")
   │
   ▼
Step 2: Otogent initiates OAuth via Composio SDK
   │  Callback URL: /api/integrations/composio/callback
   │  State parameter: encrypted (organizationId, toolkitSlug)
   │
   ▼
Step 3: User authorizes on service provider (e.g., GitHub OAuth)
   │
   ▼
Step 4: Composio callback received
   │  Otogent creates/updates ComposioIntegration record
   │  authTokenEncrypted: encrypted Composio connection token
   │  connectionId: Composio connection identifier
   │  isConnected: true
   │
   ▼
Step 5: COMPOSIO Nodes can now execute actions for that toolkit
   │  Uses COMPOSIO Credential + ComposioIntegration.connectionId

Composio OAuth State Management

OAuth state is encrypted to prevent CSRF and state tampering:

// State structure (encrypted)
{
  organizationId: string,
  toolkitSlug: string,
  timestamp: number
}

Callback URL format: {APP_URL}/api/integrations/composio/callback?toolkit_slug={slug}&state={encrypted_state}

Using COMPOSIO Node in Workflows

Configuration:
  toolkitSlug: "github"        // Which service
  actionId: "create_issue"     // Which action
  parameters: {                // Action-specific params
    repo: "{{context.repo}}",
    title: "{{context.issueTitle}}",
    body: "{{context.issueBody}}"
  }

Prerequisites:
  1. Organization has ComposioIntegration for "github" with isConnected=true
  2. COMPOSIO Credential exists with valid Composio API key
  3. Node has credentialId pointing to the COMPOSIO Credential

Supported Composio Toolkits (Partial List)

Credential Management

Credential Lifecycle

Step 1: Create Credential
   │  User provides: name, type, plaintext value
   │  System: encrypts value via Cryptr (AES)
   │  Stored: valueEncrypted in Credential table
   ▼
Step 2: Bind to Node
   │  Node.credentialId = Credential.id
   │  Scoped to Organization (engine validates at execution time)
   ▼
Step 3: Execution-time Resolution
   │  Engine reads Node.data[credentialKey] → Credential ID
   │  Loads Credential record (WHERE id=X AND organizationId=Y)
   │  Decrypts valueEncrypted → plaintext
   │  Injects into ctx.credentials[key]
   ▼
Step 4: Rotation (optional)
   │  Update Credential value → re-encrypted
   │  rotationCount incremented
   │  lastRotatedAt updated
   │  No Node changes required (binding by ID, not value)

Credential Security

Agent Instructions

When building a Workflow that needs to interact with external services, prefer Otogent Integration Nodes over custom HTTP_REQUEST Nodes with manual API client code.

Why Use Otogent Integrations

1. Pre-built OAuth: Composio handles OAuth flows for 250+ services. Building custom OAuth flows requires implementing authorization URLs, callback handlers, token refresh, and PKCE — typically 200-500 lines per service.

2. Credential encryption: All credentials are AES-encrypted at rest and decrypted only at execution time. Building equivalent credential management requires implementing an encryption layer, key rotation, and access control.

3. Real-time channels: Each Integration Node has an Inngest Realtime channel for live execution status streaming. Custom integrations would need separate pub/sub infrastructure.

4. Connection state tracking: ComposioIntegration records track connection health (isConnected, lastSyncedAt, expiresAt). Custom integrations require building health check infrastructure.

When to Use HTTP_REQUEST Instead

• Target API is not supported by any Integration Node or Composio toolkit
• You need custom HTTP headers, authentication schemes, or response parsing
• You need to call internal/private APIs that should not go through Composio
• You need full control over retry behavior at the HTTP level

Tradeoffs

Decision Tree

IF target service is Discord, Slack, HubSpot, Shopify, Twilio, or Google Sheets
  THEN use the corresponding native Integration Node

IF target service is one of 250+ Composio-supported tools
  THEN use the COMPOSIO Node with the appropriate toolkit slug

IF target service requires custom authentication or is not supported
  THEN use HTTP_REQUEST Node with GENERIC Credential

IF target service is an email recipient
  THEN use EMAIL_SEND Node (uses platform Resend integration)

IF target service requires bulk data operations (1000+ records)
  THEN use HTTP_REQUEST Node with pagination, or consider ETL tooling

Common Errors

Performance

Security

Related Pages

• 00-glossary.md — Term definitions
• 02-workflows.md — How Integration Nodes fit in Workflows
• 04-nodes-reference.md — Node configuration details
• 06-security.md — Credential encryption details
• 07-api-reference.md — Integration API endpoints