Walkthrough

API Developers reference#

12. 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#

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#

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