Advanced administration

Recommend pre-reading:Understanding Hooks Test and Debug Workflows Using Logs Klass Views Calling a Rest API within a workflow Kustomer Card SDK (for Option B only)There are two options for giving agents the ability to make requests to an external API with the press of a button.Option A - Klass View Embedded Workflow Button1. Create a workflow with a Form Hook following the instructions in “Understanding Hooks”.2. Create a new Klass View with a View Location of “Insights Panel Card”, Data Source of the Klass of object you want the button to appear on while viewing (we will use kobject.order for this example) and paste in this code:<Button  onClick={() => {    fetch(      "HOOK_URL",      {        method: "POST",        headers: {          "content-type": "application/json"        },        body: JSON.stringify({kobject, customer})      }    );  }} >  Cancel </Button>HOOK_URL will be the URL of the Form Hook that you created in step 1.kobject and customer are JSON payloads representing of the timeline object and customer being viewed when the button is clicked.The resulting button in the timeline will look like this:3. We can now build out our workflow with a Rest API JSON step using the data submitted by the button. Use the Workflow Logger to inspect the JSON body of the data posted by the hook to build and troubleshoot your workflow.We can also add text inputs for agents to enter additional information before submitting. The input elements available are the standard HTML Form Elements. Use the JavaScript DOM getElementById method to pass the input value in the JSON payload posted to the form hook.<div>   <div>     <label>Reason</label><br/>   <input id="cancel-reason"/>   </div>   <br/>   <Button    onClick={() => {      fetch(        "HOOK_URL",        {          method: "POST",          headers: {            "content-type": "application/json"          },          body: JSON.stringify({             kobject,             customer,            cancellationReason: document.getElementById('cancel-reason').value,          })        }      );    }}   >    Cancel   </Button> </div>Option B - iFrame embedded CardThis approach allows you to embed a context card using our Kustomer Card SDK. Using the SDK allows you to develop and host an HTML/JavaScript page to interact with Kustomer without using the Klass View editor. This SDK will allow your context card to easily fetch information about the customer/object currently being viewed in the Kustomer timeline and use it to render your card and make API requests. The main benefit to using the SDK over the Klass View editor is that developers can build the card within their own development environment and use their own dependencies instead of working within the Klass View Editor.Once your card/iFrame is created, your company will be responsible for hosting it. Once hosted, create a new Klass View with a View Location of “Insights Panel Card” and a Data Source of the Klass of object you want the iFrame to appear on while viewing. You can then embed the card following the instructions in our developer documentation to embed your iFrame: Kustomer Apps Platform: JSX in KustomerYour card can either make a direct call to an external API or post to a Kustomer Form hook to kick off a workflow as per Option A.

The Kustomer API is a powerful tool that allows your organization to interact with nearly every resource within Kustomer. Through a series of intuitive RESTful APIs, you can securely insert and update customers, messages, conversations, custom objects (KObjects), and more.Who can access this feature?User typesAll organizations can access our APIs. Rate limits differ by tier.In this articleAPI usesUsing the Kustomer APISending requestsAuthenticationRate limitingSending data with requestsResponsesError messagesThis article will help you get started using Kustomer's REST APIs. For more information on our APIs, see our API documentation.API usesThe Kustomer API has many uses but is best applied to programmatic interactions with the Kustomer platform.For example, an airline using Kustomer could program its flight tracking software to update a customer’s timeline in Kustomer when a flight is delayed. This event would be instantly available to the airline’s customer service agents. It could also trigger a workflow that instantly sends an SMS message to the customer informing them of the delay.Note: Other common uses include the management of conversation message exports. You can create a search and export all of the conversations in that search. However, this method doesn’t include all messages within the export. To work around this limitation, consider utilizing the Kustomer API endpoint (v1/conversations/{convo id}/messages). This approach allows you to retrieve all message previews within specific conversations, providing a more comprehensive view of the data.Using the Kustomer APIThe Kustomer API is an HTTP API based on RESTful design principles. Resources are accessible via a URL similar to a website address. Each address represents a different resource.For example, requests sent to https://api.kustomerapp.com/v1/customers manipulate Customer objects. The request has a different outcome depending on the HTTP verb used in your request.A request sent to https://api.kustomerapp.com/v1/customers with the GET verb returns a list of customers belonging to your organization. Sending a POST request to the same endpoint creates a new customer.You can interact with the Kustomer API using any standard HTTP client or your own scripts and programs. We recommend Postman as a good free-to-use tool for getting started with the API.Sending requestsSending requests is as simple as choosing an endpoint, a request method, and setting the proper headers, as described below:For a full list of our available endpoints, see API reference documentation.AuthenticationAll requests to the Kustomer API are authenticated using an API token included with your request's Authorization header. Admins can manage API keys within Kustomer from the API Keys settings page. You can access this page by going to Settings > Security > API Keys.When creating a new key, you can select an API role and apply a friendly label. Roles are useful to limit the operations requests using that key can perform.To use your API key, include it in the Authorization request header, and prefix the key with “Bearer” and a single space.Rate limitingTo ensure quality service and to prevent abuse, Kustomer limits the number of API requests that can be made in a short period of time. API rate limits differ by pricing tier. For more information on our pricing tiers, see our pricing plans. To help you track your rate limit usage, we include headers in API responses that include your current rate-limiting status:For more information about our rate limits, see API rate limits.Sending Data With RequestsMost POST, GET, and PUT requests require data to be sent with them. This data is stored in the request body as a JSON object. For example, to update a customer's displayName, the request body might look like this:{  “displayName”: “Jane” }ResponsesLike requests bodies, responses are formatted in JSON. This standard format is readable by nearly all modern programming languages and environments. Most API endpoints are structured similarly, with a top-level data property that contains either an array of objects or an object with an id property, attributes, and relationships. The following is an example API response for a GET request to /v1/customers/{id}:{ "data": {   "type": "customer",   "id": "59df762a921c59001021f409",   "attributes": {     "name": "Jane Doe",     "displayName": "Jane Doe",     "displayColor": "blue",     "displayIcon": "compass",     "externalId": "59df762a921c59001021f409",     "firstName": "Jane",     "lastName": "Done",     "signedUpAt": null,     "avatarUrl": null,     "username": null,     "emails": [       {         "email": "janedoe@gmail.com",         "verified": false,         "type": "home"       }     ],     "phones": [{       "phone": "+12065551234",       "type": "home"     }]   },   "relationships": {     "org": {       "links": {         "self": "/v1/orgs/59d682e535145200131693ca"       },       "data": {         "type": "org",         "id": "59d682e535145200131693ca"       }     },     "messages": {       "links": {         "self": "/v1/customers/59df762a921c59001021f409/messages"       }     }   },   "links": {     "self": "/v1/customers/59df762a921c59001021f409"   } } }Error MessagesErrors commonly returned by the API will follow a common format: an HTTP status code indicating the error and a response body containing more information about the error. In the following example, the request failed because the user didn't have the proper permission set role to access that endpoint.

Here are some JSON data payload examples for an order ingest or data connection, with comments for each section. Feel free to use this as a reference when sending in data payloads to a Kustomer webhook.These example payloads are some suggestions based on what we've seen organizations use in past implementations. We offer these as a frame of reference to help you see how other organizations set up Kustomer, and may not be 100% accurate or relevant to your Kustomer setup. Your payload does not have to include all of these attributes or match the same attribute names.To learn more about importing data into Kustomer, please check out our help articles on Data Connect and Use workflows to import data.Notes:Always ensure the object has a unique identifier order_number.Include an attribute for customer information, as this is needed to associate an order to the appropriate customer timeline.These examples include /* inline comments */ to illustrate functionality. You should remove these in production.{   "order_number": "AB-1234",   "created_at": "2019-05-04T05:47:31+10:00",   "status": "received",   /* section for order customer information */   "customer": {     "first_name": "Jane",     "last_name": "Doe",     "email": "janedoe@example.com",     "phone": "(555) 555-1234"   },   /* section for order shipping information */   "shipping": {     "address": {       "address1": "123 Main St",       "address2": "Apt 4",       "city": "Houston",       "state": "TX",       "country_code": "US",       "zip": "77001"     },     "method": {       "description": "Fast Shipping",       "carrier": "FedEx",       "carrier_code": "FDEG"     }   },   /* section for order billing information (if applicable) */   "billing_address": {     "address1": "123 Main St",     "address2": "Apt 4",     "city": "Houston",     "state": "TX",     "country_code": "US",     "zip": "77001"   },   /* section for order items */   "line_items": [{       "sku": "1234-01",       "item_name": "Test-Item",       "sku_name": "Test-Item-Sku",       "quantity": 1,       "weight": 1,       "sale_price": 9.99,       "subtotal": 0,       "sales_tax_collected": 0     },     {       "sku": "1234-02",       "item_name": "Test-Item 2",       "sku_name": "Test-Item-Sku-2",       "quantity": 1,       "weight": 1,       "sale_price": 9.99,       "subtotal": 0,       "sales_tax_collected": 0     }   ],   /* section for order cost information (if applicable) */   "totals": {     "items": 19.98,     "shipping": 11.98,     "additional shipping": 0,     "tax": 4.04,     "grand": 36   },   /* section for order payment details (if applicable) */   "payment_details": {     "brand": "Visa",     "last_4": "1234",     "status": "successful"   } }API payload examplesKustomer's API documentation is an extensive resource around many of the API calls you can leverage to manage your Kustomer data. While the payloads may be different depending on the type of call you are looking to make, you can view the data structure of different API calls as a reference for creating different types of integrations with other systems you may use internally. To view these example payloads:Go to our API documentation to a specific API call that you want to learn more about how the data is structured. In this example, we can use our GET call for conversation information.Once on the next page, select the ‘200’ number within the Response section in the right-hand column.This will display a JSON example for a successful call to this API endpoint. You can use that information to understand the structure of how your data will look when Kustomer is communicating with your other systems.