tencent cloud

Feedback

Before Official Account Message Is Sent

Last updated: 2024-06-18 16:12:01

    Feature Overview

    This webhook allows the app backend to view the broadcast messages of a official account in real time, including:
    Records official account messages in real time, for example, by recording a log or synchronizing the messages to other systems.
    Blocks users' requests to send messages on a official account.
    Caution
    The pre-message webhook defaults to a 2-second timeout and does not support adjustments. Using this for content review will add two instances of public network transmission, thereby at least doubling the overall latency compared to regular scenarios.

    Notes

    To enable the webhook, you must configure the Webhook URL and activate the switch corresponding to this webhook protocol. For detailed configuration instructions, please refer to the Webhook Configuration document.
    During this webhook, the IM backend initiates an HTTP POST request to the app backend.
    After receiving the webhook request, the app backend must check whether the SDKAppID contained in the request URL is consistent with its own SDKAppID.
    For additional safety-related concerns, please refer to the Webhook Overview: Security Considerations document.

    Webhook Triggering Scenarios

    An app user sends a Official Account Message via the client.
    The app administrator sends a Official Account Message via RESTful APIs.

    Webhook Triggering Timing

    The webhook is triggered before the Chat backend sends a Official Account Message to subscribers.

    API Calling Description

    Sample request URL

    In the subsequent example, the webhook URL configured within the app is https://www.example.com. Example:
    https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform

    Request parameters

    Parameter
    Description
    https
    The request protocol is HTTPS, and the request method is POST.
    www.example.com
    Webhook URL.
    SdkAppid
    The SDKAppID assigned by the Chat console when an app is created.
    CallbackCommand
    Fixed as OfficialAccount.CallbackBeforeSendMsg.
    contenttype
    Fixed value: JSON.
    ClientIP
    Client IP, such as: 127.0.0.1.
    OptPlatform
    Client Platform, for values please refer to Webhook Overview: Webhook Protocol for the meaning of the OptPlatform parameter.

    Sample request

    {
    "CallbackCommand": "OfficialAccount.CallbackBeforeSendMsg", // Webhook command
    "Official_Account": "@TOA#_2J4SZEAEL", // Official Account User ID
    "OnlineOnlyFlag": 1, // The value is `1` if it is an online message and `0` if it's not
    "MsgBody": [ // Message body, refer to TIMMessage object
    {
    "MsgType": "TIMTextElem", // Text
    "MsgContent": {
    "Text": "red packet"
    }
    }
    ],
    "CloudCustomData": "your cloud custom data",
    "EventTime": 1670574414123 // Event trigger timestamp in milliseconds
    }

    Request fields

    Field
    Type
    Description
    CallbackCommand
    String
    Webhook command.
    Official_Account
    String
    Official Account User ID.
    OnlineOnlyFlag
    Integer
    Online message, `1` if true, otherwise `0`.
    MsgBody
    Array
    Message body, please refer to Message Formats.
    CloudCustomData
    String
    Custom message data (stored in the cloud, will be sent to the peer, and can be retrieved even after the app is uninstalled and reinstalled).
    EventTime
    Integer
    Event trigger timestamp in milliseconds.

    Sample response

    Allow speaking

    Allow users to speak, without modifying the content of the message to be sent.
    {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0 // 0 means allowed to speak
    }

    Prohibit speaking

    The user is not allowed to speak. Consequently, the message will not be sent, and the error code 10016 is returned to the requester.
    {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 1 // 1 means speaking is not allowed
    }

    Silent discard

    The user is not allowed to speak. In this case, the message will not be sent, but a success response will be returned to the caller, making them believe that the message has been dispatched.
    {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 2 // 2 means Silent Discard
    }

    Change Message Content

    In the following response example: The message sent to the official account is modified (a custom Definition message was added). The Chat backend will send the modified message. Based on this feature, the app backend can add special content, such as user level and title, to the message sent by the user.
    {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0, // Must be 0, only then can the modified message be properly dispatched
    "MsgBody": [ // Message after App changes; if absent, the user's sent message is the default
    {
    "MsgType": "TIMTextElem", // Text
    "MsgContent": {
    "Text": "red packet"
    }
    },
    {
    "MsgType": "TIMCustomElem", // Custom message
    "MsgContent": {
    "Desc": "CustomElement.MemberLevel", // Description
    "Data": "LV1" // Data
    }
    }
    ],
    "CloudCustomData": "your cloud custom data"
    }

    Response fields

    Field
    Type
    Attribute
    Description
    ActionStatus
    String
    Mandatory
    Processed Request Result:
    OK Signifies Successful Handling
    FAILURE signifies unsuccessful execution
    ErrorCode
    Integer
    Mandatory
    Error Identifier:
    0: Allow Speaking
    1: Refuse to Speak
    2: Silent discard
    If the service wishes to reject a speech while conveying the error code ErrorCode and ErrorInfo to the client, please set the ErrorCode within the range [120001, 130000].
    ErrorInfo
    String
    Mandatory
    Error message.
    MsgBody
    Array
    Optional
    After modifications by the app, the modified message body will be sent to Official Account Messages by the cloud communication backend. For the specific format, refer to Message Format Description.
    CloudCustomData
    String
    Optional
    Custom message data (stored in the cloud, will be sent to the peer, and can be retrieved even after the app is uninstalled and reinstalled).

    References

    
    
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support