How to get started...

  1. Onboarding:

    1. Request Access: Please request the necessary permission and details for the EYQ API, ensuring you specify the environment. Click here to access the request form

    2. Onboarding Confirmation: After processing your request, the EYQ Team will onboard you to the platform and provide the following details via email:

      • Client Details

      • App Scopes (for standard client access). Not required for service principal access

      • Subscription Key

  2. Steps to Get Started

    1. Create an Azure AD App Registration:

      • After receiving the details in the onboarding email, create an Azure Active Directory (AAD) app registration in your Azure portal.

      • For Standard Client Access, include the provided scopes as directed.

      • Service Principal Access does not require scopes but does require the app registration.

    2. API Request Headers:
      Standard Client Access:

      1. When making API calls, you need to include the following in the request header:

        • x-client-id: Your client ID

        • Ocp-Apim-Subscription-Key: Your subscription key

        • Bearer Access Token: The access token generated from the above app registration.

        Note: A user token is required for access. Please ensure that your token is valid and generated against the user’s account associated with the required permissions.

      Service Principal Access

      For service principal authentication, follow these steps:

      1. Use the following headers in your request:

        • x-client-id: Your Client ID

        • Ocp-Apim-Subscription-Key: Your subscription key

        • Authorization: Bearer Service Principal token

        • x-service-principal: true

      Important: The 'x-service-principal' header is necessary for the API to recognize the request as being made by a service principal.

  3. API Documentation:

    1. Initialize the Conversation:

    Before starting any interaction, you must initialize the conversation by making a `POST` request to the /api/v1/conversations/init endpoint. This is essential as it sets up the session for the chat. To begin a new chat session, you'll need to call this initialization endpoint again, ensuring that a fresh conversation context is created.

    2. Reference Conversation ID for Future Chats:

    After initializing a conversation, the API will return a unique conversation ID. This ID should be used as a reference for all subsequent chat messages within that particular conversation. To maintain continuity and track the flow of the chat, always reference this conversation ID when making API `POST` call to /api/v1/conversations.

    3. Generate a Conversation Title:

    You can generate a title for the conversation by making a `POST` request to the /api/v1/conversations/{conversationId}/generate-title endpoint. This action is necessary only once, and it should be performed when you receive the first response from the conversation API. A well-defined title helps in categorizing and revisiting past conversations efficiently.

    4. Integrate User Feedback:

    If you wish to allow users to provide feedback on the bot’s responses, integrate the /api/v1/conversations/{conversationId}/message-feedback endpoint using a `POST` request. Users can express their satisfaction by liking or disliking a message. Importantly, if a user dislikes a response, providing feedback becomes mandatory, ensuring that constructive criticism is captured to improve future interactions.

    5. Reference Documentation and Downloads:

    In each conversation, the bot may provide references from which the response was generated, along with specific page numbers. If users want to access or download the referenced documents, they can do so by calling the /api/v1/skills/{skillId}/version/{skillVersionId}/document endpoint using a `GET` request. This may include optional query parameters such as `documentName` or `documentId` for precise retrieval.

    6. View Past Conversations:

    Users can review their previous interactions by making a `GET` request to the /api/v1/conversations endpoint. This allows them to filter their search by parameters like `startDate`, `endDate`, `status`, `filters`, `sortOrder`, `sortColumn`, `pageNumber`, and `pageSize`. These parameters provide flexibility in retrieving conversations based on specific criteria and organizing the results in a user-friendly manner.

  4. Traceability:

    To enable tracing requests across the platform, you can generate a unique GUID and include it as an 'x-correlation-id' in the request header. This will help us trace the request if any issues occur.