Metadata Endpoint

Helper can retrieve additional information about your customers through a metadata endpoint passed in the client SDK.

How It Works

When customerInfoUrl is provided to the chat or create message API, Helper will make a GET request to the endpoint with the customer's email and timestamp. You can return metadata to improve AI responses and enable more features in the mailbox.

Request Example

terminal

GET https://your-endpoint.com/customer?email=customer@example.com&timestamp=1684234567
Authorization: Bearer dGhpcyBpcyBhbiBlbmNvZGVkIGhtYWMgc2lnbmF0dXJl

Parameter	Type	In	Description
`email`	string	query	The customer's email address.
`timestamp`	number	query	The current timestamp, optionally used for HMAC authentication.
`Authorization`	string	header	The HMAC signature for the request.

Response Format

Your server must return a JSON response in this format:

terminal

{
  "success": true,
  "customer": {
    // All fields are optional
    "name": "Customer Name",
    "value": 1000, // Numeric value for sorting/prioritization
    "actions": {
      // Key-value pairs of links to display in the sidebar, for agents to quickly access other backend apps.
      "Profile": "https://example.com/profile",
      "Orders": "https://example.com/orders"
    },
    "metadata": {
      // Arbitrary metadata to include in prompts. This will also be shown in the conversation sidebar.
      "Department": "Engineering",
      "Role": "Senior Developer",
      "Join Date": "2023-01-15"
    }
  }
}

HMAC Authentication

Helper authenticates requests to your endpoint using HMAC-SHA256.

We strongly recommend you verify the request is legitimate by generating the same HMAC signature on your server and checking it matches the header. Without this verification, if a malicious actor discovers your metadata endpoint they could continuously make requests with different emails to try and scrape customer data.

The signature is generated from the query string (?email=...&timestamp=...) and the HMAC secret shown in your settings.

HMAC Validation (Node.js Example)

index.js

import crypto from "crypto";
 
// Validate incoming request from Helper
function validateHelperRequest(queryParams, authorizationHeader, hmacSecret) {
  // Extract the Bearer token
  const hmacSignature = authorizationHeader.replace("Bearer ", "");
 
  // Create a URLSearchParams string from the query parameters
  const serializedParams = new URLSearchParams(queryParams).toString();
 
  // Generate the expected HMAC signature
  const expectedHmac = crypto.createHmac("sha256", hmacSecret).update(serializedParams).digest("base64");
 
  // Compare the signatures (consider using a time-safe comparison in production)
  return hmacSignature === expectedHmac;
}