Skip to main content

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

  1. 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

  1. 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:

Image 9

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

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

"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

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

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

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