Skip to content

Commit 5434c55

Browse files
hey-augusthey-august
authored
LiveKit integration guides (#482)
* init * fixes * move, split content * finish inbound guide, move outbound * cleanup * finish outbound guide * dejlete unneeded category * indexes * edits to Inbound
1 parent 13f2031 commit 5434c55

File tree

5 files changed

+338
-2
lines changed

5 files changed

+338
-2
lines changed

‎website/docs/main/home/calling/ai/guides/Integrations/index.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,6 @@ title: Integrations
44
description: Learn how to integrate different AI services with SignalWire
55
---
66

7+
Integrate with other popular platforms using these guides.
78

8-
9-
<GuidesList />
9+
<GuidesList />

‎website/docs/main/home/calling/ai/guides/Integrations/livekit/_category_.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
label: LiveKit

‎website/docs/main/home/calling/ai/guides/Integrations/livekit/inbound.mdx

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: Route inbound calls to LiveKit
3+
sidebar_label: Inbound
4+
description: Route calls to LiveKit via SIP and SWML's Connect method.
5+
slug: /ai/guides/integrations/livekit/inbound
6+
---
7+
8+
import CreateSWML from '/docs/main/_common/dashboard/create-swml-script.mdx'
9+
10+
# Route inbound calls to a LiveKit Agent
11+
12+
<Subtitle>Send inbound PSTN calls to LiveKit with SWML `connect`</Subtitle>
13+
14+
In this guide, we will deploy a
15+
[SWML](/swml)
16+
script that routes inbound calls from SignalWire to the LiveKit platform.
17+
The script uses the SWML [`connect`](/swml/methods/connect) method
18+
to dial a LiveKit SIP address.
19+
20+
## Prerequisites
21+
22+
Before getting started, you'll need the following:
23+
24+
- a [SignalWire Space][signup]
25+
- a [LiveKit account][livekit]
26+
- a [SignalWire phone number][buy-phone]
27+
28+
## Setup
29+
30+
<Steps>
31+
32+
### Create a SWML Script
33+
34+
<CreateSWML/>
35+
36+
- Log in to your SignalWire Dashboard and navigate to the [**Resources**](https://my.signalwire.com/?page=resources) tab on the left-hand sidebar.
37+
- Click **Add**, select **Script**, and then choose **SWML Script**.
38+
- Paste the following SWML code snippet into the editor:
39+
40+
```yaml
41+
version: 1.0.0
42+
sections:
43+
main:
44+
- connect:
45+
to: sip:%{call.to}@your-unique-SIP-domain-from-Livekit.com
46+
```
47+
48+
Be sure to replace `your-unique-SIP-domain-from-Livekit.com` with the SIP domain from your LiveKit settings
49+
(for example, `241ozqza.sip.livekit.cloud`).
50+
Find this domain under **LiveKit Settings** labeled as **SIP URI**.
51+
52+
- Save the SWML script once the modifications are complete.
53+
54+
### Assign a phone number
55+
56+
When your SignalWire phone number receives an inbound call, it needs to know how to handle it.
57+
In this step, we will assign the intended SignalWire phone number to the
58+
new SWML script Resource as an Address.
59+
60+
:::tip Resources and Addresses
61+
On the SignalWire platform,
62+
[Resources](/platform/call-fabric/resources),
63+
including SWML scripts,
64+
are powerful building blocks that can orchestrate any kind of communications application.
65+
Each Resource can have multiple
66+
[Addresses](/platform/call-fabric/addresses),
67+
such as phone numbers, SIP addresses, and aliases.
68+
:::
69+
70+
- Open the [**Phone Numbers**](https://my.signalwire.com/?page=phone_numbers) tab of your SignalWire Dashboard.
71+
- Select the **Edit Settings** option for the phone number you want to use for inbound calls.
72+
- Click **Assign Resource** and choose the SWML script you just created.
73+
74+
This ensures that incoming calls to the designated SignalWire phone number follow the routing path defined in the SWML script.
75+
76+
### Configure LiveKit
77+
78+
Next, we will configure a SIP trunk in LiveKit to handle calls routed from SignalWire.
79+
Follow the official LiveKit
80+
[SIP trunk inbound guide](https://docs.livekit.io/sip/trunk-inbound/)
81+
for further information.
82+
83+
### Add a LiveKit SIP Trunk
84+
85+
- Create a new SIP trunk using the following configuration:
86+
87+
```json
88+
{
89+
"trunk": {
90+
"name": "My trunk",
91+
"numbers": ["+1XXXXXXXXXX"]
92+
}
93+
}
94+
```
95+
96+
Be sure to replace `+1XXXXXXXXXX` with the SignalWire phone number you assigned previously.
97+
Ensure the number is formatted in E.164 format.
98+
99+
- Submit your configuration.
100+
101+
</Steps>
102+
103+
After completing this setup, you can use LiveKit's dispatch rules to determine how incoming calls should be handled.
104+
Consult LiveKit's
105+
[Dispatch Rules Guide](https://docs.livekit.io/sip/dispatch-rule/)
106+
for guidance on managing call routing.
107+
108+
You're all set to start handling inbound calls with LiveKit and SignalWire.
109+
If you need further assistance, consult the
110+
[LiveKit documentation](https://docs.livekit.io)
111+
or reach out to SignalWire support.
112+
113+
## Next steps
114+
115+
### Troubleshooting
116+
117+
- If calls are not reaching LiveKit:
118+
- Verify that the **SIP domain** in your SWML script matches your LiveKit settings.
119+
- Ensure your phone number is correctly formatted in the trunk configuration.
120+
121+
### Record calls
122+
123+
To record inbound calls, add the `record_call` method to your existing inbound SWML script:
124+
```yaml
125+
version: 1.0.0
126+
sections:
127+
main:
128+
- record_call:
129+
format: mp3
130+
- connect:
131+
to: sip:%{call.to}@your-unique-SIP-domain-from-Livekit-goes-here.com
132+
```
133+
134+
These recordings can be accessed in the Dashboard in **Storage > Recordings**,
135+
or using the
136+
[Recordings List API endpoint](/rest/signalwire-rest/endpoints/space/recordings-list).
137+
138+
### View logs
139+
140+
Access call logs in the
141+
[Logs](https://my.signalwire.com/?page=logs)
142+
tab of your SignalWire Dashboard.
143+
144+
145+
{/* Links */}
146+
147+
[signup]: https://signalwire.com/signup "Sign up for a SignalWire Space."
148+
[livekit]: https://cloud.livekit.io/login "Sign up for a LiveKit account."
149+
[buy-phone]: /platform/phone-numbers/getting-started/buying-a-phone-number/ "Buy a phone number in the SignalWire dashboard."

‎website/docs/main/home/calling/ai/guides/Integrations/livekit/index.mdx

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: LiveKit integration
3+
sidebar_label: LiveKit
4+
slug: /ai/guides/integrations/livekit
5+
description: Integrate LiveKit Agents with SignalWire's infrastructure
6+
---
7+
8+
<Subtitle>Connect LiveKit AI Agents with SignalWire's infrastructure</Subtitle>
9+
10+
If you want to enable your existing LiveKit Agent to make and receive calls on the PSTN (traditional mobile phone network) or via SIP,
11+
SignalWire's platform has you covered.
12+
13+
14+
## Available Guides
15+
16+
<GuidesList />
17+

‎website/docs/main/home/calling/ai/guides/Integrations/livekit/outbound.mdx

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Send outbound calls from LiveKit
3+
sidebar_label: Outbound
4+
description: Route LiveKit Calls onto the PSTN with SignalWire.
5+
slug: /ai/guides/integrations/livekit/outbound
6+
---
7+
8+
import CreateSWML from '/docs/main/_common/dashboard/create-swml-script.mdx'
9+
10+
# Make outbound LiveKit Agent calls via SignalWire
11+
12+
<Subtitle>Route LiveKit calls onto the PSTN with SignalWire</Subtitle>
13+
14+
This guide will help you set up outbound SIP calls using LiveKit and SignalWire.
15+
Follow these steps to configure your SIP domain, SWML script, and LiveKit settings efficiently.
16+
17+
## Prerequisites
18+
19+
Before getting started, you'll need the following:
20+
21+
- a [SignalWire Space][signup]
22+
- a [LiveKit account][livekit]
23+
- a [SignalWire phone number][buy-phone]
24+
25+
## Setup
26+
27+
<Steps>
28+
29+
### Create a SWML Script
30+
31+
<CreateSWML/>
32+
33+
- Log in to your SignalWire Dashboard and navigate to the [**Resources**](https://my.signalwire.com/?page=resources) tab on the left-hand sidebar.
34+
- Click **Add**, select **Script**, and then choose **SWML Script**.
35+
- Paste the following SWML code snippet into the editor:
36+
37+
```yaml title="SWML"
38+
version: 1.0.0
39+
sections:
40+
main:
41+
- connect:
42+
answer_on_bridge: true
43+
from: "+1XXXXXXXXXX"
44+
to: "%{call.to.replace(/^sip:/i, '').replace(/@.*/, '')}"
45+
```
46+
47+
Be sure to replace `"+1XXXXXXXXXX"` with a phone number from your SignalWire account.
48+
49+
### Add SIP address
50+
51+
- Save the SWML script and navigate to the **Addresses & Phone Numbers** section within the script.
52+
- Click **Add** and select **SIP Address** to add your SIP domain application.
53+
- Configure this SIP address based on your requirements, and save it.
54+
- After configuration, note down your unique SIP domain.
55+
56+
Example SIP domain: `test-space-live-kit.dapp.signalwire.com`.
57+
58+
</Steps>
59+
60+
Now, let’s configure LiveKit for outbound SIP calling.
61+
Follow along with LiveKit’s documentation for [outbound SIP trunk setup](https://docs.livekit.io/sip/trunk-outbound/).
62+
63+
<Steps>
64+
65+
### Create an outbound trunk
66+
67+
Use the following JSON configuration for creating an outbound SIP trunk, ensuring you update the given fields:
68+
69+
```json
70+
{
71+
"trunk": {
72+
"name": "My Outbound SIP Trunk",
73+
"address": "test-space-livekit.dapp.signalwire.com",
74+
"numbers": ["+15105550100"],
75+
"auth_username": "<username>",
76+
"auth_password": "<password>",
77+
"transport": 3
78+
}
79+
}
80+
```
81+
82+
Update placeholders in the above JSON with the following:
83+
84+
| Placeholder | Replace with |
85+
| :---------- | :----------- |
86+
| `"address"` | The SIP domain you created previously (e.g., `test-space-live-kit.dapp.signalwire.com`). |
87+
| `numbers` | A SignalWire phone number. |
88+
| `<username>` and `<password>` | The credentials provided by SignalWire Support. Contact Support if needed. |
89+
90+
Submit this request and save the generated `Trunk ID`.
91+
If you forget to save the Trunk ID, use LiveKit’s CLI tool to retrieve the trunk configurations.
92+
93+
### Create SIP participant
94+
95+
To initiate outbound calls through your configured trunk, you'll need to create a SIP participant in LiveKit.
96+
This process establishes the connection and manages the call flow.
97+
For detailed instructions on creating SIP participants and handling outbound calls,
98+
refer to LiveKit's comprehensive guide to
99+
[Creating a SIP Participant](https://docs.livekit.io/sip/outbound-calls/#creating-a-sip-participant).
100+
101+
If you're working with LiveKit AI agents for outbound calls, please see
102+
the [LiveKit AI Agent Telephony Guide](https://docs.livekit.io/agents/start/telephony/).
103+
104+
### Final checks
105+
- Ensure the trunk address matches exactly with the one created previously.
106+
- Phone numbers must be in E.164 format (e.g., "+15105550100") to ensure proper routing and connectivity.
107+
108+
</Steps>
109+
110+
You’re now ready to make your first outbound SIP call using LiveKit and SignalWire.
111+
If you encounter any issues, verify the configurations for both SignalWire and LiveKit.
112+
113+
---
114+
115+
## Next steps
116+
117+
### Record calls
118+
119+
Record calls by creating a SWML script with recording logic and slightly modifying your outbound SWML script.
120+
121+
<Steps>
122+
123+
### Create a second script
124+
125+
In your new script, paste the following SWML:
126+
127+
```yaml title="record.yaml"
128+
version: 1.0.0
129+
sections:
130+
main:
131+
- record_call:
132+
format: mp3
133+
```
134+
135+
### Update the outbound SWML script
136+
137+
Then, modify your existing outbound SWML script by adding the `confirm` parameter under the `connect` method,
138+
and setting its value to the URL for the new recording script.
139+
140+
The result should look like this:
141+
142+
```yaml title="outbound.yaml"
143+
version: 1.0.0
144+
sections:
145+
main:
146+
- connect:
147+
answer_on_bridge: true
148+
confirm: "your-recording-script-url"
149+
from: "+1XXXXXXXXXX"
150+
to: "%{call.to.replace(/^sip:/i, '').replace(/@.*/, '')}"
151+
```
152+
153+
</Steps>
154+
155+
These recordings can be accessed in the Dashboard in **Storage > Recordings**,
156+
or using the
157+
[Recordings List API endpoint](/rest/signalwire-rest/endpoints/space/recordings-list).
158+
159+
### View logs
160+
161+
Access call logs in the
162+
[Logs](https://my.signalwire.com/?page=logs)
163+
tab of your SignalWire Dashboard.
164+
165+
{/* Links */}
166+
167+
[signup]: https://signalwire.com/signup "Sign up for a SignalWire Space."
168+
[livekit]: https://cloud.livekit.io/login "Sign up for a LiveKit account."
169+
[buy-phone]: /platform/phone-numbers/getting-started/buying-a-phone-number/ "Buy a phone number in the SignalWire dashboard."

0 commit comments

Comments
 (0)