Regions API

The Regions API provides information about available deployment regions and channels. Regions help configure your AI agents to communicate using locally supported languages and dialects, ensuring natural and culturally appropriate conversations with your customers.

AlooChat currently operates exclusively in the GCC (Gulf Cooperation Council) and MENA regions, providing specialized support for Arabic dialects and local languages.

Why Regions Matter

Regions in AlooChat serve two key purposes:

Language & Dialect Support - Each region has specific languages and Arabic dialects that the AI agent will use when communicating with customers
Timezone Awareness - Agents understand local business hours and time references

When you assign a region to an agent, it automatically adapts its communication style to match local dialects and cultural norms.

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`	`/regions`	List all available regions
`GET`	`/regions/{id}`	Get region by ID
`GET`	`/regions/channels`	Get available deployment channels

Region Properties

Property	Type	Description
`id`	`string`	Unique region identifier (UUID)
`name`	`string`	Region/country name
`code`	`string`	Region code (e.g., “uae”, “ksa”, “kwt”)
`flag`	`string`	Country flag emoji
`languages`	`array`	Supported languages (e.g., [“Arabic”, “English”])
`dialects`	`object`	Supported dialects per language
`timezone`	`string`	Local timezone (e.g., “GMT+3”, “GMT+4”)

Available Regions

AlooChat supports the following GCC and MENA regions:

Region	Code	Flag	Languages	Arabic Dialects	Timezone
United Arab Emirates	`uae`	🇦🇪	Arabic, English	Emirati, Gulf	GMT+4
Saudi Arabia	`ksa`	🇸🇦	Arabic, English	Najdi, Hejazi, Gulf	GMT+3
Kuwait	`kwt`	🇰🇼	Arabic, English	Kuwaiti, Gulf	GMT+3
Bahrain	`bhr`	🇧🇭	Arabic, English	Bahraini, Gulf	GMT+3
Qatar	`qat`	🇶🇦	Arabic, English	Qatari, Gulf	GMT+3
Oman	`omn`	🇴🇲	Arabic, English	Omani, Gulf	GMT+4
Jordan	`jor`	🇯🇴	Arabic, English	Jordanian, Levantine	GMT+3
Lebanon	`lbn`	🇱🇧	Arabic, English, French	Lebanese, Levantine	GMT+3
Egypt	`egy`	🇪🇬	Arabic, English	Egyptian	GMT+2

Available Channels

Channel	Description
`web`	Web widget integration
`whatsapp`	WhatsApp Business API
`telegram`	Telegram Bot API
`slack`	Slack workspace integration
`messenger`	Facebook Messenger
`voice`	Voice/phone integration
`api`	Direct API access

List Regions

Retrieve all available deployment regions.

Endpoint: GET /regions

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

const response = await fetch('https://api.aloochat.ai/api/public/regions', {
  method: 'GET',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  }
});
 
const regions = await response.json();
console.log('Available regions:', regions);
 
// Find a specific region for deployment (e.g., UAE for Emirati dialect)
const uaeRegion = regions.find(r => r.code === 'uae');
console.log('UAE region:', uaeRegion);

import requests
 
response = requests.get(
    'https://api.aloochat.ai/api/public/regions',
    headers={
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
    }
)
 
regions = response.json()
print('Available regions:', regions)
 
# Find a specific region for deployment (e.g., Saudi Arabia for Najdi dialect)
ksa_region = next((r for r in regions if r['code'] == 'ksa'), None)
print('Saudi Arabia region:', ksa_region)

<?php
$ch = curl_init();
 
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.aloochat.ai/api/public/regions',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: your_api_key_here',
        'Content-Type: application/json'
    ]
]);
 
$response = curl_exec($ch);
$regions = json_decode($response, true);
curl_close($ch);
 
print_r($regions);
 
// Find a specific region (e.g., Kuwait for Kuwaiti dialect)
$kuwaitRegion = array_filter($regions, function($r) {
    return $r['code'] === 'kwt';
});
print_r(array_values($kuwaitRegion)[0] ?? null);
?>

require 'net/http'
require 'json'
 
uri = URI('https://api.aloochat.ai/api/public/regions')
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)
regions = JSON.parse(response.body)
puts "Available regions: #{regions}"
 
# Find a specific region (e.g., Qatar for Qatari dialect)
qatar_region = regions.find { |r| r['code'] == 'qat' }
puts "Qatar region: #{qatar_region}"

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "United Arab Emirates",
    "code": "uae",
    "flag": "🇦🇪",
    "languages": ["Arabic", "English"],
    "dialects": {
      "Arabic": ["Emirati", "Gulf"]
    },
    "timezone": "GMT+4"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Saudi Arabia",
    "code": "ksa",
    "flag": "🇸🇦",
    "languages": ["Arabic", "English"],
    "dialects": {
      "Arabic": ["Najdi", "Hejazi", "Gulf"]
    },
    "timezone": "GMT+3"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Kuwait",
    "code": "kwt",
    "flag": "🇰🇼",
    "languages": ["Arabic", "English"],
    "dialects": {
      "Arabic": ["Kuwaiti", "Gulf"]
    },
    "timezone": "GMT+3"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "name": "Qatar",
    "code": "qat",
    "flag": "🇶🇦",
    "languages": ["Arabic", "English"],
    "dialects": {
      "Arabic": ["Qatari", "Gulf"]
    },
    "timezone": "GMT+3"
  }
]

Get Region by ID

Retrieve a specific region by its ID.

Endpoint: GET /regions/{id}

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

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

import requests
 
region_id = '550e8400-e29b-41d4-a716-446655440000'
 
response = requests.get(
    f'https://api.aloochat.ai/api/public/regions/{region_id}',
    headers={'x-api-key': 'your_api_key_here'}
)
 
region = response.json()
print('Region details:', region)

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

require 'net/http'
require 'json'
 
region_id = '550e8400-e29b-41d4-a716-446655440000'
uri = URI("https://api.aloochat.ai/api/public/regions/#{region_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)
region = JSON.parse(response.body)
puts region

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "United Arab Emirates",
  "code": "uae",
  "flag": "🇦🇪",
  "languages": ["Arabic", "English"],
  "dialects": {
    "Arabic": ["Emirati", "Gulf"]
  },
  "timezone": "GMT+4"
}

Get Available Channels

Retrieve all available deployment channels.

Endpoint: GET /regions/channels

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

const response = await fetch('https://api.aloochat.ai/api/public/regions/channels', {
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const channels = await response.json();
console.log('Available channels:', channels);
 
// Check if WhatsApp is available
const whatsappChannel = channels.find(c => c.id === 'whatsapp');
if (whatsappChannel) {
  console.log('WhatsApp integration available:', whatsappChannel);
}

import requests
 
response = requests.get(
    'https://api.aloochat.ai/api/public/regions/channels',
    headers={'x-api-key': 'your_api_key_here'}
)
 
channels = response.json()
print('Available channels:', channels)
 
# Check if WhatsApp is available
whatsapp_channel = next((c for c in channels if c['id'] == 'whatsapp'), None)
if whatsapp_channel:
    print('WhatsApp integration available:', whatsapp_channel)

<?php
$ch = curl_init();
 
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.aloochat.ai/api/public/regions/channels',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: your_api_key_here'
    ]
]);
 
$response = curl_exec($ch);
$channels = json_decode($response, true);
curl_close($ch);
 
print_r($channels);
 
// Check if WhatsApp is available
$whatsappChannel = array_filter($channels, function($c) {
    return $c['id'] === 'whatsapp';
});
if (!empty($whatsappChannel)) {
    echo "WhatsApp integration available\n";
}
?>

require 'net/http'
require 'json'
 
uri = URI('https://api.aloochat.ai/api/public/regions/channels')
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)
channels = JSON.parse(response.body)
puts "Available channels: #{channels}"
 
# Check if WhatsApp is available
whatsapp_channel = channels.find { |c| c['id'] == 'whatsapp' }
puts "WhatsApp integration available: #{whatsapp_channel}" if whatsapp_channel

Response

[
  {
    "id": "web",
    "name": "Web Widget",
    "description": "Embed a chat widget on your website"
  },
  {
    "id": "whatsapp",
    "name": "WhatsApp",
    "description": "Connect via WhatsApp Business API"
  },
  {
    "id": "telegram",
    "name": "Telegram",
    "description": "Deploy as a Telegram bot"
  },
  {
    "id": "slack",
    "name": "Slack",
    "description": "Integrate with Slack workspaces"
  },
  {
    "id": "messenger",
    "name": "Facebook Messenger",
    "description": "Connect via Facebook Messenger"
  },
  {
    "id": "voice",
    "name": "Voice",
    "description": "Voice/phone integration with LiveKit"
  },
  {
    "id": "api",
    "name": "API",
    "description": "Direct API access for custom integrations"
  }
]

Using Regions with Deployments

When creating a deployment, you specify a region to determine which language and dialect your AI agent will use when communicating with customers.

Example: Create Deployment with Region

# First, get available regions
curl -X GET "https://api.aloochat.ai/api/public/regions" \
  -H "x-api-key: your_api_key_here"
 
# Then create a deployment with the selected region (e.g., Saudi Arabia)
curl -X POST "https://api.aloochat.ai/api/public/deployments" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "deployable_type": "agent",
    "deployable_id": "your-agent-uuid",
    "channel": "whatsapp",
    "region_id": "550e8400-e29b-41d4-a716-446655440001",
    "languages": "ar,en"
  }'

// Get available regions
const regionsResponse = await fetch('https://api.aloochat.ai/api/public/regions', {
  headers: { 'x-api-key': 'your_api_key_here' }
});
const regions = await regionsResponse.json();
 
// Find the best region for your customers (e.g., UAE for Emirati dialect)
const uaeRegion = regions.find(r => r.code === 'uae');
 
// Create deployment with selected region
const deploymentResponse = await fetch('https://api.aloochat.ai/api/public/deployments', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deployable_type: 'agent',
    deployable_id: 'your-agent-uuid',
    channel: 'whatsapp',
    region_id: uaeRegion.id,
    languages: 'ar,en'
  })
});
 
const deployment = await deploymentResponse.json();
console.log('Deployment created:', deployment);

import requests
 
# Get available regions
regions_response = requests.get(
    'https://api.aloochat.ai/api/public/regions',
    headers={'x-api-key': 'your_api_key_here'}
)
regions = regions_response.json()
 
# Find the best region for your customers (e.g., Kuwait for Kuwaiti dialect)
kuwait_region = next((r for r in regions if r['code'] == 'kwt'), None)
 
# Create deployment with selected region
deployment_response = requests.post(
    'https://api.aloochat.ai/api/public/deployments',
    headers={
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'deployable_type': 'agent',
        'deployable_id': 'your-agent-uuid',
        'channel': 'whatsapp',
        'region_id': kuwait_region['id'],
        'languages': 'ar,en'
    }
)
 
deployment = deployment_response.json()
print('Deployment created:', deployment)

Region Selection Best Practices

1. Choose Based on Customer Location & Dialect

Select the region that matches your customers’ location to ensure the AI agent uses the appropriate Arabic dialect.

Customer Location	Recommended Region	Primary Dialect
UAE	`uae`	Emirati, Gulf
Saudi Arabia	`ksa`	Najdi, Hejazi, Gulf
Kuwait	`kwt`	Kuwaiti, Gulf
Bahrain	`bhr`	Bahraini, Gulf
Qatar	`qat`	Qatari, Gulf
Oman	`omn`	Omani, Gulf
Jordan	`jor`	Jordanian, Levantine
Lebanon	`lbn`	Lebanese, Levantine
Egypt	`egy`	Egyptian

2. Dialect Considerations

Gulf Arabic - Common across UAE, Saudi Arabia, Kuwait, Bahrain, Qatar, and Oman
Levantine Arabic - Used in Jordan and Lebanon
Egyptian Arabic - Widely understood across the Arab world

3. Multi-Region Deployments

If your business serves customers across multiple GCC countries, consider creating separate deployments for each region to provide the most natural communication experience.

Error Responses

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

Error Response Format

{
  "detail": "Region not found"
}

Integrations Companies