> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/ai/avoma.md).
# Avoma
Discover Avoma users and roles and track per-user meeting engagement metrics across your organization
Avoma is an AI meeting assistant and conversation intelligence platform. The Avoma integration connects your Avoma account to Harmony as an AI category integration. Once connected, Harmony pulls your Avoma user roster and per-user engagement metrics, giving you visibility into your Avoma usage alongside your other tools.
### What the Avoma integration enables
| Capability | Description |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| User Discovery | Surface all Avoma users in Harmony's inventory with name, email, team, and activation status |
| Role Visibility | See each user's Avoma role (admin, manager, member, or guest) |
| Engagement Tracking | Monitor per-user daily activity - conversations listened to, shared, and commented on |
| Multi-Instance Support | Connect multiple Avoma workspaces for organizations with separate accounts |
### Prerequisites
1. **Avoma Organization or Enterprise plan** - Avoma API access is available on select plans only. Avoma's pricing page lists "API Integration & Webhooks" under the Organization and Enterprise plans. On other plans the **Developer** section is not available.
2. **Avoma Admin privileges** - only org admins can create, view, or revoke Avoma API keys. Non-admin users do not have access to the Developer page.
3. **A Harmony account** with admin privileges
### Credentials
The Avoma integration uses a bearer-token model. Avoma issues the credential as a **single string** in the format `CLIENT_KEY:CLIENT_SECRET`, which you split at the colon into the two fields Harmony asks for:
* **Client Key** - the part **before** the `:`. A text identifier generated in Avoma.
* **Client Secret** - the part **after** the `:`. This value is masked in Harmony after you save it.
### Connecting Avoma to Harmony
#### Step 1: Create an Avoma API key
1. In Avoma, go to **Settings → Organization → Developer**
2. Click **Add API Key**
3. Enter a descriptive **Name** (for example, `Harmony Integration`)
4. Select the **Scope**: **Organization - limited access**
5. Click **Create**
6. Copy the full key string - it looks like `CLIENT_KEY:CLIENT_SECRET`
{% hint style="warning" %}
Harmony needs the **Organization - limited access** scope. The two `User` scopes tie the key to a single user and only return that user's meetings, so they cannot produce an organization-wide roster. A key's scope is permanent - to change it, create a new key and revoke the old one.
{% endhint %}
{% hint style="info" %}
Your Avoma organization can hold up to **10 API keys** at a time. Revoking a key frees a slot immediately.
{% endhint %}
#### Step 2: Enter the credentials in Harmony
1. In Harmony, go to **Settings → Integrations → AI**
2. Locate the **Avoma** tile and click it to begin setup
3. Enter the part of the key string **before** the `:` in the **Client Key** field
4. Enter the part **after** the `:` in the **Client Secret** field
5. Save the integration
{% hint style="info" %}
Harmony validates the credentials at save time by calling Avoma's user-list endpoint. If Avoma rejects the key, the save fails immediately with an error telling you to verify the `CLIENT_KEY:CLIENT_SECRET` values and the key's scope.
{% endhint %}
### Disconnecting Avoma from Harmony
1. Log into your Harmony dashboard
2. Navigate to **Settings → Integrations → AI**
3. Find **Avoma** and click the integration card
4. Click **Disconnect** and confirm when prompted
Once disconnected, Harmony stops syncing data from Avoma. Previously synced data remains available in Harmony. You can also revoke the API key in Avoma under **Settings → Organization → Developer**.
### What Harmony Syncs from Avoma
| Data | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User inventory | Name, email, Avoma role (admin, manager, member, or guest), job function, position, team membership, and active/inactive status |
| Engagement metrics | Per-user daily counts: conversations listened to, listening duration, conversations shared, conversations commented on, total comments, and snippets listened to |
{% hint style="info" %}
**Sync frequency:**
* **User inventory** refreshes every 6 hours
* **Engagement metrics** are collected daily, one day at a time
{% endhint %}
{% hint style="warning" %}
**Historical data on first connection:**
Avoma only accepts engagement queries for roughly the last 7 days, so Harmony starts collecting engagement data from within that window when you first connect and builds history forward from there. Engagement activity from before you connected is not available.
{% endhint %}
### API Key Scope Explained
Avoma offers three scopes when you create an API key. Harmony requires the third:
| Scope | Tied to | What it can access | Works with Harmony |
| ----------------------------- | -------- | ---------------------------------------------------------------------- | ------------------ |
| User - limited access | One user | That user's non-private meetings only | No |
| User - full access | One user | Everything that user can see, including their private meetings | No |
| Organization - limited access | Org-wide | All non-private meetings across the org; private meetings are excluded | Yes |
Harmony reads the organization's user list and its aggregated per-user engagement metrics. It does not read meeting recordings, transcripts, or notes.
### Use Cases
AI Tool Adoption
Track who is actually consuming Avoma content - conversations listened to, listening duration, and sharing or commenting activity - to measure adoption across teams rather than relying on account counts alone.
Access Review
Review who has an Avoma account, which role they hold (admin, manager, member, or guest), and whether their account is still active.
Offboarding
Confirm Avoma access has been removed when employees leave, as part of Harmony offboarding workflows.
### Troubleshooting
Saving the integration fails with a validation error
**Possible causes:**
* The key string was not split correctly at the `:` - the Client Key and Client Secret were swapped, or the colon itself was pasted into one of the fields
* Extra spaces or characters were copied along with the key
* The key was created with a `User` scope instead of **Organization - limited access**
* The API key was deleted or regenerated in Avoma
**Solutions:**
1. Re-copy the key string from **Settings → Organization → Developer** in Avoma and split it at the `:`, leaving the colon out of both fields
2. Confirm the key's scope in Avoma's key list. If it is a `User` scope, create a new key with **Organization - limited access** and update Harmony
3. If the key was regenerated, copy the new string and update both fields in Harmony
There is no Developer section in Avoma
**Possible causes:**
* Your Avoma plan does not include API access - it is available on the Organization and Enterprise plans
* You are not signed in as an Avoma org admin - only admins can access the Developer page
**Solutions:**
1. Verify your plan with Avoma
2. Ask an Avoma org admin to create the API key
The integration worked and then started failing
**Possible causes:**
* The API key was revoked or regenerated in Avoma
* The key was issued to a user who has since been deactivated - requests using that key start returning errors
**Solutions:**
1. Check the key still exists in **Settings → Organization → Developer** and regenerate it if needed, then update the credentials in Harmony
2. Create a new **Organization - limited access** key, update Harmony, and revoke the old one
Data appears slowly after connecting
**Possible causes:**
* Avoma limits API traffic to 60 requests per minute and applies a 60-second execution timeout per request, so Harmony paces its requests
* Engagement data is collected one day at a time and can take several polls to catch up
**Solutions:**
1. Allow the first syncs to complete - user inventory refreshes every 6 hours and engagement is collected daily
### Data & Privacy
Key privacy principles
For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).
* Harmony accesses Avoma data in read-only mode and does not modify any data in your Avoma account
* Harmony only calls Avoma's user-list and engagement-metrics endpoints - it does not access meeting recordings, transcripts, or notes
* Access can be revoked at any time by deleting the API key in Avoma or disconnecting the integration in Harmony
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.harmony.io/integrations/ai/avoma.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.