Skip to content

Commit 4830698

Browse files
ShamkhShamkh
committed
java setting
1 parent 862dd90 commit 4830698

File tree

4 files changed

+200
-2
lines changed

4 files changed

+200
-2
lines changed

‎articles/communication-services/quickstarts/advanced-messaging/whatsapp/includes/common-setting-java.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
title: Include file
3+
description: Include file
4+
services: azure-communication-services
5+
author: shamkh
6+
ms.service: azure-communication-services
7+
ms.subservice: advanced-messaging
8+
ms.date: 07/15/2024
9+
ms.topic: include
10+
ms.custom: include file
11+
ms.author: shamkh
12+
ms.custom: devx-track-extended-java, devx-track-js, devx-track-python
13+
zone_pivot_groups: acs-js-csharp-java-python
14+
---
15+
16+
### Authenticate the client
17+
18+
There are a few different options available for authenticating a Message client:
19+
20+
#### [Connection String](#tab/connection-string)
21+
22+
To authenticate a client, you instantiate an `NotificationMessagesClient` or `MessageTemplateClient` with your connection string. You can also initialize the client with any custom HTTP client that implements the `com.azure.core.http.HttpClient` interface.
23+
24+
For simplicity, this quickstart uses a connection string to authenticate. In production environments, we recommend using [service principals](../../../../identity/service-principal.md).
25+
26+
Get the connection string from your Azure Communication Services resource in the Azure portal. 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}`.
27+
28+
:::image type="content" source="../../media/get-started/get-communication-resource-connection-string.png" lightbox="../../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 'Connection string' field in the 'Primary key' section.":::
29+
30+
Set the environment variable `COMMUNICATION_SERVICES_CONNECTION_STRING` to the value of your connection string.
31+
Open a console window and enter the following command:
32+
```console
33+
setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"
34+
```
35+
36+
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).
37+
38+
To instantiate a NotificationMessagesClient, add the following code to the `main` method:
39+
40+
```java
41+
// You can get your connection string from your resource in the Azure portal.
42+
String connectionString = System.getenv("COMMUNICATION_SERVICES_CONNECTION_STRING");
43+
44+
NotificationMessagesClient notificationClient = new NotificationMessagesClientBuilder()
45+
.connectionString(connectionString)
46+
.buildClient();
47+
```
48+
49+
<a name='azure-active-directory'></a>
50+
51+
#### [Microsoft Entra ID](#tab/aad)
52+
53+
You can also authenticate with Microsoft Entra ID using the [Azure Identity library](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/identity/azure-identity).
54+
55+
The [`Azure.Identity`](https://github.com/Azure/azure-sdk-for-java/tree/main/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](/java/api/overview/azure/identity-readme#credentials) and [Azure Identity - Authenticate the client](/java/api/overview/azure/identity-readme#authenticate-the-client). This option walks through one way of using the [`DefaultAzureCredential`](/java/api/overview/azure/identity-readme#defaultazurecredential).
56+
57+
The `DefaultAzureCredential` attempts to authenticate via [`several mechanisms`](/java/api/overview/azure/identity-readme#defaultazurecredential) 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.
58+
59+
To create a `DefaultAzureCredential` object:
60+
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).
61+
62+
1. Set the environment variables `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID` using the output of your app's creation.
63+
Open a console window and enter the following commands:
64+
```console
65+
setx AZURE_CLIENT_ID "<your app's appId>"
66+
setx AZURE_CLIENT_SECRET "<your app's password>"
67+
setx AZURE_TENANT_ID "<your app's tenant>"
68+
```
69+
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.
70+
71+
1. To use the [`DefaultAzureCredential`](/java/api/overview/azure/identity-readme#defaultazurecredential) provider, or other credential providers provided with the Azure SDK, follow the instruction to include the `azure-identity` package at [Azure Identity - Include the package](/java/api/overview/azure/identity-readme#include-the-package).
72+
73+
1. To instantiate a `NotificationMessagesClient`, add the following code to the `Main` method.
74+
```java
75+
String endpoint = "https://<resource name>.communication.azure.com/";
76+
NotificationMessagesClient notificationClient = new NotificationMessagesClientBuilder()
77+
.endpoint(endpoint)
78+
.credential(new DefaultAzureCredentialBuilder().build())
79+
.buildClient();
80+
```
81+
82+
A [DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/identity/azure-identity#defaultazurecredential) object must be passed to the `ClientBuilder` via the `credential()` method. An endpoint must also be set via the `endpoint()` method.
83+
84+
#### [AzureKeyCredential](#tab/azurekeycredential)
85+
86+
NotificationMessage or MessageTemplate clients can also be created and authenticated using the endpoint and Azure Key Credential acquired from an Azure Communication Resource in the [Azure portal](https://portal.azure.com/).
87+
88+
1. Add the import
89+
```java
90+
import com.azure.core.credential.AzureKeyCredential;
91+
```
92+
93+
1. To instantiate a `NotificationMessagesClient`, add the following code to the `Main` method.
94+
95+
```java
96+
String endpoint = "https://<resource name>.communication.azure.com";
97+
AzureKeyCredential azureKeyCredential = new AzureKeyCredential("<access key>");
98+
NotificationMessagesClient notificationClient = new NotificationMessagesClientBuilder()
99+
.endpoint(endpoint)
100+
.credential(azureKeyCredential)
101+
.buildClient();
102+
```
103+
104+
---
105+
106+
### Set channel registration ID
107+
108+
The Channel Registration ID GUID was created during channel registration. You can look it up in the portal on the Channels tab of your Azure Communication Services resource.
109+
110+
:::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.":::
111+
112+
Assign it to a variable called channelRegistrationId.
113+
```java
114+
String channelRegistrationId = "<your channel registration id GUID>";
115+
```
116+
117+
### Set recipient list
118+
You need to supply a real phone number that has a WhatsApp account associated with it. This WhatsApp account receives the text and media messages sent in this quickstart.
119+
For this quickstart, this phone number may be your personal phone number.
120+
121+
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.
122+
123+
The phone number should include the country code. For more information on phone number formatting, see WhatsApp documentation for [Phone Number Formats](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers#phone-number-formats).
124+
125+
> [!NOTE]
126+
> Only one phone number is currently supported in the recipient list.
127+
128+
Create the recipient list like this:
129+
```java
130+
List<String> recipientList = new ArrayList<>();
131+
recipientList.add("<to WhatsApp phone number>");
132+
```
133+
134+
Example:
135+
```java
136+
// Example only
137+
List<String> recipientList = new ArrayList<>();
138+
recipientList.add("+14255550199");
139+
```
140+
141+
### Start sending messages between a business and a WhatsApp user
142+
143+
Conversations between a WhatsApp Business Account and a WhatsApp user can be initiated in one of two ways:
144+
- The business sends a template message to the WhatsApp user.
145+
- The WhatsApp user sends any message to the business number.
146+
147+
Regardless of how the conversation was started, **a business can only send template messages until the user sends a message to the business.** Only after the user sends a message to the business, the business is allowed to send text or media messages to the user during the active conversation. Once the 24 hour conversation window expires, the conversation must be reinitiated. To learn more about conversations, see the definition at [WhatsApp Business Platform](https://developers.facebook.com/docs/whatsapp/pricing#conversations).
148+
149+
#### (Option 1) Initiate conversation from business - Send a template message
150+
Initiate a conversation by sending a template message.
151+
152+
First, create a MessageTemplate using the values for a template.
153+
> [!NOTE]
154+
> To check which templates you have available, see the instructions at [List templates](../../../../../concepts/advanced-messaging/whatsapp/template-messages.md#list-templates).
155+
> If you don't have a template to use, proceed to [Option 2](#option-2-initiate-conversation-from-user).
156+
157+
Here's MessageTemplate creation using a default template, `sample_template`.
158+
If `sample_template` isn't available to you, skip to [Option 2](#option-2-initiate-conversation-from-user). For advanced users, see the page [Templates](../../../../../concepts/advanced-messaging/whatsapp/template-messages.md) to understand how to send a different template with Option 1.
159+
160+
Messages SDK allows Contoso to send templated WhatsApp messages to WhatsApp users. To send template messages below details are required:
161+
- [WhatsApp Channel ID](#set-channel-registration-id)
162+
- [Recipient Phone Number in E16 format](#set-recipient-list)
163+
- Template details
164+
- Name like 'sample_template'
165+
- Language like 'en_us'
166+
- Parameters if any
167+
168+
```java
169+
// Assemble the template content
170+
String templateName = "sample_template";
171+
String templateLanguage = "en_us";
172+
MessageTemplate messageTemplate = new MessageTemplate(templateName, templateLanguage);
173+
174+
// Assemble template message
175+
TemplateNotificationContent templateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, messageTemplate);
176+
177+
// Send template message
178+
SendMessageResult templateMessageResult = notificationClient.send(templateContent);
179+
180+
// Process result
181+
for (MessageReceipt messageReceipt : templateMessageResult.getReceipts()) {
182+
System.out.println("Message sent to:" + messageReceipt.getTo() + " and message id:" + messageReceipt.getMessageId());
183+
}
184+
```
185+
186+
Now, the user needs to respond to the template message. From the WhatsApp user account, reply to the template message received from the WhatsApp Business Account. The content of the message is irrelevant for this scenario.
187+
188+
> [!IMPORTANT]
189+
> The recipient must respond to the template message to initiate the conversation before text or media message can be delivered to the recipient.
190+
191+
#### (Option 2) Initiate conversation from user
192+
193+
The other option to initiate a conversation between a WhatsApp Business Account and a WhatsApp user is to have the user initiate the conversation.
194+
To do so, from your personal WhatsApp account, send a message to your business number (Sender ID).
195+
196+
:::image type="content" source="../../media/get-started/user-initiated-conversation.png" lightbox="" alt-text="A WhatsApp conversation viewed on the web showing a user message sent to the WhatsApp Business Account number.":::

‎articles/communication-services/quickstarts/advanced-messaging/whatsapp/includes/download-media/download-media-java.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ Follow these steps to add the necessary code snippets to the `messages-quickstar
4545
- [Set channel registration ID](#set-channel-registration-id)
4646
- [Set recipient list](#set-recipient-list)
4747

48-
[!INCLUDE [Common setting for using Advanced Messages SDK](../common-setting.md)]
48+
[!INCLUDE [Common setting for using Advanced Messages SDK](../common-setting-java.md)]
4949

5050
## Code examples
5151

‎articles/communication-services/quickstarts/advanced-messaging/whatsapp/includes/get-started/messages-get-started-java.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Complete these steps to add required code snippets to the `messages-quickstart.p
5050
- [Set recipient list](#set-recipient-list).
5151
- [Start sending messages between a business and a WhatsApp user](#start-sending-messages-between-a-business-and-a-whatsapp-user).
5252

53-
[!INCLUDE [Common setting for using Advanced Messages SDK](../common-setting.md)]
53+
[!INCLUDE [Common setting for using Advanced Messages SDK](../common-setting-java.md)]
5454

5555
## Code examples
5656

‎articles/communication-services/quickstarts/advanced-messaging/whatsapp/send-template-messages.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,8 @@ For more information about WhatsApp requirements for templates, see the WhatsApp
7171
::: zone-end
7272

7373
::: zone pivot="programming-language-java"
74+
[!INCLUDE [Common setting for using Advanced Messages SDK](./includes/common-setting-java.md)]
75+
7476
[!INCLUDE [Send WhatsApp Messages with Java](./includes/templates/messages-quickstart-template-messages-java.md)]
7577
::: zone-end
7678

0 commit comments

Comments
 (0)