Show Caller Name, Company, and Balance on the Insight Card

Overview

When an agent answers a call, every second counts. Instead of searching through a CRM to find out who is calling, the agent should see the caller’s name, company, and account balance automatically — before they even say hello.

This guide shows how to combine Webhooks and the Insight Card API to display real-time caller data on the agent screen the moment a call connects.

How It Works

The integration uses two Hipcall developer tools:

1. Webhooks — Hipcall sends a call_init event to your server when a call starts.
2. Insight Card API — Your server looks up the caller and pushes a card to Hipcall, which displays it on the agent’s screen.

Architecture

flowchart TD
    A[Incoming call] --> B[Hipcall sends call_init webhook]
    B --> C[Your server receives event]
    C --> D{Match found\nin CRM/ERP?}
    D -- Yes --> E[POST to Insight Card API]
    D -- No --> F[Skip]
    E --> G[Agent sees caller info on screen]

Step 1: Receive the Webhook

Subscribe to the call_init event in Account > Integrations > Webhooks. Hipcall will POST a JSON payload to your endpoint when every call starts — both inbound and outbound.

Example webhook payload:

{
  "event": "call_init",
  "data": {
    "uuid": "call_abc123",
    "direction": "inbound",
    "caller_number": "+442045205757",
    "callee_number": "+441234567890",
    "callee_extension_id": 1042
  }
}

Extract data.uuid (the call ID) and the customer’s phone number:

• Inbound call → customer is data.caller_number
• Outbound call → customer is data.callee_number

Step 2: Look Up Caller Data in Your CRM or ERP

Use the customer’s phone number to query your data source — a database, CRM API, or ERP system.

Example response from your CRM:

{
  "full_name": "Jane Smith",
  "company": "Acme Corp",
  "balance": "4250.00"
}

If no match is found, you can skip the Insight Card call entirely or push a minimal fallback card.

Step 3: Push the Card to the Insight Card API

Call the Insight Card API with the call_id from the webhook to associate the card with the right call.

Endpoint:

POST /api/v3/calls/{call_id}/cards
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Request body:

{
  "card": [
    {
      "type": "title",
      "text": "Hipcall Insight",
      "link": "https://www.hipcall.com"
    },
    {
      "type": "shortText",
      "label": "Name",
      "text": "Jane Smith"
    },
    {
      "type": "shortText",
      "label": "Company",
      "text": "Acme Corp"
    },
    {
      "type": "shortText",
      "label": "Balance",
      "text": "$4,250.00"
    }
  ]
}

The card appears on the agent’s Webphone within milliseconds of the call starting.

Tools Used

Tool	Purpose
Webhooks	Receive call_init event when a call starts
Insight Card API	Push caller data card to the agent’s screen

Next Steps

• Webhooks documentation — Subscribe to events, configure retry logic, verify signatures
• Insight Card API reference — Full list of card types, formatting options, and limits
• REST API authentication — Set up API keys or OAuth 2.0 for your server