Integrations

#Configuration

Each chatbot can have one Customer Data Endpoint. Configure it from Chatbot Settings → Integrations:

• HTTP Method — GET or POST
• Endpoint URL — The URL CustomerHero will call
• Custom Headers — Add authorization tokens or other headers
• Enable/Disable — Toggle the endpoint on or off without deleting the configuration

#Request format

When an agent opens a conversation, CustomerHero sends the customer's known identifiers to your endpoint. The format depends on the HTTP method.

POST requests

Customer data is sent as a JSON body:

1
2
3
4
5
6
7
8
9
10
{
  "customer": {
    "externalId": "user_12345",
    "email": "jane@acme.com",
    "name": "Jane Smith",
    "phone": "+1234567890"
  },
  "chatbotId": "bot_xxx",
  "conversationId": "conv_xxx"
}

GET requests

Customer data is appended as query parameters:

1
2
3
4
5
6
7
GET https://api.acme.com/customer-data
  ?externalId=user_12345
  &email=jane%40acme.com
  &name=Jane+Smith
  &phone=%2B1234567890
  &chatbotId=bot_xxx
  &conversationId=conv_xxx

#Response format

Your endpoint must return a JSON object with a sections array. Each section has a title and a list of properties:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "sections": [
    {
      "title": "Account",
      "properties": [
        { "label": "Plan", "value": "Pro ($99/mo)" },
        { "label": "Status", "value": "Active", "color": "green" },
        { "label": "MRR", "value": "$99.00" },
        { "label": "Member since", "value": "2024-01-15" }
      ]
    },
    {
      "title": "Recent Orders",
      "properties": [
        {
          "label": "Last order",
          "value": "#4521 - $149.99",
          "url": "https://admin.acme.com/orders/4521"
        },
        { "label": "Order status", "value": "Delivered" },
        { "label": "Total orders", "value": "12" }
      ]
    }
  ]
}

Property fields

• label (string, required) — Property name
• value (string, required) — Display value
• url (string, optional) — Makes the value a clickable link
• color (string, optional) — green, red, yellow, or blue — renders as a colored badge

Titles are truncated at 200 characters, labels at 200, and values at 1,000. Any extra fields are stripped for security.

#Request signing

If your chatbot has an Identity Secret configured, every request includes an X-CustomerHero-Signature header containing an HMAC-SHA256 hex digest. This lets you verify the request came from CustomerHero.

• POST requests — The signature is computed over the JSON body
• GET requests — The signature is computed over the query string (the ?key=value&... portion of the URL)

To verify, compute HMAC-SHA256(secret, payload) and compare the hex digest to the header value.

#Testing

The integrations page includes a Test Endpoint button that calls your endpoint with mock customer data. You can customize the test values (External ID, Email, Name, Phone) before sending.

After the test, CustomerHero validates the response against the expected format and shows:

• HTTP status code and response time
• The raw JSON response
• Format validation — whether the response has the correct sections structure, with specific error messages for any issues

You can test before saving — the test uses the current form values, not the saved configuration.

#Caching

Responses are cached server-side for 5 minutes per customer to avoid excessive calls to your endpoint. Agents can click the Refresh button in the inbox sidebar to bypass the cache and fetch fresh data.