Skip to main content

Integration Guide

How to integrate Crella.ai into your application.

Integration Patterns​

1. API Integration​

Direct API calls for real-time processing:

flowchart LR
    App[Your App] --> API[Crella API]
    API --> Agent[AI Agent]
    Agent --> API
    API --> App

Best for: Real-time interactions, chat interfaces

2. Webhook Integration​

Async processing with webhook notifications:

flowchart LR
    App[Your App] --> API[Crella API]
    API --> Queue[Task Queue]
    Queue --> Agent[AI Agent]
    Agent --> Webhook[Webhook]
    Webhook --> App

Best for: Batch processing, background tasks

3. Widget Integration​

Embed Crella agents in your website:

<script src="https://cdn.crella.ai/widget.js"></script>
<script>
  Crella.init({ apiKey: 'YOUR_API_KEY', agent: 'm' });
</script>

Best for: Customer-facing chat, lead capture

Common Integrations​

CRM Integration (Salesforce)​

// When a lead is created in Salesforce
async function onLeadCreated(lead: SalesforceLead) {
  // Enrich with Crella
  const enriched = await crella.tasks.create({
    agent: 'ECHO001',
    type: 'lead_enrichment',
    payload: {
      name: lead.Name,
      company: lead.Company,
      email: lead.Email
    }
  });
  
  // Wait for completion
  const result = await crella.tasks.waitForCompletion(enriched.task_id);
  
  // Update Salesforce with enriched data
  await salesforce.leads.update(lead.Id, {
    LinkedIn_URL__c: result.data.linkedin_url,
    Company_Size__c: result.data.company_size
  });
}

Email Platform (SendGrid)​

// Generate personalized email and send
async function sendPersonalizedEmail(recipient: Contact) {
  // Generate email with Crella
  const content = await crella.tasks.create({
    agent: 'FOXTROT001',
    type: 'email_generation',
    payload: {
      recipient: {
        name: recipient.name,
        company: recipient.company,
        title: recipient.title
      },
      template: 'cold_outreach',
      sender: { name: 'Sales Team', company: 'Acme' }
    }
  });
  
  const result = await crella.tasks.waitForCompletion(content.task_id);
  
  // Send via SendGrid
  await sendgrid.send({
    to: recipient.email,
    subject: result.data.subject,
    html: result.data.body
  });
}

Document Processing (Upload → Extract)​

// Process uploaded document
async function processDocument(file: File) {
  // Upload to your storage
  const fileUrl = await storage.upload(file);
  
  // Extract with Crella
  const extraction = await crella.tasks.create({
    agent: 'CHARLIE001',
    type: 'document_extraction',
    payload: {
      file_url: fileUrl,
      document_type: 'paystub',
      extract_fields: ['employer', 'gross_pay', 'net_pay']
    }
  });
  
  const result = await crella.tasks.waitForCompletion(extraction.task_id);
  
  return result.data.extracted_data;
}

Workflow Builder​

Create multi-step workflows:

const workflow = await crella.workflows.create({
  name: 'lead_to_outreach',
  steps: [
    {
      id: 'validate',
      agent: 'ALPHA001',
      action: 'validate_lead'
    },
    {
      id: 'enrich',
      agent: 'ECHO001',
      action: 'enrich_lead',
      dependsOn: ['validate']
    },
    {
      id: 'generate_email',
      agent: 'FOXTROT001',
      action: 'generate_email',
      dependsOn: ['enrich']
    },
    {
      id: 'send',
      agent: 'HOTEL001',
      action: 'send_email',
      dependsOn: ['generate_email']
    }
  ]
});

// Execute workflow
const execution = await crella.workflows.execute(workflow.id, {
  lead: { name: 'John', email: 'john@example.com' }
});

Best Practices​

1. Error Handling​

try {
  const result = await crella.tasks.create(taskData);
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    // Implement exponential backoff
    await delay(error.retryAfter * 1000);
    return retry();
  }
  if (error.code === 'VALIDATION_ERROR') {
    // Fix input data
    console.error('Invalid input:', error.details);
  }
  throw error;
}

2. Idempotency​

// Use idempotency keys for retryable requests
const result = await crella.tasks.create({
  ...taskData,
  idempotencyKey: `lead-${leadId}-${Date.now()}`
});

3. Batching​

// Process multiple items in batch
const tasks = leads.map(lead => ({
  agent: 'ALPHA001',
  type: 'validate',
  payload: lead
}));

const results = await crella.tasks.createBatch(tasks);

4. Caching​

// Cache agent responses for similar queries
const cacheKey = `enrich:${company}:${email}`;
let result = await cache.get(cacheKey);

if (!result) {
  result = await crella.tasks.create({...});
  await cache.set(cacheKey, result, { ttl: 3600 }); // 1 hour
}

Testing​

Sandbox Environment​

Use sandbox for testing:

const crella = new Crella({
  apiKey: 'YOUR_SANDBOX_KEY',
  environment: 'sandbox'
});

Mock Responses​

// In test environment
jest.mock('@crella/sdk', () => ({
  Crella: jest.fn().mockImplementation(() => ({
    tasks: {
      create: jest.fn().mockResolvedValue({
        task_id: 'mock_task_123',
        status: 'completed',
        result: { validated: true }
      })
    }
  }))
}));

Support​

  • Documentation: docs.crella.ai
  • API Status: status.crella.ai
  • Support: support@crella.ai