Walkthrough
We will conclude by examining the example requests required from both the administration and application roles to set up the API with an agent and make a request to send a message to a channel.
12.1 Pre-requisites
We assume the following:
-
The MindLink API is configured to run at https://mindlink.domain.com
-
Skype is the underlying chat system.
-
The MindLink API is configured with domain\mindlinksuperuser as the super user account
-
Active Directory user accounts domain\mindlinkadmin1 and domain\mindlinkuser1 are configured.
-
The MindLink API is configured for manual authentication. All Active Directory user accounts have “Password1” as the password.
-
Skype SIP accounts have been created with SIP addresses sip:mindlinkslave@domain.com and sip:agent1@domain.com
-
There is a Skype Persistent Chat Room called “TestChatRoom” with ID chat-room:f9a694eb3cae-4235-bcb6-b8aeefb83284 which is visible to sip:mindlinkslave@domain.com and accessible by sip:agent1@domain.com
12.2 High-Level Strategy
Our high level strategy will be as follows
- Provision the agents and users
-
a. Use the super user to create a normal admin user and slave agent
-
b. Use the admin user to create an application user and an agent
-
c. Search for a channel using the slave agent
-
d. Provision the application agent with the channel
- Send a message
-
a. Use the application agent to send a message to the channel
-
b. Verify that the message was sent to the channel
-
By the end of the provisioning steps the system will look as follows:
12.3. Provisioning Requests
12.3.1 Obtain a Super User Token
-
Make a POST request to https://mindlink.domain.com/Authentication/V1/Tokens with the payload:
{"Username":"domain\\mindlinksuperuser","Password":"Password1","AgentId":""}
-
This will return 200 OK with the token e.g. "xPq5OitUf9NIOUI8VMN314EjEEsvmatZTqZ7LHuo0AQ0Xq1VRhZ8tL6mmGSRe_xO+YGEDBDE52SOCeJphu +cGg==" If it does not then check the configured super user credentials in the MindLink Management Center and in Active Directory.
-
This token must be provided in all subsequent requests in the “Authorization” HTTP header, prefixed with “FCF ”. For example the Authorization header in this case will be: FCF xPq5OitUf9NIOUI8VMN314EjEEsvmatZTqZ7LHuo0AQ0Xq1VRhZ8tL6mmGSRe_xO+YGEDBDE52SOCeJphu+ cGg==
-
Setting this header and then making a GET request to https://mindlink.domain.com/Authentication/V1/Tokens/xPq5OitUf9NIOUI8VMN314EjEEsv matZTqZ7LHuo0AQ0Xq1VRhZ8tL6mmGSRe_xO+YGEDBDE52SOCeJphu+cGg== will return 200 OK with the token details:
{"AgentId":"","ExpiresTimestamp":1370990873148,"Username":"domain\\mindlinksuperuser"}
12.3.2 Create the admin user
-
Making a GET request to https://mindlink.domain.com/Provisioning/V1/Users will return an empty collection as there are no configured users: []
-
Make a PUT request to https://mindlink.domain.com/Provisioning/V1/Users/admin1 with the payload:
{"UserId":"admin1","Username":"domain\\mindlinkadmin1"}
-
This will return with 200 OK.
-
Making a GET request to https://mindlink.domain.com/Provisioning/V1/Users will now return 200 OK with a collection containing the admin1 user:
{"UserId":"admin1","Username":"domain\mindlinkadmin1"}
-
Similarly, whereas a GET request to https://mindlink.domain.com/Provisioning/V1/Users/admin1 would have previously returned 404 Not Found, it will now return:
{"UserId":"admin1","Username":"domain\mindlinkadmin1"}
12.3.3 Create the admin slave agent
-
Making a GET request to https://mindlink.domain.com/Provisioning/V1/Agents will return an empty collection as there are no configured agent: []
-
Make a PUT request to https://mindlink.domain.com/Provisioning/V1/Agents/slaveagent with the payload:
{"Id":"slaveagent","UserName":"sip:mindlinkslave@domain.com","Channels":[],"MetaData":[],"Users":[|"admin1"],"CanProvision":"true"}
-
This will return with 200 OK.
-
Making a GET request to https://mindlink.domain.com/Provisioning/V1/Agents will now return 200 OK with a collection containing the slaveagent agent:
[{"CanProvision":true,"Channels":[],"Id":"slaveagent","MetaData":[],"State":2,"User Name":"sip:mindlinkslave@domain.com","Users":[|"admin1"]}]
-
Similarly, whereas a GET request to https://mindlink.domain.com/Provisioning/V1/Agents/slaveagent would have previously returned 404 Not Found, it will now return:
{"CanProvision":true,"Channels":[],"Id":"slaveagent","MetaData":[],"State":2,"UserName":"sip:mindlinkslave@domain.com","Users":[|"admin1"]}
-
Note that the “State” property being “2” indicates that the agent has logged on successfully. If this value is 0 or 1 then check the agent user name.
12.3.4 Reauthenticate as the new admin account
-
Make a POST request to https://mindlink.domain.com/Authentication/V1/Tokens with the payload:
{"Username":"domain\\mindlinkadmin1","Password":"Password1","AgentId":"slaveagent"}
-
This will return 200 OK with the token e.g.
"fQaQrO2QgeDoOeQpnaALQMsYdQlSm75hAZDWs0CR6eL5OVzFx8ONEjia5gp1QMEc99aLsDVTaEa_FY+3dK ZuFQ=="
-
This token must be provided in all subsequent requests in the “Authorization” HTTP header, prefixed with “FCF ”
-
Setting this header and then making a GET request to https://mindlink.domain.com/Authentication/V1/Tokens/fQaQrO2QgeDoOeQpnaALQMsYd QlSm75hAZDWs0CR6eL5OVzFx8ONEjia5gp1QMEc99aLsDVTaEa_FY+3dKZuFQ== will return 200 OK with the token details:
{"AgentId":"slaveagent","ExpiresTimestamp":1370990873148,"Username":"domain\\mindlinkadmin1"}
12.3.5 Create the application user
-
Make a PUT request to https://mindlink.domain.com/Provisioning/V1/Users/user1 with the payload:
{"UserId":"user1","Username":"domain\\mindlinkuser1"}
-
This will return with 200 OK.
-
Making a GET request to https://mindlink.domain.com/Provisioning/V1/Users/user1 will now return:
{"UserId":"user1","Username":"domain\mindlinkuser1"}
12.3.6 Create the application agent
-
Make a PUT request to https://mindlink.domain.com/Provisioning/V1/Channels?query=TestChatRoom with the payload:
{"Id":"agent1","UserName":"sip:agent1@domain.com","Channels":[[]],"MetaData":[[]],"User s":[["user1"]],"CanProvision":"false"}
-
This will return with 200 OK.
-
Making a GET request to https://mindlink.domain.com/Provisioning/V1/Agents/agent1 would have previously returned 404 Not Found, it will now return:
{"CanProvision":false,"Channels":[[]],"Id":"agent1","MetaData":[[]],"State":2,"UserName ":"sip:agent1@domain.com","Users":[|"user1"]}
-
Note that the “State” property being “2” indicates that the agent has logged on successfully. If this value is 0 or 1 then check the agent user name.
12.3.7 Look up the channel ID for the target chat room
-
Make a GET request to https://mindlink.domain.com/Provisioning/V1/Channels?query=TestChatRoom.
-
This will return with 200 OK and the list of matching channels:
{"Key":"chat-room:f9a694eb-3cae-4235-bcb6-b8aeefb83284","Value":" TestChatRoom "}
-
From this response we know that the ID of chat room TestChatRoom as recognized by the MindLink API is “chat-room:f9a694eb-3cae-4235-bcb6-b8aeefb83284”.
12.3.8 Provision the application agent with the target chat room channel
-
Make a PUT request to https://mindlink.domain.com/Provisioning/V1/Agents/agent1/Channels/chatroom:f9a694eb-3cae-4235-bcb6-b8aeefb83284
-
This will return with 200 OK.
-
Making a GET request to https://mindlink.domain.com/Provisioning/V1/Agents/agent1 will return 200 OK with:
{"CanProvision":false,"Channels"[:{"Id":"chat-room:f9a694eb-3cae-4235-bcb6b8aeefb83284","State":2},"Id":"agent1","MetaData":[],"State":2,"UserName":"sip:age nt1@domain.com","Users":[|"user1"]}
-
The channel’s “State” property being “2” indicates that the agent has successfully joined the channel. If this value is 0 or 1 then check the chat room permissions for the agent’s user name.
12.4. Collaboration Requests
12.4.1 Obtain an agent Token
-
Make a POST request to https://mindlink.domain.com/Authentication/V1/Tokens with the payload:
{"Username":"domain\\mindlinkuser1","Password":"Password1","AgentId":"agent1"}
-
This will return 200 OK with the token e.g. "PzE4IsnjVkmLn+XnYM8LRQvWr+1xyaGkIi58qkx5mV4yBiz4kw1QAAqtGIKY4Feqdh8FtE9WKFeDZ4lADY R2xA=="
-
This token must be provided in all subsequent requests in the “Authorization” HTTP header, prefixed with “FCF ”.
-
Setting this header and then making a GET request to https://mindlink.domain.com/Authentication/V1/Tokens/PzE4IsnjVkmLn+XnYM8LRQvWr+1 xyaGkIi58qkx5mV4yBiz4kw1QAAqtGIKY4Feqdh8FtE9WKFeDZ4lADYR2xA== will return 200 OK with the token details:
{"AgentId":"agent1","ExpiresTimestamp":1370990873148,"Username":"domain\\mindlinkuser1"}
12.4.2 Verify the agent channels
-
For the sake of example, to verify the agent is configured correctly make a GET request to https://mindlink.domain.com/Collaboration/V1/Channels
-
This will return 200 OK with the channel collection:
{"CanAcceptFiles":true,"Description":"Test Room","DisplayName":"TestChatRoom","EmailAddress":null,"Id":"chat-room:f9a694eb-3cae-4235-bcb6b8aeefb83284","IsReadOnly":false,"MaxMessageLength":500,"MaxStoryLength":4000,"Meta data":null,"Subject":"Test Room"}
12.4.3 Post a message to the channel
-
Make a POST request to https://mindlink.domain.com/Collaboration/V1/Channels/chat-room:f9a694eb-3cae-4235-bcb6-b8aeefb83284/Messages with payload:
{"IsAlert":false,"Text":"Test Message"}
-
This will return 200 OK with the sent message:
{"ChannelId":"chat-room:f9a694eb-3cae-4235-bcb6b8aeefb83284","Id":null,"IsAlert":false,"Origin":0,"SenderId":"agent1","Subject":null,"Text":"Test Message","Timestamp":1370994481922}
12.4.4 Verify the message was sent
-
Make a GET request to [https:// mindlink.domain.com/Collaboration/V1/Channels/chatroom:f9a694eb-3cae-4235-bcb6-b8aeefb83284/Messages?take=10](https:// mindlink.domain.com/Collaboration/V1/Channels/chatroom:f9a694eb-3cae-4235-bcb6-b8aeefb83284/Messages?take=10)
-
This will return 200 OK with the 10 most recent messages in the channel:
{|{"ChannelId":"chat-room:f9a694eb-3cae-4235-bcb6b8aeefb83284","Id":"136180","IsAlert":false,"Origin":1,"SenderId":"contact:agent1@d omain.com","Subject":null,"Text":"Test Message","Timestamp":1370994482073} …
Sample Code Repository
Sample code can be downloaded from https://github.com/mindlink/api-samples