Documentation
API reference, integration guides, deployment, and administration — everything you need to extend and operate the platform.
Authenticate, query, and mutate your Octavion data programmatically.
All API requests require a Bearer token in the Authorization header. Generate API keys in Settings → Integrations → API Keys. Each key can be scoped to specific modules (CRM, ERP, Call Center) and rate-limited. Tokens do not expire unless revoked by an administrator.
The API is served at https://app.octavion.ae/api/. All endpoints are unversioned — breaking changes are announced 30 days in advance with a deprecation header. Responses are JSON with consistent envelope: { data, meta, error }.
Core resources: /api/leads (CRUD), /api/customers, /api/opportunities, /api/invoices, /api/items, /api/calls, /api/messages, /api/employees, /api/queues, /api/agents. Each supports GET (list with filters), GET /:id, POST (create), PATCH /:id (update), and DELETE /:id. List endpoints accept ?page, ?limit, ?sort, and ?filter[] query parameters.
List endpoints return paginated results: { data: [...], meta: { page, limit, total, pages } }. Filter with ?filter[status]=Open&filter[owner]=user@example.com. Sort with ?sort=-created_at (prefix - for descending). Default limit is 20, maximum is 100.
Errors return a standard object: { error: { code: "VALIDATION_ERROR", message: "...", details: [...] } }. HTTP status codes follow REST conventions: 400 (validation), 401 (auth), 403 (permission), 404 (not found), 429 (rate limit), 500 (server). Rate-limited responses include Retry-After and X-RateLimit-Remaining headers.
Configure webhooks in Settings → Integrations → Webhooks. Events include lead.created, call.completed, invoice.submitted, message.received, and 40+ more. Payloads are POST requests with JSON body and an X-Octavion-Signature header (HMAC-SHA256) for verification. Failed deliveries retry 3 times with exponential backoff.
SIP trunks, FreeSWITCH, IVR, and call routing configuration.
Navigate to Settings → Telephony → SIP Trunks. Click 'Add Trunk' and select a preset: Etisalat (IP authentication), du (IP authentication), or International (SIP registration). For IP auth trunks, enter the provider's gateway IP and your authorized IP. For registration trunks, enter the SIP server, username, password, and realm. Click Save — the system writes the gateway to the PBX and reloads FreeSWITCH automatically.
Octavion's telephony runs on FreeSWITCH managed through FusionPBX. The dashboard communicates with FreeSWITCH via ESL (Event Socket Layer) for real-time events, and writes configuration to the FusionPBX PostgreSQL database. Changes are applied with a reloadxml + sofia profile rescan — no manual CLI needed.
Extensions are managed in Call Center → Extensions. Each extension has a number, password, and voicemail box. Ring groups bundle extensions so multiple phones ring on one number. Strategies include simultaneous, sequential, and enterprise (ring all for N seconds, then overflow).
Build IVR menus in Call Center → IVR Builder. Upload audio prompts in Arabic and English. Map DTMF digits to destinations: ring groups, queues, extensions, voicemail, or sub-menus. Set a timeout action for callers who don't press any key.
Recordings are stored on the server filesystem under /var/lib/freeswitch/recordings/ organized by date. The dashboard serves recordings through a signed-URL API so they are never publicly accessible. Retention policies can be configured per queue — recordings older than the retention period are automatically purged.
Connect external services: WhatsApp, Twilio, the ERP engine, and custom webhooks.
In Settings → WhatsApp, enter your WhatsApp Business API credentials (phone number ID, access token, and webhook verify token). Configure the webhook URL provided by Octavion in your Meta Business Manager. Once connected, inbound and outbound WhatsApp messages appear in the messaging inbox and are linked to CRM records automatically.
Enter your Twilio Account SID, Auth Token, and phone number in Settings → Telephony. Twilio acts as a fallback voice carrier when no SIP trunk is configured, and provides SMS send/receive capability. Number verification and import are handled from the same settings page.
Octavion's ERP module connects to the ERP engine via a secure token-authenticated API. The connection is configured through server environment variables. All ERP operations — invoices, inventory, HR — go through this API, and the dashboard creates and reads ERP records directly.
Set up outbound webhooks for any event in Settings → Integrations → Webhooks. Select the events to subscribe to, enter the destination URL, and optionally set a secret for HMAC signature verification. Test the webhook with a sample payload before saving. View delivery logs to debug failed attempts.
Two embeddable widgets are available for your website: the Chat Widget (live web chat routed to your messaging inbox) and the Callback Widget (visitors request a call-back, which creates a queued outbound call). Both are added with a single <script> tag and styled to match your brand.
Self-hosting, environment variables, database, backups, and updates.
Octavion runs on a single Linux server (Ubuntu 22.04+ recommended). Minimum: 4 vCPUs, 8 GB RAM, 80 GB SSD. The stack includes Node.js 20+, PostgreSQL 15+, FreeSWITCH, and FusionPBX. A dedicated service runs the ERP backend. All services communicate over localhost.
Configuration is managed through environment variables in the application root, covering the database connection, ERP engine endpoint and token, telephony (PBX/SIP) settings, messaging providers, AI provider keys, and session secrets. These values are provisioned securely per deployment and are never committed to version control.
The dashboard uses PostgreSQL for its own tables (users, sessions, audit logs, knowledge base, call tracking, campaigns, etc.) and reads from the FusionPBX PostgreSQL database for telephony data. The ERP engine uses its own dedicated database. Migrations are applied automatically on startup.
Nginx serves as the reverse proxy for all services: the marketing site (port 3100), the dashboard (port 3002), the ERP engine, and the source repository. SSL certificates are managed with Certbot (Let's Encrypt) and auto-renew. Each subdomain (octavion.ae, app.octavion.ae, erp.octavion.ae, git.octavion.ae) has its own Nginx server block.
Database backups should be scheduled with pg_dump for PostgreSQL and the ERP engine's native backup command. Store backups off-server (S3 or another VPS). Call recordings can be rsynced to backup storage. We recommend daily database backups and weekly full-system snapshots.
Pull the latest code from your Gitea repository, run the build command, and restart the PM2 process. Database migrations apply automatically. For ERP engine updates, follow the standard managed update procedure. Always back up before updating.
Brand the platform as your own — logo, colors, domain, and client-facing widgets.
Replace the Octavion logo and color scheme with your own in Settings → Appearance. Upload your logo (SVG recommended), set a primary color, and choose light or dark mode as the default. Changes apply to the dashboard, login page, and email templates.
Point your domain's DNS to your server IP and add the domain in Nginx. Certbot will provision an SSL certificate automatically. Your clients will access the platform at your domain — no Octavion branding visible anywhere.
Each workspace is isolated by tenant ID. Users in one tenant cannot see data from another. The admin console (admin.octavion.ae) manages tenant provisioning, plan assignments, and usage monitoring. Each tenant gets its own database schema and PBX domain.
The chat widget and callback widget inherit your branding automatically. Colors, welcome messages, and offline behavior are configurable per tenant. Embed them on your clients' websites with a tenant-specific script tag.
Authentication, audit logging, data protection, and UAE compliance.
User authentication uses JWT tokens with secure HTTP-only cookies. Sessions expire after 24 hours of inactivity. Passwords are hashed with bcrypt. Two-factor authentication can be enabled per user. Failed login attempts are logged in the audit trail.
Four built-in roles control access: Admin (full access), Manager (department pages + reports), Agent (operational pages only), and Viewer (read-only dashboards). Admins assign roles in Settings → Team. Page-level permissions are enforced both in the sidebar and on the API.
Every significant action is logged: user logins, data changes, API key usage, telephony changes, and admin operations. Audit logs are immutable and queryable in Settings → Security → Audit Log. Logs include the user, action, timestamp, IP address, and affected record.
Because Octavion is self-hosted, your data resides on infrastructure you control. No customer data is sent to external servers except where you explicitly configure it (Twilio for calls, WhatsApp API for messages). AI copilot queries are sent to Anthropic's API but your business data is not stored by the AI provider.
The ERP module supports FTA-compliant e-invoicing with proper VAT handling. Payroll generates WPS-ready files. Telephony configuration respects UAE telecom regulations. The privacy policy and terms of service templates are written for UAE jurisdiction.
Related Resources
New to Octavion? Start with the user manual for a guided walkthrough, or browse frequently asked questions.
Free API access on every plan. No credit card required.