> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/channels-integrations/crm-service/topdesk.md).
# TOPdesk CRM Service
Configure CRM Service for TOPdesk.
Configure CRM Service for TOPdesk when WebAgent must retrieve TOPdesk information through the TOPdesk REST API.
Before requesting the service, confirm the [shared CRM connector licensing prerequisites](/channels-integrations/crm-service.md#licensing-prerequisites).
{% hint style="info" %}
Confirm that TOPdesk CRM Service is offered for the customer environment before starting. Provider availability can depend on the environment and support policy.
{% endhint %}
## Request TOPdesk CRM Service in OnePortal
1. Request the TOPdesk CRM Service for the customer environment through the current OnePortal, delivery, or support process.
2. Confirm which UCC and WebAgent configuration must consume TOPdesk data.
3. Confirm that TOPdesk is the enabled CRM Service provider before changing provider settings.
4. Use [Configure CRM Service settings](/channels-integrations/crm-service/configure-crm-service-settings.md) for shared request, change, `PluginSettings`, `PluginAttributes`, and secret-handling rules.
## Prepare TOPdesk
Prepare TOPdesk API access before CRM Service settings are completed.
| Preparation item | What to prepare | Used by CRM Service |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| TOPdesk environment URL | Customer-specific TOPdesk URL, such as `https://[name].topdesk.net`. | `ApplicationHost` |
| REST API path | TOPdesk REST API path. The default API path is `/tas/api/` unless the environment uses a different approved path. | `ApiPath` |
| Service account | TOPdesk account approved for CRM Service API access. | `Username` and encrypted `ApplicationPassword` |
| Service-account group access | Group has read access to the TOPdesk REST API and the records WebAgent must display. | Provider-side authorization |
| Object scope | Person, contact, incident, case, or related data WebAgent must display. | Query and mapping design |
Use the [TOPdesk API tutorial](https://developers.topdesk.com/tutorial.html) and verify current TOPdesk UI labels before changing API access.
## Configure TOPdesk CRM Service in Dialogue Cloud Neo / SharePoint
Enter or request these values in the active configuration source for `CrmService` `PluginSettings`.
| Setting | Requirement | Value |
| ---------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `ApplicationHost` | Required | TOPdesk environment URL supplied for the environment, for example `https://[name].topdesk.net`. |
| `Username` and encrypted `ApplicationPassword` | Required | TOPdesk service-account values handled through the approved secret process. |
| `ApiPath` | Optional | API path combined with `ApplicationHost` where the integration requires a separate path; default path is `/tas/api/`. |
Configure TOPdesk field mappings in `CrmService` `PluginAttributes` when the default mapping is not sufficient for the customer data model.
## Configure optional TOPdesk settings in Dialogue Cloud Neo / SharePoint
Add optional settings with scope `CrmService`.
| Setting | Where configured | Default or value guidance |
| ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ApiPath` | `PluginSettings` | Combines with `ApplicationHost` to form the TOPdesk API URL. Default: `/tas/api/`. |
| `DefaultPhoneNumberRegion` | `PluginSettings` | ISO 3166 alpha-2 region code. Default: `ZZ`. |
| `PhoneNumberFormat` | `PluginSettings` | Supported modes include `E164`, `International`, `Rfc3966`, and `Pattern`. Example formats include `+12065551234`, `+1 (206) 555-1234`, and `tel:+12065551234`. Use the mode that matches how TOPdesk stores customer phone numbers. |
| `ContactBaseQuery` | `PluginSettings` | Contact query template. Default: `persons?[conditions][fields]&page_size=20`. |
| `CaseBaseQuery` | `PluginSettings` | Case query template. Default: `incidents?[conditions][fields]&page_size=20`. |
| `ContactCaseFilter` | `PluginSettings` | Contact-to-case filter. Default: `caller_id.sys_id={0}`. Attribute and value must be valid `SystemName` values. |
| `CaseStatus` | `PluginSettings` | Maps TOPdesk case status to WebAgent status. Default maps `true=Closed`; other statuses are treated as open. |
| `UseFiql` | `PluginSettings` | Uses the newer API with FIQL queries. Default: `true`. |
| `UseDefaultPluginAttributes` | `PluginSettings` | Default behavior: if the setting is absent or `True`, CRM Service uses default TOPdesk `PluginAttributes`. Set to `False` only when all required TOPdesk `PluginAttributes` will be maintained manually. Default: `true`. |
| `UseStartsWith` | `PluginSettings` | For FIQL text search, uses a starts-with operation instead of equals. Applies to text search only, not ID, phone-number, SIP URI, or email search. |
| `ShowMappedStatus` | `PluginSettings` | Shows the mapped WebAgent status (`Open` or `Closed`) instead of the internal incident status. Default: `true`. |
| TOPdesk `PluginAttributes` | `PluginAttributes` | Map TOPdesk attributes to WebAgent contact, contact-search, case, and case-search output. |
TOPdesk query and mapping guidance
For TOPdesk `PluginAttributes`, use TOPdesk attributes as `SystemName` values. If an attribute comes from a linked entity, include the alias before the attribute. Use:
* `DisplayName` for the label shown in WebAgent.
* `ShowOnExtensionWindow` to control whether WebAgent displays the value.
* `Order`; restart numbering for each `Category`.
* `FieldType` values such as `Id`, `Name`, `PhoneNumber`, `SipAddress`, `Email`, `Date`, and `Search`.
* `Hyperlink` to make a value clickable; include `SystemName` placeholders in square brackets when the link needs field values.
* `ShowOnToast` to force the attribute into the query.
Keep complete FIQL or text-search templates and mapping records in the delivery or configuration record. Include customer-specific TOPdesk query text only when the customer must validate an object, field, or filter.
### Default `PluginAttributes`
The default TOPdesk rows are used when `UseDefaultPluginAttributes` is absent or `True`. These rows do not include a `ShowOnToast` column.
| DisplayName | SystemName | Category | Order | ShowOnExtensionWindow | FieldTypes | Hyperlink |
| --------------- | ------------------ | ------------- | ----: | --------------------- | -------------------- | -------------------------------------------------------- |
| Id | `id` | Case | 0 | No | `Id` | `[TopDeskUrl]/tas/secure/incident?action=show&unid=[id]` |
| Subject | `number` | Case | 1 | Yes | `Title` | |
| Description | `briefDescription` | Case | 2 | Yes | `Description` | |
| Date | `creationDate` | Case | 3 | Yes | `Date` | |
| Status | `closed` | Case | 4 | Yes | `Status` | |
| ContactId | `caller.id` | Case | 4 | No | `Id` | |
| Subject | `number` | CaseSearch | 1 | Yes | `Search` | |
| Id | `id` | Contact | 0 | No | `Id` | `[TopDeskUrl]/tas/secure/person?action=show&unid=[id]` |
| Name | `dynamicName` | Contact | 1 | Yes | `Name` | |
| Email | `email` | Contact | 2 | Yes | `SipAddress,Search` | |
| Phone Number | `phoneNumber` | Contact | 3 | Yes | `PhoneNumber,Search` | |
| Mobile | `mobileNumber` | Contact | 4 | Yes | `PhoneNumber,Search` | |
| First Name | `firstName` | ContactSearch | 1 | No | `Name` | |
| Surname | `surName` | ContactSearch | 2 | No | `Name` | |
| Employee Number | `employeeNumber` | ContactSearch | 3 | Yes | `Search` | |
## Validate TOPdesk CRM Service
1. Confirm that CRM Service can reach the TOPdesk endpoint.
2. Search for a known TOPdesk person, contact, incident, or case from WebAgent.
3. Confirm that expected TOPdesk fields appear in WebAgent.
4. Confirm that phone-number recognition returns the expected TOPdesk record.
## References
* [TOPdesk API tutorial](https://developers.topdesk.com/tutorial.html)
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://atlas.anywhere.now/channels-integrations/crm-service/topdesk.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.