---
sidebar_position: 1
title: Introduction
description: Introduction to the Firetell Developer Platform — Cloud Communications APIs for voice, calls, SIP, and AI.
---

# Introduction

Welcome to the **Firetell Developer Platform**. Firetell provides a suite of cloud communications APIs that enable you to build voice-powered applications, automate call workflows, and integrate intelligent voice agents into your products.

## What is Firetell?

Firetell is a **Communications Platform as a Service (CPaaS)** that offers:

- **Cloud Phone Numbers** — Provision and manage virtual phone numbers worldwide
- **Programmable Voice** — Make, receive, and control calls via API
- **Smart IVR / Call Flows** — Build drag-and-drop interactive voice response systems
- **SIP Trunking** — Connect your existing PBX infrastructure to the cloud
- **Call Center** — Manage agents, teams, queues, and call routing
- **Voice AI** — Deploy AI-powered voice agents for customer interactions
- **Call Recording** — Record and store call audio for compliance and quality assurance
- **Webhooks** — Receive real-time event notifications

## Who is this for?

This documentation is designed for **developers** who want to integrate Firetell's capabilities into their applications using our REST APIs, webhooks, and SDKs.

## Base URL

Each workspace has its own unique regional domain based on the region selected at creation time:

```
{workspace_id}.{regional_domain}
```

The base URL for all developer API requests follows this pattern:

```
https://{workspace_id}.{regional_domain}/api/v1
```

To find your exact workspace domain:

1. Log in to [Firetell Console](https://console.firetell.com)
2. Select your workspace
3. Go to **Workspace Settings** → **General**
4. Copy the **Domain** value (e.g., `yourcompany.firetell.vn`, `yourcompany.firetell.asia`, or `yourcompany.firetell.us`)

For example, if your workspace ID is `yourcompany` in the **Vietnam (`asia-east-1`)** region, your API base URL is:

```
https://yourcompany.firetell.vn/api/v1
```

:::tip[Documentation Placeholder Convention]
Throughout this documentation, examples use `https://{workspace_id}.firetell.app/api/v1` for brevity. When making requests, replace `{workspace_id}.firetell.app` with your workspace's actual regional domain (`{workspace_id}.{regional_domain}`).
:::

## Workspaces & Regions

When you create a workspace, Firetell **automatically suggests the region closest to your current location**, or you can manually select any other region that best serves your customers and agents.

Once you enter your `workspace_id` and select a region, your workspace domain is provisioned as `{workspace_id}.{regional_domain}` and DNS-resolved directly to that regional server cluster.

### How It Works

```
Create workspace "companyA" with region ASIA-SOUTH1 (Singapore)
                    │
                    ▼
  companyA.firetell.asia  →  DNS  →  asia-south-1 cluster
                                     ├─ API servers
                                     ├─ Database
                                     ├─ Media servers
                                     ├─ Signaling servers
                                     └─ Storage servers
```

All API traffic, call data, recordings, and agent sessions for that workspace are processed and stored within the selected region.

### Available Regions

Each region uses a dedicated regional domain (`{regional_domain}`):

| Region            | ID               | Location       | Regional Domain   | Workspace Domain Pattern          |
| ----------------- | ---------------- | -------------- | ----------------- | --------------------------------- |
| **ASIA-EAST1**    | `asia-east-1`    | Vietnam        | `firetell.vn`     | `{workspace_id}.firetell.vn`      |
| **ASIA-SOUTH1**   | `asia-south-1`   | Singapore      | `firetell.asia`   | `{workspace_id}.firetell.asia`    |
| **US-EAST1**      | `us-east-1`      | United States  | `firetell.us`     | `{workspace_id}.firetell.us`      |
| **EUROPE-NORTH1** | `europe-north-1` | France         | `eu.firetell.com` | `{workspace_id}.eu.firetell.com`  |
| **Other Regions** | —                | Global / Other | `firetell.app`    | `{workspace_id}.firetell.app`     |

:::warning
The region **cannot be changed** after workspace creation. Choose the region closest to your customers and agents for the lowest voice and API latency.
:::

:::note
**Need a custom domain?**

Enterprise customers can use their own domain (e.g., `api.yourcompany.com`) instead of the default regional domain (`*.firetell.vn`, `*.firetell.asia`, `*.firetell.us`, `*.eu.firetell.com`, or `*.firetell.app`). Contact [enterprise@firetell.com](mailto:enterprise@firetell.com) for details.
:::

## Call Center Portal

Every workspace comes with a **ready-to-use Call Center Portal** that your agents can use immediately — no development required.

### Access Points

| Platform    | URL / App                                                                       | Description                      |
| ----------- | ------------------------------------------------------------------------------- | -------------------------------- |
| **Web**     | `https://{workspace_id}.{regional_domain}`                             | Browser-based agent portal       |
| **iOS**     | [App Store](https://apps.apple.com/us/app/firetell-agent/id6812291119)          | Native iOS app with VoIP push    |
| **Android** | [Google Play](https://play.google.com/store/apps/details?id=com.firetell.agent) | Native Android app with FCM push |

Agents log in with their username and password to make/receive calls, manage their availability, chat with team members, and more.

### Built on the Same API

The Call Center Portal is built entirely on the **same public API** documented here. This means:

- Everything the portal does, **your app can do too**
- The portal serves as a **reference implementation** of the API
- You can build your own custom agent experience using the same endpoints

### Open Source

The Call Center Portal source code is available on GitHub:

| Repository                                                                          | Platform       | Description                    |
| ----------------------------------------------------------------------------------- | -------------- | ------------------------------ |
| [firetell-call-center-web](https://github.com/firetellcom/firetell-call-center-web) | Web            | Browser-based portal (Angular) |
| [firetell-call-center-app](https://github.com/firetellcom/firetell-call-center-app) | iOS, Android   | Mobile app (Flutter)           |
| —                                                                                   | Windows, macOS | Desktop app _(coming soon)_    |

You can fork and customize these apps to match your brand, add custom features, or use them as a starting point for your own agent application.

## Authentication

Firetell APIs support authentication using either a server-side **API Key** or a client-side **JWT Token**.

### API Key (Server)

Used for backend/server-to-server integrations.

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/phone-numbers" \
  -H "Authorization: ApiKey YOUR_API_KEY"
```

### JWT Token (Client)

Used for client-side applications (such as WebRTC or mobile SDKs) to authenticate agents or clients securely.

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/phone-numbers" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

See the [Authentication](/developers/getting-started/authentication) guide and [Client Authentication](/developers/sdks/javascript/authentication) guide for more details.

## Next Steps

- [Authentication](/developers/getting-started/authentication) — Learn how to authenticate API requests
- [Quickstart](/developers/getting-started/quickstart) — Make your first API call
- [API Reference](/developers/rest-api/overview) — Explore all available endpoints
