[Communication] SMS 1:N Messages - Update Samples (Azure#14125)

* Update samples

* Update samples and readme

* formatting and text

* update readme

* minor readme touchup

* make tag example more realistic

* update snippet in readme

* update ts sample

sdk/communication/communication-sms/README.md

@@ -39,7 +39,7 @@ You can get a key and/or connection string from your Communication Services reso
 ```typescript
 import { SmsClient } from "@azure/communication-sms";
 
-const connectionString = `endpoint=<Host>;accessKey=<Base64-Encoded-Key>`;
+const connectionString = `endpoint=https://<resource-name>.communication.azure.com/;accessKey=<Base64-Encoded-Key>`;
 const client = new SmsClient(connectionString);
 ```
 
@@ -49,8 +49,9 @@ const client = new SmsClient(connectionString);
 import { AzureKeyCredential } from "@azure/core-auth";
 import { SmsClient } from "@azure/communication-sms";
 
+const endpoint = "https://<resource-name>.communication.azure.com";
 const credential = new AzureKeyCredential("<Base64-Encoded-Key>");
-const client = new SmsClient("<Host>", credential);
+const client = new SmsClient(endpoint, credential);
 ```
 
 ### Using Azure Active Directory managed identity
@@ -62,33 +63,70 @@ npm install @azure/identity
 ```
 
 The [`@azure/identity`][azure_identity] package provides a variety of credential types that your application can use to do this. The README for @azure/identity provides more details and samples to get you started.
+AZURE_CLIENT_SECRET, AZURE_CLIENT_ID and AZURE_TENANT_ID environment variables are needed to create a DefaultAzureCredential object.
 
 ```typescript
 import { DefaultAzureCredential } from "@azure/identity";
 import { SmsClient } from "@azure/communication-sms";
 
+const endpoint = "https://<resource-name>.communication.azure.com";
 let credential = new DefaultAzureCredential();
 const client = new SmsClient(endpoint, credential);
 ```
 
-## Sending SMS
-
-```typescript
-import { AzureKeyCredential } from "@azure/core-auth";
-import { SmsClient } from "@azure/communication-sms";
+## Send a 1:N SMS Message
 
-const credential = new AzureKeyCredential("<Base64-Encoded-Key>");
-const client = new SmsClient("<Host>", credential);
+To send a SMS message, call the `send` function from the `SmsClient`. You need to pass in a `SmsSendRequest` object.
+You may also add pass in an options object to specify whether the delivery report should be enabled and set custom tags for the report.
+An array of `SmsSendResult` is returned. A `successful` flag is used to validate if each individual message was sent successfully.
 
-const response = await client.send({
-  from: "+12345678902",
-  to: ["+12345678901"],
-  message: "Hey there!"
-});
+```typescript
+const sendResults = await client.send(
+  {
+    from: "<from-phone-number>", // Your E.164 formatted phone number used to send SMS
+    to: ["<to-phone-number-1>", "<to-phone-number-2>"], // The list of E.164 formatted phone numbers to which message is being sent
+    message: "Weekly Promotion!" // The message being sent
+  },
+  {
+    enableDeliveryReport: true,
+    tag: "marketing"
+  }
+);
+
+for (const sendResult of sendResults) {
+  if (sendResult.successful) {
+    console.log("Success: ", sendResult);
+  } else {
+    console.error("Something went wrong when trying to send this message: ", sendResult);
+  }
+}
 ```
 
 ## Troubleshooting
 
+SMS operations will throw an exception if the request to the server fails.
+Exceptions will not be thrown if the error is caused by an individual message, only if something fails with the overall request.
+Please use the `successful` flag to validate each individual result to verify if the message was sent.
+
+```typescript
+try {
+  const sendResults = await client.send({
+    from: "<from-phone-number>", // Your E.164 formatted phone number used to send SMS
+    to: ["<to-phone-number-1>", "<to-phone-number-2>"], // The list of E.164 formatted phone numbers to which message is being sent
+    message: "Hello World via SMS!" // The message being sent
+  });
+  for (const sendResult of sendResults) {
+    if (sendResult.successful) {
+      console.log("Success: ", sendResult);
+    } else {
+      console.error("Something went wrong when trying to send this message: ", sendResult);
+    }
+  }
+} catch (e) {
+  console.error(e.message);
+}
+```
+
 ## Next steps
 
 Please take a look at the

sdk/communication/communication-sms/samples/javascript/package.json

@@ -26,6 +26,7 @@
   "sideEffects": false,
   "dependencies": {
     "@azure/communication-sms": "latest",
+    "@azure/identity": "^1.1.0",
     "dotenv": "^8.2.0"
   }
 }

sdk/communication/communication-sms/samples/javascript/sample.env

@@ -1,3 +1,9 @@
 # Used in most samples. Retrieve these values from a Communication Service instance
 # in the Azure Portal.
-COMMUNICATION_CONNECTION_STRING="endpoint=https://<resource name>.communication.azure.net/;accessKey=<key>"
+COMMUNICATION_CONNECTION_STRING="endpoint=https://<resource name>.communication.azure.com/;accessKey=<key>"
+
+# For token authentication
+COMMUNICATION_ENDPOINT="https://<resource name>.communication.azure.com",
+AZURE_CLIENT_ID: "YourClientId",
+AZURE_TENANT_ID: "YourTenantId",
+AZURE_CLIENT_SECRET: "YourClientSecret"

sdk/communication/communication-sms/samples/javascript/sendSms.js

@@ -7,36 +7,80 @@
  */
 
 const { SmsClient } = require("@azure/communication-sms");
+const { DefaultAzureCredential } = require("@azure/identity");
 
 // Load the .env file if it exists
 const dotenv = require("dotenv");
-dotenv.config();
+dotenv.config({
+  path: "sample.env"
+});
 
-// You will need to set this environment variables or edit the following values
-const connectionString =
-  process.env["COMMUNICATION_CONNECTION_STRING"] || "<communication service connection string>";
+export const createSmsClient = () => {
+  // You will need to set this environment variable or edit the following value
+  const connectionString =
+    process.env["COMMUNICATION_CONNECTION_STRING"] ||
+    "endpoint=https://<resource-name>.communication.azure.com/;<access-key>";
+  return new SmsClient(connectionString);
+};
 
-async function main() {
-  console.log("== Send SMS Message Sample ==");
+export const createSmsClientWithToken = () => {
+  // You will need to set this environment variable or edit the following value
+  const endpoint =
+    process.env["COMMUNICATION_ENDPOINT"] || "https://<resource-name>.communication.azure.com";
+  //AZURE_CLIENT_SECRET, AZURE_CLIENT_ID and AZURE_TENANT_ID environment variables are needed to create a DefaultAzureCredential object.
+  return new SmsClient(endpoint, new DefaultAzureCredential());
+};
+
+export const sendingSmsMessage = async () => {
+  console.log("== Send SMS Message, Default Options ==");
+  const client = createSmsClient();
+  const sendResults = await client.send({
+    from: "<from-phone-number>", // Your E.164 formatted phone number used to send SMS
+    to: ["<to-phone-number-1>", "<to-phone-number-2>"], // The list of E.164 formatted phone numbers to which message is being sent
+    message: "Hello World via SMS!" // The message being sent
+  });
 
-  const client = new SmsClient(connectionString);
+  for (const sendResult of sendResults) {
+    if (sendResult.successful) {
+      console.log("Success: ", sendResult);
+    } else {
+      console.error("Something went wrong when trying to send this message: ", sendResult);
+    }
+  }
+  console.log("== Done: Send SMS Message, Default Options ==");
+};
 
-  // Send SMS message
+export const sendingSmsMessageWithOptions = async () => {
+  console.log("== Send SMS Message With Options ==");
+  const client = createSmsClient();
   const sendResults = await client.send(
     {
-      from: "<phone number>", // Your E.164 formatted phone number used to send SMS
-      to: ["<phone number>", "<phone number>", "<phone number>"], // The list of E.164 formatted phone numbers to which message is being send
-      message: "Hello World via SMS!" // The message being sent
+      from: "<from-phone-number>", // Your E.164 formatted phone number used to send SMS
+      to: ["<to-phone-number-1>", "<to-phone-number-2>"], // The list of E.164 formatted phone numbers to which message is being sent
+      message: "Weekly Promotion!" // The message being sent
     },
     {
       enableDeliveryReport: true,
-      tag: "customTag"
+      tag: "marketing"
     }
   );
+
   for (const sendResult of sendResults) {
-    console.log("result: ", sendResult);
+    if (sendResult.successful) {
+      console.log("Success: ", sendResult);
+    } else {
+      console.error("Something went wrong when trying to send this message: ", sendResult);
+    }
   }
-}
+  console.log("== Done: Send SMS Message With Options ==");
+};
+
+export const main = async () => {
+  console.log("== Send SMS Message Sample ==");
+  await sendingSmsMessage();
+  await sendingSmsMessageWithOptions();
+  console.log("== SMS Sample Complete! ==");
+};
 
 main().catch((error) => {
   console.error("Encountered an error while sending sms: ");

sdk/communication/communication-sms/samples/typescript/package.json

@@ -31,6 +31,7 @@
   "sideEffects": false,
   "dependencies": {
     "@azure/communication-sms": "latest",
+    "@azure/identity": "^1.1.0",
     "dotenv": "^8.2.0"
   },
   "devDependencies": {

sdk/communication/communication-sms/samples/typescript/sample.env

@@ -1,3 +1,9 @@
 # Used in most samples. Retrieve these values from a Communication Service instance
 # in the Azure Portal.
-COMMUNICATION_CONNECTION_STRING="endpoint=https://<resource name>.communication.azure.net/;accessKey=<key>"
+COMMUNICATION_CONNECTION_STRING="endpoint=https://<resource name>.communication.azure.com/;accessKey=<key>"
+
+# For token authentication
+COMMUNICATION_ENDPOINT="https://<resource name>.communication.azure.com",
+AZURE_CLIENT_ID: "YourClientId",
+AZURE_TENANT_ID: "YourTenantId",
+AZURE_CLIENT_SECRET: "YourClientSecret"

sdk/communication/communication-sms/samples/typescript/src/sendSms.ts

@@ -7,38 +7,83 @@
  */
 
 import { SmsClient } from "@azure/communication-sms";
+import { DefaultAzureCredential } from "@azure/identity";
 
 // Load the .env file if it exists
 import * as dotenv from "dotenv";
-dotenv.config();
+dotenv.config({
+  path: "sample.env"
+});
 
-// You will need to set this environment variables or edit the following values
-const connectionString =
-  process.env["COMMUNICATION_CONNECTION_STRING"] || "<communication service connection string>";
+export const createSmsClient = () => {
+  // You will need to set this environment variable or edit the following value
+  const connectionString =
+    process.env["COMMUNICATION_CONNECTION_STRING"] ||
+    "endpoint=https://<resource-name>.communication.azure.com/;<access-key>";
+  return new SmsClient(connectionString);
+};
 
-export const main = async () => {
-  console.log("== Send SMS Message Sample ==");
+export const createSmsClientWithToken = () => {
+  // You will need to set this environment variable or edit the following value
+  const endpoint =
+    process.env["COMMUNICATION_ENDPOINT"] || "https://<resource-name>.communication.azure.com";
+  //AZURE_CLIENT_SECRET, AZURE_CLIENT_ID and AZURE_TENANT_ID environment variables are needed to create a DefaultAzureCredential object.
+  return new SmsClient(endpoint, new DefaultAzureCredential());
+};
 
-  const client = new SmsClient(connectionString);
+export const sendingSmsMessage = async () => {
+  console.log("== Send SMS Message, Default Options ==");
+  const client = createSmsClient();
+  const sendResults = await client.send({
+    from: "<from-phone-number>", // Your E.164 formatted phone number used to send SMS
+    to: ["<to-phone-number-1>", "<to-phone-number-2>"], // The list of E.164 formatted phone numbers to which message is being sent
+    message: "Hello World via SMS!" // The message being sent
+  });
 
-  // Send SMS message
+  for (const sendResult of sendResults) {
+    if (sendResult.successful) {
+      console.log("Success: ", sendResult);
+    } else {
+      console.error("Something went wrong when trying to send this message: ", sendResult);
+    }
+  }
+  console.log("== Done: Send SMS Message, Default Options ==");
+};
+
+export const sendingSmsMessageWithOptions = async () => {
+  console.log("== Send SMS Message With Options ==");
+  const client = createSmsClient();
   const sendResults = await client.send(
     {
-      from: "<phone number>", // Your E.164 formatted phone number used to send SMS
-      to: ["<phone number>", "<phone number>", "<phone number>"], // The list of E.164 formatted phone numbers to which message is being send
-      message: "Hello World via SMS!" // The message being sent
+      from: "<from-phone-number>", // Your E.164 formatted phone number used to send SMS
+      to: ["<to-phone-number-1>", "<to-phone-number-2>"], // The list of E.164 formatted phone numbers to which message is being sent
+      message: "Weekly Promotion!" // The message being sent
     },
     {
       enableDeliveryReport: true,
-      tag: "customTag"
+      tag: "marketing"
     }
   );
 
   for (const sendResult of sendResults) {
-    console.log("result: ", sendResult);
+    if (sendResult.successful) {
+      console.log("Success: ", sendResult);
+    } else {
+      console.error("Something went wrong when trying to send this message: ", sendResult);
+    }
   }
+  console.log("== Done: Send SMS Message With Options ==");
+};
+
+export const main = async () => {
+  console.log("== Send SMS Message Sample ==");
+  await sendingSmsMessage();
+  await sendingSmsMessageWithOptions();
+  console.log("== SMS Sample Complete! ==");
 };
 
 main().catch((error) => {
-  console.error("Encountered an error while sending sms: ", error);
+  console.error("Encountered an error while sending sms: ");
+  console.error("Request: \n", error.request);
+  console.error("\nResponse: \n", error.response);
 });