Social+ Docs
About UsDeveloper PortalArchives
  • Social+
  • Announcements
  • Technical FAQ
  • Getting Started
    • Installation and Authentication
      • Install iOS SDK
      • Install Android SDK
      • Install JavaScript SDK (Deprecated)
      • Install TypeScript SDK
      • Install Flutter SDK
      • Install SDK for Ionic
    • Tutorials
  • Social+ SDK
    • Core Concepts
      • Session State
      • User
        • Create User
        • Get User Information
        • Search and Query Users
        • Update User Information
        • Delete User
        • Roles & Permissions
        • User Token Management
        • Flag / Unflag User
      • Files, Images, and Videos
        • File Handling
        • Image Handling
        • Video Handling
      • Push Notifications
        • iOS Push Notification Certificate Setup
        • Android Push Notifications Initialization
        • React Native Push Notifications Initialization
        • Register and Unregister Push Notifications on a Device
        • Push Notification Toggles
          • User Push Notification Settings
          • Channel Push Notification Settings
          • Community Push Notification Settings
      • Mentions
      • Poll
      • Ads
        • Get Ads and Settings
        • Ad Impressions
      • Presence State
        • Heartbeat Sync
        • User Presence
        • Channel Presence
      • Live Objects/Collections
        • iOS Live Objects/Collections
        • Android Live Objects/Collections
        • Javascript Live Objects/Collections
        • TypeScript Live Objects/Collections
        • Flutter Live Objects/Collections
      • Realtime Events
        • Social Realtime Events
        • Chat Realtime Events
      • Error Handling
      • Content Moderation
      • Logging
    • Chat
      • Channels
        • Create Channel
        • Query Channels
        • Get Channel
        • Get Channels
        • Update Channel
        • Join/Leave Channel
        • Subchannel
        • Message Preview
        • Unread Count
          • Channel Unread Count
          • Start / stop message read receipt sync
          • Mark Message as Read
          • Message Delivery Status
          • Observe reading count
        • Read Status & Unread Count (Legacy)
        • Channel Moderation
        • Query Members
        • Search Members
        • Archive Channels
      • Messaging
        • Send a Message
          • Text Message
          • Image Message
          • Audio Message
          • Video Message
          • File Message
          • Custom Message
          • Reply to a Message
        • Query and Filter Messages
        • Get and View a Message
        • Edit and Delete Messages
        • Message Reaction
        • Mention in Messages
        • Flag/Unflag a Message
      • Moderation
        • Roles and Permission
        • Mute/Unmute a List of Channel Members
        • Ban/Unban a List of Channel Members
        • Channel Rate-Limiting
    • Social
      • Posts
        • Create Post
          • Text Post
          • Image Post
          • File Post
          • Video Post
          • Live stream Post
          • Poll Post
          • Custom Post
        • Query Post
        • Get Post
        • Viewing Post Content
        • Edit Post
        • Delete Post
        • Mention in Post
        • Flag / Unflag Post
        • Post Review
        • Post Impression
        • Pinned Post
      • Stories
        • Get Global Story Targets
        • Create Story
        • Get Stories
        • Delete Story
        • Get Story Targets
        • Story Impressions
      • Comments
        • Create Comment
        • Query Comment
        • View Comment
        • Get Comment
        • Get Latest Comment
        • Edit Comment
        • Delete Comment
        • Flag/Unflag
        • Get Comment Reaction Data
        • Mention in Comment
      • Reactions
        • Query Reactions
        • Add / Remove Reaction
      • Feed
        • Custom Post Ranking
        • Query Global Feed
      • Communities
        • Create Community
        • Get Community
        • Query Communities
        • Update Community
        • Delete Community
        • Join/Leave Community
        • Trending and Recommended Communities
        • Query Community Members
        • Community Moderation
        • Community Categories
      • Follow/Unfollow
        • Get Connection Status and Connection Counter
        • Follow/Unfollow User
        • Get Follower/Following List
        • Accept/Decline Follow Request
      • Block and Unblock User
      • Intelligent Search
        • Intelligent Search - Post
        • Intelligent Search - Community
      • Notification tray
        • Get Notification Tray Seen
        • Mark Notification Tray Seen
        • Query Notification Tray Item
        • Mark Notification Tray Item Seen
    • Video
      • iOS
        • View & Play Live Stream
        • Broadcast Live Stream
        • Push Notifications
      • Android
        • View & Play Live Stream
        • Broadcast Live Stream
        • Push Notifications
      • Flutter
        • View & Play Live Stream
        • Push Notifications
      • Web
        • View & Play Live Stream
        • Create Live Stream
        • Push Notifications
      • TypeScript (Beta)
        • RunQuery Pattern
        • Live Stream
      • React Native
        • View & Play Live Stream
        • Broadcast Live Stream
    • Changelogs & Versioning
      • iOS
      • Android
      • TypeScript
      • React Native
      • Flutter (Beta)
      • React Native (Video)
      • JavaScript (Deprecated)
  • Social+ UIKit
    • UIKit 4
      • Installation Guide
        • iOS
        • Android
        • Web React
        • Flutter (Beta)
        • React Native (Beta)
      • Setup and Authentication
        • iOS
        • Android
        • Web React
        • Flutter (Beta)
        • React Native (Beta)
      • Customization
        • Remote Config
        • Customization Basics
        • Overriding Navigation Behaviour
      • Social
        • Discover & Search
          • Social Home Page
            • Top Navigation Component
            • Newsfeed Component
            • Empty Newsfeed Component
            • Global Feed Component
            • Create Post Menu Component
            • Community Categories Component
            • Recommended Communities Component
            • Trending Communities Component
          • Global Search Page
            • Top Search Bar Component
            • Community Search Result Component
            • User Search Result Component
          • My Communities Search Page
          • All Categories Page
          • Communities By Category Page
          • Notification Tray
        • Community
          • Community Setup Page
            • Add Category Page
            • Add Member Page
          • Community Profile Page
            • Community Header Component
            • Community Feed Component
            • Community Pin Feed Component
            • Community Image Feed Component
            • Community Video Feed Component
          • Pending Post Page
            • Pending Post Content Component
          • Community Setting Page
            • Community Notification Setting Page
              • Community Posts Notification Page
              • Community Comments Notification Page
              • Community Stories Notification Page
            • Community Post Permissions Page
            • Community Story Setting Page
          • Community Membership Page
        • User
          • User Profile Page
            • User Profile Header Component
            • User Feed Component
            • User Image Feed Component
            • User Video Feed Component
          • Edit User Profile Page
          • Blocked User Page
          • User Relationship Page
          • User Pending Follow Request Page
        • Post
          • Post Details Page
            • Post Content Component
          • Post Composer Page
            • Media Attachment Component
            • Detailed Media Attachment Component
          • Post Target Selection Page
          • Poll Post Composer Page
          • Poll Target Selection Page
        • Livestream
          • Livestream Target Selection Page
          • Livestream Creation Page
          • Livestream Player Page
          • Livestream Terminated Page
        • Story
          • Story Target Tab Component
          • Story Creation Page
            • Story Drafting Page
          • Story Viewing Page
          • Story Target Selection Page
        • Comment & Reaction
          • Comment Tray Component
          • Reaction List Component
        • Content moderation
      • Chat
        • Recent chats (channel list)
          • Chat Home Page
          • Chat List Component
          • Archived Chat List Component
          • Amity Channel Create Conversation Page
        • Conversation Chat
          • AmityChatPage
          • AmityMessageComposer
        • Live Chat
          • Live Chat Page
            • Live Chat Header Component
            • Live Chat Message List Component
              • Reaction List Component
            • Live Chat Compose Bar Component
    • UIKit 3
      • iOS (Deprecated)
        • Overview
        • iOS UIKit Installation Guide
        • Installing UIKit (deprecated)
        • Setup & Authentication
        • Using Themes
        • Social UIKit
          • Using as a whole feature with the default settings
          • Our Components
            • Community Home Page
              • Newsfeed
                • Global Feed
                • My Community Preview
              • Explore Tab
                • Recommended Community
                • Top Trending
                • Categories
            • My Community Page
            • Category List Page
            • Community List by Category Page
            • Community Creation Page
            • Community Profile Edit Page
            • Community Setting Page
              • Community Push Notification Settings Page
                • Community Push Notification Settings - Comment and Reply Relate Event Page
                • Community Push Notification Settings - Post Relate Event Page
            • Post Creation Page
              • Livestream Post
            • Post Detail Page
            • Post Edit Page
            • Comment Creation
            • Comment Edit Page
            • Community Profile Page
              • Community Feed
              • Media Gallery
            • Community Member Page
            • User Profile Page
              • User Feed
            • User Profile Page (2.2)
              • User Feed (2.2)
            • User Setting Page(2.2)
            • User Profile Edit Page
            • Following / Follower User List Page (2.2)
            • Follow Request Page (2.2)
            • Member Selection Page
            • Post Target Selection Page
          • Using Your Own Component
            • Using Your Own Navigation Bar
          • Overriding UIKit Behaviour
            • Feed UI Settings
              • Post Sharing
              • Post Rendering
            • Event Handling
              • Example
          • Roles & Permissions
        • Chat UIKit
          • Using as a Whole Feature with the Default Settings
          • Using Only Some Components
            • Chat Home Page
              • Recent chat
            • Chat Room Page
          • Using your own component
            • Message Bubble
        • Video UIKit
          • Livestream
      • Android (Deprecated)
        • Overview
        • Android UIKit Installation Guide
        • Installing UIKit (deprecated)
        • Setup & Authentication
        • Using Themes
        • Social UIKit
          • Using as a whole feature with the default settings
          • Our Components
            • Community Home Page
              • Newsfeed
                • Global Feed
                • My Community Preview
              • Explore Tab
                • Recommended Community
                • Top Trending Community
                • Categories
            • My Community Page
            • Category List Page
            • Community List By Category Page
            • Community Creation Page
            • Community Profile Edit Page
            • Post Creation Page
              • Livestream Post
            • Post Details Page
            • Post Edit Page
            • Comment Creation
            • Comment Edit Page
            • Community Profile Page (2.5)
              • Community Feed (2.5)
              • Media Gallery
            • Community Member Page
            • User Profile Page
              • User Feed
            • User Profile Page (2.3)
              • User Feed (2.3)
            • User Setting Page (2.3)
            • Following and Follower User List Page(2.3)
            • Follow Request Page (2.3)
            • User Profile Edit Page
            • Member Selection Page
            • Post Target Selection Page
          • Using Your Own Components
            • Using Your Own Navigation Bar
          • Overriding UIKit Behaviour
            • Overriding Global Behaviour
              • Feed UI Settings
                • Post Sharing
                • Post Rendering
            • Event Handling
              • Example
        • Chat UIKit
          • Using as a whole feature with the default settings
          • Using Only Some Components
            • Chat Home Page
              • Recent Chat
            • Chatroom Page
          • Using Your Own Component
            • Message Bubble
      • React (Deprecated)
        • Overview
        • Web UIKit Installation Guide
        • Installing UI Kit (deprecated)
        • Setup & Authentication
        • Using Themes
        • Social UIKit
          • Using as a whole feature with the default settings
          • Our Components
            • Community Home Page
              • Search Communities
              • Newsfeed
                • Global Feed
              • Explore
                • Recommended Communities
                • Top Trending Communities
                • Categories
            • My Community
            • Community List By Category Page
            • Community Creation Page
            • Community Settings
              • Edit Profile Page
              • Members
              • Permissions
            • Post Creation
              • Livestream Post
            • Post Edit
            • Comments
            • Community Profile Page
              • Community Feed
              • Media Gallery
              • Community Members Page
              • Transfer Moderator Role
            • User Profile
              • User Feed
              • Media Gallery
              • Following / Follower User List Page
            • Follow Request Page
            • Profile Settings Page
          • Using Your Own Component
            • Using Your Own Like Button for Posts
          • Overriding UIKit Behaviour
            • Post Rendering
        • Chat UIKit
          • Using as a Whole Feature with the Default Settings
          • Our Components
            • Recent Chat
            • Chat Room
            • Message Bubble
            • Chat Details
        • Event Handling
          • Example
        • Roles & Permissions
      • Flutter (Beta)
        • Overview
        • Flutter UIKit Installation Guide
        • Setup & Authentication
        • Using Themes
        • Social UIKit
          • Using as a whole feature with the default settings
      • React Native (Beta)
        • Setup & Authentication
        • Running the Sample App with Expo
    • Changelogs
      • iOS
      • Android
      • Flutter
      • Web (React)
      • React Native
        • React Native Chat UIKit
        • React Native Social UIKit
  • Analytics & Moderation
    • Social+ Portal
      • Getting Started
      • Application Management
      • Account Management
      • Dashboard
        • Raw Data Export
      • Changelogs
    • Social+ Console
      • Moderation, Roles & Privileges
      • Chat Management
        • Channel Management
        • Message Management
        • Chat Activities (Beta)
      • Social Management
        • Communities
        • Posts
          • Post Viewing and Management
          • Post Creation
          • Post Pinning and Featuring
        • Comments
          • Comment Viewing and Management
          • Comment Creation and Reply
        • Stories
      • User & Content Management
        • User Social History
      • Admin Access Control
      • Livestream Moderation
      • Premium Ads
        • Setting Up Premium Ads
        • Setting Up Advertiser Profile
      • Settings
        • Image Moderation
        • Push Notifications
        • Security
          • Admin Token Management
        • Brand Settings
      • AI Content Moderation
      • Changelogs
    • Social+ APIs and Services
      • Network Settings
      • Generate User Last Activity Report
      • Pre-Hook Event
  • Developers
    • Developer Kits
    • Beta Features
      • Enhance Moderation
      • Search Posts API
      • Content Search V2 (Deprecated)
      • Webhook Events
      • Notification Tray
      • Block User
      • User Activity
    • Migration Guides
      • FCM legacy API Migration Guide
      • SDK v6.26.0 Unread Count Migration Guide
      • JS SDK to TS SDK Migration Guide
      • Web UIKit v3.0 Migration Guide
      • iOS UIKit V3.0 Migration Guide
      • iOS SDK v7.0.0 Migration Guide
      • iOS SDK v6.0.0 Migration Guide
        • iOS SDK v6.9.0 Deprecation Note
        • iOS SDK v6.8.0 Deprecation Note
        • iOS SDK v6.7.0 Deprecation Note
        • iOS SDK v6.5.0 Deprecation Note
      • Android SDK v7.0.0 Migration Guide
      • Android SDK v6.0.0 Migration Guide
        • Android SDK v.6.20.0 Deprecation Note
        • Android SDK v.6.19.0 Deprecation Note
        • Android SDK v6.10.0 Deprecation Note
        • Android SDK v6.9.0 Deprecation Note
        • Android SDK v6.5.0 Deprecation Note
      • TS SDK v7.0.0 Migration Guide
      • TS SDK v6.0.0 Migration Guide
        • TS SDK v6.4.6 Deprecation Note
        • TS SDK v6.8.0 Deprecation Note
      • Web SDK v5.0.0 Migration Guide
      • Flutter SDK v7.0.0 Migration Guide
      • Flutter SDK beta Migration Guide
        • Flutter SDK v0.21.0 Deprecation Note
    • SDK API Reference
      • Server API Reference
      • iOS SDK API Reference (beta)
      • Android SDK API Reference (beta)
      • Flutter SDK API Reference
  • Miscellaneous
    • Support
      • Code of conduct
      • Managed UI Kit - Deprecation
      • Contribute
      • Security
    • Announcements Archive
Powered by GitBook
On this page
  • Overview
  • Configurations
  • Implementation
  • Components
  • Security
  • Response Handling
  • Error Handling
  • Supported Events

Was this helpful?

Export as PDF
  1. Analytics & Moderation
  2. Social+ APIs and Services

Pre-Hook Event

Last updated 6 months ago

Was this helpful?

Overview

Our Pre-Hook Event feature has been designed to offer customers increased control over user-generated content, community access, and the moderation of sensitive material. This enhancement not only provides a safer environment for applications but also empowers users to create custom moderation rules tailored to their specific requirements.

The Pre-Hook Event feature delivers a range of functionalities that users can employ to establish a more controlled environment within their applications. By enabling the Pre-Hook Event feature through network settings and adjusting the configuration parameters as needed, users can define custom rules and implement APIs to create custom use cases for enhanced moderation. This may include measures such as denying entrance to specific channels for certain users or modifying messages containing sensitive words before they are sent.

The system is designed to trigger pre-hook events for major available actions. Users can monitor the three response types provided by the APIs (allow, deny, and API timeout) and implement proper error handling measures to manage API error cases, ensuring a seamless user experience.

Please note that this feature is only available for customers who are on the max plan.

Configurations

To make the most of the Pre-Hook Event feature, follow these steps to implement it in your application:

  1. Enable the Feature: Access your network settings through the and enable the Pre-Hook Event feature. While doing so, adjust the configuration parameters, such as enabled, callbackUrl, and defaultAction, according to your requirements.

  2. Create Custom Rules: Develop custom moderation rules based on your application's specific needs. These rules will help you address unique use cases and strengthen your moderation measures.

  3. Implement APIs: Use the provided APIs to create custom use cases for enhanced moderation. These use cases can include denying entrance to specific channels for certain users, modifying messages containing sensitive words before they are sent, and more.

  4. Monitor API Responses: Keep track of the three response types provided by the APIs: allow, deny, and API timeout. These responses will give you insight into the success or failure of your custom rules and actions. Here are the example of request and response of pre-hook event.

Timeout of the provided pre-hook callback is 3 seconds. If it exceeds the timeout, it will execute the provided default action instead.

Request:

{
  "eventName": "message.shouldCreate",
  "data": {
    "key": "value"
  },
  "actor": {
    "_id": "string",
    "userId": "string"
  }
}

Response:

{
  "action": "allow",
  "data": {
    "key": "modified value"
  },
  "message": "string"
}
  1. Error Handling: Ensure that you have a robust error handling mechanism in place to manage API error cases effectively. Proper error handling will contribute to a seamless user experience and prevent potential disruptions.

Implementation

The following sections explain the components, response handling, and error handling involved in the Pre-Hook Event feature.

Components

The external system's response must include the following components:

  1. HTTP status code = 200

  2. Response object with three possible scenarios:

    a. Allow the action without modification: { "action" : "allow" }

    b. Allow the action with modification: { "action" : "allow", "data" : { ... } // Modified data object }

    c. Deny the action: { "action" : "deny", "message" : "this is an error message" }

  3. Signature key to ensure the security between the server and the client.

If a modified data object is returned, its data schema must match the original one.

Security

The security of the pre-hook events feature is ensured through the use of a signature key, which are crucial components in maintaining the confidentiality and integrity of the communication between the server and the client.

Secret Key

  1. Upon configuring and enabling the pre-hook feature for the first time, a secret key is generated. This secret key is a randomly generated 16-byte hexadecimal string.

  2. The secret key serves as a shared symmetric key between the server and the client, which is used for authentication purposes.

  3. In case the secret key is leaked, it can be regenerated to maintain security.

  4. Only network administrators are allowed to access and update the pre-hook setting and regenerate the secret key.

  5. The secret key is available in the update setting API response only when enabling the feature for the first time or when regenerating the secret key. It is not available in the get setting API or when updating other fields.

Signature Key

  1. The signature key is used to authenticate the payload on the external system.

  2. It is computed using the HMAC Base64 digest of the request body. The HMAC Base64 digest is generated by performing the SHA-256 hash function with the secret key as the HMAC key, the request body as the payload, and digested as a Base64 string. Here's an example of generating a signature key from a secret key:

function genSignature(secretKey: string, payload: any): string {
  const hmac = crypto.createHmac('sha256', secretKey);
  hmac.update(JSON.stringify(payload));
  return hmac.digest('base64');
}

const payload = {
  eventName: 'message.shouldCreate',
  data: {
    ...
  },
  actor: {
    _id: 'privateId',
    userId: 'publicId'
  }
}
genSignature('secret', payload)
  1. The signature key is included in the request header, ensuring secure communication between the server and the client.

  2. To verify the signature key on the client side, they could do this by computing the hash with the above method and comparing it with the one in the request header. Here is an example

const signatureKey = req.headers['ASC-Signature-Key'];
const payload = req.body

const hmac = crypto.createHmac('sha256', secretKey);
hmac.update(JSON.stringify(payload));
const hash = hmac.digest('base64');

if (hash !== signatureKey) {
  throw new Error('Invalid signature!')
}

Example of an HTTP request with a signature key attached:

curl --location --request POST '<<CALLBACK_URL>>' \
--header 'ASC-Signature-Key: <<SIGNATURE_KEY>>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "eventName": "channel.shouldCreate",
  "actor": {
    "_id": "63aab2059c25c70d98c32ecc",
    "userId": "sam"
  },
  "data": {
    "key": "value"
  }
}'

Response Handling

  1. If the action is "allow", the system continues with the remaining application flow, using either the modified data payload (if provided) or the original payload.

  2. If the action is "deny", the system returns an error to the caller with code 400000 as a BadRequestError:

    {
      "errorCode" : 400000,
      "message" : "error message from deny action or BusinessError if null"
    }

Error Handling

In cases where the response object doesn't adhere to the specified format, or the request takes longer than 3 seconds, the system executes the following error handling flow:

  1. Log the error with the endpoint URL, response status code, response object (trimmed to 300 characters length), or null if the request times out, and the error reason.

  2. Use the default action (allow or deny) as configured in the setting. If the "deny" action is configured, the system returns an error to the caller with code 500401 as a BusinessError:

    {
      "errorCode" : 500401,
      "message" : "error message from BusinessError due to external system error"
    }

If the pre-hook service is unavailable or unresponsive due to reaching maximum capacity or other internal server problems, the system executes the following error handling flow:

Use the default action (allow or deny) as configured in the setting. If the "deny" action is configured, the system returns an error to the caller with code 500000 as a BusinessError:

{
  "errorCode" : 500000,
  "message" : "error message from BusinessError due to internal error"
}

Once the pre-hook process is completed, the system logs the pre-hook URL, response action, and response duration.

Supported Events

Module
Event
Request Data
Modifiable Response Data
REST API Endpoint

Chat

message.shouldCreate

  • Message Data

  • Sender ID

  • Channel ID

  • Message Data

POST /api/v5/messages or /api/v3/messages

message.shouldUpdate

  • Message Data

  • Sender ID

  • Channel ID

  • Message Data

PUT /api/v5/messages or /api/v3/messages

message.shouldFlag

  • Message Data

  • Sender ID

  • Flag Count

  • Message Data

POST /api/v5/messages/{messageId}/flag or /api/v3/messages/{messageId}/flag

message.shouldUnflag

  • Message Data

  • Sender ID

  • Flag count

  • Message Data

DELETE /api/v5/messages/{messageId}/unflag or /api/v3/messages/{messageId}/unflag

channel.shouldCreate

  • Channel Data

  • Creator ID

  • Channel Data

POST /api/v3/channels or /api/v3/channels/conversation

channel.shouldJoin

  • Channel ID

  • User ID

-

POST /api/v3/channels/{channelId}/join

channel.shouldLeave

  • Channel Data

  • User ID

  • Channel Data

DELETE /api/v3/channels/{channelId}/leave

Social

post.shouldCreate

  • Post Data

  • Creator ID

  • Entity ID

  • Post Data

POST /api/v4/posts

post.shouldUpdate

  • Post Data

  • Creator ID

  • Entity ID

  • Post Data

PUT /api/v4/posts/{postId}

post.shouldFlag

-

-

POST /api/v3/posts/flag

post.shouldUnFlag

-

-

DELETE /api/v3/posts/unflag

comment.shouldCreate

  • Comment Data

  • Creator ID

  • Post ID

  • Comment Data

POST /api/v3/comments

comment.shouldUpdate

  • Comment Data

  • Creator ID

  • Post ID

Comment Data

PUT /api/v3/comments

comment.shouldFlag

-

-

POST /api/v3/comments/flag

comment.shouldUnFlag

-

-

DELETE /api/v3/comments/unflag

community.shouldJoin

  • Community ID

  • User ID

-

POST /api/v3/communities/{communityId}/join

community.shouldLeave

  • Community ID

  • User ID

-

DELETE /api/v3/communities/{communityId}/leave

community.shouldCreate

  • Community Data

  • Creator ID

  • Community Data

POST /api/v3/communities

community.shouldUpdate

  • Community Data

  • Creator ID

  • Community Data

reaction.shouldCreate

-

-

POST /api/v2/reactions

follow.shouldUnfollow

  • Follow Data

-

DELETE /api/v4/me/following/{userId}

follow.shouldRequest

  • Follow Data

-

POST /api/v4/me/following/{userId}

Core

user.shouldFlag

-

-

POST /api/v4/me/flags/{userId}

user.shouldUnflag

-

-

DELETE /api/v4/me/flags/{userId}

pre-hook configuration API