API Call - Add/Update Metadata

General description:

Metadata plays a crucial role in organizing and categorizing data across various touchpoints within our platform. To streamline the process of updating or adding metadata entries, we utilize a specialized API endpoint. For a detailed understanding of metadata and its importance, you can refer to our comprehensive guide on Participant Attributes. This article will guide you through the process of using the UpdateMetadataBatch endpoint to efficiently update or add metadata for specific participant transactions.

It is important to note that while updates are processed immediately, they will only be visible in the platform the next day due to our data integration cycle. This ensures that all updates are fully integrated and accurately reflected in your platform by the following day.

API Endpoint Overview

Endpoint:

Type: POST

https://api-v4.hellocustomer.com/tenant/{{tenantUniqueId}}/Metadata/UpdateMetadataBatch

This endpoint allows batch updates or additions of metadata entries associated with participant transactions within a specified touchpoint of a tenant.

JSON Request Body Format

{
  "touchpointUniqueId": "YourTouchpointIDHere",
  "values": [
    {
      "participantTransactionUniqueId": "YourParticipantTransactionIDHere",
      "key": "team filter",
      "value": "Ghent"
    }
  ]
}

Fields Explanation:

• touchpointUniqueId : The unique identifier of the touchpoint for which metadata needs to be updated.
• values : An array of objects, each representing a metadata entry to be updated or added. Each object includes:
  • participantTransactionUniqueId : The unique identifier of the participant transaction to which the metadata is linked.
  • key : The metadata key (e.g., team filter ).
  • value : The value assigned to the metadata key (e.g., Ghent ).

Step-by-Step Instructions

Step 1: Prepare the Required Information

1. Identify Your Tenant and Touchpoint IDs: These can be found in the touchpoints settings of your platform or provided by your system administrator.
2. Gather Participant Transaction IDs: Obtainable by exporting data from the Conversation Manager; the needed ID can be found in the first column.
3. Decide on Metadata Keys and Values: Choose what metadata key needs to be updated (e.g., "team filter") and the new or additional value (e.g., "Ghent").

Step 2: Request a Bearer Token

1. Set Up Your API Client: Use an API client such as Postman.
2. Configure the Token Request:
   • Type: POST
   • URL: https://api-v4.hellocustomer.com/token
   • Body (x-www-form-urlencoded):
     • grant_type : client_credentials
     • client_id : (Client ID from your API connector available in the platform)
     • client_secret : (Client secret from your API connector available in the platform)
3. Send the Request and Retrieve Your Token: Upon successful authentication, you will receive a bearer token. Copy this token as it will be used in the metadata update request.

Step 3: Construct the JSON Request Body

• Create a JSON object in a simple text editor (like Notepad) as follows:

{
  "touchpointUniqueId": "YourTouchpointIDHere",
  "values": [
    {
      "participantTransactionUniqueId": "YourParticipantTransactionIDHere",
      "key": "team filter",
      "value": "Ghent"
    },
    {
      "participantTransactionUniqueId": "Your2ndParticipantTransactionIDHere",
      "key": "team filter",
      "value": "Brussels"
    }
  ]
}

• Replace "YourTouchpointIDHere" and "YourParticipantTransactionIDHere" with your actual IDs.

Step 4: Send the Request

• Use an API Client: Such as Postman.
• Enter the Endpoint URL: Substitute {{tenantUniqueId}} with your tenant ID:

https://api-v4.hellocustomer.com/tenant/{{tenantUniqueId}}/Metadata/UpdateMetadataBatch

• Set to POST: This specifies the action type.
• Add Authorization: Include the bearer token in the header as 'Authorization: Bearer {token}'.

• Add the JSON Body: Paste the prepared JSON into the body section of your API client.
• Send the Request: Click the send button.

Step 5: Handle the Response

• Success: Receive confirmation of metadata updates.
• Error Handling: If errors occur, the system will provide a message. Correct any issues based on this feedback.

Step 6: Verify the Update with Batch Progress Call

To confirm your metadata updates have been processed, you can check the status of the submitted batch:

• Construct the Batch Progress URL:

https://api-v4.hellocustomer.com/tenant/{{tenantUniqueId}}/Metadata/batch/{{batchId}}/progress

Replace {{tenantUniqueId}} and {{batchId}} with the appropriate values. The {{batchId}} is provided in the response of your metadata update request.

• Set Request to GET: Indicating you are retrieving information.
• Add Authorization: Include the bearer token in the header as 'Authorization: Bearer {token}'.
• Send the Request: Use your API client to make the request and view the status of your metadata updates.
• Interpret the Response: The response will provide details on how many entries were processed, how many are in processing, and if any failed.