DOCSEARCHbyAlgolia
Submit Docs

Coral Documentation

website·Indexed 35 days ago

https://docs.coralproject.net/

Documentation for Coral, featuring a GraphQL API for managing users, stories, and moderation. Includes guides on SSO configuration, GDPR compliance, webhook signing, analytics tool integration, and migration paths from Talk (v4.x) through Coral v8+.

Tokens
36K
Snippets
244
Records
388
Agent score
60%

What's inside Coral

  1. Understand Coral GraphQL API access requirements

    The Coral API is a GraphQL API. Access is restricted to administrative users only. Because of this restriction, the Coral API cannot be used for native app integrations that require non-administrative users to interact with the API.

  2. Understand Coral GraphQL API access restrictions

    The Coral API is a GraphQL API. Access is restricted to administrative users only. It cannot be used for native app integrations that require non-administrative users to interact with the API directly.

  3. External Moderation Request schema

    The ExternalModerationRequest object is sent by Coral to the callback URL. It contains details about the action being performed, the comment content, the author, the story, and tenant information.
    interface ExternalModerationRequest {
  /** "NEW" for new comments, "EDIT" for edits */
  action: "NEW" | "EDIT";
  comment: {
    body: string;
    parentID: string | null;
  };
  author: {
    id: string;
    role: "COMMENTER" | "STAFF" | "MODERATOR" | "ADMIN";
  };
  story: {
    id: string;
    url: string;
  };
  site: {
    id: string;
  };
  tenantID: string;
  tenantDomain: string;
}

  4. Understand the Coral Redis Cache architecture

    Introduced in Coral v8.0.0, the Redis Cache optimizes the retrieval of comment streams by caching comments, users, and comment actions data in Redis. This reduces the load on MongoDB, which now primarily serves as a write store for long-term data persistence. This architecture is specifically designed to handle extremely large and active streams (e.g., 4000+ comments with 500+ active users) while maintaining performance and reducing MongoDB scaling costs.

  5. Manage user data for GDPR compliance in Coral

    Coral provides built-in features to help administrators comply with the EU General Data Protection Regulation (GDPR) and provide users with control over their data. Available user-facing features include:

    • Comment Data Export: Users can request a CSV download of all their comments, including the associated story, comment ID, and timestamp.
    • Account Deletion: Users can request account deletion. Requests are pending for 24 hours (allowing for data download or reactivation) before permanently removing all comments, database actions, and account information.
    • Email Association: Users with OAuth/external accounts (e.g., Google, Facebook) are prompted to add an email address to enable GDPR-related communications.
    • Profile Management: Users can change their email, password, and username (username changes are limited to once every 2 weeks).

  6. Integrate an external moderation service with Coral

    External Moderation Phases allow you to integrate a custom moderation pipeline via HTTP. Coral sends a POST request with a JSON payload to a configured callback URL whenever a comment is created or edited.

    Key operational details:

    • Configuration: Set up the callback URL at /admin/configure/moderation/phases.
    • Execution Order: External moderation phases run last in the pipeline, only if all preceding moderation phases have not returned a status.
    • Timeout: The external service must respond within the designated timeout, or the action will be skipped.
    • Security: It is strongly recommended to verify the request signature using the same process as Coral webhooks.

  7. Customize Coral styling via Admin panel

    Because Coral uses Shadow DOM Encapsulation, styles from the parent page do not apply to the embed. To customize the appearance, add stylesheets in the Coral Admin panel:

    • Custom CSS: Navigate to Admin > Configure > Advanced > Custom CSS.
    • Custom Fonts: Navigate to Admin > Configure > Advanced > Custom Fonts CSS (used for @font-face imports).

  8. Set up Coral for local development

    To run Coral in development mode, you need NodeJS ^18.16.0 (using nvm is recommended). The setup involves cloning the repository, installing dependencies, ensuring MongoDB and Redis are running, and initializing the system.
    # Clone and enter the directory
git clone https://github.com/coralproject/talk.git
cd talk

# Install dependencies
sh scripts/pnpm-i.sh

# Initialize Coral
sh initialize.sh

  9. Embed the Coral comment stream on a page

    To add the Coral comment stream to a page, place a container element with a specific ID (e.g., coral_thread) and include the Coral embed script. The script loads embed.js from your Coral installation and initializes the stream using Coral.createStreamEmbed. You can find your specific embed code in the Coral Admin under Configure > Organization > Site Details.
    <div id="coral_thread"></div>
<script type="text/javascript">
  (function () {
    var d = document,
      s = d.createElement("script");
    var URL = "{{ CORAL_DOMAIN_NAME }}";
    s.src = "//" + URL + "/assets/js/embed.js";
    s.async = false;
    s.defer = true;
    s.onload = function () {
      Coral.createStreamEmbed({
        id: "coral_thread",
        autoRender: true,
        rootURL: "//" + URL,
      });
    };
    (d.head || d.body).appendChild(s);
  })();
</script>

  11. Migrate from Talk (v4.x) to Coral (v7.x+)

    Migrating from Talk (v4.x) to Coral (v7.x+) requires creating a completely new instance of the latest Coral version and migrating data into it, as Talk is no longer supported and the platform was rewritten to remove custom plugins in favor of core configurations and a TypeScript application model.

    Critical Requirement: Complete all data import steps before creating any new stories, users, or comments in the new Coral instance to avoid data conflicts.

  12. Install the commentEmbed.js script

    To enable comment embedding, add the commentEmbed.js script to your HTML tree. For optimal performance, place it within the <head> tag. If the page already includes the Stream Embed, this script is added automatically.
    <script
  class="coral-script"
  src="//{{ CORAL_DOMAIN_NAME }}/assets/js/commentEmbed.js"
  defer
></script>