# Azure Communication Call Automation client library for Python
This package contains a Python SDK for Azure Communication Call Automation. Call Automation provides developers the ability to build server-based, intelligent call workflows, and call recording for voice and PSTN channels.
[Overview of Call Automation][overview] | [Product documentation][product_docs]
## _Disclaimer_
_Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please
refer to https://github.com/Azure/azure-sdk-for-python/issues/20691_
## Getting started
### Prerequisites
- Python 3.7 or later is required to use this package.
- You need an [Azure subscription][azure_sub] to use this package.
- A deployed Communication Services resource. You can use the [Azure Portal][azure_portal] or the [Azure PowerShell][azure_powershell] to set it up.
### Installing
Install the Azure Communication Service Call Automation SDK.
```bash
pip install azure-communication-callautomation
```
## Key concepts
| Name | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CallAutomationClient | `CallAutomationClient` is the primary interface for developers using this client library. It can be used to initiate calls by `createCall` or `answerCall`. It can also be used to do recording actions such as `startRecording` | |
| CallConnectionClient | `CallConnectionClient` represents a ongoing call. Once the call is established with `createCall` or `answerCall`, further actions can be performed for the call, such as `transfer` or `play_media`. | |
| Callback Events | Callback events are events sent back during duration of the call. It gives information and state of the call, such as `CallConnected`. `CallbackUrl` must be provided during `createCall` and `answerCall`, and callback events will be sent to this url. |
| Incoming Call Event | When incoming call happens (that can be answered with `answerCall`), incoming call eventgrid event will be sent. This is different from Callback events above, and should be setup on Azure portal. See [Incoming Call][incomingcall] for detail. |
## Examples
### Initialize CallAutomationClient
```Python
from azure.communication.callautomation import (CallAutomationClient)
# Your unique Azure Communication service endpoint
endpoint_url = '<ENDPOINT>'
client = CallAutomationClient.from_connection_string(endpoint_url)
```
### Create Call
```Python
from azure.communication.callautomation import (
CallAutomationClient,
CommunicationUserIdentifier
)
# target endpoint for ACS User
user = CommunicationUserIdentifier("8:acs:...")
# callback url to receive callback events
callback_url = "https://<MY-EVENT-HANDLER-URL>/events"
# send out the invitation, creating call
result = client.create_call(
target_participant=user,
callback_url=callback_uri
)
# this id can be used to do further actions in the call
call_connection_id = result.call_connection_id
```
### Play Media
```Python
# using call connection id, get call connection
call_connection = client.get_call_connection(call_connection_id)
# from callconnection of result above, play media to all participants
my_file = FileSource(url="https://<FILE-SOURCE>/<SOME-FILE>.wav")
call_connection.play_to_all(my_file)
```
## Troubleshooting
## Next steps
- [Call Automation Overview][overview]
- [Incoming Call Concept][incomingcall]
- [Build a customer interaction workflow using Call Automation][build1]
- [Redirect inbound telephony calls with Call Automation][build2]
- [Quickstart: Play action][build3]
- [Quickstart: Recognize action][build4]
- [Read more about Call Recording in Azure Communication Services][recording1]
- [Record and download calls with Event Grid][recording2]
## Provide Feedback
If you encounter any bugs or have suggestions, please file an issue in the [Issues](https://github.com/Azure/azure-sdk-for-python/issues) section of the project
## Contributing
This project welcomes contributions and suggestions. Most contributions require
you to agree to a Contributor License Agreement (CLA) declaring that you have
the right to, and actually do, grant us the rights to use your contribution.
For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether
you need to provide a CLA and decorate the PR appropriately (e.g., label,
comment). Simply follow the instructions provided by the bot. You will only
need to do this once across all repos using our CLA.
This project has adopted the
[Microsoft Open Source Code of Conduct][code_of_conduct]. For more information,
see the Code of Conduct FAQ or contact opencode@microsoft.com with any
additional questions or comments.
<!-- LINKS -->
[overview]: https://learn.microsoft.com/azure/communication-services/concepts/voice-video-calling/call-automation
[product_docs]: https://docs.microsoft.com/azure/communication-services/overview
[azure_cli]: https://docs.microsoft.com/cli/azure
[azure_sub]: https://azure.microsoft.com/free/
[azure_portal]: https://portal.azure.com
[azure_powershell]: https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice
[build_doc]: https://aka.ms/AzureSDKBundling
[incomingcall]: https://learn.microsoft.com/azure/communication-services/concepts/voice-video-calling/incoming-call-notification
[build1]: https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/callflows-for-customer-interactions?pivots=programming-language-csha
[build2]: https://learn.microsoft.com/azure/communication-services/how-tos/call-automation-sdk/redirect-inbound-telephony-calls?pivots=programming-language-csharp
[build3]: https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/play-action?pivots=programming-language-csharp
[build4]: https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/recognize-action?pivots=programming-language-csharp
[recording1]: https://learn.microsoft.com/azure/communication-services/concepts/voice-video-calling/call-recording
[recording2]: https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/get-started-call-recording?pivots=programming-language-csharp
Raw data
{
"_id": null,
"home_page": "https://github.com/Azure/azure-sdk-for-python",
"name": "azure-communication-callautomation",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "azure, azure sdk",
"author": "Microsoft Corporation",
"author_email": "azpysdkhelp@microsoft.com",
"download_url": "https://files.pythonhosted.org/packages/5e/24/8b7a6d00dd256e65bf5b64a2cc58b08956163e7a8dcf718d1624837381e9/azure-communication-callautomation-1.2.0.tar.gz",
"platform": null,
"description": "# Azure Communication Call Automation client library for Python\n\nThis package contains a Python SDK for Azure Communication Call Automation. Call Automation provides developers the ability to build server-based, intelligent call workflows, and call recording for voice and PSTN channels.\n\n[Overview of Call Automation][overview] | [Product documentation][product_docs]\n\n## _Disclaimer_\n_Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please\nrefer to https://github.com/Azure/azure-sdk-for-python/issues/20691_\n\n## Getting started\n### Prerequisites\n- Python 3.7 or later is required to use this package.\n- You need an [Azure subscription][azure_sub] to use this package.\n- A deployed Communication Services resource. You can use the [Azure Portal][azure_portal] or the [Azure PowerShell][azure_powershell] to set it up.\n\n### Installing\nInstall the Azure Communication Service Call Automation SDK.\n\n```bash\npip install azure-communication-callautomation\n```\n\n## Key concepts\n| Name | Description |\n| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| CallAutomationClient | `CallAutomationClient` is the primary interface for developers using this client library. It can be used to initiate calls by `createCall` or `answerCall`. It can also be used to do recording actions such as `startRecording` | |\n| CallConnectionClient | `CallConnectionClient` represents a ongoing call. Once the call is established with `createCall` or `answerCall`, further actions can be performed for the call, such as `transfer` or `play_media`. | |\n| Callback Events | Callback events are events sent back during duration of the call. It gives information and state of the call, such as `CallConnected`. `CallbackUrl` must be provided during `createCall` and `answerCall`, and callback events will be sent to this url. |\n| Incoming Call Event | When incoming call happens (that can be answered with `answerCall`), incoming call eventgrid event will be sent. This is different from Callback events above, and should be setup on Azure portal. See [Incoming Call][incomingcall] for detail. |\n\n## Examples\n### Initialize CallAutomationClient\n```Python\nfrom azure.communication.callautomation import (CallAutomationClient)\n\n# Your unique Azure Communication service endpoint\nendpoint_url = '<ENDPOINT>'\nclient = CallAutomationClient.from_connection_string(endpoint_url)\n```\n\n### Create Call\n```Python\nfrom azure.communication.callautomation import (\n CallAutomationClient,\n CommunicationUserIdentifier\n)\n\n# target endpoint for ACS User\nuser = CommunicationUserIdentifier(\"8:acs:...\")\n\n# callback url to receive callback events\ncallback_url = \"https://<MY-EVENT-HANDLER-URL>/events\"\n\n# send out the invitation, creating call\nresult = client.create_call(\n target_participant=user,\n callback_url=callback_uri\n)\n\n# this id can be used to do further actions in the call\ncall_connection_id = result.call_connection_id\n```\n\n### Play Media\n```Python\n# using call connection id, get call connection\ncall_connection = client.get_call_connection(call_connection_id)\n\n# from callconnection of result above, play media to all participants\nmy_file = FileSource(url=\"https://<FILE-SOURCE>/<SOME-FILE>.wav\")\ncall_connection.play_to_all(my_file)\n```\n\n## Troubleshooting\n## Next steps\n- [Call Automation Overview][overview]\n- [Incoming Call Concept][incomingcall]\n- [Build a customer interaction workflow using Call Automation][build1]\n- [Redirect inbound telephony calls with Call Automation][build2]\n- [Quickstart: Play action][build3]\n- [Quickstart: Recognize action][build4]\n- [Read more about Call Recording in Azure Communication Services][recording1]\n- [Record and download calls with Event Grid][recording2]\n\n## Provide Feedback\n\nIf you encounter any bugs or have suggestions, please file an issue in the [Issues](https://github.com/Azure/azure-sdk-for-python/issues) section of the project\n\n## Contributing\n\nThis project welcomes contributions and suggestions. Most contributions require\nyou to agree to a Contributor License Agreement (CLA) declaring that you have\nthe right to, and actually do, grant us the rights to use your contribution.\nFor details, visit https://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine whether\nyou need to provide a CLA and decorate the PR appropriately (e.g., label,\ncomment). Simply follow the instructions provided by the bot. You will only\nneed to do this once across all repos using our CLA.\n\nThis project has adopted the\n[Microsoft Open Source Code of Conduct][code_of_conduct]. For more information,\nsee the Code of Conduct FAQ or contact opencode@microsoft.com with any\nadditional questions or comments.\n\n<!-- LINKS -->\n[overview]: https://learn.microsoft.com/azure/communication-services/concepts/voice-video-calling/call-automation\n[product_docs]: https://docs.microsoft.com/azure/communication-services/overview\n[azure_cli]: https://docs.microsoft.com/cli/azure\n[azure_sub]: https://azure.microsoft.com/free/\n[azure_portal]: https://portal.azure.com\n[azure_powershell]: https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice\n[build_doc]: https://aka.ms/AzureSDKBundling\n[incomingcall]: https://learn.microsoft.com/azure/communication-services/concepts/voice-video-calling/incoming-call-notification\n[build1]: https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/callflows-for-customer-interactions?pivots=programming-language-csha\n[build2]: https://learn.microsoft.com/azure/communication-services/how-tos/call-automation-sdk/redirect-inbound-telephony-calls?pivots=programming-language-csharp\n[build3]: https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/play-action?pivots=programming-language-csharp\n[build4]: https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/recognize-action?pivots=programming-language-csharp\n[recording1]: https://learn.microsoft.com/azure/communication-services/concepts/voice-video-calling/call-recording\n[recording2]: https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/get-started-call-recording?pivots=programming-language-csharp\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Microsoft Azure Communication Call Automation Client Library for Python",
"version": "1.2.0",
"project_urls": {
"Bug Reports": "https://github.com/Azure/azure-sdk-for-python/issues",
"Homepage": "https://github.com/Azure/azure-sdk-for-python",
"Source": "https://github.com/Azure/azure-sdk-for-python"
},
"split_keywords": [
"azure",
" azure sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7f5a7b7ed399b1c92ef13560dd9456854b2541b2472494b2b17c64a70371187c",
"md5": "c88e2de56d2b574778ee4af3ea55f8cb",
"sha256": "45efce4c0990e9421b3de755d592c750dabd8b19e90441e03f84e12127896461"
},
"downloads": -1,
"filename": "azure_communication_callautomation-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c88e2de56d2b574778ee4af3ea55f8cb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 120044,
"upload_time": "2024-05-01T02:28:13",
"upload_time_iso_8601": "2024-05-01T02:28:13.646920Z",
"url": "https://files.pythonhosted.org/packages/7f/5a/7b7ed399b1c92ef13560dd9456854b2541b2472494b2b17c64a70371187c/azure_communication_callautomation-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5e248b7a6d00dd256e65bf5b64a2cc58b08956163e7a8dcf718d1624837381e9",
"md5": "71a8fdd86db357b66f9af07dcaeab6ca",
"sha256": "aa02155878f2540c267729657f1b12e98683bc7e7831e6d576277606ece9e3a7"
},
"downloads": -1,
"filename": "azure-communication-callautomation-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "71a8fdd86db357b66f9af07dcaeab6ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 111277,
"upload_time": "2024-05-01T02:28:11",
"upload_time_iso_8601": "2024-05-01T02:28:11.611853Z",
"url": "https://files.pythonhosted.org/packages/5e/24/8b7a6d00dd256e65bf5b64a2cc58b08956163e7a8dcf718d1624837381e9/azure-communication-callautomation-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-01 02:28:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Azure",
"github_project": "azure-sdk-for-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "azure-communication-callautomation"
}
JSON
