Overview
Connect Voiceflow to Dynamics 365 Sales with API tools to capture confirmed enquiries, use authorized customer records and create assigned follow-up work. The tools call your CRM directly; credentials are stored in Voiceflow Secrets.
- Connect Dynamics 365 Sales — prepare account access and a tested customer lookup.
- Capture an enquiry — save confirmed details for your sales team.
- Recognize a customer — read the record authorized by your application.
- Update customer details — change a confirmed phone number and read it back.
- Create follow-up — save work linked to the customer and approved owner.
Studio
Use an editable test project, a CRM administrator and an application developer. The developer prepares trusted customer mappings for protected records and confirmed JSON payloads; the steps below name the values to obtain.
Code
Use Voiceflow APIs or CLI to create, execute and attach the same API tools. Your backend owns CRM authorization, customer identity and JSON construction. Test with records you can inspect before attaching tools to a customer-facing agent.
Connecting Dynamics 365 Sales
Prepare direct API access and a protected customer lookup.
Use the Dataverse environment backing Dynamics 365 Sales. An administrator must register a single-tenant Microsoft Entra application, create its application user in that environment and assign a custom security role. Grant Lead Create/Read, Contact Read/Write and Task Create/Read at the intended record access level. Linking the Task requires the applicable Append/Append To privileges; assigning another owner requires Assign and access to that user. Dataverse security roles govern these operations.
This recipe uses public-cloud server-to-server authentication, with the environment origin such as https://YOUR_ORG.crm.dynamics.com. The application user and role are required in each environment; an Entra client ID alone grants no CRM record access. Sales, Customer Service and Finance & Operations are different workloads. See single-tenant setup.
For a public capture-only agent, prepare the credential and capture payload variable, then continue to Capturing sales enquiries. Skip the customer lookup and Contact mapping. The lookup steps below are for the authenticated customer agent.
Prepare the lookup and credentials
Studio
Obtain the account and application setup
Ask the CRM administrator and application developer to complete the authorization above. Obtain the fixed CRM origin, restricted Secret dynamics_api_token, the approved owner ID and a test application URL. For a customer lookup, also obtain an authorized test login and Contact ID. For token renewal, obtain the worker owner and a successful renewal check on your test Environment; the readiness test must still pass after the first access token expires.
Create the protected variables
Open Agent studio, select the test project and intended Environment, then open More → Variables. Create dynamics_contact_id, dynamics_capture_payload, dynamics_phone_payload and dynamics_followup_payload with empty defaults. For the authenticated agent, have the developer supply the authorized mapping and prepared payloads on every turn/resume while retaining runtime credentials on the backend. The public capture-only agent supplies confirmed capture payloads without a Contact mapping. Do not accept browser overrides or ask the model to choose a record/owner.
Configure the customer lookup
In Agent → Global tools → + → API, create Find customer in Dynamics 365 Sales. Select GET and use https://example.crm.dynamics.com/api/data/v9.2/contacts({contact_id})?$select=contactid,firstname,lastname,emailaddress1,mobilephone, replacing only the example origin with the approved one. Add Authorization: Bearer {token} and Accept: application/json.
Bind credential and customer identity
Save the request and click the attached tool in Global tools. Under Input variables, click the token row, then select dynamics_api_token through Default value → Secrets. Open contact_id and select dynamics_contact_id through Default value → Variables. Click outside to save. Enabling a switch does not bind the input. Reopen each row to verify the selected reference.
Test the actual record
Open the saved API tool’s editor and click Run. In its test-input panel, choose the token Secret and enter the developer-approved test contact_id, then click Run again. These test values are separate from attached runtime defaults; the proxy does not populate this panel. Inspect contactid in the provider body and compare it with the intended CRM record. Use Capture response only for approved fields; a saved request or Secret does not verify record access.
Code
- In Microsoft Entra App registrations, register a single-tenant application. Retain the tenant ID and application/client ID; create a client secret under Certificates & secrets and retain its value in your server’s secret store.
- In the target environment’s Power Platform admin center, create an application user for that application and assign the custom role described above. Confirm its permitted records and approved owner IDs with the administrator.
- Acquire an access token from
https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/tokenusing form fieldsgrant_type=client_credentials,client_id,client_secretandscope=CRM_API_ORIGIN/.default. The renewal worker below implements this request. This S2S path does not use delegateduser_impersonationor an interactive user grant. Renew fromexpires_in; the client secret also needs its own expiry/rotation owner.
Use a Voiceflow bearer credential with the required project/Environment permissions. Keep it server-side. Set VF_TOKEN, PROJECT_ID, ENVIRONMENT and CRM_CONTACT_ID to your test resources; install the CLI if choosing CLI. CRM_CONTACT_ID is the authorized Contact/Person ID, not a new Lead ID.
Download and extract the direct CRM example bundle. It contains the tool definitions, payload builders, renewal worker and fixture tests. Run node --test direct-requests.test.mjs on Node.js 22 or later; these are local fixtures, not authenticated provider tests. Set CRM_API_ORIGIN to your approved CRM origin, then prepare the definitions locally:
Each definition fixes the provider host, method and fields. Write definitions use raw JSON body {payload}; the backend builder supplies that entire serialized value. No provider credential is embedded in these files. The Dynamics write definitions select only the returned fields needed for these recipes.
Create dynamics_api_token as a restricted Secret without defaultValue through POST /v2/stable/secret?projectID=$PROJECT_ID with body {"name":"dynamics_api_token","visibility":"restricted"} and the Voiceflow bearer header, or:
Save secret.id as SECRET_ID. The placeholder has no value. Set its explicit test Draft target using Secret value configuration. The renewal procedure below maintains this short-lived access token. Supply environmentAlias and versionVariant; omitting the target can write Main’s Published value.
Create the identity and payload variables before attachment. The API is POST /v2/stable/variable with the same project/Environment query and body {"name":"dynamics_contact_id","defaultValue":null,"color":"#515A63"}; repeat with each payload variable name. Through CLI:
Repeat for dynamics_capture_payload, dynamics_phone_payload, dynamics_followup_payload with empty defaults. For protected customer records, your authenticated proxy must use trustedDirectTurn on every turn and resume, strip browser variables/state and retain the runtime session key. An initial launch mapping alone is insufficient.
Save each returned apiTool.id separately. Set API_TOOL_ID to the lookup’s ID for its test, and retain it as LOOKUP_TOOL_ID for later readback. List its inputs with GET /v2/stable/api-tool-variable?apiToolID=$API_TOOL_ID&projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT, or vf api-tool variable list --api-tool-id "$API_TOOL_ID" --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --output-format json. Match variables[].name to id for attachment.
Save the lookup inputs:
Require success: true, error: null, truncated: false, provider output.status: 200 and the expected output.body.contactid. Standalone execution uses the selected Environment’s Draft; it does not attach or publish the tool.
Keep the access token current
These OAuth recipes use fresh HTTP Chat execution contexts. Stored Secret updates do not refresh the Secret snapshot of an already-open persistent executor. A persistent Voice/Socket transport needs its own verified token-broker or reconnect lifecycle; this recipe does not establish uninterrupted coverage for it.
Access tokens expire. Assign an application developer to run oauth-renewal.mjs on a supervised server worker. Before customer use, verify a new request and the same continuing conversation across a token expiry, monitor failed writes and renew the correct Secret values for every Draft/Published version you use. A Draft token does not supply a Published agent.
Studio
Obtain confirmation from the application developer and worker owner that dynamics_api_token is populated on your test Draft and scheduled for renewal. Before publishing, have them add the intended Published target and prove the lookup after renewal. You do not need to implement the worker in Studio.
Code
Download the worker and its fixture tests. On Node.js 22 or later, configure these server-only values; adjust the provider origins to your account:
Replace every target ID with the created resources. The worker renews at the provider and writes only the explicit target through /v1/stable/secret/SECRET_ID/value; it logs expiry metadata, not tokens. Its Voiceflow credential needs Secret update permission. A failed multi-target run can leave earlier targets updated: inspect each target before retrying.
Run node oauth-renewal.mjs --loop under your existing supervisor with restart/backoff and health alerts. It schedules renewal before expiry and caps the interval at 30 minutes. Use one worker per credential/target set. For a reviewed Published agent, deliberately add its versionVariant: "published" target as well as any Draft target. Test after publication/revert/discard, which can change version overrides. This is credential maintenance, not agent publication.
Read Secret version behavior and the provider’s token contract before changing targets. Never expose the provider client secret, refresh token or Voiceflow management credential to the model or browser.
Use CRM tools in an agent
Start with an agent that already handles a Draft conversation in the selected test Environment. Keep its existing Playbooks or Workflows registered while adding these tools.
Studio
Open the attached customer lookup
In Agent → Global tools, open Find customer in Dynamics 365 Sales. Keep the lookup on the authenticated customer agent. The separate public capture-only agent gets only its create tools; a saved API request in Tools alone is not an agent attachment.
Set the Trigger and provided inputs
Set Trigger to “Find the signed-in customer’s contact details when they ask about their profile.” Keep token bound to the Secret and contact_id to dynamics_contact_id. For writes, bind the complete payload from the backend variable named in that capability. The agent collects the customer’s request, not credentials, CRM IDs or raw JSON.
Test the question through your application
Use the authenticated test application and ask “What phone number do you have for me?” Inspect the tool call and the approved returned field before the agent answers. Repeat without a permitted mapping: the backend must stop the private read and the agent must use general help. API-editor Run tests the request separately.
Code
Attach the saved lookup to the authenticated agent with target: {"global":true}; use {"playbookID":"YOUR_PLAYBOOK_ID"} to restrict a read to one Playbook. Set the attachment’s description to “Find the signed-in customer’s contact details when they ask about their profile,” keeping token and contact_id as provided defaults. Each write uses its own saved tool ID, input IDs, description and backend-prepared payload binding. The complete attachment commands are in Attach tested tools to an agent below.
Compile the Draft, then send “What phone number do you have for me?” through the authenticated application. Inspect the actual tool call, current result and answer. Test a missing/foreign mapping and a later-turn override. For a first enquiry, use trustedEnquiryTurn with a separate capture-only agent; protected customer tools use trustedDirectTurn on every turn/resume. A Trigger describes selection; the backend enforces access and confirmation.
For API-tool Capture response, use contactid for the lookup, leadid for a Lead and activityid for a Task. The path starts in the provider JSON, without the standalone output.body prefix. Create any output variables with empty defaults using the variable setup above; keep returned IDs separate from dynamics_contact_id.
Capture paths are relative to the tool’s current response, not the standalone output envelope. Captures can retain an earlier value after a failure or missing field; a retained ID alone is not a success check. Use the current result and the capability’s completion check before answering, and clear retained outputs before a new attempt when your workflow relies on them.
Code
Attach tested tools to an agent
Bind protected inputs, compile and test a conversation after standalone execution.
Save this attachment as attachment.json, replacing the resource and input IDs with those returned above:
For a write, add the payload input using its returned input ID and defaultValue: "{dynamics_capture_payload}", "{dynamics_phone_payload}" or "{dynamics_followup_payload}" for that tool. Include contact_id only on tools whose schema declares it. Defaults are protected server-supplied values; do not leave IDs, credentials or full JSON payloads to model selection.
POST the attachment to /v2/stable/tool with the project/Environment query and Voiceflow bearer header, or:
Resolve unresolvedReferences. Compile, exercise a conversation and inspect the resulting CRM record before publishing the reviewed Environment. Compilation does not publish. Verify that your proxy resets protected variables on later turns, including resumes, and that unprepared payloads cannot execute a write.
Rotate or stop account access
Remove credentials deliberately without deleting CRM records.
Disable affected tools before revoking access. Stop the renewal worker, disable the Dataverse application user and review all Secret targets. Clear obsolete Secret values only after checking other tools and versions. Revoking authorization does not delete records already created.
Capturing sales enquiries
Save confirmed details for your sales team.
A first enquiry does not require an existing CRM Contact. For public prospects, use a separate capture-only agent with just these create tools and the backend’s trustedEnquiryTurn boundary. Keep customer lookup, update and linked follow-up tools on the authenticated agent.
Apply your qualification policy, then ask the customer to confirm the details and follow-up request. The qualification Guide explains that broader journey; a CRM write does not qualify the customer by itself.
Create one Lead using firstname, lastname, emailaddress1, companyname and the enquiry subject. Bind ownerid@odata.bind to /systemusers(APPROVED_USER_UUID) in the prepared payload. Include any environment-required custom columns. The tool sends Prefer: return=representation, so require HTTP 201 and retain leadid. Creating a Lead does not qualify it into an Opportunity. Verify the Lead columns and Dataverse record creation.
In the conversation: Set the capture tool’s Trigger to recording a confirmed sales enquiry when dynamics_capture_payload is ready. Let the agent gather the enquiry details; the backend validates confirmation, selects the approved owner and supplies the complete payload. Use the current saved record ID before acknowledging capture; a rejection must not produce a success message. Test a demo request with missing details and then confirmed details; verify that only the confirmed request creates the intended record.
Save the confirmed enquiry
Studio
Prepare the reviewed request
Have your developer use capturePayload in the request builders to populate dynamics_capture_payload from confirmed, validated fields and the approved owner. Require a recorded confirmation, not a model assertion.
Add the capture request
Create an API tool with POST https://example.crm.dynamics.com/api/data/v9.2/leads?$select=leadid,subject,firstname,lastname,emailaddress1,companyname,_ownerid_value and the credential header from setup. Add Content-Type: application/json and Prefer: return=representation. Use Body → Raw → JSON with the complete input {payload}; do not interpolate customer text into a quoted JSON template.
Bind and test the write
In the attached tool’s Input variables, bind token → Default value → Secrets → dynamics_api_token. Open payload and bind Default value → Variables → dynamics_capture_payload. Click outside and reopen to check. Open the API tool editor’s Run panel. Select the token Secret and paste the developer-prepared complete JSON string in payload. Click Run and inspect the saved Lead. Retain its IDs; do not announce success from HTTP status alone.
Code
Select .capture from tools.json into tool.json, then create it and retain its new apiTool.id as CAPTURE_TOOL_ID. Set API_TOOL_ID to that ID.
Use the request builders on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as prepare.mjs and run node prepare.mjs to write inputs.json:
The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied fixture tests exercise this boundary.
Require the Voiceflow execution checks from setup and the provider result described above. Keep output.body.leadid with the request.
Inspect the saved CRM record and its owner before confirming completion. A write timeout is ambiguous: reconcile the existing record and execution evidence before retrying. Creation is not an idempotent upsert. It does not send a customer email, book a meeting or create a qualified opportunity.
Recognizing returning customers
Use only the customer record authorized by your application.
Customer identity comes from your application sign-in and server-side CRM mapping. A typed email, a CRM ID suggested in chat or provider account authorization is not customer authentication. Use the tested lookup after the proxy has reset the protected mapping for this turn.
The GET uses $select to retrieve contactid, firstname, lastname, emailaddress1 and mobilephone. Require HTTP 200 and the expected contactid; a valid application token does not prove access to this particular record. Customer sign-in and the application’s Contact mapping remain separate from the Dataverse application user.
In the conversation: Set Find customer in Dynamics 365 Sales to run when the signed-in customer asks about their saved profile. Provide dynamics_contact_id from the authenticated application and the token from Secrets; neither is collected by the agent. Answer from approved fields in the current matching record; failed or empty reads use general help. Test “What phone number do you have for me?” plus a missing mapping and a later-turn override; no private data may escape the permitted record.
Use the authorized record
Studio
Check the supplied mapping
Have the application developer demonstrate that dynamics_contact_id is rebuilt from the authenticated server-side map on every turn/resume and client runtime credentials stay on that backend. The lookup input must remain bound to that variable.
Run the customer question
Use the provided authenticated test application with an authorized test customer, then ask for another customer’s record and attempt a later-turn variable override. Neither may expose it. Test a missing mapping and fall back to general help.
Use only the approved result
Inspect the actual response before configuring Capture response. Verify contactid and the fields approved for this customer. Do not turn a failed lookup into automatic record creation.
Code
Set API_TOOL_ID to the saved LOOKUP_TOOL_ID. Authorize the customer and record again, prepare inputs.json with the server-mapped ID as in setup, then execute that lookup. Check the provider ID and permitted fields before returning an answer.
trustedDirectTurn discards browser variables/state and resets the Contact ID and every payload variable; integrate it behind your application authentication on all supported runtime actions. Its allowlist covers launch/text only. Additional actions require their own audited boundary. Missing mappings must fail before the tool executes; never use a shared customer ID as a default.
Updating customer details
Save a confirmed phone change and verify persistence.
Confirm the requested number and authorize the same customer before changing it. This recipe accepts international phone strings matching ^\+[1-9][0-9]{7,14}$; it does not accept free-form text or additional fields.
Use PATCH with If-Match: * to change only mobilephone on the authorized Contact. This enforces update-only: a missing/deleted Contact must fail instead of creating a replacement. This is the mobile field, distinct from telephone1. With Prefer: return=representation, require HTTP 200 and inspect the returned Contact; then repeat the lookup and compare mobilephone. Without that preference a successful Dataverse update can return HTTP 204 with no body. See Contact fields and update-only requests.
In the conversation: Call the phone-update tool only after the backend supplies a confirmed dynamics_phone_payload, then run the lookup again. Let the agent collect the proposed number; the application owns validation, customer identity and the complete write payload. Use the current readback to confirm the same record changed; reconcile uncertain writes before retry. Test an unconfirmed change and a confirmed number; the first must not write, and the second must preserve the authorized record.
Save and read back the change
Studio
Prepare the permitted change
Have the developer populate dynamics_phone_payload using phonePayload with the authorized Contact/Person ID and confirmed number. Reject malformed numbers before execution.
Configure the update tool
Create an API tool with PATCH https://example.crm.dynamics.com/api/data/v9.2/contacts({contact_id})?$select=contactid,mobilephone, the setup credential header and Content-Type: application/json plus Prefer: return=representation and If-Match: *. Set Body → Raw → JSON to {payload}. Bind token to the Secret, contact_id to the protected identity variable and payload to dynamics_phone_payload using each row’s Default value.
Verify persistence
In the API editor’s Run test panel, choose the token Secret, enter the approved contact_id and paste the complete prepared payload. Run the update, inspect provider errors and repeat the lookup test for that same ID. Then exercise the change through the provided authenticated application and inspect Transcripts. Compare mobilephone with the confirmed change and open the CRM record. A failed read does not prove the write failed.
Code
Select .phone from tools.json, create the new API tool and retain its ID as PHONE_TOOL_ID. Set API_TOOL_ID to it. Use the actual mapped ID in both the prepared payload and execution input:
Use the request builders on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as prepare.mjs and run node prepare.mjs to write inputs.json:
The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied fixture tests exercise this boundary.
Check the provider result, then set API_TOOL_ID back to LOOKUP_TOOL_ID, prepare lookup inputs and re-read that same record. Compare output.body.contactid and the saved phone field. On a timeout, reconcile this read before choosing whether to retry the write.
Creating assigned follow-up
Link the requested work to the customer and approved owner.
Create a Task only after the customer has requested follow-up. The administrator supplies an active permitted owner ID and verifies assignment permissions. This is a recorded work item, not a live human conversation or a guarantee that someone has contacted the customer.
Create a Task with subject, description, scheduledend and the approved owner. The helper writes regardingobjectid_contact_task@odata.bind: "/contacts(CONTACT_UUID)" and ownerid@odata.bind: "/systemusers(USER_UUID)". It treats dueDate/dueTime as UTC; convert the customer’s agreed local time first. Require HTTP 201 with activityid, then inspect the Task’s regarding Contact, owner and due time. See Task relationships.
In the conversation: Set the follow-up tool’s Trigger to a requested follow-up when dynamics_followup_payload is ready. Let the agent collect the subject and agreed UTC date/time; the backend supplies the approved Contact link, owner and confirmed payload. Use the current work-item ID and saved owner/date before acknowledging the request; a saved task is not a delivered message. Test a confirmed follow-up and a rejected write; only the saved, correctly linked work may be reported as recorded.
Record the assigned work
Studio
Prepare the linked request
Have the developer call followUpPayload with the authorized customer record, approved owner, confirmed subject and agreed due date/time. Obtain dynamics_followup_payload; the customer/model must not choose a CRM owner ID.
Configure and bind the follow-up tool
Create an API tool with POST https://example.crm.dynamics.com/api/data/v9.2/tasks?$select=activityid,subject,scheduledend,_ownerid_value,_regardingobjectid_value, the setup credential header and Content-Type: application/json plus Prefer: return=representation. Set Body → Raw → JSON to {payload}. Bind the token Secret and the payload row to dynamics_followup_payload through Default value.
Check the assigned record
In the API editor’s Run panel, select the token Secret and paste the complete confirmed payload. Run once and inspect the returned Task ID and open that record in the CRM. Confirm its linked customer, intended owner, UTC due time and request details; retain the customer-to-work-item mapping.
Code
Select .followup from tools.json, create the tool and retain its ID as FOLLOWUP_TOOL_ID. Set API_TOOL_ID to it, then prepare:
Use the request builders on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as prepare.mjs and run node prepare.mjs to write inputs.json:
The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied fixture tests exercise this boundary.
Require the Voiceflow execution checks and the provider result described above. Retain output.body.activityid and inspect the corresponding CRM record’s customer/owner/date before reporting completion. Retry only after reconciling an uncertain create; an authentication failure and a lost successful response need different handling.
Diagnose a rejected or uncertain request
Separate credential failures, record access and writes whose outcome is unknown.
- 401 / invalid token: check the Secret target and renewal worker before acquiring another token.
- 403 / permission failure: have the administrator inspect object, field, record and assignment access in the selected CRM account. A token or successful read does not establish write access.
- Validation or duplicate error: inspect the provider body and administrator-required fields. Do not treat a Voiceflow HTTP 200 as provider success.
- 429: respect the provider’s retry/reset information and review API usage; do not loop writes.
- Timeout or lost response: inspect the CRM and retained request/record IDs before retrying. The write may already have completed.