Microsoft Teams Phone System Integration

Velaro integrates with Microsoft Teams Phone (calling-bot architecture via Microsoft Graph Communications APIs) to deliver screen pops on inbound calls, log call activity to your CRM, and let agents hold/resume/transfer/end a call from the Velaro sidebar. Setup has two parts: a one-time step Velaro's engineering team does once for all customers, and a per-customer walkthrough your own Microsoft 365 administrator completes in a short self-serve wizard.

See the Telephony & CTI Overview guide for how screen pop, call logging, and IVR hand-off work across all Velaro phone integrations — this guide covers Teams Phone-specific setup only.

---

Requirements

Requirement	Details
Microsoft 365 tenant ID	Your organization's Entra (Azure AD) directory ID
Teams Phone license	Teams Phone Standard (or Direct Routing) on the resource account used for calling
M365 global/Teams admin access	Required to grant admin consent and to create the resource account in Teams Admin Center
Graph application permissions	Calls.AccessMedia.All and Calls.Initiate.All, consented on Velaro's existing Graph app for your tenant

---

Setup — self-serve wizard

Go to Settings → Integrations → Microsoft Teams Phone → Start Setup. The wizard walks through the same steps documented below and saves your entries directly — no separate ticket to Velaro support is required for the Velaro-side configuration steps. The wizard is re-entrant: reopening it after initial setup offers Edit existing configuration or Start over, and never silently overwrites a working connection.

Step 1 — Tenant admin consent (customer action, ~2 minutes)

Teams Phone reuses Velaro's existing, already-live multitenant Graph app registration ("Velaro Outlook Email Integration", the same app the Outlook email-inbox integration uses) — you do not register a new Azure app. Velaro adds the two Teams-calling permission scopes to this one app; you only need to consent to them for your own tenant.

Have your Microsoft 365 admin open this URL (shown in the wizard) while signed in as a Global Administrator or Privileged Role Administrator for your tenant:

https://login.microsoftonline.com/common/adminconsent?client_id=c77a93cd-92a2-41e1-ad4d-c7cb54d674a3

Review the requested permissions and click Accept. This grants tenant-wide admin consent for whatever application permissions Velaro's app currently requests — including the two below once they're added on Velaro's side.

Step 2 — Confirm permissions were granted (customer action, ~1 minute)

In the Azure Portal (portal.azure.com) as your tenant:

1. Microsoft Entra ID → Enterprise applications → search for "Velaro Outlook Email Integration"

2. Open Permissions — confirm both of the following show a green "Granted for [your organization]" status:

- Calls.AccessMedia.All — required for Velaro's calling bot to be a controllable participant on any call at all; hold, resume, transfer, and end all depend on this

- Calls.Initiate.All — required for Velaro's bot to place outbound calls as your resource account

If either is missing, admin consent (Step 1) was not completed successfully — re-run the consent URL.

Step 3 — Create the Teams Phone resource account (customer action, ~10 minutes)

This step happens entirely inside your own Microsoft 365 tenant. Velaro cannot automate it — a resource account is a real, licensed object your tenant admin controls. In Teams Admin Center (admin.teams.microsoft.com):

1. Users → Manage resource accounts → + Add. Create an account (e.g. "Velaro Phone Bot") of type Call Queue or Auto Attendant is NOT what you want here — pick the plain resource-account type intended for a calling application/bot integration.

2. Assign the new resource account a Teams Phone Standard license (or Teams Phone Resource Account license, depending on your tenant's licensing) via the Microsoft 365 admin center (admin.microsoft.com → Users → Active users → the resource account → Licenses and apps).

3. Back in Teams Admin Center: Voice → Phone numbers → assign a phone number to the resource account (a Calling Plan number or a Direct Routing number, whichever your organization uses).

4. Voice → Calling policies → confirm the resource account's assigned calling policy allows both inbound and outbound calling.

5. Users (in Teams Admin Center, or Entra ID → Users in the Azure Portal) → open the resource account → copy its Object ID (a GUID). You'll need this in Step 4.

Which Teams voice license do you need?

Microsoft offers three ways to license Teams voice for the resource account above:

• Calling Plan - Microsoft-billed per-minute or unlimited plan bundled with the license. Simplest to set up; no separate carrier/SIP account needed.
• Direct Routing - you bring your own SIP trunk/carrier. Most flexible if you want to keep an existing carrier relationship or existing numbers, but requires a Session Border Controller (or SBC-as-a-service provider) already configured on your side - the most setup of the three options.
• Operator Connect - a Microsoft-certified carrier manages the connection instead of a self-hosted SBC. Billing is per-number through the carrier - a commonly reported gotcha is that carriers bill for your entire assigned number range, even when only a fraction of those numbers are actually assigned to users, so confirm your carrier contract's billing model before choosing this option expecting it to be the cheapest.

Velaro's Teams Phone integration works identically regardless of which of the three you use - it talks to the resource account and phone number Microsoft already provisioned, not to the underlying voice-routing mechanism.

Step 4 — Enter values into the wizard (customer or Velaro action, ~2 minutes)

Back in the Velaro wizard, enter:

• Microsoft 365 tenant ID — your Entra directory ID
• Resource account object ID — from Step 3.5
• Assigned phone number — optional, display-only in the Velaro UI
• Webhook secret — leave blank to auto-generate

Save. Velaro stores these against your site's voice configuration.

Step 5 — Verify

Click Test connection. This is a REAL Microsoft Graph call — Velaro creates a live Change Notification subscription for /communications/calls using your tenant ID. If Steps 1-3 aren't fully complete, this fails with Microsoft's actual rejection reason (e.g. missing consent, resource account not found) rather than a generic error, so you know exactly what to fix.

Once verified, Velaro's background job automatically renews this subscription every 15 minutes (Microsoft's maximum lifetime for a calls subscription is about 60 minutes) — no ongoing manual action is required.

---

A note on Bot Framework registration

Microsoft's Teams "calling bot" capability (an app that can host/join/control an active Teams call — which hold, resume, transfer, and hangup all require) has, in some Microsoft documentation, been described as needing an additional Azure Bot Service / Bot Framework channel registration layered on top of a plain Graph application's API permissions — this is a Teams-calling-specific requirement that ordinary Graph scopes like Mail.Read do not need. This has not been independently verified against Velaro's specific app registration or confirmed as strictly required for the Cloud Communications API command/control pattern this integration uses (Velaro's bot issues control-plane commands like hold/transfer/hangup against calls it's already a party to, rather than hosting media itself). If Step 5's live verification succeeds without an additional Bot Framework registration, no further action is needed. If Graph consistently rejects calls with an authorization error even after Steps 1-3 are confirmed correct, an Azure Bot Service registration for the existing app (with the Calling channel enabled) is the next thing to investigate — contact support@velaro.com if you hit this.

---

Screen Pop on Inbound Calls

When a call arrives through Teams Phone, Velaro reuses the SAME screen-pop mechanism every other CTI voice integration uses (NetSuite, HubSpot, Salesforce, VAST, and more) — no Teams-specific screen-pop code exists or is needed:

1. Velaro receives the call event from Microsoft Graph Communications APIs

2. Every screen-pop provider enabled for your site is checked in parallel for a match on the caller's number

3. The first match surfaces in the Velaro agent sidebar before the agent answers

The sidebar shows name, company, open tickets, recent conversations, and any CRM fields your team has mapped during setup. If no match is found, the sidebar displays the raw caller ID and a search box for manual lookup.

---

In-Call Agent Controls

Once a Teams Phone call is active, the agent's Velaro sidebar can hold, resume, transfer, or end the call directly — no need to switch to the Teams client. Hold/resume use Microsoft's real participant-level hold action (not a self-mute), so the caller hears hold music as expected.

---

Call Log Sync

After each call ends, Velaro writes a log entry to your connected CRM (direction, duration, outcome, agent, timestamp, notes — see the Telephony & CTI Overview guide for the shared field set). Teams Phone additionally logs the Teams user alongside the Velaro agent.

Field	Details
Direction	Inbound or outbound
Duration	In seconds
Outcome	Answered, missed, voicemail, transferred
Agent	Teams user and Velaro agent
Timestamp	Call start in UTC
Notes	Agent wrap-up notes from Velaro

---

Use Cases

Inbound sales calls — Agents see the caller's CRM record, deal stage, and last activity before answering. No hold time for lookups.

Support queues — Agents see open tickets and previous conversations immediately. Customers do not need to repeat themselves.

CRM activity history — Every Teams call is logged automatically. Sales managers can review call volume and outcomes in the CRM without manual entry.

---

Troubleshooting

Symptom	What to check
Test connection fails in the wizard	Read the exact Graph error shown — it names the missing piece (consent not granted, resource account not found, tenant ID wrong). Re-check Steps 1-3.
Screen pop does not appear	Confirm both Calls.AccessMedia.All and Calls.Initiate.All show Granted in Entra ID → Enterprise applications → Velaro Outlook Email Integration → Permissions. Check Settings → Integrations → Teams Phone → Activity for auth errors.
Call logs not in CRM	Verify the CRM connection is active (Settings → Integrations → [CRM name] → Activity). Check for 401 or 403 errors.
Hold/resume does nothing	Confirm the call is still active (a call that already ended has no holdable participant). Check the Activity Log for the specific Graph error.
Admin consent error in Azure	Consent must be granted by a Global Administrator or Privileged Role Administrator. Ask your M365 admin to revisit the consent URL in Step 1.

Contact Velaro support at support@velaro.com with your M365 tenant domain for setup and escalation.