--- sidebar_position: 5 title: SIP Trunks description: Manage SIP trunk connections, Inbound IP Access Control Lists (ACLs), and Outbound Gateways via the Firetell REST API. --- # SIP Trunks SIP Trunks allow you to connect your existing IP PBX or telephony infrastructure to Firetell's cloud communications network for inbound and outbound voice traffic. SIP Trunking in Firetell consists of two primary resources: 1. **Inbound IP Access Control Lists (ACLs)**: Whitelist IP addresses or CIDR blocks allowed to send inbound SIP calls into Firetell. 2. **Outbound Gateways**: Configure outbound carrier SIP trunks, origination target URIs, protocols, and SIP authentication credentials. --- ## Resource Endpoints ### Inbound IP Access Control Lists (ACLs) | Method | Endpoint | Description | | -------- | --------------------- | -------------------------------- | | `GET` | `/sip-trunks/acls` | List all Inbound ACLs | | `GET` | `/sip-trunks/acls/:id` | Get Inbound ACL details | | `POST` | `/sip-trunks/acls` | Create an Inbound ACL | | `PATCH` | `/sip-trunks/acls/:id` | Update an Inbound ACL | | `DELETE` | `/sip-trunks/acls/:id` | Delete an Inbound ACL | ### Outbound Gateways | Method | Endpoint | Description | | -------- | ------------------------- | ----------------------------- | | `GET` | `/sip-trunks/gateways` | List all Outbound Gateways | | `GET` | `/sip-trunks/gateways/:id` | Get Outbound Gateway details | | `POST` | `/sip-trunks/gateways` | Create an Outbound Gateway | | `PATCH` | `/sip-trunks/gateways/:id` | Update an Outbound Gateway | | `DELETE` | `/sip-trunks/gateways/:id` | Delete an Outbound Gateway | --- # Part 1: Inbound IP Access Control Lists (ACLs) Inbound ACLs control which remote IP addresses or subnets are authorized to send inbound SIP traffic into your Firetell workspace. ## The ACL Object | Field | Type | Description | | ------------- | -------- | -------------------------------------------------------------- | | `id` | string | Unique ACL identifier (prefixed with `acl_`) | | `workspace_id`| string | Workspace identifier | | `title` | string | Descriptive label for this ACL | | `mode` | string | Filter mode (`ip` or `domain`) | | `allowed_ips` | array | List of authorized IPv4/IPv6 addresses or CIDR blocks (max: 5) | | `created_at` | string | ISO 8601 creation timestamp | | `updated_at` | string | ISO 8601 last update timestamp | --- ## List Inbound ACLs ``` GET /sip-trunks/acls ``` ### Query Parameters | Parameter | Type | Default | Description | | ------------ | ------ | ------------ | ------------------------------------------------- | | `page` | number | `1` | Page number | | `limit` | number | `10` | Items per page (max: 100) | | `search` | string | — | Search by ACL title | | `sort_field` | string | `created_at` | Sort field (`created_at`, `title`) | | `sort_order` | string | `desc` | Sort direction (`asc`, `desc`) | ### Response `200 OK` ```json { "data": [ { "id": "acl_123456789", "workspace_id": "ws_company", "title": "Primary PBX Server", "mode": "ip", "allowed_ips": ["118.69.123.45", "203.162.0.0/24"], "created_at": "2026-07-21T15:00:00.000Z", "updated_at": "2026-07-21T15:00:00.000Z" } ], "meta": { "total": 1, "page": 1, "limit": 10, "total_pages": 1 } } ``` --- ## Create Inbound ACL ``` POST /sip-trunks/acls ``` ### Request Body ```json { "title": "Backup Data Center PBX", "mode": "ip", "allowed_ips": ["14.225.10.12/32"] } ``` ### Response `201 Created` ```json { "id": "acl_987654321", "workspace_id": "ws_company", "title": "Backup Data Center PBX", "mode": "ip", "allowed_ips": ["14.225.10.12/32"], "created_at": "2026-07-21T15:15:00.000Z", "updated_at": "2026-07-21T15:15:00.000Z" } ``` --- ## Update Inbound ACL ``` PATCH /sip-trunks/acls/:id ``` ### Request Body ```json { "title": "HQ Asterisk PBX", "allowed_ips": ["118.69.123.45", "118.69.123.46"] } ``` ### Response `200 OK` ```json { "id": "acl_123456789", "workspace_id": "ws_company", "title": "HQ Asterisk PBX", "mode": "ip", "allowed_ips": ["118.69.123.45", "118.69.123.46"], "updated_at": "2026-07-21T15:20:00.000Z" } ``` --- ## Delete Inbound ACL ``` DELETE /sip-trunks/acls/:id ``` ### Response `200 OK` ```json { "id": "acl_123456789", "workspace_id": "ws_company", "title": "HQ Asterisk PBX" } ``` --- # Part 2: Outbound Gateways Outbound Gateways define carrier trunks and remote SIP endpoints for routing outbound calls from Firetell to external telco networks or private PBX systems. ## The Gateway Object | Field | Type | Description | | --------------------- | -------- | -------------------------------------------------------------------- | | `id` | string | Unique gateway identifier (prefixed with `gw_`) | | `workspace_id` | string | Workspace identifier | | `title` | string | Descriptive label for this gateway | | `outbound_caller_id` | string | Default caller ID number to present when placing calls via this trunk | | `outbound_uris` | array | Array of target SIP destination URIs (1 to 10 targets) | | `outbound_uris[].uri` | string | Destination IP or FQDN host (e.g. `sip.telco.com` or `1.2.3.4`) | | `outbound_uris[].port`| number | SIP port (`1` to `65535`, default `5060`) | | `outbound_uris[].protocol` | string | Transport protocol (`udp`, `tcp`, `tls`) | | `outbound_uris[].priority` | number | Routing priority order (`1` highest to `10`) | | `credential` | object | SIP Digest authentication credentials (if required by trunk provider)| | `credential.username` | string | SIP auth username | | `created_at` | string | ISO 8601 creation timestamp | | `updated_at` | string | ISO 8601 last update timestamp | --- ## List Outbound Gateways ``` GET /sip-trunks/gateways ``` ### Response `200 OK` ```json { "data": [ { "id": "gw_abc123456", "workspace_id": "ws_company", "title": "Viettel Carrier Trunk", "outbound_caller_id": "842471001234", "outbound_uris": [ { "uri": "10.0.1.50", "port": 5060, "protocol": "udp", "priority": 1 } ], "credential": { "username": "vt_trunk_user" }, "created_at": "2026-07-21T15:05:00.000Z", "updated_at": "2026-07-21T15:05:00.000Z" } ], "meta": { "total": 1, "page": 1, "limit": 10, "total_pages": 1 } } ``` --- ## Create Outbound Gateway ``` POST /sip-trunks/gateways ``` ### Request Body ```json { "title": "FPT Telecom Trunk", "outbound_caller_id": "842873009999", "outbound_uris": [ { "uri": "sip.fpttelecom.vn", "port": 5060, "protocol": "udp", "priority": 1 } ], "credential": { "username": "fpt_user", "password": "SecretPassword123" } } ``` ### Response `201 Created` ```json { "id": "gw_xyz789012", "workspace_id": "ws_company", "title": "FPT Telecom Trunk", "outbound_caller_id": "842873009999", "outbound_uris": [ { "uri": "sip.fpttelecom.vn", "port": 5060, "protocol": "udp", "priority": 1 } ], "created_at": "2026-07-21T15:25:00.000Z", "updated_at": "2026-07-21T15:25:00.000Z" } ``` --- ## Update Outbound Gateway ``` PATCH /sip-trunks/gateways/:id ``` ### Request Body ```json { "title": "FPT Telecom Primary Trunk", "outbound_uris": [ { "uri": "sip.fpttelecom.vn", "port": 5061, "protocol": "tls", "priority": 1 } ] } ``` ### Response `200 OK` ```json { "id": "gw_xyz789012", "workspace_id": "ws_company", "title": "FPT Telecom Primary Trunk", "outbound_uris": [ { "uri": "sip.fpttelecom.vn", "port": 5061, "protocol": "tls", "priority": 1 } ], "updated_at": "2026-07-21T15:30:00.000Z" } ``` --- ## Delete Outbound Gateway ``` DELETE /sip-trunks/gateways/:id ``` ### Response `200 OK` ```json { "id": "gw_xyz789012", "workspace_id": "ws_company", "title": "FPT Telecom Primary Trunk" } ```