From c0dbddaa67de119dbe2fc34f4731ad6593e8826b Mon Sep 17 00:00:00 2001 From: manny-r31 Date: Fri, 31 Oct 2025 12:58:26 -0400 Subject: [PATCH 1/3] Added SWML example to create/receive call guide --- .../index.mdx | 154 +++++++++++++----- 1 file changed, 109 insertions(+), 45 deletions(-) diff --git a/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx b/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx index fb02d5c9e..76210502f 100644 --- a/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx +++ b/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx @@ -67,55 +67,67 @@ To configure your number to handle incoming calls with an SWML Script, click the That's it! Inbound calls to this SignalWire number will execute the specified SWML Script. -## Compatibility API - ### Making your first call -You now have all you need to make your first call, for example to your personal phone number. - -We want to call a number and play an audio message which says "Welcome to -SignalWire. This is my first call". We are going to define this behavior in a -cXML bin, which is used to declare what should happen during a call. - - +Outbound calls can be made via The SignalWire REST API's [Create a Call endpoint](/rest/signalwire-rest/endpoints/calling/calls-create). +This is accomplished by sending a POST request with SWML in the body to handle the call. +The SWML can be served via URL or passed inline directly. -Create a new bin, and paste the following XML in it: + + -```xml - - - Welcome to SignalWire. This is my first call. - +```bash +curl -L -g 'https://Your_Space_Name.signalwire.com/api/calling/calls' \ +-H 'Content-Type: application/json' \ +-H 'Accept: application/json' \ +-H 'Authorization: Basic YOUR-PROJECT-ID:YOUR-API-TOKEN' \ +--data-raw '{ + "command": "dial", + "params": { + "from": "sip:from-sip@example-112233445566.sip.signalwire.com", + "to": "+1xxxxxxxxxx", + "caller_id": "+1234567890", + "fallback_url": "https://example.com/fallback", + "status_url": "https://example.com/status_callback", + "status_events": [ + "answered", + "ended" + ], + "url": "https://example.com/swml" + } +}' ``` -The XML above uses the [<Say>](/compatibility-api/cxml/voice/say) -verb to play a text-to-speech message. Save the bin and take note of its Request -URL. - -You are now ready to start the call using cURL: + + ```bash -curl -L -X POST 'https://{SpaceName}.signalwire.com/api/laml/2010-04-01/Accounts/{ProjectID}/Calls' \ - -H 'Content-Type: application/x-www-form-urlencoded' \ - -H 'Accept: application/json' \ - -u '{ProjectID}:{APIToken}' \ - --data-urlencode 'Url=https://{BinRequestURL}' \ - --data-urlencode 'From={+XXXXXXXXXX}' \ - --data-urlencode 'To={+YYYYYYYYYY}' +curl -L -g 'https://Your_Space_Name.signalwire.com/api/calling/calls' \ +-H 'Content-Type: application/json' \ +-H 'Accept: application/json' \ +-H 'Authorization: Basic YOUR-PROJECT-ID:YOUR-API-TOKEN' \ +--data-raw '{ + "command": "dial", + "params": { + "from": "sip:from-sip@example-112233445566.sip.signalwire.com", + "to": "+1xxxxxxxxxx", + "caller_id": "+1234567890", + "fallback_url": "https://example.com/fallback", + "status_url": "https://example.com/status_callback", + "status_events": [ + "answered", + "ended" + ], + "swml": "{'version':'1.0.0','sections':{'main':[{'play':'say:Hello from SignalWire!'}]}}" + } +}' ``` -Make sure to replace all occurrences of `{SpaceName}`, `{ProjectID}`, -`{APIToken}`, `{BinRequestURL}`, `{+XXXXXXXXXX}`, and `{+YYYYYYYYYY}` with -your actual values. - -:::note + + -Instead of your own bin, feel free to try one of ours: `.signalwire.com/laml-bins/f85376be-7fe1-439b-a24f-3113ff980804>`. -::: - -Congratulations! Once the cURL request is executed, your personal phone number -(`{+YYYYYYYYYY}`) will start ringing. +## Compatibility API ### Receiving incoming calls @@ -125,10 +137,27 @@ Congratulations! Once the cURL request is executed, your personal phone number To handle incoming calls we need to configure the phone number in our [SignalWire Space](https://signalwire.com/signin) to answer calls using a cXML resource. + + If you're on the **new UI**, go to the "Resources" section from the sidebar, and create a new Resource. + In the new resource picker, select "Script" and create a "cXML script". + + + ![Attach Phone Number](@image/dashboard/resources/new-cxml-bin.png) + - If you're on the **new UI**, go to the "Phone Numbers" section from the sidebar, and - edit the phone number you want to answer calls from. There, click on the - "Assign Resource" button for incoming calls, and select the cXML or SWML script you'd like to connect. + Utilize the following cXML which uses the [<Say>](/compatibility-api/cxml/voice/say) + verb to play a text-to-speech message: + + ```xml + + + Welcome to SignalWire. This is my first call. + + ``` + + Go to the "Phone Numbers" section from the sidebar, and + edit the phone number you want to answer calls with. From there, click on the + "Assign Resource" button for incoming calls, and select the newly created cXML script to connect. ![Attach Resource](@image/dashboard/phone-numbers/assign-resource-voice.png) @@ -141,14 +170,19 @@ Congratulations! Once the cURL request is executed, your personal phone number To handle incoming calls we need to configure the phone number in our [SignalWire Space](https://signalwire.com/signin) to answer calls using a SWML or cXML script. - Take note of the Request URL for the bin that we created in the previous - section. You can even create a new bin if you want to define a different - behavior for incoming calls. + Utilize the following cXML which uses the [<Say>](/compatibility-api/cxml/voice/say) + verb to play a text-to-speech message: + ```xml + + + Welcome to SignalWire. This is my first call. + + ``` Click the "Phone Numbers" section from your sidebar, and select the specific number you would like to use to answer calls. The same number we used before can work. - Make sure that "_Accept Calls As_" is set to "_Voice Calls_", "_Handle Calls Using_" is set to "_LaML Webhooks_" or "_SWML Scripts_", - and paste your Bin URL in as the value for "_When a Call Comes In_". Click "_Save_", and you're done! + Make sure that "_Accept Calls As_" is set to "_Voice Calls_", "_Handle Calls Using_" is set to "_LaML Webhooks_" or "_SWML Scripts_", + and paste your Bin URL in as the value for "_When a Call Comes In_". Click "_Save_", and you're done! Inbound calls to this SignalWire number will execute the specified bin. @@ -158,6 +192,36 @@ Congratulations! Once the cURL request is executed, your personal phone number +### Making your first call + +To call a number via cXML you can make a POST request to the Compatibility REST API's [Create a Call](/rest/compatibility-api/endpoints/create-a-call) endpoint. + +```bash +curl -L -X POST 'https://{SpaceName}.signalwire.com/api/laml/2010-04-01/Accounts/{ProjectID}/Calls' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -H 'Accept: application/json' \ + -u '{ProjectID}:{APIToken}' \ + --data-urlencode 'Url=https://{BinRequestURL}' \ + --data-urlencode 'From={+XXXXXXXXXX}' \ + --data-urlencode 'To={+YYYYYYYYYY}' +``` + +Make sure to replace all occurrences of `{SpaceName}`, `{ProjectID}`, +`{APIToken}`, `{BinRequestURL}`, `{+XXXXXXXXXX}`, and `{+YYYYYYYYYY}` with +your actual values. + +In order to locate the `{BinRequestURL}`, navigate to your cXML script and copy the Request URL that is present. + + +:::note + +Instead of your own bin, feel free to try one of ours: `.signalwire.com/laml-bins/f85376be-7fe1-439b-a24f-3113ff980804>`. + +::: + +Congratulations! Once the cURL request is executed, your personal phone number +(`{+YYYYYYYYYY}`) will start ringing. + # Wrapping up From 0156cdd91d13d78643b45b777c3730be5fb47d97 Mon Sep 17 00:00:00 2001 From: manny-r31 Date: Fri, 21 Nov 2025 11:42:54 -0500 Subject: [PATCH 2/3] Completed create call example, various changes to formatting. --- .../_common/dashboard/create-cxml-script.mdx | 6 ++-- .../_common/dashboard/create-swml-script.mdx | 6 ++-- ...egacy-making-and-receiving-phone-calls.mdx | 28 ++++++++++--------- .../index.mdx | 17 +++++------ 4 files changed, 30 insertions(+), 27 deletions(-) diff --git a/website/docs/main/_common/dashboard/create-cxml-script.mdx b/website/docs/main/_common/dashboard/create-cxml-script.mdx index 9b36e30a4..7807f2a78 100644 --- a/website/docs/main/_common/dashboard/create-cxml-script.mdx +++ b/website/docs/main/_common/dashboard/create-cxml-script.mdx @@ -2,8 +2,8 @@ - If you're on the **new UI**, go to the "Resources" section from the sidebar, and create a new Resource. - In the new resource picker, select "Script" and create a "cXML script". + If you're on the **new UI**, go to the **Resources** section from the sidebar, and create a new Resource. + In the new resource picker, select **Script** and create a **cXML script**. ![Attach Phone Number](@image/dashboard/resources/new-cxml-bin.png) @@ -13,7 +13,7 @@ - If you're on the **Legacy UI**, go to the "cXML/LaML" section in your [SignalWire Space](https://signalwire.com/signin), then click on "Bins", and create a new script. + If you're on the **Legacy UI**, go to the **cXML/LaML** section in your [SignalWire Space](https://signalwire.com/signin), then click on **Bins**, and create a new script. ![Legacy bin](@image/dashboard/legacy/xml-bins.png) diff --git a/website/docs/main/_common/dashboard/create-swml-script.mdx b/website/docs/main/_common/dashboard/create-swml-script.mdx index 09730f92c..a97bf8246 100644 --- a/website/docs/main/_common/dashboard/create-swml-script.mdx +++ b/website/docs/main/_common/dashboard/create-swml-script.mdx @@ -2,8 +2,8 @@ - To create a SWML Script in the **new UI**, go to the "Resources" section from the sidebar, and create a new Resource. - In the new resource picker, select "Script" and create a "SWML Application". + To create a SWML Script in the **new UI**, go to the **Resources** section from the sidebar, and create a new Resource. + In the new resource picker, select **Script** and create a **SWML Application**. ![Attach Phone Number](@image/dashboard/resources/swml-resource-vid.webp) @@ -13,7 +13,7 @@ - If you are using the **Legacy UI**, go to the "Relay/SWML" section in your sidebar, then click on the "SWML Scripts" tab. Click on "Create a SWML Script", + If you are using the **Legacy UI**, go to the "Relay/SWML" section in your sidebar, then click on the **SWML Scripts** tab. Click on **Create a SWML Script**, and then give it a name and pass it some instructions. You can use the following as a starting point: diff --git a/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/_legacy-making-and-receiving-phone-calls.mdx b/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/_legacy-making-and-receiving-phone-calls.mdx index 1ad93e8c8..9a2bba345 100644 --- a/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/_legacy-making-and-receiving-phone-calls.mdx +++ b/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/_legacy-making-and-receiving-phone-calls.mdx @@ -27,7 +27,7 @@ To be able to make calls, you will need: To acquire a phone number, [Log in](https://signalwire.com/signin) to your SignalWire Space. From the [Phone Numbers section](https://my.signalwire.com/?phone_numbers), you can [buy a new phone number](/platform/phone-numbers/getting-started/buying-a-phone-number). You will need at least one number to make and receive calls. -For what concerns your API credentials, find these in the API section of your Space, as shown in the following figure. You may need to create a new token if you never used one. Make sure that your token has the "Voice" scope enabled. +For what concerns your API credentials, find these in the API section of your Space, as shown in the following figure. You may need to create a new token if you never used one. Make sure that your token has the **Voice** scope enabled. @@ -54,12 +54,12 @@ import NewLegacy from '/docs/main/_common/dashboard/_ui-accordion.mdx' To handle incoming calls we need to configure the phone number in our [SignalWire Space](https://signalwire.com/signin) to answer calls using a SWML Script. -To create a SWML Script in the **new UI**, go to the "Resources" section from the sidebar, and create a new Resource. -In the new resource picker, select "Script" and create a "SWML Application". +To create a SWML Script in the **new UI**, go to the **Resources** section from the sidebar, and create a new Resource. +In the new resource picker, select **Script** and create a **SWML Application**. -If you are using the **Legacy UI**, go to the "Relay/SWML" section in your sidebar, then click on the "SWML Scripts" tab. Click on "Create a SWML Script", -and then give it a name and pass it some instructions. You can use the following as a starting point: +If you are using the **Legacy UI**, go to the **Relay/SWML** section in your sidebar, then click on the **SWML Scripts** tab. +Click on **Create a SWML Script*, and then give it a name and pass it some instructions. You can use the following as a starting point: ```yaml andJson version: 1.0.0 @@ -68,9 +68,11 @@ sections: - play: say:Hello from SignalWire! ``` -Take note of the Request URL for the SWML Script that we created. You can even create a new script if you want to define a different behavior for incoming calls. +Take note of the Request URL for the SWML Script that we created. +You can even create a new script if you want to define a different behavior for incoming calls. -To configure your number to handle incoming calls with an SWML Script, click the ["Phone Numbers" section](https://my.signalwire.com/?phone_numbers) within your SignalWire Space, and edit the settings of the specific number you would like to use to answer calls. Set "Handle calls using" to "a SWML Script", then select your SWML Script from the dropdown: +To configure your number to handle incoming calls with an SWML Script, click the [**Phone Numbers**](https://my.signalwire.com/?phone_numbers) section within your SignalWire Space, and edit the settings of the specific number you would like to use to answer calls. +Set **Handle calls using** to **a SWML Script**, then select your SWML Script from the dropdown: That's it! Inbound calls to this SignalWire number will execute the specified SWML Script. @@ -84,10 +86,10 @@ We want to call a number and play an audio message which says "Welcome to SignalWire. This is my first call". We are going to define this behavior in an XML bin, which is used to declare what should happen during a call. -If you're on the **new UI**, go to the "Resources" section from the sidebar, and create a new Resource. -In the new resource picker, select "Script" and create a "cXML script". +If you're on the **new UI**, go to the **Resources** section from the sidebar, and create a new Resource. +In the new resource picker, select **Script** and create a **cXML script**. -If you're on the **Legacy UI**, go to the "cXML/LaML" section in your [SignalWire Space](https://signalwire.com/signin), then click on "Bins". +If you're on the **Legacy UI**, go to the **cXML/LaML** section in your [SignalWire Space](https://signalwire.com/signin), then click on **Bins**. Create a new bin, and paste the following XML in it: @@ -133,15 +135,15 @@ To handle incoming calls we need to configure the phone number in our [SignalWire Space](https://signalwire.com/signin) to answer calls using a cXML bin. -If you're on the **new UI**, go to the "Phone Numbers" section from the sidebar, and +If you're on the **new UI**, go to the **Phone Numbers** section from the sidebar, and edit the phone number you want to answer calls from. There, click on the -"Assign Resource" button for incoming calls, and select the cXML or SWML script you'd like to connect. +**Assign Resource** button for incoming calls, and select the cXML or SWML script you'd like to connect. If you're on the **old UI**, take note of the Request URL for the bin that we created in the previous section. You can even create a new bin if you want to define a different behavior for incoming calls. -Click the "Phone Numbers" section from your sidebar, and select the specific number you would like to use to answer calls. The same number we used before can work. +Click the **Phone Numbers** section from your sidebar, and select the specific number you would like to use to answer calls. The same number we used before can work. Make sure that "_Accept Calls As_" is set to "_Voice Calls_", "_Handle Calls Using_" is set to "_LaML Webhooks_", and paste your Bin URL in as the value for "_When a Call Comes In_". Click "_Save_", and you're done! Inbound calls to this SignalWire number will execute the specified bin. diff --git a/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx b/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx index 76210502f..fee4c87b6 100644 --- a/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx +++ b/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx @@ -63,14 +63,15 @@ sections: Take note of the Request URL for the SWML Script that we created. You can even create a new script if you want to define a different behavior for incoming calls. -To configure your number to handle incoming calls with an SWML Script, click the ["Phone Numbers" section](https://my.signalwire.com/?phone_numbers) within your SignalWire Space, and edit the settings of the specific number you would like to use to answer calls. Set "Handle calls using" to "a SWML Script", then select your SWML Script from the dropdown: +To configure your number to handle incoming calls with an SWML Script, click the [Phone Numbers](https://my.signalwire.com/?phone_numbers) section within your SignalWire Space, and edit the settings of the specific number you would like to use to answer calls. +Set **Handle calls using** to **a SWML Script**, then select your SWML Script from the dropdown That's it! Inbound calls to this SignalWire number will execute the specified SWML Script. ### Making your first call -Outbound calls can be made via The SignalWire REST API's [Create a Call endpoint](/rest/signalwire-rest/endpoints/calling/calls-create). -This is accomplished by sending a POST request with SWML in the body to handle the call. +Outbound calls can be made via the SignalWire REST API's [Create a Call endpoint](/rest/signalwire-rest/endpoints/calling/calls-create). +This is accomplished by sending a POST request using SWML in the request body to handle the call. The SWML can be served via URL or passed inline directly. @@ -138,8 +139,8 @@ curl -L -g 'https://Your_Space_Name.signalwire.com/api/calling/calls' \ [SignalWire Space](https://signalwire.com/signin) to answer calls using a cXML resource. - If you're on the **new UI**, go to the "Resources" section from the sidebar, and create a new Resource. - In the new resource picker, select "Script" and create a "cXML script". + If you're on the **new UI**, go to the **Resources** section from the sidebar, and create a new Resource. + In the new resource picker, select **Script** and create a **cXML script**. ![Attach Phone Number](@image/dashboard/resources/new-cxml-bin.png) @@ -155,9 +156,9 @@ curl -L -g 'https://Your_Space_Name.signalwire.com/api/calling/calls' \ ``` - Go to the "Phone Numbers" section from the sidebar, and + Go to the **Phone Numbers** section from the sidebar, and edit the phone number you want to answer calls with. From there, click on the - "Assign Resource" button for incoming calls, and select the newly created cXML script to connect. + **Assign Resource** button for incoming calls, and select the newly created cXML script to connect. ![Attach Resource](@image/dashboard/phone-numbers/assign-resource-voice.png) @@ -179,7 +180,7 @@ curl -L -g 'https://Your_Space_Name.signalwire.com/api/calling/calls' \ Welcome to SignalWire. This is my first call. ``` - Click the "Phone Numbers" section from your sidebar, and select the specific number you would like to use to answer calls. The same number we used before can work. + Click the **Phone Numbers** section from your sidebar, and select the specific number you would like to use to answer calls. The same number we used before can work. Make sure that "_Accept Calls As_" is set to "_Voice Calls_", "_Handle Calls Using_" is set to "_LaML Webhooks_" or "_SWML Scripts_", and paste your Bin URL in as the value for "_When a Call Comes In_". Click "_Save_", and you're done! From 20d7efdc3deace6206ab9339f0fda009d86ec565 Mon Sep 17 00:00:00 2001 From: manny-r31 Date: Fri, 21 Nov 2025 12:04:48 -0500 Subject: [PATCH 3/3] Fixed broken link --- .../getting-started/making-and-receiving-phone-calls/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx b/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx index fee4c87b6..ea0016b10 100644 --- a/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx +++ b/website/docs/main/home/calling/voice/getting-started/making-and-receiving-phone-calls/index.mdx @@ -70,7 +70,7 @@ That's it! Inbound calls to this SignalWire number will execute the specified SW ### Making your first call -Outbound calls can be made via the SignalWire REST API's [Create a Call endpoint](/rest/signalwire-rest/endpoints/calling/calls-create). +Outbound calls can be made via the SignalWire REST API's [Create a Call endpoint](/rest/signalwire-rest/endpoints/calling/call-commands). This is accomplished by sending a POST request using SWML in the request body to handle the call. The SWML can be served via URL or passed inline directly.