How to Fix Azure Communication Services Setup & Errors

Before anything else, confirm that your ACS resource exists in a supported Azure geography for what you're trying to do. This is where a lot of teams get burned early. Azure Communication Services is available in multiple Azure geographies, but phone number acquisition and PSTN calling are region-restricted. Not every Azure region supports acquiring local or toll-free numbers for every country.

To check: open the Azure portal, navigate to your Communication Services resource, and in the left menu select Phone numbers. Click Get. If the country you need isn't listed, your resource region doesn't support it. You have two options: create a new ACS resource in a supported region, or use Azure Communication Services direct routing to bring your own phone numbers via a SIP-enabled session border controller.

For the SMS channel specifically, you need a phone number with SMS capability enabled. When acquiring a number, the portal shows you which capabilities each number type supports. A number provisioned for voice only will silently drop outbound SMS, the API call will return success but the message won't go anywhere. Always double-check capability flags.

To confirm via the REST API rather than the portal:

GET https://<your-resource>.communication.azure.com/phoneNumbers?api-version=2023-05-01
Authorization: Bearer <your-access-token>

Look at the capabilities object in the response. You want to see "sms": "inbound+outbound" for full SMS, or "calling": "inbound+outbound" for voice. If those aren't there, the number isn't configured for what you need.

If it worked: your phone numbers list loads without error, and the capabilities match what you need. Move to Step 2.

Azure Communication Services SDKs, available for JavaScript/TypeScript, .NET, Python, Java, and more, all authenticate the same way: either a connection string or a managed identity credential. The connection string approach is the most common, and it's also the most common source of 401 errors in my experience.

A valid ACS connection string looks like this:

endpoint=https://<your-resource-name>.communication.azure.com/;accesskey=<base64-encoded-key>

Two things break this silently. First, trailing whitespace, if you copied the connection string from the portal and accidentally grabbed a space at the end, the SDK will parse it incorrectly and you'll get authentication failures with no obvious error message. Trim the string in your code or config. Second, using just the access key (the base64 string) instead of the full connection string, the SDK expects both the endpoint and the key together in that format.

In JavaScript/TypeScript, initialize your SMS client like this:

import { SmsClient } from "@azure/communication-sms";

const connectionString = process.env.COMMUNICATION_SERVICES_CONNECTION_STRING;
const smsClient = new SmsClient(connectionString);

const sendResults = await smsClient.send({
  from: "+15551234567",
  to: ["+15559876543"],
  message: "Hello from Azure Communication Services"
});

If you're on a managed identity setup (recommended for production), swap the connection string for a DefaultAzureCredential and pass your resource endpoint URL separately. Make sure the managed identity has the Contributor role on the ACS resource, Reader isn't enough to send messages.

If it worked: your first SDK call returns a result object with httpStatusCode: 202 for SMS sends, or a valid response body for other channels. No more 401 errors.

Email is the channel I see most misconfigured. Azure Communication Services email works through a separate sub-resource called an Email Communication Service, it's not built into your main ACS resource automatically. A lot of developers miss this and can't figure out why their email sends return 202 but nothing arrives.

Here's the setup path: in the Azure portal, search for Email Communication Services and create one. Then, link it to your main Communication Services resource by going to your ACS resource → Email in the left menu → Connect your email domain. Without this link, the SDK call will appear to succeed (202 Accepted) but emails won't actually be dispatched.

For the sender domain: you have two choices. The quick one is the free azurecomm.net subdomain Microsoft provides, no DNS changes needed, works in minutes. The production choice is connecting your own domain, which requires adding SPF, DKIM, and DMARC records to your DNS. Microsoft's email documentation explicitly calls out sender authentication as a best practice, and for good reason. Without proper DKIM/DMARC alignment, your emails will land in spam folders or get rejected by major providers.

To send an email using the SDK:

import { EmailClient } from "@azure/communication-email";

const client = new EmailClient(connectionString);
const emailMessage = {
  senderAddress: "donotreply@your-verified-domain.com",
  content: {
    subject: "Test email from ACS",
    plainText: "Hello, this is a test.",
  },
  recipients: {
    to: [{ address: "user@example.com", displayName: "Test User" }],
  },
};

const poller = await client.beginSend(emailMessage);
const result = await poller.pollUntilDone();

The beginSend method returns a long-running operation poller. If you only await client.beginSend() without calling pollUntilDone(), you'll miss delivery errors. Poll until done to get the final status field, look for Succeeded.

If it worked: result.status is "Succeeded" and the recipient receives the email within a few seconds.

Voice and video calling in Azure Communication Services runs through the Calling SDK on the client side, and optionally through Call Automation on the server side for IVR flows, bots, and programmable call routing. Both have distinct failure patterns.

For the client-side Calling SDK, the most common issue is a missing or expired user access token. Every call participant needs a short-lived token issued by your backend using the ACS Identity SDK. Tokens expire after 24 hours by default. If a user's session persists longer than that, their call attempts will fail with a 401. The fix: implement token refresh in your application. Your backend should expose an endpoint that generates a fresh token, and your frontend should call it before the current token expires.

Generating a user access token in Node.js looks like this:

import { CommunicationIdentityClient } from "@azure/communication-identity";

const identityClient = new CommunicationIdentityClient(connectionString);
const user = await identityClient.createUser();
const tokenResponse = await identityClient.getToken(user, ["voip"]);

console.log(tokenResponse.token);      // short-lived JWT
console.log(tokenResponse.expiresOn);  // expiry timestamp

For Call Automation, the server-side API for building IVR workflows, recording calls, and running bots, the critical thing since the November 2024 update is handling the new CreateCallFailed and AnswerFailed events. Previously, if your CreateCall API call failed asynchronously, you'd get nothing back. Now, these events fire on your callback webhook. Make sure your webhook endpoint is publicly reachable (use a tool like ngrok for local development), returns HTTP 200 quickly, and processes events asynchronously in a background queue.

You can now also monitor Call Automation callback events directly in Azure Metrics, go to your ACS resource → Metrics → select the Call Automation namespace. This is a huge improvement for debugging production call flows.

If it worked: incoming call events appear in your webhook handler, and the Metrics dashboard shows callback event counts incrementing normally.

The Chat SDK and Advanced Messaging for WhatsApp both require a thread or conversation context before any messages can flow, and that context needs a valid user access token with the right scopes.

For chat, the common failure point is scope mismatch. When you generate a user token, you must explicitly include the "chat" scope. A token generated with only the "voip" scope will get rejected by the Chat API with a 403 Forbidden. Check your token generation code and include both scopes if you need both channels:

const tokenResponse = await identityClient.getToken(user, ["voip", "chat"]);

For Advanced Messaging for WhatsApp, setup is more involved. You need to register a WhatsApp Business Account through the Azure portal's Advanced Messaging section. The process involves connecting your Meta (Facebook) Business Manager account to your ACS resource. Before going live, Microsoft provides an Advanced Messaging sandbox you can use to test message flows without a real WhatsApp Business account, highly recommend starting there to verify your integration before committing to the full registration process.

Once registered, sending a WhatsApp message requires using an approved message template for the first outbound message to a new user (this is a WhatsApp Business Platform rule, not an ACS rule). Trying to send a free-form message to a user who hasn't messaged you first will get rejected. Use the template message API for your initial outreach:

// Advanced Messaging send via ACS REST API
POST https://<resource>.communication.azure.com/messages/notifications:send?api-version=2024-02-01
{
  "channelRegistrationId": "<your-channel-id>",
  "to": "+15551234567",
  "kind": "template",
  "template": {
    "name": "your_approved_template_name",
    "language": { "code": "en_US" }
  }
}

If it worked: the API returns 202 Accepted and the recipient receives the WhatsApp template message on their device within seconds.