How to Embed Viva Engage in a PHP Web App

Before a single line of PHP can talk to the Viva Engage REST API, you need an app registration in Azure Active Directory (Microsoft Entra ID). This is where most PHP developers lose an hour, so let me walk you through it precisely.

Open your browser and go to the Azure Portal at portal.azure.com. In the left sidebar, click Azure Active Directory (or search for "Entra ID" in the top search bar, Microsoft has been renaming things). Then click App registrations in the left menu, and click + New registration at the top.

Fill in the form:

• Name: Something descriptive like "My PHP App – Viva Engage"
• Supported account types: Choose "Accounts in this organizational directory only" for single-tenant, or "Accounts in any organizational directory" if your PHP app serves multiple Microsoft 365 tenants
• Redirect URI: Select "Web" and enter the exact URL where Microsoft will send the OAuth callback, e.g. https://yourapp.com/auth/viva-callback.php

Click Register. You'll land on the app's overview page. Copy down the Application (client) ID and the Directory (tenant) ID, you need both in your PHP config. Now click Certificates & secrets in the left menu, then + New client secret. Give it a description, set an expiry (24 months is reasonable), and click Add. Copy the secret Value immediately, Microsoft only shows it once.

Next, click API permissions, then + Add a permission. Select Yammer from the list (it's still listed under Yammer, not Viva Engage). Under Delegated permissions, check user_impersonation, this is the scope that allows your app to act on behalf of a signed-in user. Click Add permissions. If your tenant requires admin consent, click Grant admin consent for [your org].

If everything worked, your API permissions list should show Yammer / user_impersonation with a green checkmark under the Status column.

With your app registered, your PHP app needs to redirect users to Microsoft's authorization endpoint to get their consent and receive an authorization code. Here's the exact implementation.

Create a file called viva-login.php. This page redirects the user to Microsoft to sign in:

<?php
$tenantId     = 'YOUR_TENANT_ID';
$clientId     = 'YOUR_CLIENT_ID';
$redirectUri  = 'https://yourapp.com/auth/viva-callback.php';
$scope        = 'https://api.yammer.com/user_impersonation offline_access';
$state        = bin2hex(random_bytes(16));

session_start();
$_SESSION['oauth_state'] = $state;

$authUrl = "https://login.microsoftonline.com/{$tenantId}/oauth2/v2.0/authorize?"
    . http_build_query([
        'client_id'     => $clientId,
        'response_type' => 'code',
        'redirect_uri'  => $redirectUri,
        'response_mode' => 'query',
        'scope'         => $scope,
        'state'         => $state,
    ]);

header('Location: ' . $authUrl);
exit;

Now create viva-callback.php to handle the code Microsoft sends back and exchange it for tokens:

<?php
session_start();

$tenantId    = 'YOUR_TENANT_ID';
$clientId    = 'YOUR_CLIENT_ID';
$clientSecret = 'YOUR_CLIENT_SECRET';
$redirectUri = 'https://yourapp.com/auth/viva-callback.php';

// Validate state to prevent CSRF
if (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['oauth_state']) {
    die('State mismatch, possible CSRF attack.');
}

if (isset($_GET['error'])) {
    die('Auth error: ' . htmlspecialchars($_GET['error_description']));
}

$tokenEndpoint = "https://login.microsoftonline.com/{$tenantId}/oauth2/v2.0/token";

$response = file_get_contents($tokenEndpoint, false, stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => 'Content-Type: application/x-www-form-urlencoded',
        'content' => http_build_query([
            'client_id'     => $clientId,
            'client_secret' => $clientSecret,
            'grant_type'    => 'authorization_code',
            'code'          => $_GET['code'],
            'redirect_uri'  => $redirectUri,
            'scope'         => 'https://api.yammer.com/user_impersonation offline_access',
        ]),
    ],
]));

$tokens = json_decode($response, true);
$_SESSION['viva_access_token']  = $tokens['access_token'];
$_SESSION['viva_refresh_token'] = $tokens['refresh_token'];
$_SESSION['viva_token_expiry']  = time() + $tokens['expires_in'];

header('Location: /dashboard.php');
exit;

After a successful callback, the user's access token is stored in the PHP session. The access token expires in 3600 seconds (1 hour), which is why you also capture the refresh token, covered in Step 4. If this works, your session will contain a valid bearer token you can use immediately.

With a valid access token in hand, your PHP app can now talk directly to the Viva Engage REST API. The base URL for all API calls is https://www.yammer.com/api/v1/, yes, the old Yammer domain, not a viva.microsoft.com URL. Microsoft has kept this endpoint active through the rebrand and there's no announced deprecation date.

Create a reusable helper function in a file like viva-api.php:

<?php
function vivaApiGet(string $endpoint, string $accessToken): array {
    $url = 'https://www.yammer.com/api/v1/' . ltrim($endpoint, '/');

    $context = stream_context_create([
        'http' => [
            'method' => 'GET',
            'header' => [
                'Authorization: Bearer ' . $accessToken,
                'Accept: application/json',
            ],
        ],
        'ssl' => [
            'verify_peer' => true,
        ],
    ]);

    $response = file_get_contents($url, false, $context);
    if ($response === false) {
        throw new RuntimeException('Viva Engage API request failed for: ' . $endpoint);
    }
    return json_decode($response, true);
}

Now use it to retrieve messages from a specific community. The endpoint to get messages from a group is messages/in_group/GROUP_ID.json:

<?php
require 'viva-api.php';
session_start();

$token   = $_SESSION['viva_access_token'];
$groupId = 12345678; // your community's numeric ID

$data = vivaApiGet("messages/in_group/{$groupId}.json?threaded=true&limit=10", $token);

foreach ($data['messages'] as $msg) {
    echo '<p>' . htmlspecialchars($msg['body']['plain']) . '</p>';
}

Other useful API endpoints for Viva Engage PHP integration:

• users/current.json, returns the authenticated user's profile
• groups.json, lists all communities the user is a member of
• messages/following.json, the user's following feed
• messages/liked_by/current.json, messages the user has liked

To post a message via PHP, use a POST call to messages.json with a body parameter and a group_id. If it returns HTTP 201, the message was created successfully.

Access tokens from Azure AD expire after 3600 seconds, one hour. If your users stay on your PHP app longer than that (and they will), your API calls will start returning HTTP 401 Unauthorized. The fix is implementing automatic token refresh using the refresh token you captured in Step 2.

Add this token refresh function to your viva-api.php helper:

<?php
function refreshVivaToken(): bool {
    session_start();

    $tenantId     = 'YOUR_TENANT_ID';
    $clientId     = 'YOUR_CLIENT_ID';
    $clientSecret = 'YOUR_CLIENT_SECRET';

    if (empty($_SESSION['viva_refresh_token'])) {
        return false; // user must re-authenticate
    }

    $response = file_get_contents(
        "https://login.microsoftonline.com/{$tenantId}/oauth2/v2.0/token",
        false,
        stream_context_create([
            'http' => [
                'method'  => 'POST',
                'header'  => 'Content-Type: application/x-www-form-urlencoded',
                'content' => http_build_query([
                    'client_id'     => $clientId,
                    'client_secret' => $clientSecret,
                    'grant_type'    => 'refresh_token',
                    'refresh_token' => $_SESSION['viva_refresh_token'],
                    'scope'         => 'https://api.yammer.com/user_impersonation offline_access',
                ]),
            ],
        ])
    );

    if ($response === false) return false;

    $tokens = json_decode($response, true);
    if (empty($tokens['access_token'])) return false;

    $_SESSION['viva_access_token']  = $tokens['access_token'];
    $_SESSION['viva_refresh_token'] = $tokens['refresh_token'] ?? $_SESSION['viva_refresh_token'];
    $_SESSION['viva_token_expiry']  = time() + $tokens['expires_in'];

    return true;
}

Then wrap every API call with a freshness check. Add this before any API call in your pages:

<?php
session_start();

// Refresh if token expires within 5 minutes
if (empty($_SESSION['viva_access_token']) ||
    $_SESSION['viva_token_expiry'] < (time() + 300)) {

    if (!refreshVivaToken()) {
        header('Location: /viva-login.php'); // force re-auth
        exit;
    }
}

$token = $_SESSION['viva_access_token'];

The 300-second buffer (5 minutes) is intentional. It prevents a race condition where the token expires between the freshness check and the actual API call, something that's hard to debug and causes intermittent failures in production. I've seen this bite teams who check with a 0-second buffer.

Note: Refresh tokens themselves expire too, typically after 90 days of inactivity (Microsoft's default). When both tokens are expired, the user will need to go through the full login flow again. That's normal and expected behavior.

Now that your PHP backend can reliably fetch and refresh tokens and pull data from the Viva Engage REST API, the last step is rendering that data cleanly in your PHP templates. Here's a complete example of a community feed component you can drop into any PHP page:

<?php
require_once 'viva-api.php';
session_start();

$token   = $_SESSION['viva_access_token'];
$groupId = 12345678;

try {
    $feedData = vivaApiGet(
        "messages/in_group/{$groupId}.json?threaded=true&limit=20",
        $token
    );
    $messages = $feedData['messages'] ?? [];
} catch (RuntimeException $e) {
    $messages = [];
    error_log('Viva Engage API error: ' . $e->getMessage());
}
?>

<section class="viva-feed">
  <h2>Team Updates</h2>

  <?php if (empty($messages)): ?>
    <p class="viva-empty">No recent posts in this community.</p>
  <?php else: ?>
    <?php foreach ($messages as $msg): ?>
      <div class="viva-post">
        <div class="viva-author">
          <img src="<?= htmlspecialchars($msg['sender_type'] === 'user'
              ? ($msg['sender']['mugshot_url'] ?? '/img/default-avatar.png')
              : '/img/default-avatar.png') ?>"
               alt="Author avatar" width="40" height="40">
          <div>
            <strong><?= htmlspecialchars($msg['sender']['full_name'] ?? 'Unknown') ?></strong>
            <time datetime="<?= htmlspecialchars($msg['created_at']) ?>">
              <?= htmlspecialchars(date('M j, Y', strtotime($msg['created_at']))) ?>
            </time>
          </div>
        </div>
        <div class="viva-body">
          <?= nl2br(htmlspecialchars($msg['body']['plain'] ?? '')) ?>
        </div>
        <div class="viva-actions">
          <span>👍 <?= (int)($msg['liked_by']['count'] ?? 0) ?></span>
          <span>💬 <?= (int)($msg['thread']['stats']['updates'] ?? 0) ?> replies</span>
        </div>
      </div>
    <?php endforeach; ?>
  <?php endif; ?>
</section>

A few important security notes on this rendering code: always run user-generated content through htmlspecialchars() before outputting it, Viva Engage posts can contain angle brackets and other characters that would break your HTML or introduce XSS vulnerabilities. Never echo raw API response data directly. Cast numeric fields explicitly with (int) rather than assuming the API always returns integers, the API can return null for zero-count fields on newer communities.

If you see a blank section instead of posts, add var_dump($feedData) temporarily to inspect the raw API response. The messages key may be named differently depending on whether you hit a threaded or unthreaded endpoint.