Skip to main content

Cancelling a Stream with the Update a Call API

This guide will show you how to cancel a stream using the SignalWire Rest API.

Updating the Call​

To cancel a stream, you need to send a POST request to the Update a Call API with a Url that returns XML to cancel the stream. Be sure to update the call-sid that started the stream.

Example using cURL to update the call:

curl -L -X POST 'https://EXAMPLE.signalwire.com/api/laml/2010-04-01/Accounts/PROJECT_ID_HERE/Calls/CALL_SID_HERE' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64 TOKEN HERE' \
--data-urlencode 'Url=https://Example.com/update'

Cancelling the Stream​

The XML returned by the Url should contain a <Stop> element with a <Stream> element inside it with the name of the stream you wish to stop.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Stop>
        <Stream name="stream_name" />
    </Stop>
    <Say>Stopping stream</Say>
</Response>

Once the above XML is returned, the stream will be cancelled.

XML Bin Example​

You can set the Url to an XML Bin that returns the XML to cancel the stream.

Use the XML provided in the Cancelling the Stream section above.

Dynamic Stream Names with XML Bins​

If you are using dynamic stream names, you can use custom mustache templating to dynamically set the stream name in the XML Bin.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Stop>
        <Stream name="{{STREAMNAME}}" />
    </Stop>
    <Say>Stopping stream</Say>'
</Response>

Update the call​

Then in your POST request to the Update a Call API, you can set the Url to the XML Bin endpoint and set the STREAMNAME query string to the name of the stream you wish to cancel.

curl -L -X POST 'https://EXAMPLE.signalwire.com/api/laml/2010-04-01/Accounts/PROJECT_ID_HERE/Calls/CALL_SID_HERE' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64 TOKEN HERE' \
--data-urlencode 'Url=https://YOURSPACE.signalwire.com/laml-bins/xxxx-xxxx-xxxx-xxxx-xxxx?STREAMNAME=streamname'

Server Endpoint Example​

Below is a Python Flask example of a server endpoint that will return the XML to cancel the stream. In this example we are utilizing the SignalWire Python SDK to generate the XML.

from flask import Flask
from signalwire.voice_response import VoiceResponse, Stream, Stop

app = Flask(__name__)


@app.route('/update', methods=['GET', 'POST'])
async def update_call():
    response = VoiceResponse()
    stop = Stop()
    stream = Stream(name='stream')
    stop.append(stream)
    response.append(stop)
    response.say('Stopping stream')
    return response.to_xml()


if __name__ == '__main__':
    app.run(port=3000)

Update the call​

Then in your POST request to the Update a Call API, the Url should be set to the endpoint of this server.

curl -L -X POST 'https://EXAMPLE.signalwire.com/api/laml/2010-04-01/Accounts/PROJECT_ID_HERE/Calls/CALL_SID_HERE' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE64 TOKEN HERE' \
--data-urlencode 'Url=https://Example.com/update'

This should return the XML to cancel the stream.