Publish an agent to WhatsApp

After you publish your agent, you can make it available to your WhatsApp users. Your WhatsApp users can't interact with the agent until you publish the agent.

Note

When you publish your agent to WhatsApp, some data, such as agent content and user chat content, is shared with WhatsApp. As a result, the data flows outside your organization's compliance and geographic or regional boundaries. For more information, see WhatsApp Business Platform Policy and Spam Enforcement.
In the WhatsApp channel, the conversation start process works differently than in synchronous channels. For more information, see Automatically start an agent conversation.

Set up your agent to use WhatsApp

Important

Make sure all prerequisites are met before beginning this procedure.

Set your agent's authentication to either No authentication or Authenticate manually.
Publish your agent. See Publish the latest content.
Go to the Channels page for your agent.
Select WhatsApp. The configuration panel appears.
On the first page of the configuration panel, select Continue.
Select your Azure subscription and Azure Communication Services (ACS) resource, and then select Continue.
Select the phone number you want your agent to connect to, and then select Deploy.

Note

After you select Deploy, Copilot Studio might take a moment before showing a QR code.
Use your WhatsApp device to scan the QR code and start chatting with the agent over WhatsApp. Alternatively, select Download to download the QR code image. Anyone with this QR code who meets all authentication criteria can chat to the agent over WhatsApp.

Use supported Adaptive Cards in your agent's topics

As with all agents in Copilot Studio, agents deployed to WhatsApp use topics to define how an agent conversation progresses. Adaptive cards allow you to write platform-agnostic UI snippets in JSON that are interpreted into native UI when delivered to specific apps. WhatsApp agents support the following three types of adaptive cards:

Interactive actions adaptive card ("type": "Action.Submit")
Choice adaptive card ("type": "Input.ChoiceSet")
Open URL adaptive card ("type": "Action.OpenUrl")

As a maker, if you want to deploy an agent to a WhatsApp channel, you must restrict your use of adaptive cards to this subset of card types. For more information about the use of adaptive cards in Copilot Studio, see Using Adaptive Cards in Copilot Studio.

Example: Interactive actions adaptive card

Use the Interactive Actions adaptive card to allow end-users to select one of up to three options in the form of buttons. This method of selecting from multiple options is quicker for the end-user, with fewer steps, than the alternative method of selecting from a list of options (the Choice adaptive card method). However, the Interactive actions adaptive card can't be used for more than three buttons. Makers can invoke this adaptive card by using the Ask with Adaptive Card functionality.

Go to the desired topic and add an Adaptive Card node.

In the Card payload editor of the Adaptive card designer, copy and paste the following JSON code:

{
"type": "AdaptiveCard",
"$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
  {
    "type": "TextBlock",
    "text": "Do you want to go to a weather web site for a specific country?",
    "wrap": true
  },
  {
    "type": "ActionSet",
    "actions": [
      {
        "type": "Action.Submit",
        "title": "Yes",
        "id": "yesButtonId"
      },
      {
        "type": "Action.Submit",
        "title": "No",
        "id": "noButtonId"
      }
    ]
 }
]
}

In the JSON, in the section with a type key of value ActionSet, under "actions":, make sure you have the right number of actions.

For example, if you need three buttons, under "actions":, there should be three sets of actions, with each set comprised of a type, title, and id key.

Make the following further changes to the JSON:

Change	To
Value of `"text":` (under `"type": "TextBlock"`)	The desired text that prompts end-users to make a choice from among the buttons
Value of `"title":` (under the first `"type": "Action.Submit"` key)	The desired text on the first button
Value of `"id":` (under the first `"type": "Action.Submit"` key)	The desired ID for the first button
Value of `"title":` (under the second `"type": "Action.Submit"` key)	The desired text on the second button
Value of `"id":` (under the second `"type": "Action.Submit"` key)	The desired ID for the second button

Select Save in the Adaptive card designer, and then select Close.

The authoring canvas for this topic might resemble the following screenshot:
Save your topic.
Once you finish all changes to the agent, publish your agent again.

Example: Choice adaptive card

Use the Choice adaptive card to allow end-users to select one option from up to 10 presented as a list. This adaptive card uses a text block the WhatsApp end-user must select which then displays the choice set of options. The end-user must then select one of the options, and then select Send. Makers can invoke this adaptive card with the Ask with Adaptive Card functionality.

In the authoring canvas of the topic you want to add this adaptive card to, select the Add node icon in the desired location, and then select Ask with adaptive card.
Select the new Adaptive Card node to bring it into focus. Select the More icon for the node and select Properties.
On the Adaptive Card Node properties pane, select Edit adaptive card.

In the Card payload editor of the Adaptive card designer, copy and paste the following JSON code:

{
"type": "AdaptiveCard",
"$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
  {
    "type": "TextBlock",
    "text": "Pick a country:",
    "wrap": true
  },
  {
    "type": "Input.ChoiceSet",
    "choices": [
      {
        "title": "Falkland Islands",
        "value": "Falkland Islands"
      },
      {
        "title": "Singapore",
        "value": "Singapore"
      },
      {
        "title": "Norway",
        "value": "Norway"
      },
      {
        "title": "South Africa",
        "value": "South Africa"
      }
    ],
    "placeholder": "Select Country",
    "id": "countryChoice"
  },
  {
    "type": "ActionSet",
    "actions": [
      {
        "type": "Action.Submit",
        "title": "Submit Response",
        "id": "submitResponseId"
      }
    ]
  }
]
}

In the JSON, in the section with a type key of value Input.ChoiceSet, under "choices":, make sure you have the right number of choices.

For example, if you need seven (7) selectable choices presented in a list, under "choices":, there should be seven sets of choices, with each set comprised of a title and value key.

Make the following further changes to the JSON:

Change	To
Value of `"text":` (under `"type": "TextBlock"`)	The desired text that prompts end-users to display a list of options
Value of `"title":` (for each choice under `"type": "Input.ChoiceSet"` key)	The desired text describing or naming the listed option
Value of `"value":` (for each choice under `"type": "Input.ChoiceSet"` key)	The value assigned to the `Input.ChoiceSet.value`, which is then used for further processing
Value of `"id":` (under `"type": "Input.ChoiceSet"`)	The ID value for the choice set variable (named `countryChoice`, in the example). This ID value takes on the recorded `value` signifying the user's choice from the list. Note: This value should be in camelCase formal format.

Select Save in the Adaptive card designer, and then select Close.

The authoring canvas for this topic might resemble the following screenshot:
Select Save in the authoring canvas to commit your adaptive card changes to the topic.
When you finish all changes to the agent, republish the agent.

Example: Open URL adaptive card

Use the Open URL adaptive card to send an end-user to a website. Unlike the other two adaptive cards, the Open URL adaptive card can't be invoked by using the Ask with Adaptive Card functionality in Copilot Studio. Instead, you must attach this adaptive card to a message created by using the Send a message functionality.

In the authoring canvas of the topic where you want to add this adaptive card, select the Add node icon in the desired location, and then select Send a message.
In the new Message node, select Add > Adaptive card.
Select the new Media area of the message node. Then, select the More icon for the node and select Properties.

Note

Select the new Media area of the message node again if the Edit adaptive card button doesn't appear on the Adaptive Card properties pane.
On the Adaptive Card properties pane, select Edit adaptive card.

In the Card payload editor of the Adaptive card designer, copy and paste the following JSON code:

{
"type": "AdaptiveCard",
"$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
  {
    "type": "TextBlock",
     "text": "Click 'Ok' for weather information for Singapore.",
     "wrap": true
  },
  {
    "type": "ActionSet",
    "actions": [
       {
         "type": "Action.OpenUrl",
         "title": "Ok",
         "url": "https://www.msn.com/en-za/weather/forecast/in-Singapore"
       }
    ]
  }
]
}

Make the following changes to the JSON:

Change	To
Value of `"text":` (under `"type": "TextBlock"`)	The desired text that prompts end-users to open the website
Value of `"title":` (under `"type": "ActionSet"` key)	The desired selectable text that opens the website in a browser when selected
Value of `"url":` (under `"type": "ActionSet"` key)	The desired value of the website's uniform resource locator (URL)

Select Save in the Adaptive card designer, and then select Close.

The authoring canvas for this topic might resemble the following screenshot:
Select Save in the authoring canvas to commit your adaptive card changes to the topic.
When you finish all changes to the agent, republish the agent.

Configure user authentication by using phone numbers in WhatsApp

When you publish an agent to WhatsApp, you can choose whether to authenticate users. If you choose not to authenticate users, you don't need to take any further action.

If you choose to authenticate users, you have the following options:

Authenticate manually (see Authenticate manually)
Authenticate by using a phone number as a recognized WhatsApp ID (see Example: Authenticate with a phone number)
Authenticate manually and by using phone number recognition. Authenticate by using both methods for added security.

Important

The WhatsApp channel doesn't support authentication with Microsoft.

Example: Authenticate with a phone number

WhatsApp uses phone numbers as identifiers (IDs). When a maker selects phone number authentication, a backend API checks that the user’s WhatsApp phone number is in the list of authorized numbers in the database. Configure a trigger in Copilot Studio to send an HTTP request to the API, define the response schema, and set conditions to control the conversation flow based on user registration status.

Note

Make sure the backend server provides an API to validate if a given phone number is registered in the database.

In this example, the server provides the following API:

URI: /exists/_{phoneNumber}_

Response:

  {
      phone: string
      exists: boolean 
  }

Go to the Topics page for your agent.
Select Add a topic > From blank.
Select the Change trigger icon of the Trigger node, and then select A message is received.
Select the Add node icon under the trigger node and select Variable management > Set a variable value.
In the Set variable value node, select the Set variable field.
In the Select a variable window, select Create new.
In the Set variable value node, select the variable name in the Set variable field and then rename the variable name in the Variable properties pane.
In the Set variable value node, in the To value field, select the three dots (…).
In the Enter formula window, select the Formula tab.
Copy the following formula to the formula field, substituting <<BaseUri>> with the uniform resource identifier (URI) of the API, and then select Insert.

<BaseUri>/exists/"&System.Activity.From.Id
Select the Add node icon under the Set variable value node and select Advanced > Send HTTP request.
Select Record under Response data type.

Select Edit Schema and provide the response schema.

kind: Record
properties:
  exists: Boolean
  phone: String

For Save response as, create a new variable named apiResponse.
Select the Add node icon under the HTTP Request node, and select Add a Condition.
On the Condition node, select Select a variable > apiResponse.exists.
On the second input field, select Is equal to.
Under Enter or Select a value, type true.
Select the Add node icon under the All other conditions node, and select Send a message.
Write a message to display to unregistered users.

Note

You can customize the message sent to unregistered users. In this example, the message is Sorry, you are not registered.
Select the Add node icon under the Message node, and select Topic management > End all topics.
Select the Add node icon under the End all topics node, and select Topic Management > End conversation.
Select Save in the authoring canvas to commit your changes to the topic.
When you finish all changes to the agent, republish the agent.

After you publish the change, the system checks the phone number linked to the user's WhatsApp device. If the number isn't in the database, the system displays the message you configured as the unregistered message.

Disconnect an agent from a phone number

To disconnect your agent from the phone number configured for the WhatsApp channel, open the configuration panel and select Disconnect.

Limitations

The WhatsApp channel doesn't support uploading or downloading files.

Feedback

Was this page helpful?

Last updated on 2026-02-13

Share via

Publish an agent to WhatsApp

Set up your agent to use WhatsApp

Use supported Adaptive Cards in your agent's topics

Example: Interactive actions adaptive card

Example: Choice adaptive card

Example: Open URL adaptive card

Configure user authentication by using phone numbers in WhatsApp

Example: Authenticate with a phone number

Disconnect an agent from a phone number

Limitations

Feedback

Additional resources