Business Assist SelfHelp API User Guide

Article
06/19/2024

The Business Assist SelfHelp API is a synchronous API that uses machine learning to suggest answers to user queries.

To use the API, first set up an Azure App Registration to authenticate your requests.

Microsoft is committed to storing and processing all personal data of commercial and public sector customers within their geo boundary. The offer applies to all core cloud services, which were identified as Azure, Microsoft 365, and Dynamics 365.To meet this commitment, European customers should use the European endpoint, and all other global customers should use the global endpoint.

Submit SelfHelp Solutions API Request

Send a POST request with the data in the request body to

Global endpoint

https://businessassist.microsoft.com/api/beta/selfhelp/insights

site_url: businessassist.microsoft.com
version: beta

European endpoint

https://eu.businessassist.microsoft.com/api/beta/selfhelp/insights

site_url: eu.businessassist.microsoft.com
version: beta

Field Name	Definition
`QueryText`	User query to provide insights and other information for.
`Locale`	query text locale. Defaults to "en-us" (US English).
`ClientContext`	Optional. (Required for CSP requests) Serialized JSON contextual information that client wants to send. Used for CSP requests.
`emailid`	Email identity associated with a tenant. Used for CSP requests.
`domainname`	Domain associated with a tenant. Used for CSP requests.

SelfHelp Solutions API sample request (Enterprise customers)

{
  "QueryText": "How to install Office",
  "Locale": "en-us"
}

SelfHelp Solutions API sample request (CSP customers)

The Optional clientcontext field can be used to parse the CSP partner's customer email or domain name. This is used to search for tenant id in AAD (Azure Active Directory) and parse it to self-help service. This is to ensure any "Service Incident" related to the tenant can be shared with the impacted tenant.

{
  "QueryText": "Help installing word",
  "Locale": "en-US",
  "ClientContext": {{"emailid": "test123@contoso.com"}}
}

Solutions API sample success response (Enterprise)

{
  "solution": [{
    "title": "How to install Office",
    "details": "<div>\r\n\t\t\t<p>To install office…</p></div>",
    "solutionConfidence": 0.5
  }],
  "webSearchResults": [{
    "title": "Installing Office 101",
    "details": "Step 1: Install Office…",
    "url": "https://support.microsoft.com/en-us/office/"
  }],
  "Incidents": [{
    "Id": "EX675941",
    "WorkloadDisplayName": "Exchange Online",
    "WorkloadName": "Exchange",
    "FeatureDisplayName": null,
    "Classification": "Advisory",
    "StartTime": "2023-09-19T20:19:40+00:00",
    "EndTime": null,
    "LastUpdatedTime": "2023-09-20T21:50:48.987+00:00",
    "ImpactDescription": "If action isn't taken, bulk messages sent with large BCC recipients may be rejected.",
    "Title": "We've detected an increase in email message rejections from multiple providers",
    "MessageText": "Title: We've detected an increase in email message rejections from multiple providers\n\nUser impact: If action isn't taken, bulk messages sent with large BCC recipients may be rejected.\n\nCurrent Status: We've detected an increase in rejections of bulk messages from multiple email providers. Please review the above recommendations and documentation to adhere to the bulk messaging best practices. \n\nThis communication will expire in 14 days and is scheduled to remain active for the full duration.",
    "MessagePublishedTime": "2023-09-19T20:32:08.937+00:00",
    "Severity": null,
    "AffectedTenantCount": 0,
    "IncidentStatusDisplayName": null,
    "IncidentIsResolved": false,
    "RelevanceConfidence": 0.851,
    "SimilarityScore": 7.0,
    "IncidentWeight": -1033.932,
    "PublishedIncident": true,
    "RelevanceType": "3wayMatch",
    "RelevanceConfidence3WayMatch": "0.851",
    "RelevanceConfidence2WayMatch": "0.0",
    "RelevanceConfidenceManualOverride": "0.0",
    "SimilarityScoreThreshold": 1.0,
    "RelevanceConfidenceThreshold": 0.7
  }]
}

Solutions API sample success response (CSP)

{
  "solution": [{
    "title": "Help installing word",
    "details": "<div>\r\n\t\t\t<p>To install Word</p></div>",
    "solutionConfidence": 0.5
  }],
  "webSearchResults": [{
    "title": "Installing Word 101",
    "details": "Step 1: Install Word",
    "url": "https://support.microsoft.com/en-us/office/"
  }],
  "Incidents": [{
    "Id": "EX675941",
    "WorkloadDisplayName": "Exchange Online",
    "WorkloadName": "Exchange",
    "FeatureDisplayName": null,
    "Classification": "Advisory",
    "StartTime": "2023-09-19T20:19:40+00:00",
    "EndTime": null,
    "LastUpdatedTime": "2023-09-20T21:50:48.987+00:00",
    "ImpactDescription": "If action isn't taken, bulk messages sent with large BCC recipients may be rejected.",
    "Title": "We've detected an increase in email message rejections from multiple providers",
    "MessageText": "Title: We've detected an increase in email message rejections from multiple providers\n\nUser impact: If action isn't taken, bulk messages sent with large BCC recipients may be rejected.\n\nCurrent Status: We've detected an increase in rejections of bulk messages from multiple email providers. Please review the above recommendations and documentation to adhere to the bulk messaging best practices. \n\nThis communication will expire in 14 days and is scheduled to remain active for the full duration.",
    "MessagePublishedTime": "2023-09-19T20:32:08.937+00:00",
    "Severity": null,
    "AffectedTenantCount": 0,
    "IncidentStatusDisplayName": null,
    "IncidentIsResolved": false,
    "RelevanceConfidence": 0.851,
    "SimilarityScore": 7.0,
    "IncidentWeight": -1033.932,
    "PublishedIncident": true,
    "RelevanceType": "3wayMatch",
    "RelevanceConfidence3WayMatch": "0.851",
    "RelevanceConfidence2WayMatch": "0.0",
    "RelevanceConfidenceManualOverride": "0.0",
    "SimilarityScoreThreshold": 1.0,
    "RelevanceConfidenceThreshold": 0.7
  }]
}

Field	Definition
`solution`	Instant answer to the user query. Contains `title`, `details` and `SolutionConfidence` score.
`title`	Solution or article title.
`details`	Preview text of article or content.
`solutionConfidence`	Algorithmic confidence score of the confidence the solution is relevant to the query.
`webSearchResults`	Related article from the web search.Contains the `title`, `details`, and `url` found through a web search.
`url`	Link to full content of the `WebSearchResults`.
`WorkloadDisplayName`	Workload display name.
`WorkloadName`	Workload name
`FeatureDisplayName`	Feature display name
`Classification`	Incident classification
`StartTime`	Incident start time
`EndTime`	Incident end time
`LastUpdatedTime`	Incident last updated time
`ImpactDescription`	Impact description for incident
`Title`	title for incident
`MessageText`	Latest message text for incident
`MessagePublishedTime`	Latest message published time for incident
`Severity`	Severity for incident
`AffectedTenantCount`	Affected tenant count
`IncidentStatusDisplayName`	Status name for incident
`IncidentIsResolved`	A value indicating whether the incident is resolved
`RelevanceConfidence`	Relevance confidence for incident
`SimilarityScore`	Similarity score for incident
`IncidentWeight`	Incident weight obtained from Relevance API
`PublishedIncident`	A value indicating whether incident is published
`Theme`	Theme for some types of incidents
`RelevanceType`	Relevance Type
`RelevanceConfidence3WayMatch`	Relevance Confidence 3WayMatch. Match (Query Text <-> Spike Cluster <-> SHD Post)
`RelevanceConfidence2WayMatch`	Relevance Confidence 2WayMatch. Match (Query Text <-> SHD Posts)
`RelevanceConfidenceManualOverride`	Relevance Confidence Manual Override
`SimilarityScoreThreshold`	Field to reflect the config setting base for `similarityscore`. Only set for qualifying incidents which meet the criteria. For others, The default is -1.
`RelevanceConfidenceThreshold`	Field to reflect the config setting base value for `RelevanceConfidence`. Only set for qualifying incidents which meet the criteria. For others, The default is -1.

SelfHelp Solutions success response code

Code	Explanation
`200`	Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request the response will contain an entity describing or containing the result of the action.

SelfHelp Solutions error responses

Error Code	Cause
`400`	InputData is null.
`403`	Missing permissions.
`500`	Submit request failed.

First time user of Business Assist SelfHelp API?

Overview: High-level introduction to Business Assist SelfHelp API.
Core concepts: Learn how Business Assist SelfHelp API works.
API reference: Familiarize yourself with the Business Assist SelfHelp API actions and data types.

Share via