Skip to main content

Spike - Integrating Auth0 User Management with Dixa

Overview​

This guide demonstrates how to integrate Auth0 with Dixa using the custom card integration. This is to prove out the use of moving customer related actions out of CS Cockpit and into Dixa.

Setup​

Firstly we have setup a UAT instance of Dixa. In production we only have a single account that serves across all of our environments. This is not useful when producing and testing custom card integrations.

The url is https://rapha-uat.dixa.com/

To gain access either use sputnik to create an account on your behalf or send a query in the Technology Slack channel.

What are Custom Cards?​

With Custom Cards you can display information from external sources (for instance your CRM system) in the conversation view in Dixa, so the agent has all the necessary information available to them without having to switch between systems. In our instance this would be performing auth actions on behalf of a user such as triggering the reset password flow, changing the customers emails or even blocking an account from logging in.

Prerequisites​

You have to add an HTTPS API endpoint exposed on the default port 443 that responds with a JSON payload. Currently Dixa only supports HTTPS traffic on port 443. This endpoint is used during the first render to get user information from the third party. In our instance we should check that the user exists in Auth0.

Adding a Custom Card in Dixa​

  1. Go to Settings.
  2. Go to Integrations.
  3. Click on Custom Card.
  4. Click on Add Custom Card.
  5. Enter a Title for the Custom Card. This will be the header in the conversation view. In our example this is Auth0.
  6. Enter the Hook URL (the URL to the endpoint you want to fetch data from) and choose the request method. In our POC we used GET.
  7. Add an Authorization Header. This wasn't done as part of the POC. However we should implement this when for production.
    • If the authorization type is Basic you will be asked to provide the user and password required for the 3rd party API (the information will be encoded in base64 and passed to the 3rd party).
    • If you select the Bearer authorization type then you will be required to specify the token required for the 3rd party API (the information will be passed with the Bearer prefix).
    • If you select the custom Authorization type, you can specify the prefix to be used inside the Authorization header.
  8. (optional) Add a Custom header. If the API you are connecting to requires additional or alternative headers (like x-api-key for a Amazon hosted system) then you can use the Custom Header option to add additional key-value headers.
  9. You can use placeholders in the Hook URL, headers and body of the request. It is recommended to use a POST and pass multiple placeholders. This is because a customer can contact via multiple channels and we need to extract their email depending which route they take.
  10. Add HTML that will render the information from the external system. The template can be written in HTML and supports Liquid, too. An exaple can be found in the POC git repository here. When the Custom Card is set up correctly, information from your external system will be displayed in the conversation view.

iframe​

Each Custom Card is wrapped in a sandboxed iframe. This means each card is completely isolated from the Dixa interface and any other custom card.

It's possible to execute javascript in the custom card eg. fetching data, validating input, etc, as well as use CSS to style the card. You can see that this is possible in the POC.

⚠️ When fetching data using Javascript (with eg. Fetch API) please be aware of CORS on the receiving endpoint.

You can fix it by adding the header Access-Control-Allow-Origin: * on OPTIONS and actual (POST/GET/PUT/PATCH/DELETE,....) requests, which will allow that the resource can be accessed by custom cards.

Resources​