Reference of ProPTT2 OpenAPI

Description of ProPTT2 OpenAPI.

Auth

Get Server URL

Get server's URL for company.

1) request
Method POST
URL https://{CloudURL or YourServer's URL}/openapi/1/server

Body :

field nametypedescriptionoption
idstring company owner's id(email)mandatory
hidnumber source host id(1~10). Cutomer can select the value. Customer can have 10 hosts to connect OpenAPI.mandatory

Example :

{
    "id" : "owner@company.com",
    "hid" : 1
}					
					
2) response
field nametypedescriptionoption
ServerURLstring API server's URLmandatory
Randstring API server's Random numbermandatory

Available error code :

codedescription
403Request forbidden. parameter invalid

Example :

{
    "ServerURL": "https://aa.aa.com"
    "Rand": "452673a34b"
}
					

Get Session Key

After "/server" call, you have to call this just one time. Server's Random number will be reset.

1) request
Method POST
URL {ServerURL}/openapi/1/auth

Body :

field nametypedescriptionoption
idstring company owner's id(ProPTT2 ID)mandatory
hidnumber source host id(1~10) in server command.mandatory
authKeystring Lowercase(Base16(Sha512(Rand + '-' + company's interaction key))) mandatory
If Rand=12345678, interacionKey="bb00cc"
Lowercase(Base16(Sha512("12345678-bb00cc"))) 
= "7aeaef20455f726d8aa464c4fd57f670657dfea039585e7a6a1e5889537956a43f3a4600ee7eef
305f4f7e309792062cd01be49f6c0438007774347477feb558"

[ Java sample code ]
public static String encryptSha512(String str) {
	String eip;  
	byte[] bip; 
	String resultStr = ""; 
	try { 
		MessageDigest sha512 = MessageDigest.getInstance("SHA-512"); 
		
		bip = sha512.digest(str.getBytes());
		for (int i=0; i < bip.length; i++) { 
			eip = "" + Integer.toHexString((int)bip[i] & 0x000000ff); 
			if (eip.length() < 2) eip = "0" + eip; 
			resultStr = resultStr + eip; 
		} 
	} catch(Exception e) { 
		e.printStackTrace(); 
	} 
	return resultStr;
}

String myAuthKey = encryptSha512("12345678-bb00cc");

[ PHP sample code ]
$authKey = strtolower(hash("sha512", "12345678-bb00cc"));
					

Example :

{
    "id": "abc@proptt2.com",
    "hid" : 1,
    "authKey": "452673a34b"
}
					
2) response
field nametypedescriptionoption
sessionkeystring session key. In server 3.1.2, this sesstion has 10 minute timeout. You can refer to the keepalive API.mandatory

Available error code :

codedescription
401Authentication failure
403Request forbidden. parameter invalid

Example :

{
    "sessionkey":"a34b56c21"
}
					

Keep Alive

This is for keeping session key. Please call this every 3 minute to keet seesion time.

1) request
Method GET
Required Server 3.1.2 ~
URL {ServerURL}/openapi/1/keepalive?id={userid}&hid={hostid}&skey={sessionkey}
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
401Authentication failure
403Request forbidden. parameter invalid

Channel

Get Channel List

1) request
Method GET
URL {ServerURL}/openapi/1/channels?id={userid}&hid={hostid}&skey={sessionkey}
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
channels channel list
idnumber channel's IDmandatory
nostring channel's Nomandatory
namestring channel's namemandatory

Available error code :

codedescription
500Internal error

Example :

{
    "channels":[
        {
            "id" : 1,
            "no" : "34",
            "name" : "abc"
        },{
            "id" : 2,
            "no" : "23",
            "name" : "efg"
        }
    ]
}
					

Create Channel

1) request
Method POST
URL {ServerURL}/openapi/1/channels?id={userid}&hid={hostid}&skey={sessionkey}
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body :

field nametypedescriptionoption
nostring channel's Nomandatory
namestring channel's namemandatory
descriptionstring channel's description
notificationstring channel's notification
TOTnumberTime Over Timedefault 30
recordablebooleanIs recordable in client-side?default true
encryptedbooleanIs encrypted channel (Required Server 2.2.8 ~)default false
shareLocationsbooleanIs location shared channel (Required Server 3.3.0 ~)default false

Example :

{
    "no" : 123,
    "name": "abc",
    "description":"this is a good channel."
    "notification":"welcome.",
    "TOT":20,
    "recordable":true,
    "encrypted":false
}
					
2) response
field nametypedescriptionoption
idnumbercreated channel's IDmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "id":12
}
					

Get Channel

1) request
Method GET
URL {ServerURL}/openapi/1/channels/{cid}?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to get
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
nostring channel's Nomandatory
namestring channel's namemandatory
descriptionstring channel's descriptionmandatory
notificationstring channel's notificationmandatory
TOTnumberTime Over Timemandatory
recordablebooleanIs recordable?mandatory
encryptedbooleanIs encrypted (Required Server 2.2.8 ~)mandatory
shareLocationsbooleanIs location shared channel (Required Server 3.3.0 ~)
leadernumberleader's user idmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "no" : 123,
    "name":"abc",
    "description":"this is a good channel."
    "notification":"welcome.",
    "TOT":20,
    "recordable":true,
    "encrypted":true,
    "leader":5
}
					

Update Channel

1) request
Method PUT
URL {ServerURL}/openapi/1/channels/{cid}?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to update
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body :

field nametypedescriptionoption
namestring channel's namemandatory
descriptionstring channel's description
notificationstring channel's notification

Example :

{
    "name": "abc",
    "description":"this is a good channel.",
    "Notification":"welcome.",
}
					
2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "code":"200"
}
					

Delete Channel

1) request
Method DELETE
URL {ServerURL}/openapi/1/channels/{cid}?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to delete
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "code":"200"
}
					

Link User To Channel

1) request
Method POST
URL {ServerURL}/openapi/1/channels/{cid}/users/{uid}?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to be link
uid user's ID to be linked
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body :

field nametypedescriptionoption
rolenumberuser's role, 10:normal,20:Receiver,90:Operator, (Required Server 3.2.0 ~)default 10
3) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
409Conflict. Already linked user
500Internal error

Example :

{
    "code":"200"
}
					

Get Users Of Channel

1) request
Method GET
URL {ServerURL}/openapi/1/channels/{cid}/users?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to get
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
users user listmandatory
idnumber user's IDmandatory
strIdnumber user's ProPTT2 ID(email)mandatory
namestring user's namemandatory
typenumberuser's type. 20: ProGate, 21: SIP device, 50: Normal, 70: Channel Leader, 80: Dispatcher, 90:Manager (Required Server 3.0.1 ~)mandatory
rolenumberuser's role, 10:normal,20:Receiver,90:Operator, (Required Server 3.2.0 ~)default 10

Available error code :

codedescription
500Internal error

Example :

{
    "users":[
        {
            "id" : 1,
            "strId" : "abc@company.ptt",
            "name" : "abc",
            "type" : 50,
            "role" : 10
        },{
            "id" : 2,
            "strId" : "efg@company.ptt",
            "name" : "efg",
            "type" : 50,
            "role" : 20
        }
    ]
}
					

Unlink User To Channel

1) request
Method DELETE
URL {ServerURL}/openapi/1/channels/{cid}/users/{uid}?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to be unlink
uid user's ID to be unlinked
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "code":"200"
}
					

Get Records Of Channel(Server 2.2.8~)

1) request
Method GET
URL {ServerURL}/openapi/1/channels/{cid}/records?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to get
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey
start start record index. 0 based
pageSize size to get

Body : Nothing

2) response
field nametypedescriptionoption
records record listmandatory
idnumber record's IDmandatory
typenumber 10: AudioPTT, 20:VideoPTT, 31:VideoSharedmandatory
statusnumber 10: Normalmandatory
fileSizenumber file size(KB)mandatory
ownerIdnumber owner idmandatory
ownerNamestring owner's namemandatory
createDatestring created datemandatory

Available error code :

codedescription
500Internal error

Example :

{
    "records":[
        {
            "id" : 1,
            "type" : 10,
            "status" : 10,
            "fileSize" : 32,
            "ownerId" : 1,
            "ownerName" : "owner name",
            "createDate" : "2017-11-02 04:29:02"
        },{
            "id" : 2,
            "type" : 10,
            "status" : 20,
            "fileSize" : 40,
            "ownerId" : 1,
            "ownerName" : "owner name",
            "createDate" : "2017-11-02 04:45:02"
        }
    ]
}
					

Send a message to Channel

1) request
Method POST
Required Server 1.2.x ~
URL {ServerURL}/openapi/1/channels/{cid}/sendMessage?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to get
id company owner's id(email). It is a sender.
hid source host id(1~10) in auth command
skey server's sessionkey

Body :

field nametypedescriptionoption
messageIdnumber message's idmandatory
messageContentstring message to be sent. messageContent=Base64(message)

Example :

{
    "messageId": 1,
    "messageContent":"SGVsbG8="
}
					
2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "code":"200"
}
					

Send a SOS to Channel

1) request
Method POST
Required Server 2.0.x ~
URL {ServerURL}/openapi/1/channels/{cid}/sendSOS?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to get
id company owner's id(email). It is a sender.
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "code":"200"
}
					

Send an alert to Channel

1) request
Method POST
Required Server 2.0.x ~
URL {ServerURL}/openapi/1/channels/{cid}/sendAlert?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to get
id company owner's id(email). It is a sender.
hid source host id(1~10) in auth command
skey server's sessionkey

Body :

field nametypedescriptionoption
messageIdnumber message's idmandatory
messageTypenumber message's type. 0:Generalmandatory
messageContentstring message to be sent. messageContent=Base64(message)

Example :

{
    "messageId": 1,
    "messageType": 0,
    "messageContent":"SGVsbG8="
}
					
2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "code":"200"
}
					

Send a custom message to Channel

1) request
Method POST
Required Server 2.0.x ~
URL {ServerURL}/openapi/1/channels/{cid}/sendCustomMessage?id={userid}&hid={hostid}&skey={sessionkey}
cid channel's ID to get
id company owner's id(email). It is a sender.
hid source host id(1~10) in auth command
skey server's sessionkey

Body :

field nametypedescriptionoption
messageIdnumber message's idmandatory
messageContentstring message to be sent. messageContent=Base64(message)

Example :

{
    "messageId": 1,
    "messageContent":"SGVsbG8="
}
					
2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "code":"200"
}
					

User

Get User List

1) request
Method GET
URL {ServerURL}/openapi/1/users?id={userid}&hid={hostid}&skey={sessionkey}
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
users user listmandatory
idnumber user's IDmandatory
strIdnumber user's ProPTT2 ID(email)mandatory
namestring user's namemandatory
typestringuser's type. 20: ProGate, 21: SIP device, 50: Normal, 70: Channel Leader, 80: Dispatcher, 90:Manager (Required Server 3.0.1 ~)mandatory
latitudestringuser's last latitude. (Required Server 1.2.x ~)
longitudestringuser's last longitude. (Required Server 1.2.x ~)
locationDatestringlast update date of user's location. (Required Server 1.2.x ~)

Available error code :

codedescription
500Internal error

Example :

{
    "users":[
        {
            "id" : 1,
            "strId" : "abc@company.ptt",
            "name" : "abc",
            "type" : 50,
            "latitude":"37.4898",
            "longitude":"127.033",
            "locationDate":"2016-07-21 05:42:35"
        },{
            "id" : 2,
            "strId" : "efg@company.ptt",
            "name" : "efg",
            "type" : 50,
            "latitude":"37.4346",
            "longitude":"127.023",
            "locationDate":"2016-07-22 03:22:33"
        }
    ]
}
					

Create User

1) request
Method POST
URL {ServerURL}/openapi/1/users?id={userid}&hid={hostid}&skey={sessionkey}
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body :

field nametypedescriptionoption
strIdstringuser's ProPTT2 id. In package mode it is full email address. In cloud service it is only Id)mandatory
hashedPasswordstringLowercase(Base16(Sha512(user's password)))mandatory
namenumberuser's namemandatory
typestringuser's type. 50: Normal, 70: Channel Leader, 80: Dispatcher, 90:Manager (Required Server 3.0.1 ~)mandatory
emailstringuser's email
descriptionstringuser's description

Example :

{
    "strId": "abc@company.ptt",
    "hashedPassword": "c321ba878",
    "name": "abc",
    "type": 50,
    "email": "abc@company.com",
    "description":"team leader"
}
					
2) response
field nametypedescriptionoption
idnumbercreated user's IDmandatory

Available error code :

codedescription
400Bad Request. Would be paramater invalid
406Not Acceptable. Would be license limitation
412Precondition failed. Would be already same ID
500Internal error

Example :

{
    "id":12
}
					

Get User

1) request
Method GET
URL {ServerURL}/openapi/1/users/{uid}?id={userid}&hid={hostid}&skey={sessionkey}
uid user's ID to get
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
idnumberuser's IDmandatory
strIdstringuser's ProPTT2 id(email)mandatory
namestringuser's namemandatory
typestringuser's type. 20: ProGate, 21: SIP device, 50: Normal, 70: Channel Leader, 80: Dispatcher, 90:Manager (Required Server 3.0.1 ~)mandatory
emailstringuser's email
descriptionstringuser's description
latitudestringuser's last latitude. (Required Server 1.2.x ~)
longitudestringuser's last longitude. (Required Server 1.2.x ~)
locationDatestringlast update date of user's location. (Required Server 1.2.x ~)

Available error code :

codedescription
500Internal error

Example :

{
    "id":123
    "strId": "abc@company.ptt",
    "name": "abc",
    "type": 50,
    "email": "abc@company.com",
    "description":"team leader",
    "latitude":"37.4898",
    "longitude":"127.033",
    "locationDate":"2016-07-21 05:42:35"
}
					

Update User

1) request
Method PUT
URL {ServerURL}/openapi/1/users/{uid}?id={userid}&hid={hostid}&skey={sessionkey}
uid user's ID to be updated
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body :

field nametypedescriptionoption
namestringuser's namemandatory
typestringuser's type. 50: Normal, 70: Channel Leader, 80: Dispatcher, 90:Manager (Required Server 3.0.1 ~)
emailstringuser's email
descriptionstringuser's description
authTokenstringuser's authToken for second authentication (Required Server 2.2.8 ~)

Example :

{
    "email": "abc@proptt2.com",
    "name": "abc",
    "description":"team leader"
}
					
2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "code":"200"
}
					

Delete User

1) request
Method DELETE
URL {ServerURL}/openapi/1/users/{uid}?id={userid}&hid={hostid}&skey={sessionkey}
uid user's ID to be deleted
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "code":"200"
}
					

Send a message to User

1) request
Method POST
Required Server 1.2.x ~, SDK 1.2.x ~, Client 1.3.x ~
URL {ServerURL}/openapi/1/users/{uid}/sendMessage?id={userid}&hid={hostid}&skey={sessionkey}
uid user's ID to be received
id company owner's id(email). It is a sender.
hid source host id(1~10) in auth command
skey server's sessionkey

Body :

field nametypedescriptionoption
messageIdnumber message's idmandatory
messageContentstring message to be sent. messageContent=Base64(message)

Example :

{
    "messageId": 1,
    "messageContent":"SGVsbG8="
}
					
2) response
field nametypedescriptionoption
codestringresult. "200" is successmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "code":"200"
}
					

Organization

Get Organization List

1) request
Method GET
URL {ServerURL}/openapi/1/organizations?id={userid}&hid={hostid}&skey={sessionkey}
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
organizations radio listmandatory
idnumber organization's IDmandatory
parentIdnumber organization's parent ID. if parent ID is zero, it is root.mandatory
namestring organization's namemandatory

Available error code :

codedescription
500Internal error

Example :

{
    "organizations":[
        {
            "id" : 1,
            "parentId" : 0,
            "name" : "abc"
        },{
            "id" : 2,
            "parentId" : 1,
            "name" : "efg"
        }
    ]
}
					

Get Organization

1) request
Method GET
URL {ServerURL}/openapi/1/organizations/{oid}?id={userid}&hid={hostid}&skey={sessionkey}
oid organization's ID to get
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
idstringorganization's idmandatory
parentIdstringorganization's parentIdmandatory
namestringorganization's namemandatory
descriptionstringorganization's description

Available error code :

codedescription
500Internal error

Example :

{
    "id":123,
    "parentId" : 0,
    "name": "abc",
    "description":"office"
}
					

Get Users Of Organization

1) request
Method GET
URL {ServerURL}/openapi/1/organizations/{oid}/users?id={userid}&hid={hostid}&skey={sessionkey}
oid organization's ID to get
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
users user listmandatory
idnumber user's IDmandatory
strIdstring user's ProPTT2 ID(email)mandatory
namestring user's namemandatory

Available error code :

codedescription
500Internal error

Example :

{
    "users":[
        {
            "id" : 1,
            "strId" : "abc@company.ptt",
            "name" : "abc"
        },{
            "id" : 2,
            "strId" : "efg@company.ptt",
            "name" : "efg"
        }
    ]
}
					

Record (Server 2.2.8~)

Get Record List

1) request
Method GET
URL {ServerURL}/openapi/1/records?id={userid}&hid={hostid}&skey={sessionkey}
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey
start start record index. 0 based
pageSize size to get

Body : Nothing

2) response
field nametypedescriptionoption
records record listmandatory
idnumber record's IDmandatory
typenumber 10: AudioPTT, 20:VideoPTT, 31:VideoSharedmandatory
statusnumber 10: Normalmandatory
fileSizenumber file size(KB)mandatory
channelIdnumber channel idmandatory
channelNonumber channel nomandatory
channelNamestring channel's namemandatory
ownerIdnumber owner idmandatory
ownerNamestring owner's namemandatory
createDatestring created datemandatory

Available error code :

codedescription
500Internal error

Example :

{
    "records":[
        {
            "id" : 1,
            "type" : 10,
            "status" : 10,
            "fileSize" : 32,
            "ownerId" : 1,
            "channelId" : 1,
            "channelNo" : 1,
            "channelName" : "channel name",
            "ownerName" : "owner name",
            "createDate" : "2017-11-02 04:29:02"
        },{
            "id" : 2,
            "type" : 10,
            "status" : 20,
            "fileSize" : 40,
            "channelId" : 1,
            "channelNo" : 1,
            "channelName" : "channel name",
            "ownerId" : 1,
            "ownerName" : "owner name",
            "createDate" : "2017-11-02 04:45:02"
        }
    ]
}
					

Get Record

1) request
Method GET
URL {ServerURL}/openapi/1/records/{rid}?id={userid}&hid={hostid}&skey={sessionkey}
rid record's ID to get
id company owner's id(email)
hid source host id(1~10) in auth command
skey server's sessionkey

Body : Nothing

2) response
field nametypedescriptionoption
idnumber record's IDmandatory
typenumber 10: AudioPTT, 20:VideoPTT, 31:VideoSharedmandatory
statusnumber 10: Normalmandatory
fileSizenumber file size(KB)mandatory
channelIdnumber channel idmandatory
channelNonumber channel nomandatory
channelNamestring channel's namemandatory
ownerIdnumber owner idmandatory
ownerNamestring owner's namemandatory
createDatestring created datemandatory
filepathstring recorded file pathmandatory

Available error code :

codedescription
500Internal error

Example :

{
    "id" : 2,
    "type" : 10,
    "status" : 20,
    "fileSize" : 40,
    "channelId" : 1,
    "channelNo" : 1,
    "channelName" : "channel name",
    "ownerId" : 1,
    "ownerName" : "owner name",
    "createDate" : "2017-11-02 04:45:02",
    "filepath" : "/proptt2/record/ptt/20171104/ptt-userid.ptt"
}
					

Reference

- Base16, Base64 : RFC 3548(http://www.ietf.org/rfc/rfc3548.txt)