Links

Version 2 functionality

All operations relative to message drafts in this document are based on the version 2 of the message draft functionality, unless otherwise specified.

Chat SDK lets you encode URLs that begin with www, http, or https (plain links) so that they can be customized and rendered as clickable links. You can also let chat users create hyperlinks manually by replacing URLs in messages with descriptive texts (text links).

Generic referencing

Channel references, user mentions, and links are instances of MessageElement with different mentionType values.

Add links

addMention() lets you replace a plain link on the draft message to display a meaningful text in the published message.

Method signature

You can attach links to a draft message by calling the addMention() method with the mentionType of textLink.

Refer to the addMention() method for details.

Basic usage

Create the Hello Alex! I have sent you this link on the #offtopic channel. message where link is a URL.

// Create a message draft
messageDraft = channel.createMessageDraftV2({ userSuggestionSource: "global" })

// Add initial text
messageDraft.update("Hello Alex! I have sent you this link on the #offtopic channel.")

// Add a user mention to the string "Alex"
messageDraft.addMention(33, 4, "textLink","https://example.com")

Remove links

removeMention() lets you remove a previously added link from a draft message.

Method signature

You can remove links from a draft message by calling the removeMention() method at the exact offset where the link starts.

Refer to the removeMention() method for details.

Offset value

If you don't provide the position of the first character of the message element to remove, it isn't removed.

Basic usage

Remove the link from the Hello Alex! I have sent you this link on the #offtopic channel. message where link is a URL.

// assume the message reads
// Hello Alex! I have sent you this link on the #offtopic channel.`

// remove the link mention
messageDraft.removeMention(33)

Render URLs

getMessageElements() shows all URLs starting with www, http, or https as links in the final published message. You can create custom functions if you want to customize how these links render.

This is the same method that lets you show mentions as links.

Method signature

This method has the following signature:

message.getMessageElements(): MixedTextTypedElement[]

Input

This method doesn't take any parameters.

Output

Parameter	Type	Description
MixedTextTypedElement[]	array	A returned array of elements that the message is composed of. Each element is a separate array. For plain text, you'll get a text type element, like {"type": "text", "content": { "text": "This is a sample text "}}. For plain links, you'll get a plainLink element, like {"type": "plainLink", "content": {"link": "https://my-company.com"}}. For text links, you'll get a textLink element, like {"type": "textLink", "content": {"link": "https://my-company.com", "text": "my company"}}. For mentions, you'll get a mention element, like {"type": "mention", "content": {"name": "Peter", "id": "some-id-for-peter"}}. For channel references, you'll get a channelReference element, like {"type": "channelReference", "content": {"name": "Support", "id": "some-id-for-channel"}}.

Basic usage

Show all URLs starting with www, http, or https as clickable links.

message.getMessageElements()

Other examples

Check how you can customize the default behavior of the Chat SDK methods and render the links differently.

Show links as plain text

Show all URLs starting with www, http, or https as plain text instead of clickable links.

React

const renderMessagePart = (messagePart: MixedTextTypedElement) => {
  if (messagePart.type === "plainLink") {
    return messagePart.content.link;
  }
  return "";
}

React Native

import React from 'react';
import {Text, Linking} from 'react-native';

const showClickableLink = (url) => {
    if(url.startsWith('http') || url.startsWith('https') || url.startsWith('www')) { 
        return (
            <Text style={{color: 'blue'}} onPress={() => Linking.openURL(url)}>
               {url}
            </Text>
        );
    }
    return url;
};

export default showClickableLink;

Vue

<template>
    <a v-if="isURL(text)" :href="text" target="_blank">{{ text }}</a>
    <p v-else>{{ text }}</p>
</template>

<script>
export default {
    props: {
        text: String
    },
    methods: {
        isURL(str) {
            return str.startsWith('http') || str.startsWith('https') || str.startsWith('www');
        }
    }

show all 17 lines

Angular

You can create a component to handle the rendering of URLs using Angular's built-in directive for binding attributes and events:

<!-- your-component.component.html -->
<a *ngIf="isUrl(url)" [href]="url" target="_blank">{{ url }}</a>
<p *ngIf="!isUrl(url)">{{url}}</p>

Add the corresponding TypeScript code:

// your-component.component.ts
import { Component, Input } from '@angular/core';

@Component({
  selector: 'app-your-component',
  templateUrl: './your-component.component.html',
  styleUrls: ['./your-component.component.css'],
})
export class YourComponent {
  @Input() url: string;

  isUrl(): boolean {
    return this.url.startsWith('http') || this.url.startsWith('https') || this.url.startsWith('www');
  }
}

Change background color of plain links

Change the background color of all plain links to yellow.

React

if (messagePart.type === "plainLink") {
    const linkStyle = { backgroundColor: "yellow" };
    return (
      <a href={messagePart.content.link} style={linkStyle}>
        {messagePart.content.link}
      </a>
    );
  }
  return "";

React Native

import { Text, Linking } from 'react-native';

if (messagePart.type === "plainLink") {
    const linkStyle = { backgroundColor: 'yellow' };
    return (
        <Text 
            onPress={() => Linking.openURL(messagePart.content.link)} 
            style={linkStyle}
        >
            {messagePart.content.link}
        </Text>
    );
}
return null;

Vue

<template>
  <div>
    <a v-bind:style="linkStyle" v-bind:href="messagePart.content.link" v-if="messagePart.type === 'plainLink'">
      {{ messagePart.content.link }}
    </a>
  </div>
</template>

<script>
export default {
  data() {
    return {
      messagePart: {
        type: 'plainLink',
        content: {

show all 25 lines

Angular

Use [style] to bind a styles object to an HTML element:

<a *ngIf="messagePart?.type === 'plainLink'" [href]="messagePart?.content.link" [style]="{'background-color': 'yellow'}">
   {{messagePart?.content.link}}
</a>

Add the corresponding TypeScript code:

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent{
  messagePart = {
    type: 'plainLink', 
    content: { 
      link: 'http://example.com' 
    } 
  };
}

Change background color of text links

Change the background color of all text links to red.

React

const renderMessagePart = (messagePart: MixedTextTypedElement) => {
  if (messagePart.type === "textLink") {
    return (
      <a href={messagePart.content.link} style={{ backgroundColor: 'red' }}>
        {messagePart.content.text}
      </a>
    );
  }
  return "";
}

React Native

import { Text, TouchableHighlight } from 'react-native';

const renderMessagePart = (messagePart) => {
  if (messagePart.type === "textLink") {
    return (
      <TouchableHighlight onPress={() => handleLinkPress(messagePart.content.link)}>
        <Text style={{ backgroundColor: 'red' }}>{messagePart.content.text}</Text>
      </TouchableHighlight>
    );
  }
  return null;
}

Vue

<template>
  <div>
    <span v-if="messagePart.type === 'textLink'">
      <a :href="messagePart.content.link" :style="{ backgroundColor: 'red' }">
        {{ messagePart.content.text }}
      </a>
    </span>
    <span v-else></span>
  </div>
</template>

<script>
export default {
  props: {
    messagePart: Object // assuming the messagePart is passed as a prop

show all 18 lines

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <ng-container *ngFor="let messagePart of messageParts">
      <a *ngIf="messagePart.type === 'textLink'" [href]="messagePart.content.link" [ngStyle]="{ 'background-color': 'red' }">
        {{ messagePart.content.text }}
      </a>
    </ng-container>
  `,
})
export class AppComponent {
  messageParts: MixedTextTypedElement[] = [
    {

show all 39 lines

Exclude selected links

Don't display YouTube links as plain links.

React

const renderMessagePart = (messagePart: MixedTextTypedElement) => {
  if (messagePart.type === "plainLink") {
    const youtubeRegex = /^(https?:\/\/)?(www\.)?(youtube\.com|youtu\.be)\//i;
    if (youtubeRegex.test(messagePart.content.link)) {
      // if it's a YouTube link, you can handle it differently, for example, embedding the video or displaying a custom YouTube link format
      return <div>Custom rendering for YouTube link: {messagePart.content.link}</div>;
    } else {
      // for other plain links, display them as regular anchor tags
      return <a href={messagePart.content.link}>{messagePart.content.link}</a>;
    }
  }
  return "";
}

React Native

import { Text, Linking } from 'react-native';

const renderMessagePart = (messagePart) => {
  if (messagePart.type === 'plainLink') {
    const youtubeRegex = /^(https?:\/\/)?(www\.)?(youtube\.com|youtu\.be)\//i;
    if (youtubeRegex.test(messagePart.content.link)) {
      // if it's a YouTube link, you can handle it differently, for example, embedding the video or displaying a custom YouTube link format
      return <Text>Custom rendering for YouTube link: {messagePart.content.link}</Text>;
    } else {
      // for other plain links, display them as regular anchor tags
      return (
        <Text onPress={() => Linking.openURL(messagePart.content.link)}>
          {messagePart.content.link}
        </Text>
      );

show all 19 lines

Vue

<template>
  <div>
    <template v-if="messagePart.type === 'plainLink'">
      <template v-if="isYouTubeLink(messagePart.content.link)">
        <!-- Custom rendering for YouTube link -->
        <div>Custom rendering for YouTube link: {{ messagePart.content.link }}</div>
      </template>
      <template v-else>
        <!-- Display plain links as anchor tags -->
        <a :href="messagePart.content.link">{{ messagePart.content.link }}</a>
      </template>
    </template>
  </div>
</template>

show all 31 lines

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-message',
  template: `
    <ng-container *ngFor="let messagePart of messageParts">
      <div *ngIf="messagePart.type === 'plainLink'">
        <ng-container *ngIf="isYouTubeLink(messagePart.content.link)">
          Custom rendering for YouTube link: {{ messagePart.content.link }}
        </ng-container>
        <a *ngIf="!isYouTubeLink(messagePart.content.link)" href="{{messagePart.content.link}}">
          {{ messagePart.content.link }}
        </a>
      </div>
    </ng-container>

show all 25 lines

Show text link preview

getMessagePreview() returns a list of message draft elements, such as: text, plain URLs, text URLs, user mentions, or referenced channels. You can decide how you want to render these elements in your app and format them separately. For example, you could use this method to render an anchor tag for your links.

Method signature

This method has the following signature:

messageDraft.getMessagePreview(): MixedTextTypedElement[]

Input

This method doesn't take any parameters.

Output

Parameter	Type	Description
MixedTextTypedElement[]	array	A returned array of elements that the message is composed of. Each element is a separate array. For plain text, you'll get a text type element, like {"type": "text", "content": { "text": "This is a sample text "}}. For plain links, you'll get a plainLink element, like {"type": "plainLink", "content": {"link": "https://my-company.com"}}. For text links, you'll get a textLink element, like {"type": "textLink", "content": {"link": "https://my-company.com", "text": "my company"}}. For user mentions, you'll get a mention element, like {"type": "mention", "content": {"name": "Peter", "id": "some-id-for-peter"}}.

Basic usage

Show a preview of the modified link.

// replace a link with text
messageDraft.addLinkedText(
  {
    text: "this support article",
    link: "https://www.support-article.com/",
    positionInInput: 10
  }
)
//show the preview of the changed link
messageDraft.getMessagePreview()

For examples of how you can customize draft message previews, refer to the getMessageElements() method that's similar in structure but is meant for final, published messages.

Add linked text

addLinkedText() lets you replace a plain link on the draft message to display a meaningful text in the published message.

Method signature

This method has the following signature:

messageDraft.addLinkedText({
  text: string;
  link: string;
  positionInInput: number;
}): void

Input

Parameter	Type	Required	Default	Description
text	string	Yes	n/a	Text that you want to replace the link with.
link	string	Yes	n/a	Link that you want to replace with text.
positionInInput	number	Yes	n/a	Position of a character in a message where the link you want to replace starts. It's counted from the beginning of the message (including spaces), with 0 as the first character.

Output

Type	Description
void	Method returns no output data.

Errors

You'll get the You need to insert a URL error if you don't provide a URL. If you try to replace a link with a different link, you'll get the You cannot insert a link inside another link error.

Basic usage

Replace Check out this support article https://www.support-article.com/. with Check out this support article.

messageDraft.addLinkedText(
  {
    text: "this support article",
    link: "https://www.support-article.com/",
    positionInInput: 10
  }
)

Remove linked text

removeLinkedText() removes a linked URL from a given text on the draft message.

Method signature

This method has the following signature:

messageDraft.removeLinkedText(positionInInput: number): void

Input

Parameter	Type	Required	Default	Description
positionInInput	number	Yes	n/a	Beginning of the text in a message where the link you want to remove starts. The position is counted from the beginning of the message (including spaces), with 0 as the first character.

Output

Type	Description
void	Method returns no output data.

Errors

If you don't provide the link text's position in the message, you'll get the You need to insert a number error. If you try to remove a link that doesn't exist, you'll get the This operation is noop. There is no link at this position. error.

Basic usage

Remove a link from the "Check out this support article." message.

messageDraft.removeLinkedText(
  {
    positionInInput: 10
  }
)

Get text links (deprecated)

Deprecated

This method is deprecated.

textLinks is a getter method that returns all text links in a given message.

Method signature

This method has the following signature:

message.textLinks: TextLink[]

Properties

Property	Type	Description
textLinks	TextLink[]	Array of text links included in the message.

Basic usage

Get all text links included in the message with the 16200000000000000 timetoken.

// reference the "message" that you're interested in
const message = await channel.getMessage("16200000000000000")

// get all text links
message.textLinks