Skip to main content

Rest API

OpenTalk provides a REST API to integrate actions like room creation into other applications, portals or automated processes.

The API is explained at: https://opentalk.eu/api

This article gives a short overview to use the API with a bash script. The concept can also transfered to other languages which offer a similar functionality.

Please note that you have to enable the option "Direct access grants" in keycloak to access the API.

Login

First you need to to authenticate via OAuth (keycloak) to access the API.

For this the following data is needed, replace the example values with the ones from your environment:

OT_USER=m.mustermann@example.com
OT_PASSWORD=secret

OT_MAIN_URL=admdemo.opentalk.eu
OT_KEYCLOAK_URL=accounts.${OT_MAIN_URL}
OT_CONTROLLER_URL=controller.${OT_MAIN_URL}
OT_PROTO=https://

# you can find the next values in keycloak or you see the them when you login:
# https://accounts.admdemo.opentalk.eu/auth/realms/admdemo/login-actions/
# authenticate?session_code=<session>&client_id=openid_admdemo_test_public&..
OT_CLIENT_ID=openid_admdemo_test_public
OT_REALM_NAME=admdemo

Request token

First you need a token from keycloak:

OT_TOKEN=$(curl -s -d 'client_id='${OT_CLIENT_ID}'' \
-d 'username='${OT_USER}'' \
-d 'password='${OT_PASSWORD}'' \
-d 'scope=openid' \
-d 'grant_type=password' \
'https://'${OT_KEYCLOAK_URL}'/auth/realms/'${OT_REALM_NAME}'/protocol/openid-connect/token')

Extract token

You can extract the token with jq:

OT_TOKEN="$(echo "$OT_TOKEN" | jq -r .access_token)"

Request session

With the token you can request a session:

OT_SESSION=$(curl -s -X POST 'https://'${OT_CONTROLLER_URL}'/v1/auth/login' \
-H 'Content-Type: application/json' \
-d '{ "id_token": "'${OT_TOKEN}'" }')

The session is not needed for further calls but must be requested. After getting it you can make API calls.

Examples

Getting the room list

curl -s "https://${OT_CONTROLLER_URL}/v1/rooms" \
-H 'Content-Type: application/json' \
-H "authorization: Bearer $OT_TOKEN"

Getting room information

The $ROOM_ID is from the room list:

curl -s "https://${OT_CONTROLLER_URL}/v1/rooms/$ROOM_ID" \
-H 'Content-Type: application/json' \
-H "authorization: Bearer $OT_TOKEN"

List all events

curl -s "https://${OT_CONTROLLER_URL}/v1/events?per_page=60&adhoc=false" \
-H 'Content-Type: application/json' \
-H "authorization: Bearer $OT_TOKEN"

In this example the optional per_page parameter was added, without only 30 entries will be displayed. Please have a look at the API documentation to get an overview of other options to limit or extend the output, for example with time_min and time_max you can set a timeframe of the shown events.

Bash script

An extended script with more examples:

#!/bin/bash

OT_USER=testuser@example.com
OT_PASSWORD=secret

OT_MAIN_URL=admdemo.opentalk.eu
OT_KEYCLOAK_URL=accounts.${OT_MAIN_URL}
OT_CONTROLLER_URL=controller.${OT_MAIN_URL}
OT_PROTO=https://

# if the next two values are not known you can read them from the URL when
# logging in:
# https://accounts.admdemo.opentalk.eu/auth/realms/admdemo/login-actions/
# authenticate?session_code=<session>&client_id=openid_admdemo_test_public&..
OT_CLIENT_ID=openid_admdemo_test_public
OT_REALM_NAME=admdemo

DEFAULT_EXPIRATION_HOURS=24
GET_MAX_EVENTS=30

# you probably want to store the credentials and other variables
# in a configuration file
OT_CONFIG=~/.opentalk_api.rc
if [ -r "$OT_CONFIG" ]; then
. "$OT_CONFIG"
fi

# nothing to change below
usage () {
SCRIPT=$(basename $0)
echo "$SCRIPT -c create event (--create)
$SCRIPT -l list events (--list-events)
$SCRIPT -r list rooms (--rooms)
$SCRIPT -i <room id> show information for room (--info)
"
exit 0
}

ot_login () {
OT_TOKEN=$(curl -s -d 'client_id='${OT_CLIENT_ID}'' \
-d 'username='${OT_USER}'' \
-d 'password='${OT_PASSWORD}'' \
-d 'scope=openid' \
-d 'grant_type=password' \
'https://'${OT_KEYCLOAK_URL}'/auth/realms/'${OT_REALM_NAME}'/protocol/openid-connect/token')

if [ "$(echo "$OT_TOKEN" | grep \"access_token\":)" = "" ]; then
echo "- something went wrong getting token:"
echo "$OT_TOKEN"
exit 1
else
OT_TOKEN="$(echo "$OT_TOKEN" | jq -r .access_token)"
fi

SESSION=$(curl -s -X POST 'https://'${OT_CONTROLLER_URL}'/v1/auth/login' \
-H 'Content-Type: application/json' \
-d '{ "id_token": "'${OT_TOKEN}'" }')
}

ot_create_room () {
E_ROOM_ID=$(curl -s -X POST 'https://'${OT_CONTROLLER_URL}'/v1/rooms' \
-H "Authorization: Bearer ${OT_TOKEN}" -H 'Content-Type: application/json' \
-d '{"password": null, "enable_sip": false, "waiting_room": false}' )

if [ "$(echo "$E_ROOM_ID" | grep \"id\":)" = "" ]; then
echo "- something went wrong:"
echo "$E_ROOM_ID"
exit 1
fi

E_ROOM_ID="$(echo "$E_ROOM_ID" | jq -r .id)"
ot_get_invite
echo "Room: ${OT_PROTO}${OT_MAIN_URL}/room/$E_ROOM_ID Guest: $INVITE_LINK"
}

ot_get_invite () {
EXPIRATION_DATE=$(date --date="-${DEFAULT_EXPIRATION_HOURS} hours ago" +"%Y-%m-%dT%H:%M:%SZ")
INVITE_CODE=$(curl -s -X POST "https://${OT_CONTROLLER_URL}/v1/rooms/${E_ROOM_ID}/invites" \
-H "Authorization: Bearer ${OT_TOKEN}" -H 'Content-Type: application/json' \
-d '{"expiration": "'${EXPIRATION_DATE}'"}' | jq -r '.invite_code' \
)
INVITE_LINK="${OT_PROTO}${OT_MAIN_URL}/invite/${INVITE_CODE}"
}

ot_get_rooms () {
ROOM_LIST=$(curl -s "https://${OT_CONTROLLER_URL}/v1/rooms?per_page=${GET_MAX_EVENTS}" \
-H 'Content-Type: application/json' \
-H "authorization: Bearer $OT_TOKEN")

ROOM_COUNT="$(echo "$ROOM_LIST" | jq '. | length')"
ROOM_COUNT=$((ROOM_COUNT - 1))

echo $ROOM_LIST > /tmp/rl

echo "number,room id"

for ROOM in $(seq 0 $ROOM_COUNT); do
E_ROOM_ID=$(echo $ROOM_LIST | jq -r '.['$ROOM'] | .id')
echo "$ROOM $E_ROOM_ID"
done
}

ot_get_room_info () {
ROOM_ID=$1
if [ "$ROOM_ID" = "" ]; then
echo "please use the room id as parameter"
usage | grep -- --info
fi
ROOM_INFO=$(curl -s "https://${OT_CONTROLLER_URL}/v1/rooms/$ROOM_ID" \
-H 'Content-Type: application/json' \
-H "authorization: Bearer $OT_TOKEN")

echo $ROOM_INFO
}

ot_get_events () {
EVENT_LIST=$(curl -s "https://${OT_CONTROLLER_URL}/v1/events?per_page=${GET_MAX_EVENTS}&adhoc=false" \
-H 'Content-Type: application/json' \
-H "authorization: Bearer $OT_TOKEN")

EVENT_COUNT="$(echo "$EVENT_LIST" | jq '. | length')"
EVENT_COUNT=$((EVENT_COUNT - 1))

echo "$EVENT_LIST" > /tmp/el

echo "number,title,room_link,start,end,sip,password,guest_link"

for EVENT in $(seq 0 $EVENT_COUNT); do
E_ROOM_ID=$(echo $EVENT_LIST | jq -r '.['$EVENT'] | .room.id')
E_ROOM_LINK="${OT_PROTO}${OT_MAIN_URL}/room/$E_ROOM_ID"
E_ROOM_TITLE=$(echo $EVENT_LIST | jq '.['$EVENT'] | .title')
E_START=$(echo $EVENT_LIST | jq '.['$EVENT'] | .starts_at.datetime')
E_END=$(echo $EVENT_LIST | jq '.['$EVENT'] | .ends_at.datetime')
E_SIP=$(echo $EVENT_LIST | jq '.['$EVENT'] | "\(.room.sip_tel),,\(.room.sip_id),,\(.room.sip_password)"')
E_PASSWORD=$(echo $EVENT_LIST | jq '.['$EVENT'] | .room.password')
ot_get_invite
echo "$EVENT $E_ROOM_TITLE,$E_ROOM_LINK,$E_START,$E_END,$E_SIP,$E_PASSWORD,$INVITE_LINK"
done
}

case "$1" in
-l|--list-events)
ot_login
ot_get_events ;;
-c|--create-room)
ot_login
ot_create_room ;;
-r|--rooms )
ot_login
ot_get_rooms ;;
-i|--info )
ot_login
ot_get_room_info $2 ;;
*) usage ;;
esac