Skip to content

Sending messages through API

Overview

An example how to create a message into internal communication channel using an API. Please note that internal communication channels can be accessed by users only using new Giosg UI.

Prerequisites

You need a valid api_token Log in to Console → Settings Menu → Company → Access tokens

What is my organization id?

Organization id is a uuid string, for example db9f631d-203f-4b73-b32b-73eaf67f2790.

1
2
3
4
5
6
7
8
9
const api_token = "8ttjj2qbhlej1fes86gqriibc70pku79evgcezpn"; // Replace it with your token

const me = await fetch("https://service.giosg.com/api/v5/users/me", {
  headers: {
    Authorization: `Token ${api_token}`,
    "content-type": `application/json`,
  },
}).then((response) => response.json());
console.info(me);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import requests

api_token = "8ttjj2qbhlej1fes86gqriibc70pku79evgcezpn" # Replace it with your token

headers = {'Authorization': 'Token ' + api_token}

response = requests.get("https://service.giosg.com/api/v5/users/me", headers=headers)
response.raise_for_status()
data = response.json()
print(data)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "id": "dec7af12-687e-4b9f-ad5b-8fb32de798d1",
    "organization_id": "db9f631d-203f-4b73-b32b-73eaf67f2790",
    "organization": {
        "id": "db9f631d-203f-4b73-b32b-73eaf67f2790",
        "name": "Super name"
    },
    "first_name": "Superman",
    ...
}

List internal communication channels

Let's take a look on current internal communication channels:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
const api_token = "8ttjj2qbhlej1fes86gqriibc70pku79evgcezpn"; // Replace it with your token
const organization_id = "db9f631d-203f-4b73-b32b-73eaf67f2790"; // Replace it with your organization id

// This endpoint returns a paginated collection, so we have to iterate over all pages to get all channels
let url = `https://service.giosg.com/api/pub/v1/orgs/${organization_id}/channels`;
while (url) {
  const data = await fetch(url, {
    headers: {
      Authorization: `Token ${api_token}`,
      "content-type": `application/json`,
    },
  }).then((response) => response.json());

  console.info(data.results);

  // It will be next page url or null if there is no next page
  url = data.next;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import requests

api_token = "8ttjj2qbhlej1fes86gqriibc70pku79evgcezpn" # Replace it with your token
organization_id = "db9f631d-203f-4b73-b32b-73eaf67f2790" # Replace it with your organization id

headers = {'Authorization': 'Token ' + api_token}

# This endpoint returns a paginated collection, so we have to iterate over all pages to get all channels
url = f"https://service.giosg.com/api/pub/v1/orgs/{organization_id}/channels"

while url:
  response = requests.get(url, headers=headers)
  response.raise_for_status()
  data = response.json()
  print(data['results'])

  # It will be next page url or null if there is no next page
  url = data['next']

1
2
3
4
5
6
7
8
[
    {
        "id": "146ff4d9-ca6f-4486-a9cb-c3a0c513db9b",
        "name": "My super channel name",
        ...
    },
    ...
]

Create a message into internal communication channel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
const api_token = "8ttjj2qbhlej1fes86gqriibc70pku79evgcezpn"; // Replace it with your token
const organization_id = "db9f631d-203f-4b73-b32b-73eaf67f2790"; // Replace it with your organization id
const channel_id = "146ff4d9-ca6f-4486-a9cb-c3a0c513db9b"; // Use `id` attribute from any channel from previous step

const url = `https://service.giosg.com/api/pub/v1/orgs/${organization_id}/channels/${channel_id}/messages`;

const messageBody = {
  version: 3,
  chunks: [
    { type: "text", text: "Hello " },
    { type: "link", kind: "email", text: "support@giosg.com" },
    { type: "text", text: "\nHow are you?" },
  ],
};

const data = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Token ${api_token}`,
    "content-type": `application/json`,
  },
  body: JSON.stringify({ body: messageBody }),
}).then((response) => response.json());

console.info(data);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import requests

api_token = "8ttjj2qbhlej1fes86gqriibc70pku79evgcezpn"; # Replace it with your token
organization_id = "db9f631d-203f-4b73-b32b-73eaf67f2790"; # Replace it with your organization id
channel_id = "146ff4d9-ca6f-4486-a9cb-c3a0c513db9b"; # Use `id` attribute from any channel from previous step

headers = {'Authorization': 'Token ' + api_token}

url = f"https://service.giosg.com/api/pub/v1/orgs/{organization_id}/channels/{channel_id}/messages";

message_body = {
  "version": 3,
  "chunks": [
    { "type": "text", "text": "Hello " },
    { "type": "link", "kind": "email", "text": "support@giosg.com" },
    { "type": "text", "text": "\nHow are you?" },
  ],
}

response = requests.post(url, headers=headers, json={"body": message_body})
response.raise_for_status()
data = response.json()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "id":"4ebbb3bf-051a-4cae-ba2b-ac93ee178cf3",
    "created_at":"2021-02-11T12:32:47.079271Z",
    "updated_at":"2021-02-11T12:32:47.079295Z",
    "body":{
        "version":3,
        "chunks":[
            { "type": "text", "text": "Hello " },
            { "type": "link", "kind": "email", "text": "support@giosg.com" },
            { "type": "text", "text": "\nHow are you?" },
        ]
    }
}

This will create a message:

Screenshot

Create a message with external view to show anything you want

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
const api_token = "8ttjj2qbhlej1fes86gqriibc70pku79evgcezpn"; // Replace it with your token
const organization_id = "db9f631d-203f-4b73-b32b-73eaf67f2790"; // Replace it with your organization id
const channel_id = "146ff4d9-ca6f-4486-a9cb-c3a0c513db9b"; // Use `id` attribute from any channel from previous step

const url = `https://service.giosg.com/api/pub/v1/orgs/${organization_id}/channels/${channel_id}/messages`;

const messageBody = {
  version: 3,
  chunks: [
    { type: "text", text: "Click me to see an external view" },
  ],
  externalView: {
    url: "https://giosg.com",
    title: "Giosg in Giosg",
  },
};

const data = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Token ${api_token}`,
    "content-type": `application/json`,
  },
  body: JSON.stringify({ body: messageBody }),
}).then((response) => response.json());

console.info(data);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import requests

api_token = "8ttjj2qbhlej1fes86gqriibc70pku79evgcezpn"; # Replace it with your token
organization_id = "db9f631d-203f-4b73-b32b-73eaf67f2790"; # Replace it with your organization id
channel_id = "146ff4d9-ca6f-4486-a9cb-c3a0c513db9b"; # Use `id` attribute from any channel from previous step

headers = {'Authorization': 'Token ' + api_token}

url = f"https://service.giosg.com/api/pub/v1/orgs/{organization_id}/channels/{channel_id}/messages";

message_body = {
  "version": 3,
  "chunks": [
    { "type": "text", "text": "Click me to see an external view" },
  ],
  "externalView": {
    "url": "https://giosg.com",
    "title": "Giosg in Giosg",
  },
}

response = requests.post(url, headers=headers, json={"body": message_body})
response.raise_for_status()
data = response.json()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "id":"4ebbb3bf-051a-4cae-ba2b-ac93ee178cf3",
    "created_at":"2021-02-11T12:32:47.079271Z",
    "updated_at":"2021-02-11T12:32:47.079295Z",
    "body":{
        "version":3,
        "chunks":[
            { "type": "text", "text": "Click me to see an external view" },
        ],
        "externalView": {
          "url": "https://giosg.com",
          "title": "Giosg in Giosg",
        },
    }
}

This will create a message:

Screenshot

It will open an external view with an iframe to a url you provided:

Screenshot

Endpoints used in this tutorial

https://docs.giosg.com/api_reference/giosg_live/giosg_http_api/users/#retrieve-the-authenticated-user

https://docs.giosg.com/api_reference/pub/