Integrations API

The Integrations API allows you to connect your AI agents with external services and platforms. Integrations enable agents to access third-party data, perform actions, and communicate through various channels.

Base URL

https://api.aloochat.ai/api/public

Authentication

All requests require an API key in the x-api-key header:

x-api-key: your_api_key_here

Endpoints Overview

Method	Endpoint	Description
`GET`	`/integrations`	List all integrations
`POST`	`/integrations`	Create a new integration
`GET`	`/integrations/{id}`	Get integration by ID
`PUT`	`/integrations/{id}`	Update an integration
`DELETE`	`/integrations/{id}`	Delete an integration
`GET`	`/integrations/types`	Get available integration types

Integration Properties

Property	Type	Description
`id`	`string`	Unique integration identifier (UUID)
`name`	`string`	Integration name
`type`	`string`	Integration type (e.g., “shopify”, “zendesk”)
`config`	`object`	Integration configuration
`is_active`	`boolean`	Whether the integration is active
`visibility`	`string`	Visibility: “private” or “public”
`company_id`	`string`	Associated company ID
`agent_id`	`string`	Linked agent ID (optional)

Supported Integration Types

Type	Description
`shopify`	Shopify e-commerce platform
`zendesk`	Zendesk customer support
`hubspot`	HubSpot CRM
`slack`	Slack messaging
`whatsapp`	WhatsApp Business
`notion`	Notion workspace
`odoo`	Odoo ERP
`google_calendar`	Google Calendar
`gmail`	Gmail email
`custom_api`	Custom REST API

List Integrations

Retrieve all integrations for your company.

Endpoint: GET /integrations

curl -X GET "https://api.aloochat.ai/api/public/integrations" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.aloochat.ai/api/public/integrations', {
  method: 'GET',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  }
});
 
const integrations = await response.json();
console.log('Integrations:', integrations);
 
// Filter active integrations
const activeIntegrations = integrations.filter(i => i.is_active);
console.log('Active integrations:', activeIntegrations);

import requests
 
response = requests.get(
    'https://api.aloochat.ai/api/public/integrations',
    headers={
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
    }
)
 
integrations = response.json()
print('Integrations:', integrations)
 
# Filter active integrations
active_integrations = [i for i in integrations if i['is_active']]
print('Active integrations:', active_integrations)

<?php
$ch = curl_init();
 
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.aloochat.ai/api/public/integrations',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: your_api_key_here',
        'Content-Type: application/json'
    ]
]);
 
$response = curl_exec($ch);
$integrations = json_decode($response, true);
curl_close($ch);
 
print_r($integrations);
 
// Filter active integrations
$activeIntegrations = array_filter($integrations, function($i) {
    return $i['is_active'] === true;
});
print_r(array_values($activeIntegrations));
?>

require 'net/http'
require 'json'
 
uri = URI('https://api.aloochat.ai/api/public/integrations')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
 
request = Net::HTTP::Get.new(uri)
request['x-api-key'] = 'your_api_key_here'
request['Content-Type'] = 'application/json'
 
response = http.request(request)
integrations = JSON.parse(response.body)
puts "Integrations: #{integrations}"
 
# Filter active integrations
active_integrations = integrations.select { |i| i['is_active'] }
puts "Active integrations: #{active_integrations}"

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Shopify Store",
    "type": "shopify",
    "config": {
      "shop_domain": "mystore.myshopify.com",
      "api_version": "2024-01"
    },
    "is_active": true,
    "visibility": "private",
    "company_id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_id": "456e7890-e89b-12d3-a456-426614174001"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Support Zendesk",
    "type": "zendesk",
    "config": {
      "subdomain": "mycompany",
      "email": "support@mycompany.com"
    },
    "is_active": true,
    "visibility": "private",
    "company_id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_id": null
  }
]

Create Integration

Create a new integration for your company.

Endpoint: POST /integrations

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Integration name
`type`	`string`	Yes	Integration type
`config`	`object`	No	Configuration object
`is_active`	`boolean`	No	Active status (default: true)
`visibility`	`string`	No	Visibility (default: “private”)
`agent_id`	`string`	No	Link to specific agent

Shopify Integration Example

curl -X POST "https://api.aloochat.ai/api/public/integrations" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Shopify Store",
    "type": "shopify",
    "config": {
      "shop_domain": "mystore.myshopify.com",
      "access_token": "shpat_xxxxxxxxxxxxx",
      "api_version": "2024-01"
    },
    "is_active": true,
    "visibility": "private"
  }'

const response = await fetch('https://api.aloochat.ai/api/public/integrations', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My Shopify Store',
    type: 'shopify',
    config: {
      shop_domain: 'mystore.myshopify.com',
      access_token: 'shpat_xxxxxxxxxxxxx',
      api_version: '2024-01'
    },
    is_active: true,
    visibility: 'private'
  })
});
 
const integration = await response.json();
console.log('Integration created:', integration);

import requests
 
response = requests.post(
    'https://api.aloochat.ai/api/public/integrations',
    headers={
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'My Shopify Store',
        'type': 'shopify',
        'config': {
            'shop_domain': 'mystore.myshopify.com',
            'access_token': 'shpat_xxxxxxxxxxxxx',
            'api_version': '2024-01'
        },
        'is_active': True,
        'visibility': 'private'
    }
)
 
integration = response.json()
print('Integration created:', integration)

<?php
$ch = curl_init();
 
$data = [
    'name' => 'My Shopify Store',
    'type' => 'shopify',
    'config' => [
        'shop_domain' => 'mystore.myshopify.com',
        'access_token' => 'shpat_xxxxxxxxxxxxx',
        'api_version' => '2024-01'
    ],
    'is_active' => true,
    'visibility' => 'private'
];
 
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.aloochat.ai/api/public/integrations',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'x-api-key: your_api_key_here',
        'Content-Type: application/json'
    ]
]);
 
$response = curl_exec($ch);
$integration = json_decode($response, true);
curl_close($ch);
 
print_r($integration);
?>

require 'net/http'
require 'json'
 
uri = URI('https://api.aloochat.ai/api/public/integrations')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
 
request = Net::HTTP::Post.new(uri)
request['x-api-key'] = 'your_api_key_here'
request['Content-Type'] = 'application/json'
request.body = {
  name: 'My Shopify Store',
  type: 'shopify',
  config: {
    shop_domain: 'mystore.myshopify.com',
    access_token: 'shpat_xxxxxxxxxxxxx',
    api_version: '2024-01'
  },
  is_active: true,
  visibility: 'private'
}.to_json
 
response = http.request(request)
integration = JSON.parse(response.body)
puts integration

Zendesk Integration Example

curl -X POST "https://api.aloochat.ai/api/public/integrations" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Zendesk",
    "type": "zendesk",
    "config": {
      "subdomain": "mycompany",
      "email": "support@mycompany.com",
      "api_token": "your_zendesk_api_token"
    },
    "is_active": true
  }'

const response = await fetch('https://api.aloochat.ai/api/public/integrations', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Support Zendesk',
    type: 'zendesk',
    config: {
      subdomain: 'mycompany',
      email: 'support@mycompany.com',
      api_token: 'your_zendesk_api_token'
    },
    is_active: true
  })
});
 
const integration = await response.json();
console.log('Zendesk integration created:', integration);

import requests
 
response = requests.post(
    'https://api.aloochat.ai/api/public/integrations',
    headers={
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Support Zendesk',
        'type': 'zendesk',
        'config': {
            'subdomain': 'mycompany',
            'email': 'support@mycompany.com',
            'api_token': 'your_zendesk_api_token'
        },
        'is_active': True
    }
)
 
integration = response.json()
print('Zendesk integration created:', integration)

Google Calendar Integration Example

curl -X POST "https://api.aloochat.ai/api/public/integrations" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Calendar",
    "type": "google_calendar",
    "config": {
      "calendar_id": "meetings@mycompany.com",
      "timezone": "Asia/Kuwait"
    },
    "is_active": true
  }'

const response = await fetch('https://api.aloochat.ai/api/public/integrations', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Company Calendar',
    type: 'google_calendar',
    config: {
      calendar_id: 'meetings@mycompany.com',
      timezone: 'Asia/Kuwait'
    },
    is_active: true
  })
});
 
const integration = await response.json();
console.log('Google Calendar integration created:', integration);

import requests
 
response = requests.post(
    'https://api.aloochat.ai/api/public/integrations',
    headers={
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Company Calendar',
        'type': 'google_calendar',
        'config': {
            'calendar_id': 'meetings@mycompany.com',
            'timezone': 'Asia/Kuwait'
        },
        'is_active': True
    }
)
 
integration = response.json()
print('Google Calendar integration created:', integration)

Get Integration

Retrieve a specific integration by ID.

Endpoint: GET /integrations/{id}

curl -X GET "https://api.aloochat.ai/api/public/integrations/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: your_api_key_here"

const integrationId = '550e8400-e29b-41d4-a716-446655440000';
 
const response = await fetch(`https://api.aloochat.ai/api/public/integrations/${integrationId}`, {
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const integration = await response.json();
console.log('Integration:', integration);

import requests
 
integration_id = '550e8400-e29b-41d4-a716-446655440000'
 
response = requests.get(
    f'https://api.aloochat.ai/api/public/integrations/{integration_id}',
    headers={'x-api-key': 'your_api_key_here'}
)
 
integration = response.json()
print('Integration:', integration)

<?php
$integrationId = '550e8400-e29b-41d4-a716-446655440000';
$ch = curl_init();
 
curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.aloochat.ai/api/public/integrations/{$integrationId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: your_api_key_here'
    ]
]);
 
$response = curl_exec($ch);
$integration = json_decode($response, true);
curl_close($ch);
 
print_r($integration);
?>

require 'net/http'
require 'json'
 
integration_id = '550e8400-e29b-41d4-a716-446655440000'
uri = URI("https://api.aloochat.ai/api/public/integrations/#{integration_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
 
request = Net::HTTP::Get.new(uri)
request['x-api-key'] = 'your_api_key_here'
 
response = http.request(request)
integration = JSON.parse(response.body)
puts integration

Update Integration

Update an existing integration.

Endpoint: PUT /integrations/{id}

curl -X PUT "https://api.aloochat.ai/api/public/integrations/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Integration Name",
    "is_active": false,
    "config": {
      "shop_domain": "newstore.myshopify.com"
    }
  }'

const integrationId = '550e8400-e29b-41d4-a716-446655440000';
 
const response = await fetch(`https://api.aloochat.ai/api/public/integrations/${integrationId}`, {
  method: 'PUT',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Updated Integration Name',
    is_active: false,
    config: {
      shop_domain: 'newstore.myshopify.com'
    }
  })
});
 
const updatedIntegration = await response.json();
console.log('Integration updated:', updatedIntegration);

import requests
 
integration_id = '550e8400-e29b-41d4-a716-446655440000'
 
response = requests.put(
    f'https://api.aloochat.ai/api/public/integrations/{integration_id}',
    headers={
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Updated Integration Name',
        'is_active': False,
        'config': {
            'shop_domain': 'newstore.myshopify.com'
        }
    }
)
 
updated_integration = response.json()
print('Integration updated:', updated_integration)

<?php
$integrationId = '550e8400-e29b-41d4-a716-446655440000';
$ch = curl_init();
 
$data = [
    'name' => 'Updated Integration Name',
    'is_active' => false,
    'config' => [
        'shop_domain' => 'newstore.myshopify.com'
    ]
];
 
curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.aloochat.ai/api/public/integrations/{$integrationId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'x-api-key: your_api_key_here',
        'Content-Type: application/json'
    ]
]);
 
$response = curl_exec($ch);
$updatedIntegration = json_decode($response, true);
curl_close($ch);
 
print_r($updatedIntegration);
?>

require 'net/http'
require 'json'
 
integration_id = '550e8400-e29b-41d4-a716-446655440000'
uri = URI("https://api.aloochat.ai/api/public/integrations/#{integration_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
 
request = Net::HTTP::Put.new(uri)
request['x-api-key'] = 'your_api_key_here'
request['Content-Type'] = 'application/json'
request.body = {
  name: 'Updated Integration Name',
  is_active: false,
  config: {
    shop_domain: 'newstore.myshopify.com'
  }
}.to_json
 
response = http.request(request)
updated_integration = JSON.parse(response.body)
puts updated_integration

Delete Integration

Delete an integration.

Endpoint: DELETE /integrations/{id}

curl -X DELETE "https://api.aloochat.ai/api/public/integrations/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: your_api_key_here"

const integrationId = '550e8400-e29b-41d4-a716-446655440000';
 
const response = await fetch(`https://api.aloochat.ai/api/public/integrations/${integrationId}`, {
  method: 'DELETE',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
if (response.status === 204) {
  console.log('Integration deleted successfully');
}

import requests
 
integration_id = '550e8400-e29b-41d4-a716-446655440000'
 
response = requests.delete(
    f'https://api.aloochat.ai/api/public/integrations/{integration_id}',
    headers={'x-api-key': 'your_api_key_here'}
)
 
if response.status_code == 204:
    print('Integration deleted successfully')

<?php
$integrationId = '550e8400-e29b-41d4-a716-446655440000';
$ch = curl_init();
 
curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.aloochat.ai/api/public/integrations/{$integrationId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'x-api-key: your_api_key_here'
    ]
]);
 
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($httpCode === 204) {
    echo 'Integration deleted successfully';
}
?>

require 'net/http'
 
integration_id = '550e8400-e29b-41d4-a716-446655440000'
uri = URI("https://api.aloochat.ai/api/public/integrations/#{integration_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
 
request = Net::HTTP::Delete.new(uri)
request['x-api-key'] = 'your_api_key_here'
 
response = http.request(request)
puts 'Integration deleted successfully' if response.code == '204'

Get Integration Types

Retrieve all available integration types.

Endpoint: GET /integrations/types

curl -X GET "https://api.aloochat.ai/api/public/integrations/types" \
  -H "x-api-key: your_api_key_here"

const response = await fetch('https://api.aloochat.ai/api/public/integrations/types', {
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const types = await response.json();
console.log('Available integration types:', types);

import requests
 
response = requests.get(
    'https://api.aloochat.ai/api/public/integrations/types',
    headers={'x-api-key': 'your_api_key_here'}
)
 
types = response.json()
print('Available integration types:', types)

<?php
$ch = curl_init();
 
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.aloochat.ai/api/public/integrations/types',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: your_api_key_here'
    ]
]);
 
$response = curl_exec($ch);
$types = json_decode($response, true);
curl_close($ch);
 
print_r($types);
?>

require 'net/http'
require 'json'
 
uri = URI('https://api.aloochat.ai/api/public/integrations/types')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
 
request = Net::HTTP::Get.new(uri)
request['x-api-key'] = 'your_api_key_here'
 
response = http.request(request)
types = JSON.parse(response.body)
puts types

Response

[
  {
    "type": "shopify",
    "name": "Shopify",
    "description": "E-commerce platform integration for product catalog, orders, and inventory"
  },
  {
    "type": "zendesk",
    "name": "Zendesk",
    "description": "Customer support platform for ticket management and help desk"
  },
  {
    "type": "hubspot",
    "name": "HubSpot",
    "description": "CRM platform for contacts, deals, and marketing automation"
  },
  {
    "type": "google_calendar",
    "name": "Google Calendar",
    "description": "Calendar integration for scheduling meetings and events"
  },
  {
    "type": "gmail",
    "name": "Gmail",
    "description": "Email integration for sending and receiving emails"
  },
  {
    "type": "slack",
    "name": "Slack",
    "description": "Team messaging platform integration"
  },
  {
    "type": "notion",
    "name": "Notion",
    "description": "Workspace integration for documents and databases"
  },
  {
    "type": "custom_api",
    "name": "Custom API",
    "description": "Connect to any REST API with custom configuration"
  }
]

Integration Configuration Examples

Shopify Configuration

{
  "shop_domain": "mystore.myshopify.com",
  "access_token": "shpat_xxxxxxxxxxxxx",
  "api_version": "2024-01"
}

Zendesk Configuration

{
  "subdomain": "mycompany",
  "email": "support@mycompany.com",
  "api_token": "your_zendesk_api_token"
}

HubSpot Configuration

{
  "access_token": "your_hubspot_access_token",
  "portal_id": "12345678"
}

Google Calendar Configuration

{
  "calendar_id": "meetings@mycompany.com",
  "timezone": "Asia/Kuwait",
  "credentials": {}
}

Custom API Configuration

{
  "base_url": "https://api.example.com",
  "auth_type": "bearer",
  "auth_token": "your_api_token",
  "headers": {
    "X-Custom-Header": "value"
  }
}

Error Responses

Status Code	Description
`400`	Bad Request - Invalid input data
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Integration not found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Error Response Format

{
  "detail": "Integration not found"
}

Voice Agents Regions