Integrations

Custom Integrations

Build custom integrations to connect Engrami with any service using webhooks and REST APIs.

Overview

Custom integrations allow you to connect Engrami agents with any external service. Use webhooks to receive events, REST APIs to trigger actions, and custom tools to extend agent capabilities.

Incoming Webhooks

Create a webhook endpoint to trigger agent actions from external services:

# Create webhook endpoint
curl -X POST https://api.engrami.com/api/v1/webhooks/incoming \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Lead Webhook",
    "agent_id": "agent_sales",
    "transform": {
      "message": "$.data.description",
      "metadata": {
        "lead_id": "$.data.id",
        "company": "$.data.company_name"
      }
    }
  }'

# Response
{
  "id": "wh_in_abc123",
  "url": "https://hooks.engrami.com/in/wh_in_abc123",
  "secret": "whsec_xyz789..."
}

Configure your external service to send POST requests:

# External service sends
curl -X POST https://hooks.engrami.com/in/wh_in_abc123 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=..." \
  -d '{
    "event": "lead.created",
    "data": {
      "id": "lead_123",
      "company_name": "Acme Corp",
      "description": "Interested in enterprise plan"
    }
  }'

Custom Tools

Extend your agent's capabilities with custom tools:

# Define a custom tool
curl -X POST https://api.engrami.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_customer",
    "description": "Look up customer information by email or ID",
    "parameters": {
      "type": "object",
      "properties": {
        "identifier": {
          "type": "string",
          "description": "Customer email or ID"
        },
        "fields": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Fields to return"
        }
      },
      "required": ["identifier"]
    },
    "endpoint": {
      "url": "https://your-api.com/customers/lookup",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer {{secrets.CRM_API_KEY}}"
      },
      "body_template": {
        "query": "{{identifier}}",
        "select": "{{fields}}"
      }
    }
  }'

The agent can now use this tool in conversations:

# User: "What's the status of customer john@acme.com?"

# Agent uses the tool
{
  "tool": "lookup_customer",
  "parameters": {
    "identifier": "john@acme.com",
    "fields": ["name", "status", "subscription", "last_contact"]
  }
}

# Tool response
{
  "name": "John Smith",
  "status": "active",
  "subscription": "enterprise",
  "last_contact": "2024-01-15"
}

# Agent response
"John Smith at Acme Corp is an active Enterprise customer.
Their last contact was on January 15th."

OAuth Integration

Implement OAuth 2.0 flow for user-authenticated integrations:

# Register OAuth provider
curl -X POST https://api.engrami.com/api/v1/integrations/oauth/providers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom_crm",
    "display_name": "Custom CRM",
    "authorization_url": "https://crm.example.com/oauth/authorize",
    "token_url": "https://crm.example.com/oauth/token",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scopes": ["read", "write"],
    "redirect_uri": "https://api.engrami.com/api/v1/oauth/callback"
  }'

# Users can then connect via
https://app.engrami.com/integrations/connect/custom_crm

Outgoing Actions

Configure actions that agents can trigger on external services:

# Define an action
curl -X POST https://api.engrami.com/api/v1/integrations/actions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_support_ticket",
    "description": "Create a support ticket in the help desk",
    "endpoint": {
      "url": "https://helpdesk.example.com/api/tickets",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer {{secrets.HELPDESK_KEY}}",
        "Content-Type": "application/json"
      }
    },
    "input_schema": {
      "type": "object",
      "properties": {
        "subject": { "type": "string" },
        "description": { "type": "string" },
        "priority": { "type": "string", "enum": ["low", "medium", "high"] },
        "customer_email": { "type": "string" }
      },
      "required": ["subject", "description", "customer_email"]
    },
    "output_mapping": {
      "ticket_id": "$.id",
      "ticket_url": "$.web_url"
    }
  }'

Secret Management

Store sensitive credentials securely:

# Add a secret
curl -X POST https://api.engrami.com/api/v1/secrets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM_API_KEY",
    "value": "sk_live_abc123..."
  }'

# Use in integrations
"headers": {
  "Authorization": "Bearer {{secrets.CRM_API_KEY}}"
}

Testing Integrations

# Test a tool
curl -X POST https://api.engrami.com/api/v1/tools/lookup_customer/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "identifier": "test@example.com"
    }
  }'

# Response
{
  "success": true,
  "response_time_ms": 234,
  "response": {
    "name": "Test User",
    "status": "active"
  }
}

Continue to Security & Privacy