Skip to content

Commit 894bb09

Browse files
hey-augusthey-august
authored
Merge branch 'main' into august-20260806-add-reo-dev
2 parents 2ff7f54 + a5ce4b9 commit 894bb09

68 files changed

Lines changed: 21274 additions & 21272 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Normalize line endings to LF for all text files
2+
* text=auto eol=lf

‎fern/products/swml/pages/guides/basics/deployment.mdx‎

Lines changed: 197 additions & 197 deletions
Original file line numberDiff line numberDiff line change
@@ -1,197 +1,197 @@
1-
---
2-
id: c6ba0503-6116-476c-bf6b-6254227c4b16
3-
slug: /guides/deployment
4-
title: Deploy SWML from web servers
5-
subtitle: Serve SWML scripts from web servers and Relay applications
6-
x-custom:
7-
tags:
8-
- sdk:swml
9-
- product:voice
10-
description: Learn how to serve SWML scripts from web servers and Relay applications.
11-
max-toc-depth: 3
12-
---
13-
14-
SWML scripts can be served in multiple ways beyond the SignalWire Dashboard. This guide covers serving SWML from web servers and Relay applications.
15-
16-
<Info>
17-
For complete information about variables, the Call Object, and all variable scopes, see the [**Variables and Expressions**](/docs/swml/reference/variables) reference.
18-
</Info>
19-
20-
<Note>
21-
The examples below use [**Calling SWML**](/docs/swml/reference/calling) (the voice-call flavor). The same deployment patterns apply to [**Messaging SWML**](/docs/swml/reference/messaging) for inbound SMS and MMS — the only difference is the webhook payload shape (`message` instead of `call`) and the set of available methods.
22-
</Note>
23-
24-
## From a web server
25-
26-
<Tip>
27-
This use case is described in detail in the [Handling Incoming Calls from Code](/docs/swml/guides/remote-server) guide.
28-
</Tip>
29-
30-
In the phone number settings, when you check the "Use External URL for SWML Script handler?" option,
31-
you can set a Web URL that will serve the SWML script.
32-
Every time a call comes in (or some other designated event occurs),
33-
SignalWire sends a POST request to the URL using the standard [document-fetching webhook](/docs/swml/reference/calling#document-fetching-webhook) format.
34-
The request body contains the `call` object, `vars`, `params`, and `envs`. See the [document-fetching webhook reference](/docs/swml/reference/calling#document-fetching-webhook) for the full request body structure.
35-
36-
### Understanding the POST Request
37-
38-
The `vars` object and the `params` object will be empty for a new call.
39-
If you're executing a remote SWML script using the [`execute`](/docs/swml/reference/calling/execute) or [`transfer`](/docs/swml/reference/calling/transfer) methods,
40-
the `vars` parameter has a list of the variables declared in the script so far.
41-
And the `params` object has the list of parameters explicitly set by the [`execute`](/docs/swml/reference/calling/execute) or [`transfer`](/docs/swml/reference/calling/transfer) methods.
42-
43-
You can also reference the properties of `call` and `params` objects during the script execution using the variable subtitution bracket like so:
44-
45-
<CodeBlocks>
46-
<CodeBlock title="YAML">
47-
```yaml
48-
version: 1.0.0
49-
sections:
50-
main:
51-
- play:
52-
url: 'say:%{call.from}'
53-
```
54-
</CodeBlock>
55-
<CodeBlock title="JSON">
56-
```json
57-
{
58-
"version": "1.0.0",
59-
"sections": {
60-
"main": [
61-
{
62-
"play": {
63-
"url": "say:%{call.from}"
64-
}
65-
}
66-
]
67-
}
68-
}
69-
```
70-
</CodeBlock>
71-
</CodeBlocks>
72-
73-
Further, consider the following SWML script:
74-
75-
<CodeBlocks>
76-
<CodeBlock title="YAML">
77-
```yaml
78-
version: 1.0.0
79-
sections:
80-
main:
81-
- play:
82-
url: '%{params.file}'
83-
- return: 1
84-
```
85-
</CodeBlock>
86-
<CodeBlock title="JSON">
87-
```json
88-
{
89-
"version": "1.0.0",
90-
"sections": {
91-
"main": [
92-
{
93-
"play": {
94-
"url": "%{params.file}"
95-
}
96-
},
97-
{
98-
"return": 1
99-
}
100-
]
101-
}
102-
}
103-
```
104-
</CodeBlock>
105-
</CodeBlocks>
106-
107-
It references `params.file` in its [`play`](/docs/swml/reference/calling/play) method.
108-
If this SWML was invoked as a response to a phone call, it would cause an error as the `params` object is empty.
109-
But if it was hosted on a server and called with the [`execute`](/docs/swml/reference/calling/execute) or the [`transfer`](/docs/swml/reference/calling/transfer) method,
110-
the `params` object is passed into the SWML.
111-
112-
The SWML above can be invoked as follows:
113-
114-
<CodeBlocks>
115-
<CodeBlock title="YAML">
116-
```yaml
117-
version: 1.0.0
118-
sections:
119-
main:
120-
execute:
121-
dest: https://example.com/swml.yaml
122-
params:
123-
file: https://cdn.signalwire.com/swml/audio.mp3
124-
```
125-
</CodeBlock>
126-
<CodeBlock title="JSON">
127-
```json
128-
{
129-
"version": "1.0.0",
130-
"sections": {
131-
"main": {
132-
"execute": {
133-
"dest": "https://example.com/swml.yaml",
134-
"params": {
135-
"file": "https://cdn.signalwire.com/swml/audio.mp3"
136-
}
137-
}
138-
}
139-
}
140-
}
141-
```
142-
</CodeBlock>
143-
</CodeBlocks>
144-
145-
## From a Relay application
146-
147-
You can also execute SWML from a Relay application.
148-
The following is a snippet using the [Relay SDK](/docs/server-sdks/reference/python/relay).
149-
150-
```javascript
151-
const { Voice } = require("@signalwire/realtime-api");
152-
const script = `
153-
version: 1.0.0
154-
sections:
155-
main:
156-
- answer: {}
157-
- execute:
158-
dest: play_music
159-
params:
160-
to_play: 'https://cdn.signalwire.com/swml/April_Kisses.mp3'
161-
play_music:
162-
- play:
163-
url: '%{params.to_play}'
164-
`;
165-
166-
const client = new Voice.Client({
167-
project: "<your project token>",
168-
token: "<your project API key>",
169-
topics: ["swml"],
170-
});
171-
172-
client.on("call.received", async (call) => {
173-
try {
174-
await client.execute({
175-
method: "calling.transfer",
176-
params: {
177-
node_id: call.nodeId,
178-
call_id: call.callId,
179-
dest: script,
180-
},
181-
});
182-
} catch (error) {}
183-
});
184-
```
185-
186-
In this snippet, we are registering an event for every time a call is received to any phone number in your project with the topic "swml".
187-
You can set the topics a number is subscribed to from the phone number settings page in the SignalWire Dashboard.
188-
Every time a call is received, the SWML script is executed using the `client.execute` method.
189-
190-
## Next steps
191-
192-
- **[Variables and Expressions](/docs/swml/reference/variables)**: Complete reference for SWML variables and the Call Object
193-
- **[Handle incoming calls from code](/docs/swml/guides/remote-server)**: Complete guide to serving SWML from web servers
194-
- **[Calling SWML reference](/docs/swml/reference/calling)**: Methods available for voice calls
195-
- **[Messaging SWML reference](/docs/swml/reference/messaging)**: Methods available for inbound SMS and MMS
196-
197-
- **[Getting started with SWML](/docs/swml)**: Learn the fundamentals
1+
---
2+
id: c6ba0503-6116-476c-bf6b-6254227c4b16
3+
slug: /guides/deployment
4+
title: Deploy SWML from web servers
5+
subtitle: Serve SWML scripts from web servers and Relay applications
6+
x-custom:
7+
tags:
8+
- sdk:swml
9+
- product:voice
10+
description: Learn how to serve SWML scripts from web servers and Relay applications.
11+
max-toc-depth: 3
12+
---
13+
14+
SWML scripts can be served in multiple ways beyond the SignalWire Dashboard. This guide covers serving SWML from web servers and Relay applications.
15+
16+
<Info>
17+
For complete information about variables, the Call Object, and all variable scopes, see the [**Variables and Expressions**](/docs/swml/reference/variables) reference.
18+
</Info>
19+
20+
<Note>
21+
The examples below use [**Calling SWML**](/docs/swml/reference/calling) (the voice-call flavor). The same deployment patterns apply to [**Messaging SWML**](/docs/swml/reference/messaging) for inbound SMS and MMS — the only difference is the webhook payload shape (`message` instead of `call`) and the set of available methods.
22+
</Note>
23+
24+
## From a web server
25+
26+
<Tip>
27+
This use case is described in detail in the [Handling Incoming Calls from Code](/docs/swml/guides/remote-server) guide.
28+
</Tip>
29+
30+
In the phone number settings, when you check the "Use External URL for SWML Script handler?" option,
31+
you can set a Web URL that will serve the SWML script.
32+
Every time a call comes in (or some other designated event occurs),
33+
SignalWire sends a POST request to the URL using the standard [document-fetching webhook](/docs/swml/reference/calling#document-fetching-webhook) format.
34+
The request body contains the `call` object, `vars`, `params`, and `envs`. See the [document-fetching webhook reference](/docs/swml/reference/calling#document-fetching-webhook) for the full request body structure.
35+
36+
### Understanding the POST Request
37+
38+
The `vars` object and the `params` object will be empty for a new call.
39+
If you're executing a remote SWML script using the [`execute`](/docs/swml/reference/calling/execute) or [`transfer`](/docs/swml/reference/calling/transfer) methods,
40+
the `vars` parameter has a list of the variables declared in the script so far.
41+
And the `params` object has the list of parameters explicitly set by the [`execute`](/docs/swml/reference/calling/execute) or [`transfer`](/docs/swml/reference/calling/transfer) methods.
42+
43+
You can also reference the properties of `call` and `params` objects during the script execution using the variable subtitution bracket like so:
44+
45+
<CodeBlocks>
46+
<CodeBlock title="YAML">
47+
```yaml
48+
version: 1.0.0
49+
sections:
50+
main:
51+
- play:
52+
url: 'say:%{call.from}'
53+
```
54+
</CodeBlock>
55+
<CodeBlock title="JSON">
56+
```json
57+
{
58+
"version": "1.0.0",
59+
"sections": {
60+
"main": [
61+
{
62+
"play": {
63+
"url": "say:%{call.from}"
64+
}
65+
}
66+
]
67+
}
68+
}
69+
```
70+
</CodeBlock>
71+
</CodeBlocks>
72+
73+
Further, consider the following SWML script:
74+
75+
<CodeBlocks>
76+
<CodeBlock title="YAML">
77+
```yaml
78+
version: 1.0.0
79+
sections:
80+
main:
81+
- play:
82+
url: '%{params.file}'
83+
- return: 1
84+
```
85+
</CodeBlock>
86+
<CodeBlock title="JSON">
87+
```json
88+
{
89+
"version": "1.0.0",
90+
"sections": {
91+
"main": [
92+
{
93+
"play": {
94+
"url": "%{params.file}"
95+
}
96+
},
97+
{
98+
"return": 1
99+
}
100+
]
101+
}
102+
}
103+
```
104+
</CodeBlock>
105+
</CodeBlocks>
106+
107+
It references `params.file` in its [`play`](/docs/swml/reference/calling/play) method.
108+
If this SWML was invoked as a response to a phone call, it would cause an error as the `params` object is empty.
109+
But if it was hosted on a server and called with the [`execute`](/docs/swml/reference/calling/execute) or the [`transfer`](/docs/swml/reference/calling/transfer) method,
110+
the `params` object is passed into the SWML.
111+
112+
The SWML above can be invoked as follows:
113+
114+
<CodeBlocks>
115+
<CodeBlock title="YAML">
116+
```yaml
117+
version: 1.0.0
118+
sections:
119+
main:
120+
execute:
121+
dest: https://example.com/swml.yaml
122+
params:
123+
file: https://cdn.signalwire.com/swml/audio.mp3
124+
```
125+
</CodeBlock>
126+
<CodeBlock title="JSON">
127+
```json
128+
{
129+
"version": "1.0.0",
130+
"sections": {
131+
"main": {
132+
"execute": {
133+
"dest": "https://example.com/swml.yaml",
134+
"params": {
135+
"file": "https://cdn.signalwire.com/swml/audio.mp3"
136+
}
137+
}
138+
}
139+
}
140+
}
141+
```
142+
</CodeBlock>
143+
</CodeBlocks>
144+
145+
## From a Relay application
146+
147+
You can also execute SWML from a Relay application.
148+
The following is a snippet using the [Relay SDK](/docs/server-sdks/reference/python/relay).
149+
150+
```javascript
151+
const { Voice } = require("@signalwire/realtime-api");
152+
const script = `
153+
version: 1.0.0
154+
sections:
155+
main:
156+
- answer: {}
157+
- execute:
158+
dest: play_music
159+
params:
160+
to_play: 'https://cdn.signalwire.com/swml/April_Kisses.mp3'
161+
play_music:
162+
- play:
163+
url: '%{params.to_play}'
164+
`;
165+
166+
const client = new Voice.Client({
167+
project: "<your project token>",
168+
token: "<your project API key>",
169+
topics: ["swml"],
170+
});
171+
172+
client.on("call.received", async (call) => {
173+
try {
174+
await client.execute({
175+
method: "calling.transfer",
176+
params: {
177+
node_id: call.nodeId,
178+
call_id: call.callId,
179+
dest: script,
180+
},
181+
});
182+
} catch (error) {}
183+
});
184+
```
185+
186+
In this snippet, we are registering an event for every time a call is received to any phone number in your project with the topic "swml".
187+
You can set the topics a number is subscribed to from the phone number settings page in the SignalWire Dashboard.
188+
Every time a call is received, the SWML script is executed using the `client.execute` method.
189+
190+
## Next steps
191+
192+
- **[Variables and Expressions](/docs/swml/reference/variables)**: Complete reference for SWML variables and the Call Object
193+
- **[Handle incoming calls from code](/docs/swml/guides/remote-server)**: Complete guide to serving SWML from web servers
194+
- **[Calling SWML reference](/docs/swml/reference/calling)**: Methods available for voice calls
195+
- **[Messaging SWML reference](/docs/swml/reference/messaging)**: Methods available for inbound SMS and MMS
196+
197+
- **[Getting started with SWML](/docs/swml)**: Learn the fundamentals

0 commit comments

Comments
 (0)