Walkthrough
#
API Developers reference#
12. WalkthroughWe 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-requisitesWe 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 StrategyOur 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 TokenMake 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 userMaking 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 agentMaking 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 accountMake 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 userMake 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 agentMake 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 roomMake 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 channelMake 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 TokenMake 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 channelsFor 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 channelMake 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 sentMake 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 RepositorySample code can be downloaded from https://github.com/mindlink/api-samples