Microsoft Dynamics 365 Integration

Overview #

The Dynamics 365 integration lets your team open WhatsApp conversations directly from a Dynamics Contact record. In short, it provides:

• Open Spoki Chat from any Contact — a single button on the Dynamics Contact form opens an embedded WhatsApp conversation, pre-filtered to that contact.
• Embedded chat experience — read history and send replies inside a modal iframe, right on the Contact form, or pop the chat out into its own window.
• Automatic contact matching — Dynamics contacts are matched to Spoki contacts by phone or email, so conversation history stays tied to the right person.
• Automatic user provisioning — Dynamics users are mapped to Spoki chat operators on first use; no manual user setup required.
• Optional contact sync — bind Dynamics marketing lists to Spoki lists for ongoing two-way contact synchronization (see Contact Sync).

The integration is read-only on your Dynamics environment. Spoki can never modify, delete, or create Dynamics records — it only reads a contact’s phone, email, and name when you click the chat button.

When to Use #

Use this integration when your team works primarily inside Dynamics 365 and needs to reach contacts on WhatsApp.

Use Case	Example
Sales outreach	Message a prospect on WhatsApp straight from their Contact record
Customer support	Open the existing conversation history while reviewing a contact
Follow-ups	Reply to a lead without leaving the Dynamics Sales Hub
Account management	Keep one source of truth for contacts across Dynamics and Spoki
Field/mobile teams	Use the embedded chat from the Dynamics mobile app

Prerequisites #

Before using the Dynamics 365 integration, you need:

1. A Spoki account with an active WhatsApp Business number.
2. A Microsoft Dynamics 365 environment with the Contact entity (Sales, Customer Service, or any model-driven app).
3. Admin rights in Dynamics — to install the solution, edit the Contact form, and publish changes.
4. Admin rights in Spoki — only the account owner can connect the integration and retrieve the signing key.

Spoki Contacts are WhatsApp-keyed and require a phone number. A Dynamics contact must have a mobile phone or business phone populated to open a chat — email alone is not enough.

Setup #

Setup is a one-time process per Dynamics tenant, in four steps.

Step 1 — Connect your Dynamics 365 tenant #

In Spoki, go to Integrations → Microsoft Dynamics 365 and connect the integration.

1. You’ll be redirected to Microsoft to authorize Spoki (OAuth 2.0 via Microsoft Entra ID).
2. Sign in with a Dynamics admin account and approve the requested permissions.
3. On success, you’re returned to the Spoki integration page and the connection is active.

“By connecting Dynamics 365, you will be able to view the Spoki chat directly in the Dynamics CRM contact form. You will be redirected to Microsoft to authorize Spoki.”

Step 2 — Install the Spoki solution #

From the integration page, click Install Spoki Dynamics 365 to download the managed solution package (SpokiDynamicsApp.zip).

• Import it into Dynamics via Power Apps Maker → Solutions → Import (Soon ⇒ from Microsoft AppSource).
• The solution adds the SpokiContactCard control (namespace Spoki) to your environment.

Step 3 — Add the control to the Contact form #

In the Power Apps form designer, edit the Contact main form:

• Add the SpokiContactCard component to the form where you want the chat panel to appear.
• Save and Publish the form.

Step 4 — Install the signing key #

The signing key authenticates every chat request sent from your Dynamics tenant to Spoki. Copy it from Spoki and paste it into the control.

On the Spoki integration page, copy the Spoki signing key, then in Dynamics:

#	Step	What to do
1	Open the Contact form	In Power Apps form designer, edit the Contact form where the Spoki PCF is installed.
2	Select the SpokiContactCard control	Click the embedded control to open its properties panel on the right.
3	Paste the key	On the right panel, paste the signing key value into the spokiSigningKey property.
4	Save and publish	Publish your changes so every user in your organization gets the update.

The signing key is per-tenant. It is derived from a Spoki master secret that is never exposed — so even if the key leaks, only your tenant is affected. Anyone with Spoki account-owner access can re-fetch it at any time.

Using the Embedded Chat #

Once setup is complete, open any Contact in Dynamics 365. The Spoki card appears on the form.

Open Spoki Chat #

Click Open Spoki Chat. What happens:

• Spoki reads the contact’s phone/email and name from the record.
• It matches (or creates) the corresponding Spoki contact and loads the WhatsApp conversation.
• The chat renders embedded in an iframe directly on the Contact form.
• The microphone permission is requested up front so WhatsApp voice calls work inside the chat.

Pop out the chat #

Click WhatsApp By Spoki ↗ in the chat toolbar to open the same conversation in a separate, correctly-sized browser window — handy for multitasking while you browse other records.

Close the chat #

Click Close to collapse the chat and return the card to its initial state.

The conversation is the same whether viewed embedded, popped out, or inside the main Spoki app. All three share one history.

Contact Matching & Data #

What Spoki reads from Dynamics #

When you click Open Spoki Chat, Spoki reads only these fields from the Contact record:

Dynamics field	Used for	Required
mobilephone	Primary phone for WhatsApp matching	One phone required
telephone1	Fallback business phone	—
emailaddress1	Email matching (secondary)	No
firstname	Contact’s first name	No
lastname	Contact’s last name	No

Spoki also reads the email/username of the Dynamics user who clicked the button (for access control and audit). No other Dynamics field or entity (Opportunities, Cases, Accounts, etc.) is ever read.

How matching works #

• Phone takes priority: mobilephone is used first, then telephone1.
• The phone is normalized (whitespace, parentheses, and dashes removed) before matching against your Spoki contacts.
• If no Spoki contact exists, one is created from the Dynamics data (phone, email, first/last name).
• If the contact has no phone, the chat cannot open — add mobilephone or telephone1 in Dynamics and try again.

User Access & Provisioning #

The Dynamics user who clicks the button is mapped to a Spoki user automatically.

• Existing Spoki users (matched by email within the account) keep their existing role and permissions.
• New users are auto-provisioned as a Chat Operator — never an admin.
• Cross-account safety: a real Spoki user belonging to a different account is never silently linked. Cross-account access remains invitation-only.
• Deactivation is respected: if an admin deactivates a Dynamics-provisioned user, that user cannot regain access by clicking the button again.

To grant a Dynamics user more than chat-operator access, invite them in Spoki (Users & Roles) using the same email they use in Dynamics.

Security & Privacy #

• OAuth 2.0 via Microsoft Entra ID — Spoki never sees your Microsoft password. Access and refresh tokens are stored encrypted and never exposed to the browser.
• Per-tenant HMAC signing — every chat request is signed; the backend verifies it against your tenant’s key, with a short timestamp window to block replay attacks. As an alternative, the control can authenticate with a Dataverse bearer token, validated server-side against your organization.
• Read-only on Dynamics — Spoki cannot modify, delete, or create Dynamics records.
• EU data residency — all processing for this integration happens on Spoki’s EU infrastructure (AWS Frankfurt, eu-central-1).
• Audit logging — each chat-open request (timestamp, organization, user, hashed phone) is logged for security forensics and retained for 90 days.

For full data-flow and disclosure details, see the Privacy paragraph for the Dynamics integration and https://spoki.com/en/security.

Examples #

Example 1 — Sales rep reaching a prospect #

Scenario: A rep opens a lead’s Contact record in the Dynamics Sales Hub and wants to send a WhatsApp message.

1. Open the Contact → the Spoki card shows Open Spoki Chat.
2. Click it → the embedded chat loads, filtered to the contact’s mobile number.
3. Type and send the message — it’s delivered via WhatsApp Business and the conversation is saved in Spoki.

Example 2 — Support agent reviewing history #

Scenario: A support agent wants the full WhatsApp history while reviewing a contact.

1. Open the Contact → click Open Spoki Chat.
2. Click WhatsApp By Spoki ↗ to pop the chat into its own window.
3. Browse other Dynamics records side-by-side while keeping the conversation open.

Example 3 — New contact created on first chat #

Scenario: A Dynamics contact exists but has no Spoki counterpart yet.

1. Click Open Spoki Chat on the Contact record.
2. Spoki creates a matching contact from the Dynamics mobilephone, email, and name.
3. The conversation opens; future chats reuse the same Spoki contact.

Best Practices #

1. Populate a phone number on every contact. WhatsApp needs a phone. Standardize on mobilephone (or telephone1) in your Dynamics data hygiene rules so reps never hit the “no phone” message.
2. Use international phone format. Store phones in full international format (e.g. +39 333 1234567). Spoki normalizes formatting, but the country code must be present to match the right WhatsApp number.
3. Keep emails consistent for user mapping. Auto-provisioning matches Dynamics users to Spoki users by email. Use the same primary email in both systems so roles and permissions line up.
4. Publish after every form change. Adding the control or pasting the signing key only takes effect after you Save and Publish the Contact form in Power Apps.
5. Grant roles deliberately. Auto-provisioned users get Chat Operator only. For team leads or admins, invite them explicitly in Spoki Users & Roles before they use the chat.
6. Re-fetch the key if chats stop authenticating. If chats suddenly fail to open with an auth error, re-copy the signing key from the Spoki integration page, re-paste it into the control, and publish.

FAQ #

Where does the chat appear? Embedded directly on the Dynamics Contact form, inside the SpokiContactCard control. You can also pop it out into its own browser window.

Can Spoki change my Dynamics data? No. The integration is strictly read-only — it reads phone, email, and name when you click the button, and nothing else. It cannot create, update, or delete any Dynamics record.

What if a contact has no phone number? The chat won’t open. Spoki contacts require a phone for WhatsApp. Add mobilephone or telephone1 to the Dynamics contact, then click the button again.

A contact has both a mobile and a business phone — which is used? mobilephone first, then telephone1 as a fallback.

Do I need to create Spoki users for everyone in Dynamics? No. Users are auto-provisioned as Chat Operators on first use. Only create/invite users manually when you need to grant a higher role.

Which permissions does the integration request? OAuth scopes to read your Dynamics organization (Dataverse) and to identify the signed-in user. No write scopes are requested.

What happens when I disconnect? The connection and its keys are removed on the Spoki side. You’ll also need to remove the installed solution from Dynamics manually. To reconnect later, you’ll repeat the full setup.

Is my data sent outside the EU? No. All processing for the Dynamics integration happens on Spoki’s EU infrastructure (AWS Frankfurt). WhatsApp message transport itself is handled by Meta’s WhatsApp Business API under Meta’s terms.

Why does the chat ask for microphone access? So WhatsApp voice calls work inside the embedded chat. The prompt rides your click on Open Spoki Chat. Denying it does not block messaging.

Can I also sync contacts between Dynamics and Spoki? Yes. Beyond the embedded chat, the integration supports binding Dynamics marketing lists to Spoki lists for scheduled, two-way contact synchronization with configurable direction and conflict resolution. Configure this from the integration’s sync settings.

The chat fails with an authentication error — what do I check?

The contact has a valid phone number.

The signing key in the control matches the current key on the Spoki integration page (re-copy and re-publish if unsure).

The Dynamics tenant is still connected in Spoki (re-run OAuth if it was disconnected).