Edit

Use CCaaS_CreateProactiveDelivery API

You can use the CCaaS_CreateProactiveDelivery API to initiate proactive outbound voice calls and SMS messages to customers through the Proactive Engagement service.

Important

  • If an organization is using the CCaaS_CreateProactiveDelivery API to initiate an outbound voice call or SMS message, the organization is responsible for consent management, including the manual updating of "don't call lists" for setting quiet hours for customer contact. Make sure that the following conditions are met:
    • Consent is obtained before contacting customers.
    • Customers are contacted during permitted hours only.

Prerequisites

  • You must have the Omnichannel agent or Omnichannel supervisor role to call this API.
  • Proactive engagement is configured. Learn more in Configure proactive engagement.

Request details

  • URL: https://<orgurl>/api/data/v9.2/CCaaS_CreateProactiveDelivery
  • Method: POST
  • Version: 1.0
  • OData Operation: Action
  • OData Type: Unbounded
  • Request Authorization: Required. Must contain a valid Microsoft Entra ID Bearer token for the user making the API call. This token must be issued from the same Microsoft Entra ID tenant as the Customer Service instance.

Request headers

Key Type Required Channel Description
ApiVersion String Yes Both The CCaaS API version.
ProactiveEngagementConfigId String Yes Both ID of the Proactive Engagement Configuration to use. It also specifies the dial mode type, workstream, and outbound profile to use. To get this ID, do the following steps:
  1. Go to Power Apps and select the required environment.
  2. Select Tables > Proactive Engagement Configuration.
  3. Select the ID of the required record.
RequestId String No Both Attribute to pass to track the request from a source system.
Priority String No Both Defines the priority value of the request.
Contacts JSON array of Contact objects Yes Both Specifies one or more contacts (up to 5) on this request. At least one phone number per contact is required.
Windows JSON array of Window objects No Both Specifies the valid time periods when the outbound call or SMS can be placed. If not provided, the system defaults to a 24-hour window starting immediately (from current time until 24 hours later).
Message String No SMS Message content to be delivered to the contacts. Can be used only for SMS proactive configuration. Message is generated from the template by default. If the parameter is provided, it overrides the template.

Contact object

Key Type Required Channel Description
uniqueIdentifier String Yes Both Unique identifier of the contact. Can be a ContactId or an external ID.
firstName String Yes Both First name of the contact.
lastName String Yes Both Last name of the contact.
mobilePhoneNumber String Yes Both Mobile phone number of the contact.
businessPhoneNumber String No Voice Business phone number of the contact.
homePhoneNumber String No Voice Home phone number of the contact.
email String No Both Email address of the contact.
postalcode String No Both Postal code of the contact.
state String No Both State of the contact.
country String No Both Country/Region of the contact.
addressline String No Both Address line of the contact.
city String No Both City of the contact.
timezone String No Both Time zone of the contact. Must be a value from the Dynamics 365-approved list.
inputAttributes JSON object of key-value strings No Both Variables that can be referenced within Copilot agent flows to customize behavior, drive conditional logic, or retrieve personalized information from Dataverse records.
windows JSON array of Window objects No Both Contact-level time windows that override the top-level Windows for this specific contact.

Note

At least one of mobilePhoneNumber, businessPhoneNumber, or homePhoneNumber is required per contact for voice. For SMS, only mobilePhoneNumber is allowed.

Windows object

Key Type Description
Start String The beginning timestamp for this window. Must be specified in UTC in the yyyy-MM-ddTHH:mm:ss.fffZ format.
End String The end timestamp for this window. Must be specified in UTC in the yyyy-MM-ddTHH:mm:ss.fffZ format.

Sample requests

Voice request

{
  "ApiVersion": "1.0",
  "ProactiveEngagementConfigId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "RequestId": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
  "Priority": "1",
  "Contacts": "[{\"uniqueIdentifier\":\"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\"firstName\":\"John\",\"lastName\":\"Doe\",\"mobilePhoneNumber\":\"+15550100\",\"businessPhoneNumber\":\"+15550101\",\"homePhoneNumber\":\"+15550102\",\"email\":\"text@a.com\",\"postalcode\":\"25642\",\"state\":\"WA\",\"country\":\"USA\",\"addressline\":\"1234 227th PL SE\",\"city\":\"Seattle\",\"timezone\":\"(GMT-03:00) Brasilia\",\"inputAttributes\":{\"AppointmentTime\":\"10:00 AM\",\"CustomerNumber\":\"1234567\"},\"windows\":[{\"start\":\"2025-12-10T09:00:00Z\",\"end\":\"2025-12-10T17:00:00Z\"}]}]"
}

SMS request

{
  "ApiVersion": "1.0",
  "ProactiveEngagementConfigId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "RequestId": "d3e4f5a6-b7c8-9012-cdef-a12345678901",
  "Priority": "1",
  "Message": "Your appointment is confirmed for tomorrow at 10:00 AM. Reply STOP to opt out.",
  "Contacts": "[{\"uniqueIdentifier\":\"a58bc20c-69dd-5483-b678-1f13c3d4e580\",\"firstName\":\"Jane\",\"lastName\":\"Smith\",\"mobilePhoneNumber\":\"+15550200\",\"email\":\"jane.smith@example.com\",\"postalcode\":\"98101\",\"state\":\"WA\",\"country\":\"USA\",\"addressline\":\"5678 Main St\",\"city\":\"Seattle\",\"timezone\":\"(GMT-08:00) Pacific Time\",\"inputAttributes\":{\"AppointmentTime\":\"10:00 AM\",\"CustomerNumber\":\"7654321\"},\"windows\":[{\"start\":\"2025-12-10T09:00:00Z\",\"end\":\"2025-12-10T17:00:00Z\"}]}]"
}

Response

Response properties

Property Type Description
DeliveryId String (GUID) The unique identifier of the created first proactive delivery
DeliveryTaskId String (GUID) The unique identifier of the created proactive delivery task

Use CCaaS_CreateProactiveVoiceDelivery API
Use CCaaS_CreateOperation API
Use proactive engagement tables for reporting

  • Last updated on