# SIP Channel

Create a SIP Channel and route calls from your PBX or SIP provider to its SIP URI. The Channel assigns those calls to an Assistant.

## How it works

Creating a SIP Channel provisions a LiveKit inbound trunk and dispatch rule. Reecall uses the Channel's Assistant assignment and whitelists to configure call routing.

### Call flow

<Mermaid chart={`sequenceDiagram
    participant Caller
    participant ClientSIP as Your SIP Trunk
    participant Livekit as Livekit SIP Trunk
    participant Assistant

    Caller->>ClientSIP: Initiates call
    ClientSIP->>Livekit: Routes SIP INVITE
    Livekit->>Livekit: Validates destination number<br/>and configured source IP restrictions
    Livekit->>Assistant: Routes to assigned Assistant
    Assistant-->>Caller: Conversation begins`} />

For each incoming call:

1. **Caller** initiates a phone call through their phone system
2. **Your SIP Trunk** (your SIP provider or PBX) routes the call to Reecall
3. **Livekit SIP Trunk** receives the call, validates it against your configured whitelists, and routes it to the assigned Assistant
4. **Assistant** receives the call and begins the conversation

***

## Configuring your SIP trunk

Configure your PBX or SIP provider to forward calls to Reecall's SIP endpoint.

### Reecall SIP endpoint

Copy the SIP URI shown for your Assistant's SIP Channel in the portal. The endpoint depends on the deployment. Route calls to that URI, for example:

```text
sip:<your-reecall-sip-host>
```

### Configuration steps

1. **Access your SIP trunk settings** in your PBX or SIP provider's admin panel
2. **Create an outbound route or trunk** pointing to Reecall's SIP URI
3. **Configure call forwarding rules** to route specific numbers or all calls to this trunk
4. **Whitelist Reecall's endpoint** if your system requires it for outbound SIP traffic

:::warning{title="Important"}

Provide at least one non-empty whitelist. If you configure both, the destination number must match `inboundNumbersWhitelist` and the source IP must satisfy the configured address restriction. IP enforcement also requires enablement on the LiveKit project; confirm it with Reecall before relying on it. See [LiveKit's inbound trunk documentation](https://docs.livekit.io/telephony/accepting-calls/inbound-trunk/).

:::

### Generic PBX configuration

Configure your PBX or SIP provider with these settings:

| Setting     | Value                              |
| ----------- | ---------------------------------- |
| Trunk Type  | SIP                                |
| Remote Host | Host from the SIP URI shown in the portal |
| Transport   | UDP or TCP                         |
| Port        | 5060                               |

Refer to your specific PBX or SIP provider documentation for exact configuration steps.

***

## Creating a SIP Channel

### Required fields

| Field                       | Required | Description                                                                             |
| --------------------------- | -------- | --------------------------------------------------------------------------------------- |
| `name`                      | Yes        | Display name for the Channel                                       |
| `type`                      | Yes        | Must be `SIP` for SIP Channels                                     |
| `assistantId`               | Yes        | The Assistant to handle calls on this Channel |
| `inboundNumbersWhitelist`   | One needed       | Provider phone numbers this trunk accepts calls for (E.164 format)                      |
| `inboundAddressesWhitelist` | One needed       | IP addresses allowed to send SIP traffic                                                |

:::warning{title="Important"}

At least one of `inboundNumbersWhitelist` or `inboundAddressesWhitelist` must contain an entry.

:::

### Create request

Use a project-scoped API key, or include `projectId` in the payload with an organization-scoped key. Data API paths below are relative to the server URL in the [API reference](/api), which includes `/data_next`.

```http
POST /conversational/channels
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "name": "Customer Support Hotline",
  "type": "SIP",
  "description": "Main support line for customer inquiries",
  "assistantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "inboundNumbersWhitelist": ["+14155551234", "+14155555678"]
}
```

### Response

```json
{
  "id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
  "name": "Customer Support Hotline",
  "type": "SIP",
  "description": "Main support line for customer inquiries",
  "assistantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "inboundNumbersWhitelist": ["+14155551234", "+14155555678"],
  "inboundAddressesWhitelist": [],
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```

***

## Configuration options

### Using phone number whitelist

Specify which provider phone numbers (destination numbers you own) this trunk should accept calls for. If none are specified, the trunk accepts calls to any number. Use E.164 format:

```json
{
  "name": "VIP Customer Line",
  "type": "SIP",
  "assistantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "inboundNumbersWhitelist": [
    "+14155551234",
    "+442071234567",
    "+33142123456"
  ]
}
```

### Using IP address whitelist

Restrict SIP traffic to the source IP addresses or CIDR ranges used by your PBX or SIP provider. Confirm that IP enforcement is enabled on the LiveKit project before relying on this restriction:

```json
{
  "name": "Office PBX Integration",
  "type": "SIP",
  "assistantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "inboundAddressesWhitelist": [
    "192.168.1.100",
    "10.0.0.0/24"
  ]
}
```

### Combining both whitelists

You can configure both restrictions together: calls must match the destination number and the enforced source IP restriction:

```json
{
  "name": "Hybrid Channel",
  "type": "SIP",
  "assistantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "inboundNumbersWhitelist": ["+14155551234"],
  "inboundAddressesWhitelist": ["192.168.1.100"]
}
```

***

## Updating a Channel

Update Channel properties using PATCH. Changes to whitelist configurations are automatically synchronised with the underlying SIP infrastructure.

```http
PATCH /conversational/channels/{channelId}
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "inboundNumbersWhitelist": ["+14155551234", "+14155559999"],
  "description": "Updated support line"
}
```

***

## Deleting a Channel

When you delete a Channel, the system automatically cleans up all associated SIP infrastructure.

```http
DELETE /conversational/channels/{channelId}
Authorization: Bearer <your-api-token>
```

***

## Constraints

* An Assistant can have one SIP Channel and one WebRTC Channel. Creating a second Channel of the same type for that Assistant returns an error.

* **Whitelist requirement**: SIP Channels must have at least one entry in either `inboundNumbersWhitelist` or `inboundAddressesWhitelist`.
