tencent cloud


Adding Custom Messages

Last updated: 2022-02-14 15:46:43

    TUIKit implements the sending and display for basic message types such as text, image, voice, video, and file messages by default. If these message types do not meet your requirements, you can add custom message types.

    Basic Message Types

    Message Type Renderings
    Text message
    Image message
    Voice message
    Video message
    File message

    Custom Message

    • If the basic message types do not meet your requirements, you can customize messages as needed.
    • This document uses sending a custom hypertext message that can redirect to the browser as an example to help you quickly understand the implementation process. In this document, version 5.8.1668 is used as an example, which is different from previous versions.

      The figure above shows a custom message that can be clicked to redirect to a specified linked address. The following describes the implementation details.

    How to Receive and Display a Custom Message

    You can receive a custom message via the onRecvNewMessage function in TUIMessageDataProvider.m, and the received custom message will be displayed in Cell mode in the message list. The data required for Cell drawing is called CellData. The following introduces how to display a custom message.

    Step 1. Create custom CellData

    1. Create the TUILinkCellData.h and TUILinkCellData.m files in TUIChat -> Cell -> CellData -> Custom. Inherit data from TUIMessageCellData to CellData to store the text to display and the link to redirect.
    @interface TUILinkCellData : TUIMessageCellData
    @property NSString *text;
    @property NSString *link;
    1. Rewrite the getCellData: method of the parent class to convert V2TIMMessage to the drawing data TUILinkCellData of the message list Cell.
    @implementation TUILinkCellData
    + (TUIMessageCellData *)getCellData:(V2TIMMessage *)message{
      NSDictionary *param = [NSJSONSerialization JSONObjectWithData:message.customElem.data options:NSJSONReadingAllowFragments error:nil];
      TUILinkCellData *cellData = [[TUILinkCellData alloc] initWithDirection:message.isSelf ? MsgDirectionOutgoing : MsgDirectionIncoming];
      cellData.innerMessage = message;
      cellData.msgID = message.msgID;
      cellData.text = param[@"text"];
      cellData.link = param[@"link"];
      cellData.avatarUrl = [NSURL URLWithString:message.faceURL];
      return cellData;
    1. Rewrite the getDisplayString: method of the parent class to convert V2TIMMessage to the lastMsg display text information of the conversation list.
    @implementation TUILinkCellData
    + (NSString *)getDisplayString:(V2TIMMessage *)message {
      NSDictionary *param = [NSJSONSerialization JSONObjectWithData:message.customElem.data options:NSJSONReadingAllowFragments error:nil];
      return param[@"text"];
    1. Rewrite the contentSize: method of the parent class to calculate the size of the drawing area occupied by the cellData content.
    - (CGSize)contentSize
      CGRect rect = [self.text boundingRectWithSize:CGSizeMake(300, MAXFLOAT) options:NSStringDrawingUsesLineFragmentOrigin | NSStringDrawingUsesFontLeading attributes:@{ NSFontAttributeName : [UIFont systemFontOfSize:15] } context:nil];
      CGSize size = CGSizeMake(ceilf(rect.size.width)+1, ceilf(rect.size.height));
      // Add bubble margins
      size.height += 60;
      size.width += 20;
      return size;

    Step 2. Create custom Cell

    1. Create the TUILinkCell.h and TUILinkCell.m files in TUIChat -> Cell -> CellUI -> Custom. Inherit data from TUIMessageCell to Cell to draw TUILinkCellData data.
    @interface TUILinkCell : TUIMessageCell
    @property UILabel *myTextLabel;  // Display text
    @property UILabel *myLinkLabel;  // Link redirection text
    - (void)fillWithData:(TUILinkCellData *)data; // Draw UI
    1. Rewrite the initWithStyle: method of the parent class to create the myTextLabel and myLinkLabel text display objects and add them to container.
    @implementation TUILinkCell
    // Initialize the control
    - (instancetype)initWithStyle:(UITableViewCellStyle)style reuseIdentifier:(NSString *)reuseIdentifier
      self = [super initWithStyle:style reuseIdentifier:reuseIdentifier];
      if (self) {
          self.myTextLabel = [[UILabel alloc] init];
          [self.container addSubview:self.myTextLabel];
          self.myLinkLabel = [[UILabel alloc] init];
          self.myLinkLabel.text = @"View details>>";
          [self.container addSubview:_myLinkLabel];
      return self;
    1. Rewrite the fillWithData: method of the parent class to custom TUILinkCellData data display in TUILinkCell.
    @implementation TUILinkCell
    // Draw the cell based on `cellData`
    - (void)fillWithData:(TUILinkCellData *)data;
      [super fillWithData:data];
      self.myTextLabel.text = data.text;
    1. Rewrite the layoutSubviews method of the parent class to custom the control coordinates.
    // Set the control coordinates
    - (void)layoutSubviews
      [super layoutSubviews];

    Step 3. Register the custom Cell and CellData

    After cell and cellData are created, you need to register the cell and cellData information in the load function in TUIMessageDataProvider.m. After the registration is completed, when a message is received, the message list automatically finds the corresponding cellData to process message data based on businessID. When refreshing the UI, the message list will also automatically create the corresponding Cell to draw cellData data based on businessID.

    @implementation TUIMessageDataProvider
    + (void)load {
      // You need to implement the following code yourself
      customMessageInfo = @[@{@"businessID" : @"custom_message_link",  // Unique ID of the custom message (Duplicated IDs are not allowed.)
                              @"cell_name" :  @"TUILinkCell"           // cell class name
                              @"cell_data_name" : @"TUILinkCellData"   // cellData class name
                            // If you need more custom message types, you can continue to add custom message information below
                            @{@"businessID" : @"custom_message_link2",
                              @"cell_name" : @"TUILinkCell2"          
                              @"cell_data_name" : @"TUILinkCellData2"

    How to Send a Custom Message

    As the figure above shows, the custom message sending button consists of the text `title` and image `image`. You can register the button using the `load` function in [TUIChatDataProvider.m](https://github.com/tencentyun/TIMSDK/blob/master/iOS/TUIKit/TUIChat/DataProvider/TUIChatDataProvider.m).
    @implementation TUIChatDataProvider
    + (void)load {
      // You need to implement the following code yourself
      customButtonInfo = @[@{@"SendBtn_Key" : @"custom_link_btn",  // Unique ID of the button
                             @"SendBtn_Title" :  @"Custom"          // Text information of the button
                             @"SendBtn_ImageName" : @"custom_link_image"   // Image name of the button

    You can create a custom message to be sent when the button is clicked by calling the createCustomMessage API in the didSelectMoreCell callback in TUIC2CChatViewController.m. In the configuration, the data parameter can be comprised of json data. You can define a businessID field in the json data to uniquely identify the message.

    @implementation TUIMessageController
    - (void)inputController:(TUIInputController *)inputController didSelectMoreCell:(TUIInputMoreCell *)cell
      if ([cell.data.key isEqualToString:@"custom_link_btn"]) { 
          // Create the custom message and set the message `businessID`, display text, and redirection link (you need to implement the following code yourself)
          NSString *businessID = @"custom_message_link";
          NSString *text = @"Welcome to Tencent Cloud IM group";
          NSString *link = @"https://www.tencentcloud.com/document/product/269/3794?from_cn_redirect=1";
          NSDictionary *param = @{@"businessID": businessID, @"text":text, @"link":link};
          NSData *data = [NSJSONSerialization dataWithJSONObject:param options:0 error:&error];
          V2TIMMessage *message = [[V2TIMManager sharedInstance] createCustomMessage:data];
          [self sendMessage:message];
    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