Edit

Configure proactive engagement for messaging

Use this article to configure proactive SMS, MMS (preview), or WhatsApp (preview) engagements. Complete the shared messaging setup, and then follow the SMS, MMS (preview), or WhatsApp (preview) instructions for your message content.

Important

  • Proactive engagement in MMS and WhatsApp is a preview feature.
  • Preview features aren’t meant for production use and might have restricted functionality. These features are subject to supplemental terms of use, and are available before an official release so that customers can get early access and provide feedback.

Prerequisites

Review the shared prerequisites, consent requirements, and audience options in Set up proactive engagement. Then complete the required setup for the required channel:

Review consent support by channel before configuring proactive engagement.

Set up an outbound workstream

  1. Create a workstream by selecting the Outbound option and setting the type to Messaging. Then, select the channel:

    • For SMS and MMS, select SMS.
    • For WhatsApp, select WhatsApp.

    Learn more in Create and manage workstreams.

  2. Set up the outbound channel in the workstream:

  3. Set up the outbound behaviors for the selected channel.

  4. Configure work distribution, optionally add an AI agent to the workstream, and configure representative notifications. Ensure that the workstream has a default queue.

The system automatically configures the routing rules based on the proactive engagement settings. These rules appear under the Auto generated rules (advanced) section of the workstream.

To have an AI agent handle customer responses, add and configure the agent on the messaging workstream. The messaging engagement wizard doesn't provide a separate AI-agent selection or the voice Engagement type and Dialing modes controls.

Create a messaging proactive engagement

In the site map of Copilot Service admin center, go to the settings by using one of the following methods. Then, create a proactive engagement setting.

  • Select Productivity under Support experience. Select Manage for Proactive engagements, and then select New.
  • Select Workstreams under Customer support, select an outbound voice or messaging workstream, and on the workstream page, select New proactive engagement.

The Create new proactive engagement wizard guides you through the steps outlined in the following sections:

  • Audience
  • Details
  • Preferences
  • Message template configuration
  • Frequency limits
  • Summary

If you select Upload a file as the intake method, File upload follows Summary.

Note

Delivery windows and expiration dates can't extend more than 30 days into the future. If a request or uploaded record doesn't specify a delivery window, the system uses a 24-hour window that starts immediately, or at the requested earliest schedule date when it's a future date.

Audience

On the Audience page, configure how you source customers and lead the engagement.

  1. Under Select your audience, choose how to provide customer contact information:

    • Contact Center: If you select this option, choose one of the following intake methods:
      • Upload a file
      • CCaaS API
      • MCP (preview)
    • Conversational Journeys in Customer Insights: This option is available only if Customer Insights is enabled. Select if you want to create conversation journeys in Customer Insights.
  1. Select Next.

Details

On the Details page, configure the engagement identity, routing, and business unit.

  1. In Engagement details, enter the following information:

    • Name: A name for the proactive engagement. The service representative sees the name on the conversation form.
    • Description: Enter a description that helps service representatives understand the purpose of the engagement. The name and description are visible to representatives during the conversation.
    • Workstream: Select the outbound workstream. If you create the proactive engagement from within a workstream, this value is preselected.
    • Channel type: The channel used for the proactive engagement.

  2. Under Contact unique identifier, select the contact attribute to use as the unique identifier. The dropdown lists only those attributes that are marked as unique key eligible on the Contact table. The default is contactid. The system performs an update or insert using this identifier. If an incoming record matches an existing contact, the record is updated. Otherwise, the system creates a new contact. Select the correct identifier to prevent duplicate contact records.

    • If Dynamics 365 Contact Center is your system of record, use contactid (the Dynamics 365 contact GUID).
    • If you use an external system such as a CRM or MDM system, create a custom attribute on the Contact table to store your external identifier, and then select the custom attribute. By passing your external system's ID in the input, you can make sure duplicates aren't created and the data in the contact center stays updated.

  3. In Routing details, enter the following details:

    • Primary queue: Select a queue.
    • Fallback queue: The system populates the queue name based on the fallback queue set for the outbound workstream.
    • Skills: Select the skills required for the proactive engagement.

  4. The Business unit field is automatically set to the business unit of the user creating the engagement. The Owner field shows the owner that you can change if needed.

  5. Select Next.

Preferences

On the Preferences page, configure channel behaviors and throttling rules for the messaging engagement.

  1. Under Channel behaviors, configure the following settings:

    • First response timeout: Set how long to wait for the customer's first reply, in minutes, hours, or days. The default is 5 minutes. A reply received after this period might be handled as an inbound message without the original proactive engagement context.
    • Priority level: Select the priority for the engagement — Normal, High, or Critical. Priority determines which proactive engagement is processed first when multiple engagements compete for the same queue and skillset.
    • Message order: Select how messages within the engagement are processed:
      • Earliest Scheduled Date: Processes records that are close to the end of the messaging window first.
      • Last in First Out: Processes the most recent records first.
      • First in, First Out: Processes older records first.
      • Custom priority ascending: Processes records in ascending order based on a priority attribute specified in the contact list or API payload.
      • Custom priority descending: Processes records in descending order based on the priority attribute.

  2. Under Rules, select Use rules to set throttling and pacing rules for the engagement. Configure conditions based on the following parameters:

    • Average wait time: The average amount of time it takes for customers to connect to representatives.
    • Escalation count: The total number of escalations made from the AI agent.
    • Open concurrent escalations: The total number of open escalations that aren't resolved.

    For each rule, specify the threshold value, the time window (In the last), and the Decrease concurrent calls by percentage. In a messaging engagement, this setting controls the number of concurrent messages when the condition is met.

  3. Select Next.

Message template configuration

On the Message template configuration page, configure the content for the channel selected by the messaging workstream.

For SMS and MMS text, use the personalization menu to insert contact details, such as first and last names, phone number, email, postal code, country/region, city, and street.

Use the Preview pane to view how the message might appear on a mobile device. The actual appearance can vary by channel, provider, and device.

SMS

  1. Under Templates, turn on Enable message templates for this workflow. This setting is on by default when you use Upload a file as the intake method.

    For engagements triggered through the CCaaS API or MCP, you must configure a template. The Message parameter can override the rendered template text, but a template is still required.

  2. In Message, compose the message to send to customers. You can enter up to 1,000 characters and use personalization to add contact details.

  3. Review the preview, and then select Next to configure frequency limits.

MMS (preview)

Important

  • This is a preview feature.
  • Preview features aren’t meant for production use and might have restricted functionality. These features are subject to supplemental terms of use, and are available before an official release so that customers can get early access and provide feedback.

The selected provider and phone number must support MMS. You can send a message with text and media attachments or with media only.

  1. Under Templates, turn on Enable message templates for this workflow. This setting is on by default when you use Upload a file as the intake method.

    For API requests that provide content and attachments through MessageAttributes, you don't need to configure an SMS template. Learn more in CCaaS_CreateProactiveDelivery API.

  2. Under Message type, select MMS.

  3. Optionally, compose a message of up to 1,600 characters. You can use personalization to add contact details.

  4. Under Multimedia, select Add media. Select an existing asset from the media library, or select Add file to upload an asset. You can add up to 10 attachments.

    Important

    Media files uploaded for MMS are publicly accessible through a content delivery network (CDN). Don't upload confidential or sensitive files.

    The editor uses the Dataverse file records for the selected assets. You don't need to enter the record IDs. Learn more in Get a media attachment ID.

    For supported formats, text-length counting, and Twilio and Infobip media size limits, learn more in MMS limits.

  5. Review the preview, and then select Next to configure frequency limits.

WhatsApp (preview)

Important

  • This is a preview feature.
  • Preview features aren’t meant for production use and might have restricted functionality. These features are subject to supplemental terms of use, and are available before an official release so that customers can get early access and provide feedback.

Use an approved WhatsApp message template for proactive engagements. Free-form outbound WhatsApp messages aren't supported.

Before you configure the engagement, prepare an approved template in WhatsApp Manager for the account associated with the workstream. Learn more in WhatsApp template messages.

The proactive engagement editor defines the message content inline and doesn't use templates configured in the workstream Behaviors settings. You don't need to complete the workstream template setup for this editor.

[!NOTE] Saving the proactive engagement doesn't submit the WhatsApp template for approval or change its approval status in WhatsApp Manager.

  1. Enter the approved template name, select the language, and define the content to match the template in WhatsApp Manager.

  2. If the template contains placeholders, specify a value for each required parameter.

  3. Review the preview, and then select Next to configure frequency limits.

Frequency limits

On the Frequency limits page, complete the following steps:

  1. Select Use frequency limits to turn on frequency controls, and then enter values for:

    • Maximum engagements per day: The maximum number of times you can reach a contact in a day across all channels.
    • Maximum engagements per week: The maximum number of times you can reach a contact in a week across all channels.

  2. Under Time zones, choose the time-zone basis for the schedule:

    • Use customer's local time zone when available (defaults to UTC if not available): Use the customer's time zone, with UTC as the fallback when it isn't available.
    • Use Coordinated Universal Time (UTC): Use UTC regardless of the customer's time zone.

    If you provide contact time-zone values, supply them explicitly in the uploaded file or API payload. The system doesn't auto-detect or geo-infer time zones. In an API payload, use a Windows standard time-zone name, such as Pacific Standard Time, or a Dataverse time-zone code as a string, such as "35". Display names and IANA time-zone names aren't accepted. See the Contact object.

  3. Select Next.

Summary

Review all settings on the Summary page, and select Create.

File upload

If you select Upload a file as the intake method, the File upload step appears where you can upload your contact list. You can skip this step to upload the file at a later time.

Supported file formats: CSV (.csv) only.

File upload constraints:

  • Maximum file size: 10 MB
  • The file must include all required columns; extra columns are optional
  • For voice engagements, use the same value for the ID column to link contacts in the same account. Contact chaining doesn't apply to messaging engagements.

Required columns:

  • UniqueIdentifier: The value used to identify and update or insert the contact record. Must correspond to the Contact unique identifier attribute selected in the Details step.
  • MobilePhoneNumber, BusinessPhoneNumber, or HomePhoneNumber: For voice engagements, at least one phone number column is required, and you can include multiple phone number columns. For messaging engagements, MobilePhoneNumber is required.

Optional columns:

Named fields are columns whose names correspond to attributes on the Contact table. Values in these columns are used to create or update the contact record during processing. Any extra columns that don't match a Contact attribute are treated as pass-through data and are available on the representative desktop during the conversation.

Data entered in the Priority column is used for custom prioritization when the call order or message order is set to Custom priority ascending or Custom priority descending.

To download a sample file that contains the required columns and formatting, select Download sample.

Processing behavior: Records are processed immediately when the file upload begins.

Note

The uploaded file isn't stored in any form and can't be downloaded. To access delivery results and records, query the relevant tables in Microsoft Dataverse directly. Learn more in Use proactive engagement tables for reporting.

Upload a file to an existing engagement:

To add a new file to an engagement that you already created, go to Copilot Service admin center > Productivity > Proactive engagements. Select the engagement, and then select Run from file. The system adds the new file to the existing pending deliveries.

Manage messaging engagements

Messaging engagements support one contact per request. Contact chaining and configurable reattempts are available for voice engagements only. Automatic service retries for messaging are separate from configurable reattempts.

To cancel messaging engagements through the CCaaS APIs:

Cancellation doesn't recall messages that are already sent, and work that already started might continue.

To monitor delivery results, see Outcomes for proactive engagement and Proactive engagement tables.

Set up proactive engagement
Configure proactive engagement for voice
Configure a WhatsApp channel through Azure Communication Services
Configure an SMS channel for Infobip
Manage consent for proactive engagement
Use CCaaS_CreateProactiveDelivery API
Best practices for proactive engagement campaigns
Proactive Outbound dashboard

  • Last updated on