🕸️Web Component

Integrating your bot into your website enhances user engagement and provides seamless support directly on your platform. This process is straightforward and involves embedding a small snippet of code.

Web Component Integration

To use the chat element component in your website, follow these steps:

1. Provide us the origin of the page you want to integrate

2. Add the following script tag to your HTML file:

<script 
  type="module"
  src="https://assets.theblockbrain.io/scripts/blocky-chat/blocky-chat.bundle.js"
  async
>
</script>

3. Add the <blockbrain-main> tag where you want to include the chat component:

<blockbrain-main
    clientId="clientId"
    secretKey="secretKey"
    orgId="orgId"
    uid="uid"
    userUid="userUid">
</blockbrain-main>

4. Replace clientId and secretKey with your actual client ID and secret key, the uid with the accountNo / machineUID and userUid with a unique User ID, if you have one that you can send - otherwise just remove it.

Private Mode Integration (Authenticated Usage)

For secure and authenticated usage, configure the web component in private mode using the issuer attribute.Attributes Required:

• orgId: Organization ID provided for your instance.

• issuer: URL of your blockbrain domain.

• uid: Unique identifier for the bot instance or application.

• userUid: Unique identifier for the user (optional).

Example:

<blockbrain-main 
  orgId="your-org-id" 
  issuer="https://your-blockbrain-domain.com" 
  uid="your-uid" 
  userUid="optional-user-id">
</blockbrain-main>

---

Public Mode Integration (Non-Authenticated Usage)

For scenarios where authentication is not required, configure the web component in public mode using the clientSecretattribute.Attributes Required:

• orgId: Organization ID provided for your instance.

• clientSecret: A client secret to enable public mode.

• uid: Unique identifier for the bot instance or application.

• userUid: Unique identifier for the user (optional).

Example:

<blockbrain-main 
  orgId="your-org-id" 
  clientSecret="your-client-secret" 
  uid="your-uid" 
  userUid="optional-user-id">
</blockbrain-main>

Customization

Extend the <blockbrain-main> tag and make it your own by adding several attributes:

<blockbrain-main
    clientId="your-clientId"
    secretKey="your-secretKey"
    orgId="your-orgId"
    issuer="my-issuer-url"
    layout="minimal"
    iconUrl="https://example.com/default-icon.png"
    iconSize="50px"
    messages='{
        "notCreated": {
            "iconSize": "100px",
            "title": "Bot Setup Completed",
            "description": "The bot setup is completed. Redirecting you to your bot..."
        },
        "completed": {
            "iconSize": "106px",
            "title": "Custom Completed Title",
            "description": "Custom completed description."
        },
        "requested": {
            "iconSize": "56px",
            "title": "Custom Requested Title",
            "description": "Custom requested description."
        },
        "needAttention": {
            "title": "Custom Attention Needed",
            "description": "Custom need attention description."
        },
        "rejected": {
            "title": "Custom Rejected Title",
            "description": "Custom rejected description."
        },
        "loading": {
            "iconUrl": "https://cdn-1.webcatalog.io/catalog/blockbrain/blockbrain-icon-filled-256.webp?v=1714777605928",
            "iconSize": "106px",
            "title": "Custom Loading Title",
            "description": "Custom loading description."
        },
        "error": {
            "title": "Custom Error Title",
            "description": "Custom error description."
        },
        "missingParams": {
            "title": "Configuration Error",
            "description": "It looks like something is missing from your setup. Please check your configuration and try again."
        }
    }'>
</blockbrain-main>

Attribute Descriptions

• iconUrl (optional)

  • Description: URL to a default icon image used for all messages if a specific iconUrl for the message is not provided.

  • Customization: Use the iconUrl property inside a specific status message to override this default.

  • Hide the Icon: To hide the icon for a message, set its iconUrl to an empty string ("").

  • Example: "https://example.com/default-icon.png"

• iconSize (optional)

  • Description: Specifies the size of the default icon.

  • Customization: You can override the size for a specific status message by specifying its iconSize.

  • Values: Accepts any valid CSS size (e.g., 50px, 4rem, 100%).

• messages (optional)

  • Description: A JSON string that allows you to customize the titles and descriptions for various statuses.

  • Structure: The messages attribute is a JSON string that allows you to customize the appearance of each status. Each status has the following customizable properties:

    • iconUrl (optional): URL to an icon specific to this status. Use an empty string ("") to hide it.

    • iconSize (optional): Overrides the default iconSize for this status.

    • title (optional): Heading text for the status. Use an empty string ("") to hide it.

    • description (optional): Text displayed below the title. Use an empty string ("") to hide it.

  • Status Keys:

    • notCreated: Displayed when no bot is found for the provided botUid. The user may need to request the bot.

    • completed: Displayed when the bot setup is complete, with an optional redirection notice.

    • requested: The bot request is submitted, and the bot will be ready in a few seconds. The user may need to refresh the page to display the bot

    • needAttention: Requires admin or user action to proceed with the bot setup.

    • rejected: Displayed when the bot request is rejected.

    • loading: Shown during initialization or other loading operations.

    • error: Indicates a failure during the bot setup process.

    • login: Shown on login page

Web Part: Deployment & Configuration Guide

Use this guide to deploy, configure, and troubleshoot your Blockbrain Chat SPFx Web Part in SharePoint Online.

1. Deploy the Package to SharePoint

1. Access the App Catalog

2. Navigate to your SharePoint Online App Catalog site. Usually the URL is something like:

https://<your-tenant>.sharepoint.com/sites/AppCatalog

1. Upload the Package

   1. Go to Apps for SharePoint (in the left navigation).

   2. Click Upload and select the .sppkg file from the sharepoint/solution folder of your project.

   3. When prompted, check Make this solution available to all sites in the organization if you want it globally available.

      
   4. Click Deploy.

      
2. Verify Deployment

   • If you selected Make this solution available to all sites, the web part should automatically be available on all site collections.

   • Otherwise, you may need to explicitly add the app to the site where you want to use it.

---

2. Add the Web Part to a SharePoint Page

1. Navigate to Your SharePoint Site

2. Go to the site where you want to add the chatbot.

3. Edit the Page

4. Click on the gear icon and select Edit Page or Edit.

5. Add the Web Part

   • Click on the + icon to add a new web part.

   • Search for BlockbrainChat (or the name you provided during setup).

   • Add it to the page.

   

---

3. Web Part Configuration

The new web part has three primary configuration sections in its Property Pane: Authentication, Content, and Appearance.

1. Open the Web Part Property Pane

   • While the page is in Edit mode, select the Blockbrain Chat web part.

   • Click the pencil icon to open the web part’s property pane.

2. Authentication

   • Login Mode (loginMode)

     • Private Login: Uses an issuer URL (auth endpoint).

     • Public Login: Uses clientId and secretKey for public authentication.

   • Issuer (Private Login only) (issuer)

     • Provide the issuer endpoint URL if you have set loginMode to "private".

   • Client ID / Secret Key (Public Login only) (clientId, secretKey)

     • Provide the OAuth2 credentials to authenticate with Blockbrain if you have set loginMode to "public".

3. Content

   • Bot Unique Identifier (uid)

     • Enter the bot UID if you want to specify a particular bot.

     • This can also be overridden by URL parameters (e.g., ?uid=your-bot-id).

4. Appearance

   • Width & Height (width, height)

     • Accepts any valid CSS size value: e.g., 100%, 600px, 50vh, etc.

     • Use % or viewport units for responsive design, or px for a fixed size.

   • Icon URL (iconUrl)

     • Provide a direct URL to the icon you want displayed in the chat.

   • Icon Size (iconSize)

     • Set the size of the icon (e.g., 50px, 96px).

   • Custom Messages JSON (messages)

     • Allows you to override or customize system messages. Must be valid JSON.

   • Background Color (backgroundColor)

     • Pick a color from the color picker or input a hex code (e.g., #FFFFFF).

5. Web Part Title

   • By default, the web part will show a title area. You can edit it directly on the page:

     1. Click on the web part title text.

     2. Enter your custom title (e.g., “Customer Support Chat”).

     3. Press Enter or click outside to save.

6. Saving and Publishing

   • After you finish configuring the properties, click Apply (if needed), then Publish the page.

---

4. Additional Configuration Options

1. URL Parameters

   • You can override the bot UID by appending ?uid=YOUR_BOT_UID to the page URL.

   • Similarly, you can specify a userUid with ?userUid=SOME_VALUE to track or identify the user differently.

2. For Detailed Prop Documentation

   • Refer to the official Blockbrain Docs for additional, up-to-date property references and usage examples.

---

5. Troubleshooting & Common Issues

1. Script Loading Issues

   • Correct External Script URL: Ensure you haven’t altered the blocky-chat.bundle.js URL.

   • Network / Proxy Restrictions: If your company network blocks external scripts, ensure https://assets.theblockbrain.io/ is allowed.

2. Authentication Errors

   • Double-check loginMode, issuer, clientId, and secretKey in the property pane.

   • If using private login, ensure the issuer endpoint is correct.

   • If using public login, ensure both client ID and secret key are valid.

3. Bot Not Found

   • Verify the uid you provided (either in the web part property or URL) is a valid bot UID from your Blockbrain environment.

4. Web Part Not Appearing or ‘Not Found’

   • Ensure you uploaded the .sppkg file to the App Catalog.

   • Check Make this solution available to all sites if you want it to appear in site collections.

   • If not, add the solution to your specific site’s Site Contents.

5. Other Users Cannot View the Web Part

   • Confirm that the web part (and the underlying script) is shared or accessible by all intended users.

   • If the script is externally hosted, verify that the script domain is not restricted by tenant policies.