> ## 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.

# Medallia Agent Connect

> Connect Medallia Agent Connect (formerly Stella Connect) so Serval workflows can call its API on demand, with all credentials handled securely by Serval.

## About Medallia Agent Connect

[Medallia Agent Connect](https://www.medallia.com/solution/agent-connect/) (formerly Stella Connect) is a real-time customer feedback and coaching platform for contact center agents. The Serval integration lets workflows call any Agent Connect API on demand - sending survey invites, managing users, or pulling feedback data - while Serval handles authentication behind the scenes. Agent Connect requires a freshly signed access token on every single request, and Serval creates one automatically each time; your workflows never see or handle the API key or secret.

**Authentication:** API Key + API Secret (Serval signs a fresh token on every request)

**Data sync:** On-demand only - no background sync, polling, or webhooks; nothing is mirrored into Serval

## What the Medallia Agent Connect integration enables

| Capability                                | Description                                                                                                                                                                                                                      |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Medallia Agent Connect API request action | A flexible workflow action that can call any endpoint on your Agent Connect API host. It covers all Agent Connect API families - Requests and Feedback (for example, sending a survey invite), User Management, and Data Return. |
| Per-request token signing                 | Serval signs a fresh token with your stored API secret on every outbound request and attaches both headers Agent Connect requires. Workflow authors get full API access without ever handling credentials.                       |
| Connection health check                   | The "Test Medallia Agent Connect Connection" health check verifies end to end that your API key, API secret, and API host work together.                                                                                         |

Anything defined in the [Medallia Agent Connect API](https://docs.medallia.com/en/agent-connect/api) can be accessed through Serval.

## Get your credentials

No app registration is needed. You need the API key and API secret that Agent Connect issues for your tenant, plus your tenant's API gateway host. Medallia's [authentication reference](https://docs.medallia.com/en/agent-connect/api/authentication) covers the underlying details.

<Steps>
  <Step title="Sign in to Agent Connect as an admin">
    Admin access is required to view the Integrations page.
  </Step>

  <Step title="Go to Settings > Integrations">
    The page lists your tenant's test and production API keys, each with a corresponding API secret.
  </Step>

  <Step title="Copy the API key and API secret for one environment">
    Choose the pair for the environment this connection will target - test or production.
  </Step>

  <Step title="Identify your API gateway host">
    Your host is `yoursubdomain.api.stellaconnect.net`, where the subdomain matches your Agent Connect account. If you sign in at `yoursubdomain.stellaconnect.net`, your API host is `yoursubdomain.api.stellaconnect.net`.
  </Step>
</Steps>

<Warning>
  Agent Connect issues separate test and production key pairs, and each Serval connection targets exactly one environment. To connect both environments, set up two separate installs. Test keys do not work against production, and vice versa.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Enter the API Key (required)">
    Paste your Agent Connect API key. The field is masked and the value is stored encrypted. Leaving it blank fails with "API Key is required".
  </Step>

  <Step title="Enter the API Secret (required)">
    Paste the matching API secret. It is stored encrypted and is only ever used inside Serval to sign tokens. Leaving it blank during setup fails with "API Secret is required".
  </Step>

  <Step title="Enter the API Host (required)">
    Enter your gateway host, for example `yoursubdomain.api.stellaconnect.net`. Pasting a full URL from your browser is fine - Serval strips a leading `https://` or `http://`, surrounding whitespace, and trailing slashes automatically. A blank value fails with "API Host is required (e.g. `subdomain.api.stellaconnect.net`)", and a host that does not end in `api.stellaconnect.net` fails with "API Host must end in `api.stellaconnect.net` (e.g. `subdomain.api.stellaconnect.net`)".
  </Step>

  <Step title="Save the connection">
    Serval trims all values before saving, so stray whitespace from copy-paste cannot break authentication.
  </Step>
</Steps>

<Note>
  When editing an existing connection, the API Key and API Secret appear masked (dots plus the last four characters of the stored value). Leaving the API Secret masked or blank keeps the stored secret. The API Key works differently: Serval requires it on every save, so re-enter your API key (use the field's edit control) before saving any change - a save with the API Key left masked or blank is rejected with "API Key is required". The API Host is shown in clear text and must pass validation on every save.
</Note>

## Verifying the connection

The integration ships one health check:

**Test Medallia Agent Connect Connection** - signs a fresh token with your stored API secret and makes a tiny query against the Data Return API (a one-second time window, so almost no data comes back). Because that API requires a valid token and API key, any successful response proves Agent Connect accepted both credentials and that the host is correct.

* On success: "Successfully authenticated with Medallia Agent Connect and reached the API gateway."
* On failure: "Unable to connect to Medallia Agent Connect. Verify your API key, API secret, and API host are correct and that the key has not been revoked on the Agent Connect Integrations page."

<Tip>
  If the connection test is green but a specific workflow call fails, check that your API key has access to that Agent Connect API family, and - for Data Return queries - that date filters are formatted without a trailing "Z" (for example "2026-04-21T00:00:00.000").
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Getting 401 errors? Check that your keys match the environment">
    Agent Connect issues independent test and production API key and secret pairs, and each Serval install targets exactly one environment. Test keys do not work against production and vice versa - mixing environments is a common cause of authentication failures. Make sure the key, secret, and the account you intend to reach all belong to the same environment.
  </Accordion>

  <Accordion title="Pasting a full URL into API Host is fine; a non-Medallia host is not">
    Serval strips a leading `https://` or `http://`, surrounding whitespace, and trailing slashes from the API Host before validating, so copy-pasting from the browser URL bar works. But the resulting host must end in `api.stellaconnect.net` - any other host is rejected at save time, and Serval independently refuses to attach your credentials to requests aimed at hosts outside Medallia's Agent Connect gateway.
  </Accordion>

  <Accordion title="The health check needs Data Return API access">
    The connection test queries the Data Return API. If your API key does not have access to that part of Agent Connect, the health check fails even though the credentials may be valid for other endpoint families. Ask your Agent Connect administrator to enable Data Return access for the key.
  </Accordion>

  <Accordion title="Editing the connection? Re-enter the API Key before saving">
    When you edit an existing connection, the API Key and API Secret display as masked values (dots plus the last four characters). Leaving the API Secret masked or blank keeps the stored secret - the masked placeholder never overwrites the real value. The API Key does not behave the same way: a save with the API Key left masked or blank is rejected with "API Key is required", so keep your API key on hand and re-enter it whenever you save changes to this connection. All values are trimmed before saving, so trailing whitespace cannot silently corrupt the signing key.
  </Accordion>

  <Accordion title="Why the generic custom HTTP integration cannot connect to Agent Connect">
    Agent Connect rejects access tokens that are not freshly issued, so a token cannot be created once and reused. Serval signs a brand-new token on every outbound request (each one expires after 60 seconds as an extra safeguard). The generic custom HTTP integration only supports static headers and cannot re-sign per request, which is exactly why this native integration exists - use it instead of a custom HTTP connection.
  </Accordion>

  <Accordion title="Comparing against your own tests? The Authorization header has no Bearer prefix">
    Per Medallia's [authentication documentation](https://docs.medallia.com/en/agent-connect/api/authentication), Agent Connect expects the Authorization header to contain the bare signed token, not "Bearer" followed by the token. Serval handles this automatically; if you are comparing against your own manual API tests, do not add a Bearer prefix.
  </Accordion>

  <Accordion title="Data Return date filters omit the timezone suffix">
    The Data Return API expects timestamps without the trailing "Z" (for example "2026-04-21T00:00:00.000") and treats them as UTC, matching [Medallia's own sample calls](https://docs.medallia.com/en/agent-connect/integrations-and-api/requests-api/requests-api---sample-call-structures). Workflows that filter Data Return queries by date should format their timestamps this way.
  </Accordion>
</AccordionGroup>

***

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