Proposed Pull Request Change

📄 Document Links

View on GitHub View on Microsoft Learn

--- title: Include file description: Include file services: azure-communication-services author: shamkh ms.service: azure-communication-services ms.subservice: advanced-messaging ms.date: 05/01/2025 ms.topic: include ms.custom: include file ms.author: shamkh ms.custom: devx-track-extended-java, devx-track-js, devx-track-python zone_pivot_groups: acs-js-csharp-java-python --- ### Authenticate the client Messages sending uses NotificationMessagesClient. NotificationMessagesClient authenticates using your connection string acquired from Azure Communication Services resource in the Azure portal.F For more information on connection strings, see [access-your-connection-strings-and-service-endpoints](../../../create-communication-resource.md#access-your-connection-strings-and-service-endpoints). #### [Connection String](#tab/connection-string) Get Azure Communication Resource connection string from Azure portal as given in screenshot. On the left, navigate to the `Keys` tab. Copy the `Connection string` field for the primary key. The connection string is in the format `endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}`. :::image type="content" source="../media/get-started/get-communication-resource-connection-string.png" alt-text="Screenshot that shows an Azure Communication Services resource in the Azure portal, viewing the 'Primary Key' field in the 'Keys' section."::: Set the environment variable `COMMUNICATION_SERVICES_CONNECTION_STRING` to the value of your connection string. Open a console window and enter the following command: ```console setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>" ``` After you add the environment variable, you might need to restart any running programs that will need to read the environment variable, including the console window. For example, if you're using Visual Studio as your editor, restart Visual Studio before running the example. For more information on how to set an environment variable for your system, follow the steps at [Store your connection string in an environment variable](../../../create-communication-resource.md#store-your-connection-string-in-an-environment-variable). ```python # Get a connection string to our Azure Communication Services resource. connection_string = os.getenv("COMMUNICATION_SERVICES_CONNECTION_STRING") def send_template_message(self): from azure.communication.messages import NotificationMessagesClient # Create NotificationMessagesClient Client messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string) ``` #### [Microsoft Entra ID](#tab/aad) NotificationMessagesClient is also authenticated using Microsoft Entra ID/TokenCredentials. For more information, see [access-Azure-Communication-Resources-using-TokenCredentials](/python/api/overview/azure/identity-readme?view=azure-python&preserve-view=true#environment-variables). The [`azure.identity`](https://github.com/Azure/azure-sdk-for-python/tree/azure-identity_1.15.0/sdk/identity/azure-identity) package provides various credential types that your application can use to authenticate. You can choose from the various options to authenticate the identity client detailed at [Azure Identity - Credential providers](/python/api/overview/azure/identity-readme?view=azure-python#credential-classes&preserve-view=true) and [Azure Identity - Authenticate the client](/python/api/overview/azure/identity-readme?view=azure-python#authenticate-with-defaultazurecredential&preserve-view=true). This option walks through one way of using the [`DefaultAzureCredential`](/python/api/overview/azure/identity-readme?view=azure-python#defaultazurecredential&preserve-view=true). The `DefaultAzureCredential` attempts to authenticate via [`several mechanisms`](/python/api/overview/azure/identity-readme?view=azure-python#defaultazurecredential&preserve-view=true) and it might be able to find its authentication credentials if you're signed into Visual Studio or Azure CLI. However, this option walks you through setting up with environment variables. To create a `DefaultAzureCredential` object: 1. To set up your service principle app, follow the instructions at [Creating a Microsoft Entra registered Application](../../../identity/service-principal.md?pivots=platform-azcli#creating-a-microsoft-entra-registered-application). 1. Set the environment variables `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID` using the output of your app's creation. Open a console window and enter the following commands: ```console setx COMMUNICATION_SERVICES_ENDPOINT_STRING "<https://<resource name>.communication.azure.com>" setx AZURE_CLIENT_ID "<your app's appId>" setx AZURE_CLIENT_SECRET "<your app's password>" setx AZURE_TENANT_ID "<your app's tenant>" ``` After you add the environment variables, you might need to restart any running programs that will need to read the environment variables, including the console window. For example, if you're using Visual Studio as your editor, restart Visual Studio before running the example. 1. To use the [`DefaultAzureCredential`](/python/api/overview/azure/identity-readme?view=azure-python#defaultazurecredential&preserve-view=true) provider, or other credential providers provided with the Azure SDK, install the `azure.identity` python package and then instantiate client. ```python # Get a connection string to our Azure Communication Services resource. endpoint_string = os.getenv("COMMUNICATION_SERVICES_ENDPOINT_STRING") def send_template_message(self): from azure.communication.messages import NotificationMessagesClient from azure.identity import DefaultAzureCredential # Create NotificationMessagesClient Client messaging_client = NotificationMessagesClient(endpoint=self.endpoint_string, credential=DefaultAzureCredential()) ``` #### [AzureKeyCredential](#tab/azurekeycredential) You can also authenticate with an AzureKeyCredential. Get the endpoint and key from your Azure Communication Services resource in the Azure portal. On the left, navigate to the `Keys` tab. Copy the `Endpoint` and the `Key` field for the primary key. :::image type="content" source="../media/get-started/get-communication-resource-endpoint-and-key.png" lightbox="../media/get-started/get-communication-resource-endpoint-and-key.png" alt-text="Screenshot that shows an Azure Communication Services resource in the Azure portal, viewing the 'Connection string' field in the 'Primary key' section."::: Set the environment variable `COMMUNICATION_SERVICES_KEY` to the value of your connection string. Open a console window and enter the following command: ```console setx COMMUNICATION_SERVICES_ENDPOINT_STRING "<https://<resource name>.communication.azure.com>" setx COMMUNICATION_SERVICES_KEY "<your key>" ``` After you add the environment variable, you might need to restart any running programs that will need to read the environment variable, including the console window. For example, if you're using Visual Studio as your editor, restart Visual Studio before running the example. For more information on how to set an environment variable for your system, follow the steps at [Store your connection string in an environment variable](../../../create-communication-resource.md#store-your-connection-string-in-an-environment-variable). To instantiate a `NotificationMessagesClient`, add the following code: ```python # Get a connection string to our Azure Communication Services resource. endpoint_string = os.getenv("COMMUNICATION_SERVICES_ENDPOINT_STRING") key = os.getenv("COMMUNICATION_SERVICES_KEY") def send_template_message(self): from azure.core.credentials import AzureKeyCredential from azure.communication.messages import NotificationMessagesClient # Create NotificationMessagesClient Client messaging_client = NotificationMessagesClient(endpoint=self.endpoint_string, credential=AzureKeyCredential(self.key)) ``` --- ### Set channel registration ID You created the Channel Registration ID GUID during [channel registration](../connect-whatsapp-business-account.md). Find it in the portal on the **Channels** tab of your Azure Communication Services resource. :::image type="content" source="../media/get-started/get-messages-channel-id.png" lightbox="../media/get-started/get-messages-channel-id.png" alt-text="Screenshot that shows an Azure Communication Services resource in the Azure portal, viewing the 'Channels' tab. Attention is placed on the copy action of the 'Channel ID' field."::: Assign it to a variable called channelRegistrationId. ```python channelRegistrationId = os.getenv("WHATSAPP_CHANNEL_ID_GUID") ``` ### Set recipient list You need to supply an active phone number associated with a WhatsApp account. This WhatsApp account receives the template, text, and media messages sent in this article. For this example, you can use your personal phone number. The recipient phone number can't be the business phone number (Sender ID) associated with the WhatsApp channel registration. The Sender ID appears as the sender of the text and media messages sent to the recipient. The phone number must include the country code. For more information about phone number formatting, see WhatsApp documentation for [Phone Number Formats](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#phone-number-formats). > [!NOTE] > Only one phone number is currently supported in the recipient list. Set the recipient list like this: ```python phone_number = os.getenv("RECIPIENT_WHATSAPP_PHONE_NUMBER") ``` Usage Example: ```python # Example only to=[self.phone_number], ``` ### Start sending messages between a business and a WhatsApp user Conversations between a WhatsApp Business Account and a WhatsApp user can be initiated in one of two ways: - The business sends a template message to the WhatsApp user. - The WhatsApp user sends any message to the business number. A business can't initiate an interactive conversation. A business can only send an interactive message after receiving a message from the user. The business can only send interactive messages to the user during the active conversation. Once the 24 hour conversation window expires, only the user can restart the interactive conversation. For more information about conversations, see the definition at [WhatsApp Business Platform](https://developers.facebook.com/docs/whatsapp/pricing#conversations). To initiate an interactive conversation from your personal WhatsApp account, send a message to your business number (Sender ID). :::image type="content" source="../media/get-started/user-initiated-conversation.png" lightbox="../media/get-started/user-initiated-conversation.png" alt-text="A WhatsApp conversation viewed on the web showing a user message sent to the WhatsApp Business Account number.":::