Skip to main content

Vodia Microsoft Teams Integration Tool

Enhance your Vodia PBX by integrating it seamlessly with Microsoft Teams using our vodia-teams NPM tool. Designed for efficiency, this tool supports the integration of multiple tenants with their respective Microsoft 365 Teams environments. The tool has an option to retrieve a list of extensions from a Vodia PBX tenant and map them to their respective Teams user accounts using email addresses. We'll demonstrate its use with an example below.

Prerequisites

  • DNS Control: Ensure you have administrative control over the DNS records for the tenant's FQDN that will be enrolled as the SBC in Teams.
  • User Licensing: Verify that all Teams users possess the necessary Microsoft licenses, such as Microsoft Business Standard with the Teams Phone add-on or a Microsoft E5 license.
  • Usage Location: Confirm that a usage location has been set for each Teams user during license assignment in Microsoft.
  • Microsoft Credentials: You must have global administrator credentials for the Microsoft tenant.
  • OS: To run the vodia-teams NPM tool, you will need an Ubuntu 24 server.
  • Emails: To leverage the tool's automation capabilities, we recommend ensuring the extension's email address matches the user's primary Microsoft username (UPN) and then selecting option 4 ( i.e. Map Vodia PBX extension numbers to Teams users? You'll need the server management address, admin credentials and API enabled for the admin user.) for phone number assignment.

Vodia PBX configuration

  • Create a tenant with a Fully Qualified Domain Name (FQDN) that will serve as the SBC for Teams enrollment.

    teams-create-tenant.png

  • Ensure the tenant has a valid certificate.

    teams-teanant-certificate.png

  • Create a Teams trunk using Vodia's predefined template, remembering to set the country code.

    teams-trunk-1.png

    teams-trunk-2.png

  • Create a generic SIP trunk for routing inbound and outbound calls for Teams users.

    teams-general-trunk.png

  • Configure the dial plan as depicted in the screenshot and assign it as default dialplan within the tenant's general settings. This is where you can normalize numbers (e.g., remove the '+' sign). Importantly, note the entry labeled [teams] for the Teams trunk, as this is crucial for proper routing of Teams calls.

    teams-diallplan.png

    teams-domain-dialplan.png

  • Create extensions and assign a Teams number to each. Remember to enable the Include Microsoft Teams when calling the extension setting.

    teams-extension-setup.png

tip

We recommend using your existing extension numbers as the Teams numbers. Additionally, map any external Direct Inward Dialing (DID) numbers to their corresponding extensions within your Vodia PBX.

Utilize the Vodia Microsoft Teams Configuration Tool to set up client Teams environments (Ubuntu 24 server)

  • Install the vodia-teams NPM tool

    curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
    apt-get install -y nodejs
    npm install -g vodia-teams
  • Execute the vodia-teams NPM tool. In the example below:

    • vodia-teams.com represents the base domain that needs to be verified within the Microsoft tenant.

    • sbc.vodia-teams.com is the SBC FQDN, which should match your Vodia tenant name.

      root@vodia:~# vodia-teams --sbc sbc.vodia-teams.com --domain vodia-teams.com
  • The tool will guide you through several steps in single flow, starting with authentication using your Microsoft global administrator credentials.

    • App registration and admin consent: This step grants the tool access to Microsoft's Graph API. When prompted, copy and paste the provided URL into your web browser and authenticate using your global administrator credentials. You should then observe output similar to what is shown below.

      To sign in, use a web browser to open the page: https://microsoft.com/devicelogin
      Enter the code J8FRT9HU7 to authenticate
      NOTE: You must sign in with a Global Administrator account

      Waiting for authentication...
      Waiting for you to complete authentication...
      Waiting for you to complete authentication...
      Authentication successful!

      Step 2: Getting tenant details...
      Tenant identified: Vodia Networks (02f2fdd7-c2d6-46ea-8ed9-6c4698ba7a8b)

      Step 3: Creating application registration...
      Application created: VodiaTeamsAutomation-174615683XXXXXX
      Application (client) ID: XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX
      Application Object ID: XXXXXX-XXXXXX-4XXXXXX-XXXXXX-XXXXXX

      Step 4: Creating client secret...
      Step 5: Creating service principal...
      Service principal created: XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX

      Credentials saved to sbc_vodia-teams_com-credentials.json

      IMPORTANT: Keep this file secure as it contains sensitive information.

      Final Step: Please open the following URL in your browser to grant admin consent:
      https://login.microsoftonline.com/02f2fdd7-c2d6-46ea-8ed9-6c4698ba7a8b/adminconsent?client_id=844091e6-b232-4434-9964-f2e883216ee6&redirect_uri=http://localhost

      After granting consent, you can use the credentials in the saved file for API calls.

      Press Enter to continue...
      App registration completed.

      You will see these permissions in your web browser when granting admin consent.

      teams-api-permissions.png

    • Add and Verify Domain: Next it will add your domain for e.g. vodia-teams.com to the Microsoft tenant and present you with DNS TXT records. You must add these records to your DNS provider. The tool will then wait for a specified time (1-30 minutes) before verifying the domain. We recommend setting a waiting period of at least 2 minutes to ensure sufficient DNS propagation time. You should then observe output similar to what is shown below.

      Step 2: Authenticating with Microsoft Graph...
      Authentication successful!
      Connected to tenant: Vodia Networks

      Step 3: Managing domain...
      Domain vodia-teams.com not found. Adding domain...
      Domain vodia-teams.com added successfully!

      Please add these DNS records to your domain:

      TXT Record:
      Host/Name: vodia-teams.com
      Value: MS=ms32055599
      TTL: 3600

      MX Record:
      Host/Name: vodia-teams.com
      Points to: ms32055599.msv1.invalid
      Priority: 32767
      TTL: 3600

      DNS propagation takes time. Please choose how long to wait before verification:
      1. Wait 1 minute
      2. Wait 2 minutes
      3. Wait 5 minutes
      4. Wait 15 minutes
      5. Wait 30 minutes
      6. Skip verification and continue with the workflow
      Select an option (1-6): 2
      You selected option: 2
      Waiting 2 minutes for DNS propagation...
      2 minute(s) remaining...
      1 minute(s) remaining...
      Wait completed. Attempting to verify domain...
      Domain vodia-teams.com verified successfully!
    • Direct Routing Configuration: While the tool configures the SBC, voice route, PSTN usage and voice policy, you will need to authenticate mutliple times. When prompted please copy the provided URL into your browser and use your global credentials. Once authenticated, the tool will proceed to detect users with valid licenses and offer you the option to set up all valid users or specific users. It will assign phone numbers and enable Enterprise Voice for each valid user. For setting up phone numbers, we strongly recommend option 4: Map Vodia PBX extension numbers to Teams users? You'll need the server management address, admin credentials and API enabled for the admin user as this option will further automate and speed up the Microsoft Teams setup process. When using this option, ensure that the extension's email address matches the user's primary Microsoft username (UPN). Additionally, the Teams Number must be identical to the extension number in your Vodia tenant. Alternatively, you can use option 3 to manually assign numbers (i.e. extension numbers) to each user. You should then observe output similar to what is shown below.

      How would you like to assign phone numbers to users?
      1. Use a base phone number with sequential digits
      2. Enter individual phone numbers for each user
      3. Enter extension numbers that will be assigned to each user
      4. Map Vodia PBX extension numbers to Teams users? You will need the server management address, admin credentials and API enabled for the admin user.
      Enter your choice (1, 2, 3, or 4): 4
      You selected option: 4

      Vodia PBX Integration Setup:
      Enter Vodia PBX server address (e.g., ztfznb.vodia-pbx.com): ztfznb.vodia-pbx.com
      Enter Vodia admin username: admin
      Enter Vodia admin password: 75EfS65NXcySQZ23

      Fetching tenants from Vodia PBX...
      Available Vodia tenants:
      1. lhgrxp.vodia-pbx.com
      2. sbc.vodia-teams.com
      Found matching tenant: sbc.vodia-teams.com

      Fetching extensions from tenant sbc.vodia-teams.com...
      Found 4 extensions in Vodia PBX.
      Fetch completed in 1.23 seconds.

      Sample extensions:
      ┌──────────────────────────────────────────────┐
      │ Extension │ Name │ Email │
      ├──────────────────────────────────────────────┤
      │ 500 │ 500 │ azure@vodia.com │
      │ 501 │ 501 │ ak@vodia.com │
      │ 502 │ 502 │ hc@vodia.com │
      │ 503 │ 503 │ cs@vodia.com │
      └──────────────────────────────────────────────┘

      ===== VODIA EXTENSION MAPPING SUMMARY =====
      ┌─────────────────────────────────────────────────────────────────────────────┐
      │ User │ Email │ Vodia Extension │
      ├─────────────────────────────────────────────────────────────────────────────┤
      │ Asad Khan │ ak@vodia.com │ 501 │
      │ Azure Vodia │ azure@vodia.com │ 500 │
      │ Christian Stredicke │ cs@vodia.com │ 503 │
      │ Hamlet Collado │ hc@vodia.com │ 502 │
      └─────────────────────────────────────────────────────────────────────────────┘
      SUMMARY: 4 users matched with Vodia extensions, 0 users need manual configuration.
      You will be prompted to confirm or change each extension in the next step.

      Continue with Enterprise Voice configuration using these mappings? (y/n): y

      Running Enterprise Voice configuration for selected users...
      Executing PowerShell script (you will be prompted to configure each user)...
      Checking for existing Teams connection...
      Existing session not valid or expired.
      Connecting to Microsoft Teams using device code authentication...
      To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code PCEBKA2BY to authenticate.

      Please complete the authentication process...
      Connected to Microsoft Teams tenant: Vodia Networks
      Using voice routing policy: vodia-teamsVoicePolicy
      ===== ENABLING ENTERPRISE VOICE FOR MULTIPLE USERS =====
      Total users to configure: 4
      ==== Configuring user 1/4: Asad Khan (ak@vodia.com) ====
      Found matching Vodia extension: 501 for email: ak@vodia.com
      Using extension: 501
      Checking if user exists...
      Assigning phone number...
      Enabling Enterprise Voice...
      Correlation id for this request : 72a89372-1dec-49e6-ac79-30104f08f3bc
      Account Environment Tenant TenantId
      ------- ----------- ------ --------
      azure@vodia.com AzureCloud 02f2fdd7-c2d6-46ea-8ed9-6c4698ba7a8b 02f2fdd7-c2d6-46ea-8ed9-6c4698ba7a8b
      Set-CsUser: /root/enable-enterprise-voice-bulk-temp.ps1:79
      Line |
      79 | Set-CsUser -Identity "ak@vodia.com" -EnterpriseVoiceEnabled $true
      | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      | This API is deprecated
      Assigning voice routing policy...
      Verifying configuration...
      Configuration Results:
      User: ak@vodia.com
      Phone Number: tel:+501
      Enterprise Voice Enabled: True
      Voice Routing Policy: vodia-teamsVoicePolicy
      Enterprise Voice configuration completed successfully!
      ==== Configuring user 2/4: Azure Vodia (azure@vodia.com) ====
      Found matching Vodia extension: 500 for email: azure@vodia.com
      Using extension: 500
      Checking if user exists...
      Assigning phone number...
      Enabling Enterprise Voice...
      Correlation id for this request : 816954dd-8af9-425a-bf98-38d758fb9140
      Set-CsUser: /root/enable-enterprise-voice-bulk-temp.ps1:125
      Line |
      125 | Set-CsUser -Identity "azure@vodia.com" -EnterpriseVoiceEnabled $t …
      | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      | This API is deprecated
      Assigning voice routing policy...
      Verifying configuration...
      Configuration Results:
      User: azure@vodia.com
      Phone Number: tel:+500
      Enterprise Voice Enabled: True
      Voice Routing Policy: vodia-teamsVoicePolicy
      Enterprise Voice configuration completed successfully!
      ==== Configuring user 3/4: Christian Stredicke (cs@vodia.com) ====
      Found matching Vodia extension: 503 for email: cs@vodia.com
      Using extension: 503
      Checking if user exists...
      Assigning phone number...
      Enabling Enterprise Voice...
      Correlation id for this request : a8fc0963-bfe7-42af-8f24-1c082ac58f9b
      Set-CsUser: /root/enable-enterprise-voice-bulk-temp.ps1:171
      Line |
      171 | Set-CsUser -Identity "cs@vodia.com" -EnterpriseVoiceEnabled $true
      | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      | This API is deprecated
      Assigning voice routing policy...
      Verifying configuration...
      Configuration Results:
      User: cs@vodia.com
      Phone Number: tel:+503
      Enterprise Voice Enabled: True
      Voice Routing Policy: vodia-teamsVoicePolicy
      Enterprise Voice configuration completed successfully!
      ==== Configuring user 4/4: Hamlet Collado (hc@vodia.com) ====
      Found matching Vodia extension: 502 for email: hc@vodia.com
      Using extension: 502
      Checking if user exists...
      Assigning phone number...
      Enabling Enterprise Voice...
      Correlation id for this request : 38b79644-336f-4d21-b7e8-56a3042cdf5f
      Set-CsUser: /root/enable-enterprise-voice-bulk-temp.ps1:217
      Line |
      217 | Set-CsUser -Identity "hc@vodia.com" -EnterpriseVoiceEnabled $true
      | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      | This API is deprecated
      Assigning voice routing policy...
      Verifying configuration...
      Configuration Results:
      User: hc@vodia.com
      Phone Number: tel:+502
      Enterprise Voice Enabled: True
      Voice Routing Policy: vodia-teamsVoicePolicy
      Enterprise Voice configuration completed successfully!
      \n===== CONFIGURATION SUMMARY =====
      User count: 4
      User configuration summary:


      User Email ExtensionSource VodiaExtension
      ---- ----- --------------- --------------
      Asad Khan ak@vodia.com Vodia (Auto) 501
      Azure Vodia azure@vodia.com Vodia (Auto) 500
      Christian Stredicke cs@vodia.com Vodia (Auto) 503
      Hamlet Collado hc@vodia.com Vodia (Auto) 502

      Configuration report saved to: /root\TeamsVoiceConfiguration_20250505_032941.csv
      Enterprise Voice configuration completed for all users.
      Disconnected from Microsoft Teams.
      Enterprise Voice configuration completed for selected users.

      === Workflow completed successfully! ===