Integrations Quickstart

Integrations are server-scoped apps that authenticate with Bearer tokens.

Create an integration

1. Open the developer portal.
2. Pick a server you manage.
3. Create an Integration app.
4. Generate a token with the scopes you need.

Available token scopes

• manage_members — update roles, nicknames, timeouts
• read_member_profile — read member profile data

Code examples

Read a member profile

cURL

curl "https://chattr.example.com/servers/SERVER_ID/memberships/USER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

JavaScript (Node.js)

const BASE    = "https://chattr.example.com";
const TOKEN   = "YOUR_TOKEN";
const SERVER  = "SERVER_ID";
const USER    = "USER_ID";

const res = await fetch(`${BASE}/servers/${SERVER}/memberships/${USER}`, {
  headers: { "Authorization": `Bearer ${TOKEN}` }
});

const data = await res.json();
console.log(data.profile);

Python

import requests

BASE    = "https://chattr.example.com"
TOKEN   = "YOUR_TOKEN"
SERVER  = "SERVER_ID"
USER    = "USER_ID"

res = requests.get(
    f"{BASE}/servers/{SERVER}/memberships/{USER}",
    headers={"Authorization": f"Bearer {TOKEN}"}
)

data = res.json()
print(data["profile"])

Update a member

cURL

curl -X PATCH "https://chattr.example.com/servers/SERVER_ID/memberships/USER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nickname": "VIP Player", "roleIds": [7, 9]}'

JavaScript (Node.js)

const BASE    = "https://chattr.example.com";
const TOKEN   = "YOUR_TOKEN";
const SERVER  = "SERVER_ID";
const USER    = "USER_ID";

const res = await fetch(`${BASE}/servers/${SERVER}/memberships/${USER}`, {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    nickname: "VIP Player",
    roleIds: [7, 9],
    timedOutUntil: null          // optional: ISO 8601 or null
  })
});

const data = await res.json();
console.log(data.membership);

Python

import requests

BASE    = "https://chattr.example.com"
TOKEN   = "YOUR_TOKEN"
SERVER  = "SERVER_ID"
USER    = "USER_ID"

res = requests.patch(
    f"{BASE}/servers/{SERVER}/memberships/{USER}",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json"
    },
    json={
        "nickname": "VIP Player",
        "roleIds": [7, 9],
        "timedOutUntil": None     # optional: ISO 8601 or None
    }
)

data = res.json()
print(data["membership"])

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url   := "https://chattr.example.com/servers/SERVER_ID/memberships/USER_ID"
	token := "YOUR_TOKEN"

	body, _ := json.Marshal(map[string]any{
		"nickname": "VIP Player",
		"roleIds":  []int{7, 9},
	})

	req, _ := http.NewRequest("PATCH", url, bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	fmt.Println("Status:", resp.StatusCode)
}

PHP

$url   = "https://chattr.example.com/servers/SERVER_ID/memberships/USER_ID";
$token = "YOUR_TOKEN";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $token",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "nickname"      => "VIP Player",
    "roleIds"       => [7, 9],
    "timedOutUntil" => null       // optional
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data["membership"]);

Permissions

Creating and managing integrations requires the manage_server permission on the target server. Server owners and administrators have this by default.

Notes

Use the same token on read endpoints that accept integration actors.