> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workvivo

> Connect Workvivo, Zoom's employee experience platform, to Serval so workflows can read from and post to your intranet through the Workvivo API.

## About Workvivo

Workvivo is Zoom's employee experience platform - the home for your company intranet, social feed, and internal communications. The Serval Workvivo integration (currently in Beta) connects with an API token: a Workvivo admin pastes a bearer token, your Organisation Id, and your API base URL into Serval. Serval stores the token securely on its servers and attaches your credentials automatically whenever a workflow talks to Workvivo - the token is never exposed to workflow builders or returned to the browser after you save it.

**Authentication:** API token (a bearer token from a Workvivo API app, plus your Organisation Id and API base URL).

**Data sync:** On demand only. Workflows call Workvivo when they run - there is no background data sync, no entity ingestion, and no inbound webhooks. Five scheduled health checks confirm the connection stays valid.

## What the Workvivo integration enables

| Capability                             | Description                                                                                                                                                                                                                            |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workvivo API request (workflow action) | Workflows get typed access to the full Workvivo v1 API - 210 endpoints covering articles, updates, kudos, events, users, chat bots and channels, spaces, pages, teams, notifications, badges, documents, goals, livestreams, and more. |
| Connection health checks               | Five scheduled checks continuously verify that your token, Organisation Id, base URL, and permission scopes still work.                                                                                                                |
| AI workflow context                    | Each connected Workvivo instance is visible to workflows and Serval AI, so even multi-instance setups can target the right Workvivo tenant.                                                                                            |

Anything defined in the [Workvivo API](https://developer.workvivo.com/) can be accessed through Serval.

## Get your credentials

You need three values, all shown on the same screen in Workvivo's developer admin: a bearer token from a Workvivo API app, your Organisation Id, and your API Base URL. Creating the app requires the Workvivo **Developer** role. Workvivo's official walkthrough is here: [API Authentication - Bearer Token](https://support.workvivo.com/hc/en-gb/articles/24560593493661-API-Authentication-Bearer-Token) (see also the [Workvivo API Overview](https://support.workvivo.com/hc/en-gb/articles/33276763921309-Workvivo-API-Overview) and the full [APIs help section](https://support.workvivo.com/hc/en-gb/sections/4917959499165-APIs)).

<Warning>
  Workvivo warns that Developer-role users can create API apps with up to Admin-level permissions, including actions the normal UI restricts. Grant the role sparingly, and give the Serval app only the scopes it needs.
</Warning>

<Steps>
  <Step title="Get the Developer role">
    Have a Workvivo admin grant your user the Developer role. This unlocks the "API Keys and JWT settings" option in the Workvivo admin panel.
  </Step>

  <Step title="Open API Keys and JWT settings">
    In your Workvivo admin panel, open API Keys and JWT settings (Admin > Developers > Apps). Workvivo tenants live on their own domains, so navigate there from inside your own Workvivo instance.
  </Step>

  <Step title="Note your Organisation Id">
    Your numeric Organisation Id is shown on this screen. This is the "Workvivo-Id (Organisation Id)" value Serval asks for.
  </Step>

  <Step title="Create an API app with minimum scopes">
    Create a new app, name it, and select only the permissions the integration needs. Include the chats.bots.read scope if you want all five Serval health checks to pass. Scopes can be changed later.
  </Step>

  <Step title="Generate and copy the token">
    Click Manage Keys on the app, then Add new Key, and copy the bearer token that populates.
  </Step>

  <Step title="Note the API Base URL">
    Note the Base URL shown when creating the Access Token (Apps > App Settings). It is usually api.workvivo.com, but regional tenants see hosts like api-eu.workvivo.com or api.eu2.workvivo.com. You will enter it in Serval without https\:// or a trailing slash.
  </Step>
</Steps>

<Note>
  The token is only shown when the key is created, and the Organisation Id and Base URL appear on the same screens - capture all three values at once.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the Workvivo connect form">
    In Serval, go to your integrations page and choose Workvivo. It is marked **Beta** in the connect UI, and all three fields are required (marked with an asterisk).
  </Step>

  <Step title="Enter the API Base URL">
    Type the bare host exactly as Workvivo showed it, for example api.workvivo.com - no https\://, no path, no trailing slash. The form rejects anything else with "Must be a valid Workvivo API host (e.g. api.workvivo.com or api.eu2.workvivo.com). Do not include https\:// or a path." Leaving it blank shows "This field is required".
  </Step>

  <Step title="Enter the Workvivo-Id (Organisation Id)">
    Paste your numeric Organisation Id, for example 12345. It is sent with every request Serval makes to Workvivo. Leaving it blank shows "This field is required".
  </Step>

  <Step title="Enter the API Token">
    Paste the bearer token from Manage Keys. This is a password field and is stored as a secret. On first setup the token is required - if you submit without it, Serval rejects the form with an error that includes "API Token is required".
  </Step>

  <Step title="Submit">
    Click Submit. The connection appears as "Workvivo (\[Organisation Id])", and Serval's health checks then run automatically.
  </Step>
</Steps>

<Tip>
  When editing an existing connection, the API Base URL and Workvivo-Id come pre-filled with their saved values, and the API Token field appears empty. Leaving the token blank keeps the saved token - so you can change the other fields, or rotate just the token, without re-entering everything.
</Tip>

## Verifying the connection

Serval runs five scheduled health checks against your Workvivo tenant:

* **Validate Workvivo API Connection** - confirms Workvivo accepts your token, Organisation Id, and base URL.
  * Success: "Successfully authenticated with the Workvivo API."
  * Failure: "Unable to connect to the Workvivo API. Verify the API token, Workvivo-Id header, and base URL are correct."
* **Check Workvivo Users Read Access** - confirms the token can read your user directory.
  * Success: "Successfully listed users (\[number] returned)"
  * Failure: "Failed to list Workvivo users. The token may be missing user-read permissions."
* **Check Workvivo Teams Read Access** - confirms the token can read your teams.
  * Success: "Successfully listed teams (\[number] returned)"
  * Failure: "Failed to list Workvivo teams. The token may be missing teams-read permissions."
* **Check Workvivo Spaces Read Access** - confirms the token can read your spaces.
  * Success: "Successfully listed spaces (\[number] returned)"
  * Failure: "Failed to list Workvivo spaces. The token may be missing spaces-read permissions."
* **Check Workvivo Chat Bots Read Access** - confirms the token has the chats.bots.read scope, which Serval validates ahead of a planned chat capability.
  * Success: "Successfully listed chat bots (\[number] returned)"
  * Failure: "Failed to list Workvivo chat bots. The token is likely missing the chats.bots.read scope; chat-source flows will not work until this is granted."

If your tenant simply has no items of a given type yet, the check still passes with a "Successfully reached the ... endpoint" message instead of a count.

<Tip>
  The most common partial failure: every check is green except "Check Workvivo Chat Bots Read Access". That means your API app is missing the chats.bots.read scope. Your workflows and the other checks are unaffected - grant the scope in Workvivo (or accept the single failing check).
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Enter the base URL as a bare host">
    The form rejects anything that is not exactly a Workvivo API host: no https\://, no path, no trailing slash. If your tenant is regional, use the exact Base URL shown when you created the Access Token - both api-eu.workvivo.com and api.eu2.workvivo.com shapes are accepted, but only workvivo.com API hosts pass Serval's outbound allow-list. Lookalike domains are rejected.
  </Accordion>

  <Accordion title="All three values come from the same admin screen">
    The Organisation Id (Workvivo-Id), the bearer token, and the Base URL are all surfaced in Workvivo's developer admin during app and token creation. Capture all three at once - the token is only shown when the key is created.
  </Accordion>

  <Accordion title="Chat bots health check can fail without breaking anything">
    The "Check Workvivo Chat Bots Read Access" check requires the chats.bots.read scope on your token. If your app lacks that scope, this single check fails while API actions and the other four checks keep working. Grant the scope, or accept the failing check - it exists to validate a future chat capability early.
  </Accordion>

  <Accordion title="Rotating the token: an empty token field keeps the saved token">
    On the edit form the API Token field appears empty even though a token is saved - Serval never sends the stored token back to the browser. Leaving it blank preserves the stored token, so to rotate it, paste the new value and submit. The base URL and Organisation Id come pre-filled and cannot be saved blank (clearing one shows "This field is required"). Note that changing the Workvivo-Id or base URL changes how the connection is identified and displayed in Serval.
  </Accordion>

  <Accordion title="Developer role is powerful in Workvivo">
    Workvivo's own documentation warns that the Developer role lets a user create API apps that can be granted up to Admin permissions, including actions the UI normally restricts. Grant the role only to trusted admins, and give the Serval app the minimum scopes it needs.
  </Accordion>

  <Accordion title="Beta integration with no event delivery yet">
    Workvivo is flagged Beta in the connect UI and is API-actions-only today: no webhooks, no background sync, and it cannot act as a Serval chat source yet. For workflow builders: list results page through with skip and take settings, and list-style filters separate multiple values with the pipe character (for example in\_teams=1|2|3).
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Workvivo integration.