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