Building Custom AI Integrations

Learn how to connect Promptha's AI capabilities to your existing tools, databases, and business processes.

Why Build Custom Integrations?

Custom integrations allow you to:

• Embed AI into existing workflows
• Automate repetitive processes
• Connect multiple tools and data sources
• Create tailored solutions for your business
• Scale AI usage across your organization

Integration Architecture

Overview

Promptha supports several integration patterns:

1. API Integration - Direct API calls from your application
2. Webhook Integration - Event-driven automation
3. Database Sync - Real-time data synchronization
4. Third-Party Connectors - Pre-built integrations

Choosing the Right Pattern

Pattern	Best For	Complexity
API	Real-time requests	Medium
Webhooks	Event-driven flows	Low-Medium
Database Sync	Large-scale data	High
Connectors	Standard tools	Low

API Integration Deep Dive

REST API Basics

All Promptha APIs follow REST conventions:

// Base setup
const PROMPTHA_API = 'https://api.promptha.com/v1';
const headers = {
  'Authorization': `Bearer ${process.env.PROMPTHA_API_KEY}`,
  'Content-Type': 'application/json'
};

Making Authenticated Requests

async function callPromptha(endpoint, method = 'GET', data = null) {
  const options = {
    method,
    headers,
  };

  if (data) {
    options.body = JSON.stringify(data);
  }

  const response = await fetch(`${PROMPTHA_API}${endpoint}`, options);

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'API request failed');
  }

  return response.json();
}

// Usage
const result = await callPromptha('/fabrics/run', 'POST', {
  fabricId: 'fabric_123',
  inputs: { topic: 'AI trends' }
});

Handling Async Operations

For long-running operations, use polling or webhooks:

async function runFabricAsync(fabricId, inputs, webhookUrl = null) {
  // Start the execution
  const { executionId } = await callPromptha('/fabrics/run/async', 'POST', {
    fabricId,
    inputs,
    webhookUrl // Optional: receive notification when complete
  });

  // If no webhook, poll for results
  if (!webhookUrl) {
    return pollForResult(executionId);
  }

  return { executionId };
}

async function pollForResult(executionId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const status = await callPromptha(`/executions/${executionId}`);

    if (status.state === 'completed') {
      return status.result;
    }

    if (status.state === 'failed') {
      throw new Error(status.error);
    }

    await sleep(2000); // Wait 2 seconds between polls
  }

  throw new Error('Execution timed out');
}

Webhook Integration

Setting Up Webhooks

Configure webhooks in your Promptha dashboard or via API:

// Register a webhook
await callPromptha('/webhooks', 'POST', {
  url: 'https://yourapp.com/webhooks/promptha',
  events: ['fabric.completed', 'ask.message', 'credits.low'],
  secret: 'your_webhook_secret'
});

Webhook Handler

// Express webhook handler
const crypto = require('crypto');

app.post('/webhooks/promptha', (req, res) => {
  // Verify webhook signature
  const signature = req.headers['x-promptha-signature'];
  const payload = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // Handle the event
  const { event, data } = req.body;

  switch (event) {
    case 'fabric.completed':
      handleFabricComplete(data);
      break;
    case 'ask.message':
      handleAskMessage(data);
      break;
    case 'credits.low':
      handleLowCredits(data);
      break;
  }

  res.status(200).send('OK');
});

Retry Logic

Promptha retries failed webhook deliveries with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: 5 seconds
• Attempt 3: 30 seconds
• Attempt 4: 5 minutes
• Attempt 5: 30 minutes

Database Integration

Real-Time Sync Pattern

For keeping your database in sync with Promptha:

// Sync fabric results to your database
async function syncFabricResult(executionId, result) {
  await db.query(`
    INSERT INTO ai_outputs (execution_id, content, created_at)
    VALUES ($1, $2, NOW())
    ON CONFLICT (execution_id)
    DO UPDATE SET content = $2, updated_at = NOW()
  `, [executionId, JSON.stringify(result)]);
}

// Webhook handler that syncs
app.post('/webhooks/promptha', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'fabric.completed') {
    await syncFabricResult(data.executionId, data.result);
  }

  res.status(200).send('OK');
});

Batch Processing

For large-scale data processing:

async function batchProcess(items, fabricId, concurrency = 5) {
  const results = [];

  for (let i = 0; i < items.length; i += concurrency) {
    const batch = items.slice(i, i + concurrency);

    const batchResults = await Promise.all(
      batch.map(item =>
        callPromptha('/fabrics/run', 'POST', {
          fabricId,
          inputs: item
        })
      )
    );

    results.push(...batchResults);

    // Rate limiting - wait between batches
    if (i + concurrency < items.length) {
      await sleep(1000);
    }
  }

  return results;
}

Popular Integration Examples

Slack Integration

Post AI-generated content to Slack:

const { WebClient } = require('@slack/web-api');
const slack = new WebClient(process.env.SLACK_TOKEN);

async function generateAndPostToSlack(topic, channel) {
  // Generate content with Promptha
  const content = await callPromptha('/fabrics/run', 'POST', {
    fabricId: 'social-post-generator',
    inputs: { topic, platform: 'slack' }
  });

  // Post to Slack
  await slack.chat.postMessage({
    channel,
    text: content.output,
    blocks: [
      {
        type: 'section',
        text: { type: 'mrkdwn', text: content.output }
      },
      {
        type: 'context',
        elements: [
          { type: 'mrkdwn', text: '_Generated with Promptha_' }
        ]
      }
    ]
  });
}

CRM Integration

Enrich CRM records with AI insights:

async function enrichLead(leadId, leadData) {
  // Generate personalized insights
  const insights = await callPromptha('/fabrics/run', 'POST', {
    fabricId: 'lead-enrichment',
    inputs: {
      company: leadData.company,
      industry: leadData.industry,
      title: leadData.title
    }
  });

  // Update CRM
  await crm.updateLead(leadId, {
    ai_insights: insights.output,
    personalized_pitch: insights.pitch,
    enriched_at: new Date()
  });

  return insights;
}

E-commerce Integration

Auto-generate product content:

// Shopify product update hook
app.post('/shopify/products/create', async (req, res) => {
  const product = req.body;

  // Generate optimized description
  const description = await callPromptha('/fabrics/run', 'POST', {
    fabricId: 'product-description',
    inputs: {
      name: product.title,
      features: product.tags,
      category: product.product_type
    }
  });

  // Generate SEO metadata
  const seo = await callPromptha('/fabrics/run', 'POST', {
    fabricId: 'product-seo',
    inputs: {
      title: product.title,
      description: description.output
    }
  });

  // Update Shopify product
  await shopify.product.update(product.id, {
    body_html: description.output,
    metafields: [
      { key: 'seo_title', value: seo.title, type: 'single_line_text_field' },
      { key: 'seo_description', value: seo.description, type: 'single_line_text_field' }
    ]
  });

  res.status(200).send('OK');
});

Error Handling & Resilience

Robust Error Handling

class PrompthaClient {
  async callWithRetry(endpoint, method, data, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        return await this.call(endpoint, method, data);
      } catch (error) {
        if (error.status === 429) {
          // Rate limited - wait and retry
          const waitTime = Math.pow(2, attempt) * 1000;
          await sleep(waitTime);
          continue;
        }

        if (error.status >= 500 && attempt < maxRetries) {
          // Server error - retry with backoff
          await sleep(attempt * 1000);
          continue;
        }

        throw error;
      }
    }
  }
}

Circuit Breaker Pattern

class CircuitBreaker {
  constructor(threshold = 5, resetTime = 60000) {
    this.failures = 0;
    this.threshold = threshold;
    this.resetTime = resetTime;
    this.state = 'closed';
  }

  async call(fn) {
    if (this.state === 'open') {
      throw new Error('Circuit breaker is open');
    }

    try {
      const result = await fn();
      this.failures = 0;
      return result;
    } catch (error) {
      this.failures++;

      if (this.failures >= this.threshold) {
        this.state = 'open';
        setTimeout(() => {
          this.state = 'half-open';
        }, this.resetTime);
      }

      throw error;
    }
  }
}

Testing Integrations

Unit Testing

describe('Promptha Integration', () => {
  it('should generate product description', async () => {
    // Mock the API call
    nock('https://api.promptha.com')
      .post('/v1/fabrics/run')
      .reply(200, { output: 'Generated description' });

    const result = await generateDescription({ name: 'Test Product' });

    expect(result.output).toBeDefined();
    expect(result.output).toContain('description');
  });
});

Integration Testing

describe('End-to-End Integration', () => {
  it('should complete full workflow', async () => {
    // Create test data
    const testProduct = await createTestProduct();

    // Trigger the integration
    await enrichProduct(testProduct.id);

    // Verify results
    const enrichedProduct = await getProduct(testProduct.id);
    expect(enrichedProduct.ai_description).toBeDefined();
    expect(enrichedProduct.seo_metadata).toBeDefined();
  });
});

Best Practices

1. Use environment variables - Never hardcode API keys
2. Implement retry logic - Handle transient failures gracefully
3. Monitor usage - Track API calls and credit consumption
4. Log comprehensively - Log requests and responses for debugging
5. Validate inputs - Sanitize data before sending to API
6. Handle rate limits - Implement backoff strategies
7. Test thoroughly - Unit and integration tests for all flows
8. Document your integration - Maintain documentation for your team

Resources

• API Reference
• SDK Documentation
• Example Integrations
• Community Forum