Links

Version 2 functionality

This document uses message drafts v2 unless otherwise specified.

Encode URLs (www, http, https) as clickable links or create hyperlinks with custom text.

Generic referencing

Channel references, user mentions, and links share the same MessageElement structure with different mentionType values.

Add links

addMention() adds a link to a draft message.

Method signature

Call addMention() with mentionType set to textLink. See addMention() for details.

Sample code

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

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

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

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

Remove links

removeMention() removes a link from a draft message.

Method signature

Call removeMention() at the exact offset where the link starts. See removeMention() 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.

Sample code

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

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

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

Render URLs

getMessageElements() returns URLs as link elements in published messages. Customize rendering with your own functions. This method also handles mention rendering.

Method signature

This method has the following signature:

1message.getMessageElements(): MixedTextTypedElement[]

Input

This method doesn't take any parameters.

Output

Parameter

Description

MixedTextTypedElement[] Type: 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"}}.

Sample code

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

1message.getMessageElements()

Other examples

Customize link rendering with these examples.

Show links as plain text

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

React

1const renderMessagePart = (messagePart: MixedTextTypedElement) => {
2  if (messagePart.type === "plainLink") {
3    return messagePart.content.link;
4  }
5  return "";
6}

React Native

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

4const showClickableLink = (url) => {
5    if(url.startsWith('http') || url.startsWith('https') || url.startsWith('www')) { 
6        return (
7            <Text style={{color: 'blue'}} onPress={() => Linking.openURL(url)}>
8               {url}
9            </Text>
10        );
11    }
12    return url;
13};
14

15export default showClickableLink;

Vue

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

6<script>
7export default {
8    props: {
9        text: String
10    },
11    methods: {
12        isURL(str) {
13            return str.startsWith('http') || str.startsWith('https') || str.startsWith('www');
14        }
15    }
16}
17</script>

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:

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

Add the corresponding TypeScript code:

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

4@Component({
5  selector: 'app-your-component',
6  templateUrl: './your-component.component.html',
7  styleUrls: ['./your-component.component.css'],
8})
9export class YourComponent {
10  @Input() url: string;
11

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

Change background color of plain links

Change the background color of all plain links to yellow.

React

1if (messagePart.type === "plainLink") {
2    const linkStyle = { backgroundColor: "yellow" };
3    return (
4      <a href={messagePart.content.link} style={linkStyle}>
5        {messagePart.content.link}
6      </a>
7    );
8  }
9  return "";

React Native

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

3if (messagePart.type === "plainLink") {
4    const linkStyle = { backgroundColor: 'yellow' };
5    return (
6        <Text 
7            onPress={() => Linking.openURL(messagePart.content.link)} 
8            style={linkStyle}
9        >
10            {messagePart.content.link}
11        </Text>
12    );
13}
14return null;

Vue

1<template>
2  <div>
3    <a v-bind:style="linkStyle" v-bind:href="messagePart.content.link" v-if="messagePart.type === 'plainLink'">
4      {{ messagePart.content.link }}
5    </a>
6  </div>
7</template>
8

9<script>
10export default {
11  data() {
12    return {
13      messagePart: {
14        type: 'plainLink',
15        content: {
16          link: 'http://example.com',
17        },
18      }, 
19      linkStyle: {
20        backgroundColor: 'yellow',
21      },
22    };
23  },
24};
25</script>

show all 25 lines

Angular

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

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

Add the corresponding TypeScript code:

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

3@Component({
4  selector: 'app-root',
5  templateUrl: './app.component.html',
6  styleUrls: ['./app.component.css']
7})
8export class AppComponent{
9  messagePart = {
10    type: 'plainLink', 
11    content: { 
12      link: 'http://example.com' 
13    } 
14  };
15}

Change background color of text links

Change the background color of all text links to red.

React

1const renderMessagePart = (messagePart: MixedTextTypedElement) => {
2  if (messagePart.type === "textLink") {
3    return (
4      <a href={messagePart.content.link} style={{ backgroundColor: 'red' }}>
5        {messagePart.content.text}
6      </a>
7    );
8  }
9  return "";
10}

React Native

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

3const renderMessagePart = (messagePart) => {
4  if (messagePart.type === "textLink") {
5    return (
6      <TouchableHighlight onPress={() => handleLinkPress(messagePart.content.link)}>
7        <Text style={{ backgroundColor: 'red' }}>{messagePart.content.text}</Text>
8      </TouchableHighlight>
9    );
10  }
11  return null;
12}

Vue

1<template>
2  <div>
3    <span v-if="messagePart.type === 'textLink'">
4      <a :href="messagePart.content.link" :style="{ backgroundColor: 'red' }">
5        {{ messagePart.content.text }}
6      </a>
7    </span>
8    <span v-else></span>
9  </div>
10</template>
11

12<script>
13export default {
14  props: {
15    messagePart: Object // assuming the messagePart is passed as a prop
16  }
17}
18</script>

show all 18 lines

Angular

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

3@Component({
4  selector: 'app-root',
5  template: `
6    <ng-container *ngFor="let messagePart of messageParts">
7      <a *ngIf="messagePart.type === 'textLink'" [href]="messagePart.content.link" [ngStyle]="{ 'background-color': 'red' }">
8        {{ messagePart.content.text }}
9      </a>
10    </ng-container>
11  `,
12})
13export class AppComponent {
14  messageParts: MixedTextTypedElement[] = [
15    {
16      type: 'text',
17      content: {
18        link: 'https://example.com',
19        text: 'Link 1',
20      },
21    },
22    {
23      type: 'textLink',
24      content: {
25        link: 'https://example.com',
26        text: 'Link 2',
27      },
28    },
29    // ... other message parts
30  ];
31}
32

33interface MixedTextTypedElement {
34  type: string;
35  content: {
36    link: string;
37    text: string;
38  };
39}

show all 39 lines

Exclude selected links

Don't display YouTube links as plain links.

React

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

React Native

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

3const renderMessagePart = (messagePart) => {
4  if (messagePart.type === 'plainLink') {
5    const youtubeRegex = /^(https?:\/\/)?(www\.)?(youtube\.com|youtu\.be)\//i;
6    if (youtubeRegex.test(messagePart.content.link)) {
7      // if it's a YouTube link, you can handle it differently, for example, embedding the video or displaying a custom YouTube link format
8      return <Text>Custom rendering for YouTube link: {messagePart.content.link}</Text>;
9    } else {
10      // for other plain links, display them as regular anchor tags
11      return (
12        <Text onPress={() => Linking.openURL(messagePart.content.link)}>
13          {messagePart.content.link}
14        </Text>
15      );
16    }
17  }
18  return null;
19};

show all 19 lines

Vue

1<template>
2  <div>
3    <template v-if="messagePart.type === 'plainLink'">
4      <template v-if="isYouTubeLink(messagePart.content.link)">
5        <!-- Custom rendering for YouTube link -->
6        <div>Custom rendering for YouTube link: {{ messagePart.content.link }}</div>
7      </template>
8      <template v-else>
9        <!-- Display plain links as anchor tags -->
10        <a :href="messagePart.content.link">{{ messagePart.content.link }}</a>
11      </template>
12    </template>
13  </div>
14</template>
15

16<script>
17export default {
18  props: {
19    messagePart: {
20      type: Object,
21      required: true
22    }
23  },
24  methods: {
25    isYouTubeLink(link) {
26      const youtubeRegex = /^(https?:\/\/)?(www\.)?(youtube\.com|youtu\.be)\//i;
27      return youtubeRegex.test(link);
28    }
29  }
30};
31</script>

show all 31 lines

Angular

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

3@Component({
4  selector: 'app-message',
5  template: `
6    <ng-container *ngFor="let messagePart of messageParts">
7      <div *ngIf="messagePart.type === 'plainLink'">
8        <ng-container *ngIf="isYouTubeLink(messagePart.content.link)">
9          Custom rendering for YouTube link: {{ messagePart.content.link }}
10        </ng-container>
11        <a *ngIf="!isYouTubeLink(messagePart.content.link)" href="{{messagePart.content.link}}">
12          {{ messagePart.content.link }}
13        </a>
14      </div>
15    </ng-container>
16  `,
17})
18export class MessageComponent {
19  messageParts: MixedTextTypedElement[] = []; // replace MixedTextTypedElement with your actual type
20

21  isYouTubeLink(link: string): boolean {
22    const youtubeRegex = /^(https?:\/\/)?(www\.)?(youtube\.com|youtu\.be)\//i;
23    return youtubeRegex.test(link);
24  }
25}

show all 25 lines

Show text link preview

getMessagePreview() returns message draft elements (text, URLs, mentions, channel references) for custom rendering.

Method signature

This method has the following signature:

1messageDraft.getMessagePreview(): MixedTextTypedElement[]

Input

This method doesn't take any parameters.

Output

Parameter

Description

MixedTextTypedElement[] Type: 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"}}.

Sample code

Show a preview of the modified link.

1// replace a link with text
2messageDraft.addLinkedText(
3  {
4    text: "this support article",
5    link: "https://www.support-article.com/",
6    positionInInput: 10
7  }
8)
9//show the preview of the changed link
10messageDraft.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() replaces a plain link with descriptive text in a draft message.

Method signature

This method has the following signature:

1messageDraft.addLinkedText({
2  text: string;
3  link: string;
4  positionInInput: number;
5}): void

Input

* required

Parameter	Description
text * Type: string Default: n/a	Text that you want to replace the link with.
link * Type: string Default: n/a	Link that you want to replace with text.
positionInInput * Type: number Default: 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.

Sample code

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

1messageDraft.addLinkedText(
2  {
3    text: "this support article",
4    link: "https://www.support-article.com/",
5    positionInInput: 10
6  }
7)

Remove linked text

removeLinkedText() removes a linked URL from text in a draft message.

Method signature

This method has the following signature:

1messageDraft.removeLinkedText(positionInInput: number): void

Input

* required

Parameter	Description
positionInInput * Type: number Default: 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.

Sample code

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

1messageDraft.removeLinkedText(
2  {
3    positionInInput: 10
4  }
5)

Get text links (deprecated)

Deprecated

This method is deprecated.

textLinks returns all text links in a message.

Method signature

This method has the following signature:

1message.textLinks: TextLink[]

Properties

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

Sample code

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

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

4// get all text links
5message.textLinks