Custom Integration Example: Talkdesk

Learn how to create a Hatch contact from your Talkdesk interactions

Use Case

Integrating your Hatch account with Talkdesk opens up a variety of possibilities. For instance, you may want to follow up on specific phone interactions with a text message.

One effective use case is implementing an abandoned call campaign. When your team misses a call, you can configure Talkdesk to automatically send that information over to Hatch as a new opportunity. This allows you to promptly engage with the customer via an instant launch campaign, demonstrating your commitment to their needs and ensuring they feel valued.

Setup

There are three main steps to setting up a custom Hatch integration from your Talkdesk account. On the Hatch side, there is a small bit of configuration required (the same key steps you would take for any custom API setup).

Hatch Setup

1. Navigate to the Integrations marketplace. 
2. Generate a custom source value. The source value should meaningfully identify where the data has originated from. In this case, we will recommend the source "custom:talkdesk"
   
   
3. Generate an API Key to be used by the new Talkdesk source. 
4. You will need these values later when configuring the connection in Talkdesk. 

Create a Custom Connection in Talkdesk

In this step you will configure the Hatch url where Talkdesk will send data to. Talkdesk has a detailed explanation on this here.

Head to your Talkdesk account, and add a custom integration.


This will bring you to the configuration screen. 

The key pieces you will need from Hatch are the same steps you will take with any custom integration to the Hatch Contacts API:

1. Name the connection (recommended: Hatch)
2. Describe the purpose of the connection
3. Input the Hatch API url to base path: https://api.usehatchapp.com/v1/contacts
4. Select No Authentication as the authentication type (we will authenticate via the headers)
5. Under Other Settings, add a header. This header will provide the API key for the Hatch API. 
   1. The field should be and the value "Bearer {API KEY}" where you should replace {API KEY} with the key generated in your Hatch account. 

Create a Custom Action in Talkdesk

Now that we have a connection, we can configure custom actions that utilize that connection. Talkdesk has a detailed article here, but we will cover the Hatch specific configurations.

Click Action and then Add Action

This will take you to the action configuration screen.

1. Name your Action (recommended Create Hatch Contact)
2. Describe your Action (what is the goal or the end result?)
3. Configure the relative path:
   1. change the method from GET to POST because we are sending data out from Talkdesk and posting it into Hatch. 
   2. the path field should remain blank-- there is no relative path needed on top of the base url that was already configured in the connection
4. The path preview should still look like https://api.usehatchapp.com/v1/contacts
5. Path parameters: none required
6. Path parameters: none required
7. Path parameters: none required
8. Path parameters: none required
9. Configure Output-- here is where we define the data that will be sent in or out of Talkdesk
10. Input is not applicable in this scenario, so leave this blank
11. Output is the data that needs to be sent to the Hatch API. Below are two example data schemas that you can copy and paste into the Output schema with minimal adjustment. 
    
    

Basic Data Schema
Use this schema if you only care about sending the bare minimum data needed to create a Hatch contact.

{
  "$schema": "http://json-schema.org/draft-07/schema#", 
  "type": "object", 
  "title": "Output",  
  "required": [ 
    "externalId", "phoneNumber", "source"
  ],
  "properties": {  
    "externalId": {
      "type": "string",   
      "title": "Contact Id" 
    },
    "status": {
      "type": "string",
      "title": "Call Status"
    },
   "email": {
      "type": "string",
      "title": "Contact Email"
    },
    "phoneNumber": {
      "type": "string",
      "title": "Contact Phone"
    },
    "firstName": {
      "type": "string",
      "title": "Contact First Name"
    },
    "lastName": {
      "type": "string",
      "title": "Contact Last Name"
    },
    "source": {
      "type": "string",
      "title": "Source for Hatch"
    }
  }
}

Advanced Data Schema

Use this schema if you care about including some additional details from the Talkdesk record. Details might include useful context that will inform the Hatch user (or bot) or can be used as a snippet in the messaging. 

{
  "$schema": "http://json-schema.org/draft-07/schema#", 
  "type": "object", 
  "title": "Output",  
  "required": [ 
    "externalId", "phoneNumber", "source"
  ],
  "properties": {  
    "externalId": {
      "type": "string",   
      "title": "Contact Id" 
    },
    "status": {
      "type": "string",
      "title": "Call Status"
    },
   "email": {
      "type": "string",
      "title": "Contact Email"
    },
    "phoneNumber": {
      "type": "string",
      "title": "Contact Phone"
    },
    "firstName": {
      "type": "string",
      "title": "Contact First Name"
    },
    "lastName": {
      "type": "string",
      "title": "Contact Last Name"
    },
    "source": {
      "type": "string",
      "title": "Source for Hatch"
    },
    "details": {
      "type": "object",
      "title": "Custom Details",
      "properties": {
        "example 1": {
          "type": "string",
          "title": "Example 1 Name"
        },
        "example 2": {
          "type": "string",
          "title": "Example 2 Name"
        },
        "additionalProperties": false
            }
    }
  }
}

Configure Automation in Talkdesk

In this step you will tie together all these pieces and choose a trigger(s) that will automatically initiate your custom action and send the data to the Hatch connection.

In the Hatch connection, add an Automation.

This will take you to the Automation configuration

1. Give the Automation a name. 
2. Choose a trigger event. 
   1. Example: Trigger when a Talkdesk call is dispositioned
3. Choose an action that should be completed after the trigger. The action in this case will be the custom action to send data to Hatch. 
4. Apply filters as necessary. The filters will determine if there are certain additional criteria to determine if the trigger event should proceed. 
   1. Example: It may not be productive to send data to Hatch when every call is dispositioned. Maybe only some dispositions are relevant. 
5. Map the related data from the event trigger into the data output schema we created earlier. The fields that will be sent to Hatch are on the right side and are the result of that schema. 
   
   1. The mapped event variables can be dragged from the left side of the screen into the Hatch fields.
   2. In the "source" field, hand-write the custom source that you setup in Hatch earlier. From our example, this was "custom:talkdesk" so we will plug that value in. 
      
      
      
      

You're Done! 

In order to go live, you will need to enable the Automation on the main page.