{"id":1407,"date":"2018-02-06T20:36:52","date_gmt":"2018-02-07T03:36:52","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=1407"},"modified":"2018-02-06T20:36:52","modified_gmt":"2018-02-07T03:36:52","slug":"kaizala-rest-api-programming-tutorial-c","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/kaizala-rest-api-programming-tutorial-c\/","title":{"rendered":"Kaizala REST API programming tutorial (C#)"},"content":{"rendered":"<h2>Kaizala API documentation<\/h2>\n<p>Kaizala APIs are documented at\u00a0<a href=\"https:\/\/docs.microsoft.com\/en-us\/kaizala\/connectors\/api\">https:\/\/docs.microsoft.com\/en-us\/kaizala\/connectors\/api<\/a>\u00a0and consuming them would need a valid Office365 organizational subscription or a Kaizala Pro subscription.<\/p>\n<p>To validate your subscription, you should be able to sign-in to the Kaizala Management Portal \u2013\u00a0<a href=\"https:\/\/manage.kaiza.la\/\">https:\/\/manage.kaiza.la<\/a>\u00a0with your account.<\/p>\n<h2>Prerequisites<\/h2>\n<p>To use Kaizala APIs, you need to be registered on the Kaizala platform as a \u201cconnector\u201d. For connector setup, please refer the documentation at\u00a0<a href=\"https:\/\/docs.microsoft.com\/en-us\/kaizala\/connectors\/setup\">https:\/\/docs.microsoft.com\/en-us\/kaizala\/connectors\/setup<\/a><\/p>\n<p>For the rest of the documentation you will need the below:<\/p>\n<ul>\n<li>Connector ID and secret (got from your connector on\u00a0<a href=\"https:\/\/manage.kaiza.la\/\">https:\/\/manage.kaiza.la<\/a>\u00a0)<\/li>\n<li>Postman REST client (available at\u00a0<a href=\"https:\/\/www.getpostman.com\/\">https:\/\/www.getpostman.com\/<\/a>\u00a0)<\/li>\n<li>Kaizala Postman collection [<a href=\"https:\/\/app.getpostman.com\/run-collection\/f68a8abec784cc00b0b9#?env%5BKaizala-APIs-environment%5D=W3siZW5hYmxlZCI6dHJ1ZSwia2V5IjoibW9iaWxlLW51bWJlciIsInZhbHVlIjoiIiwidHlwZSI6InRleHQifSx7ImVuYWJsZWQiOnRydWUsImtleSI6ImFjY2Vzcy10b2tlbiIsInZhbHVlIjoiIiwidHlwZSI6InRleHQifSx7ImVuYWJsZWQiOnRydWUsImtleSI6InRlc3QtZ3JvdXAtaWQi\">link<\/a>]. You should see this collection in your Postman window<\/li>\n<\/ul>\n<p><img decoding=\"async\" class=\"alignnone size-full wp-image-1408\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/1-api-collection.png\" alt=\"API collection list\" width=\"316\" height=\"278\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/1-api-collection.png 316w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/1-api-collection-300x264.png 300w\" sizes=\"(max-width: 316px) 100vw, 316px\" \/><\/p>\n<p>(<em>Caveat: do not open this link in incognito mode \u2013 it would render the json instead of launching Postman client<\/em>)<\/p>\n<ul>\n<li>Visual Studio 2015 (or above)<\/li>\n<\/ul>\n<h2>Brief overview of APIs<\/h2>\n<p>Kaizala service uses token based authentication. Below are the different ways of authenticating with Kaizala:<\/p>\n<ul>\n<li>User token<\/li>\n<li>Group token<\/li>\n<li>OAuth<\/li>\n<li>Tenant token<\/li>\n<\/ul>\n<p>For this article, we would be using the first mechanism \u2013 user token. For this you will need a mobile phone with Kaizala installed.<\/p>\n<p>Steps involved in authentication:<\/p>\n<ul>\n<li>Generate PIN for the mobile endpoint<\/li>\n<li>Login with PIN and Application \/ Connector ID to get the RefreshToken<\/li>\n<li>Use the RefreshToken to generate the AccessToken<\/li>\n<\/ul>\n<p>The AccessToken generated will be subsequently used for calling Kaizala APIs.<\/p>\n<p>Note: Code given below is for reference purposes only.<\/p>\n<ul>\n<li>AccessToken is valid for 24 hours<\/li>\n<li>RefreshToken is valid for 365 days<\/li>\n<\/ul>\n<p>Samples for generating these tokens are documented below.<\/p>\n<h2>Setting up Visual Studio<\/h2>\n<ul>\n<li>Create a new project (Windows Console application)<\/li>\n<li>Add nuget references to below packages\n<ol>\n<li>NewtonSoft json [<em>used to serialize \/ deserialize json<\/em>]<\/li>\n<li>RestSharp [<em>used to send http requests<\/em>]<\/li>\n<\/ol>\n<\/li>\n<\/ul>\n<h2>Getting code from Postman<\/h2>\n<p>Postman provides a way to generate source code in various languages. For this article, we will be looking at C#.<\/p>\n<ul>\n<li>To get the code, click on \u201c<strong>Step 1 \u2013 Generate pin<\/strong>\u201d in the Postman collection.<\/li>\n<li>Click on code to launch the code popup and select\u00a0<strong>C#(RestSharp)<\/strong>\u00a0from the drop down\n<img decoding=\"async\" class=\"alignnone size-full wp-image-1409\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/2-generate-code-snippets.png\" alt=\"Screenshot selecting Manage NuGet package\" width=\"623\" height=\"219\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/2-generate-code-snippets.png 623w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/2-generate-code-snippets-300x105.png 300w\" sizes=\"(max-width: 623px) 100vw, 623px\" \/><\/li>\n<li>Click on\u00a0<strong>Copy to Clipboard<\/strong>\u00a0to copy the code snippet<\/li>\n<\/ul>\n<h2>\u00a0Console application to create and send message to a group<\/h2>\n<h3>Step1: Add references to RestSharp and Newtonsoft.Json<\/h3>\n<ul>\n<li>In solution explorer right click on References and click \u201cManage NuGet Packages\u201d\n<img decoding=\"async\" class=\"alignnone size-full wp-image-1410\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/3-add-reference-in-visual-studio.png\" alt=\"search for newtonsoft dialog box\" width=\"411\" height=\"374\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/3-add-reference-in-visual-studio.png 411w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/3-add-reference-in-visual-studio-300x273.png 300w\" sizes=\"(max-width: 411px) 100vw, 411px\" \/><\/li>\n<li>Search for Newtonsoft and RestSharp and install them\n<img decoding=\"async\" class=\"alignnone size-full wp-image-1411\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/4-newtonsoft-json-reference.png\" alt=\"search for Newtonsoft JSON dialog box\" width=\"575\" height=\"72\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/4-newtonsoft-json-reference.png 575w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/4-newtonsoft-json-reference-300x38.png 300w\" sizes=\"(max-width: 575px) 100vw, 575px\" \/>\n<img decoding=\"async\" class=\"alignnone size-full wp-image-1412\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/5-restsharp-reference.png\" alt=\"search for RestSharp dialog box\" width=\"479\" height=\"67\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/5-restsharp-reference.png 479w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2018\/06\/5-restsharp-reference-300x42.png 300w\" sizes=\"(max-width: 479px) 100vw, 479px\" \/><\/li>\n<li>Add references in the visual studio program<\/li>\n<\/ul>\n<pre>using Newtonsoft.Json;\nusing RestSharp;<\/pre>\n<h3>Step2: Declare variables to cache values<\/h3>\n<pre>string accessToken = \"\";\nstring applicationId = \" XYZABCXYZABCXYZABCXYZABCXYZAABCXYZABCXYZABC\";\nstring applicationSecret = \"QWERTYUI\";\nstring endpointUrl = \"\";\nstring mobileNumber2 = \"+917995552658\"; \/\/ added as member to the group\nstring refreshToken = \"\";\n\n<\/pre>\n<h3>Step3: Generate PIN with mobile number<\/h3>\n<pre>Console.WriteLine(\"Enter your mobile number: \");\nstring MobileNumber = Console.ReadLine();\n\nvar client = new RestClient(\"https:\/\/api.kaiza.la\/v1\/generatePin\");\nvar request = new RestRequest(Method.POST);\nrequest.AddHeader(\"postman-token\", \"090af9a6-a234-7c7c-4431-9d6af937a185\");\nrequest.AddHeader(\"cache-control\", \"no-cache\");\nrequest.AddHeader(\"content-type\", \"application\/json\");\nrequest.AddParameter(\"application\/json\", \n\"{\\\"mobileNumber\\\":\\\"\" + MobileNumber\u00a0 + \"\\\", applicationId:\\\"\"\n+ applicationId + \"\\\"}\", \nParameterType.RequestBody);\nIRestResponse response = client.Execute(request);\n\n<\/pre>\n<h3>Step4: Generate refreshToken with mobile number and PIN<\/h3>\n<pre>Console.WriteLine(\"Enter the PIN: \");\n\nstring PIN = Console.ReadLine();\n\n\n\n\nclient = new RestClient(\n        \"https:\/\/api.kaiza.la\/v1\/loginWithPinAndApplicationId\");\nrequest = new RestRequest(Method.POST);\nrequest.AddHeader(\"postman-token\", \n        \"35918c70-e897-b115-03be-cc03d0fb1c82\");\nrequest.AddHeader(\"cache-control\", \"no-cache\");\nrequest.AddHeader(\"content-type\", \"application\/json\");\nrequest.AddParameter(\"application\/json\", \"{\\\"mobileNumber\\\":\\\"\" \n\u00a0 + MobileNumber + \"\\\",\\\"applicationId\\\":\\\"\" + applicationId + \n\u00a0 \"\\\", \\\"pin\\\":\" + PIN.ToString() + \"}\", \n\u00a0 ParameterType.RequestBody);\n\nIRestResponse responsePin = client.Execute(request);\nvar loginWithPinAndApplicationIdResponse = \nJsonConvert.DeserializeObject&lt;LoginWithPinAndApplicationIdResponse&gt;\n\u00a0 (responsePin.Content);\nrefreshToken = loginWithPinAndApplicationIdResponse.RefreshToken;\nendpointUrl = loginWithPinAndApplicationIdResponse.EndpointUrl;\n\n<\/pre>\n<h3>Step5: Generate accessToken with refreshToken<\/h3>\n<pre>client = new RestClient(\"https:\/\/api.kaiza.la\/v1\/accessToken\");\nrequest = new RestRequest(Method.GET);\nrequest.AddHeader(\"postman-token\", \n \"9324c36e-0c56-d145-871c-25353f69f8be\");\n\nrequest.AddHeader(\"cache-control\", \"no-cache\");\nrequest.AddHeader(\"refreshtoken\", refreshToken);\nrequest.AddHeader(\"applicationsecret\", applicationSecret);\nrequest.AddHeader(\"applicationid\", applicationId);\nIRestResponse responseAccessToken = client.Execute(request);\nvar refreshApplicationTokenApiResponse = JsonConvert.DeserializeObject\n &lt;RefreshApplicationTokenApiResponse&gt;(responseAccessToken.Content);\naccessToken = refreshApplicationTokenApiResponse.AccessToken;<\/pre>\n<h3>Step6: Create a group with a number as member<\/h3>\n<pre>client = new RestClient(endpointUrl + \"\/v1\/groups\");\nrequest = new RestRequest(Method.POST);\nrequest.AddHeader(\"postman-token\", \n \"6192e748-6f06-a90d-0d84-a57a7f04cdb5\");\nrequest.AddHeader(\"cache-control\", \"no-cache\");\nrequest.AddHeader(\"content-type\", \"application\/json\");\nrequest.AddHeader(\"accesstoken\", accessToken);\nrequest.AddParameter(\"application\/json\", \n \"{name:\\\"Kaizala Test group\\\", welcomeMessage:\\\"Welcome to group created via C# console application\\\", members:[\\\"\" + mobileNumber2 + \"\\\"], groupType:\\\"Group\\\"}\", ParameterType.RequestBody);\n\nIRestResponse responseCreateGroup = client.Execute(request);\nvar createGroupResponse = JsonConvert.DeserializeObject&lt;CreateGroupResponse&gt;(responseCreateGroup.Content);\nstring groupId = createGroupResponse.groupId;<\/pre>\n<p>&nbsp;<\/p>\n<h3>Step7:\u00a0 Send a text message to the group<\/h3>\n<pre>client = new RestClient(endpointUrl + \n\u00a0 \"\/v1\/groups\/449b16d5-772d-4b25-8154-6d39ae357dfc\/messages\");\n\nrequest = new RestRequest(Method.POST);\nrequest.AddHeader(\"postman-token\", \n \"d2ec1078-71a6-07ff-fcd2-0505c9d89ef4\");\nrequest.AddHeader(\"cache-control\", \"no-cache\");\nrequest.AddHeader(\"content-type\", \"application\/json\");\nrequest.AddHeader(\"accesstoken\", accessToken);\nrequest.AddParameter(\"application\/json\", \n \"{message:\\\"Test message via C# console application\\\"}\\r\\n\", \n ParameterType.RequestBody);\nIRestResponse responseSendMessageToGroup = client.Execute(request);<\/pre>\n<p>&nbsp;<\/p>\n<h3>Below are the classes used for de-serializing response JSONs:<\/h3>\n<pre>\u00a0\u00a0\u00a0 public class LoginWithPinAndApplicationIdResponse\n\u00a0\u00a0\u00a0 {\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 [JsonProperty(\"refreshToken\")]\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 public string RefreshToken { get; set; }\n\u00a0\u00a0\u00a0 }\n\n\u00a0\u00a0\u00a0 public class RefreshApplicationTokenApiResponse\n\u00a0\u00a0\u00a0 {\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 [JsonProperty(\"accessToken\")]\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 public string AccessToken { get; set; }\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 [JsonProperty(\"endpointUrl\")]\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 public string EndpointUrl { get; set; }\n\u00a0\u00a0\u00a0 }\n\n\u00a0\u00a0\u00a0 public class CreateGroupResponse\n\u00a0\u00a0\u00a0 {\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/\/ &lt;summary&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/\/ GroupId which was created\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/\/ &lt;\/summary&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 [JsonProperty(\"groupId\")]\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 public string groupId;\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/\/ &lt;summary&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/\/ Name of the conversation\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/\/ &lt;\/summary&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 [JsonProperty(\"groupName\")]\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 public string conversationName;\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/\/ &lt;summary&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/\/ if the members mentioned in request are added to group\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/\/ &lt;\/summary&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 [JsonProperty(\"membersAdded\")]\n\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0public bool membersAdded;\n\u00a0\u00a0\u00a0 }<\/pre>\n<h2>References<\/h2>\n<ul>\n<li>Kaizala documentation:\u00a0<a href=\"https:\/\/docs.microsoft.com\/en-us\/Kaizala\">https:\/\/docs.microsoft.com\/en-us\/Kaizala<\/a><\/li>\n<li>Postman REST client download:\u00a0<a href=\"https:\/\/www.getpostman.com\/\">https:\/\/www.getpostman.com\/<\/a><\/li>\n<\/ul>\n<p>&nbsp;<\/p>\n","protected":false},"excerpt":{"rendered":"<p>This tutorial discusses the API documentation available and prerequisites needed to program Kaizala.<\/p>\n","protected":false},"author":69216,"featured_media":1410,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[11],"tags":[87],"class_list":["post-1407","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-office-add-ins","tag-kaizala"],"acf":[],"blog_post_summary":"<p>This tutorial discusses the API documentation available and prerequisites needed to program Kaizala.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/1407","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69216"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=1407"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/1407\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/1410"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=1407"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=1407"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=1407"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}