Hipcall Developers Knowledgebase / Use Cases

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

Display caller name, company, and balance on the agent's screen the moment a call connects, using Webhooks and the Insight Card API.

Updated October 22, 2026
Read 4 min
On this page

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.initiated 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.initiated webhook"]
    B --> C["Your server receives event"]
    C --> D{"Match found in 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.initiated event in Settings > Developer > Webhooks. Hipcall will POST a JSON payload to your endpoint when every call starts (both inbound and outbound).

Example webhook payload:

{
"id": "msg_01j8m4k8c9p2x4r7v3z1a9b2c3",
"type": "call.initiated",
"timestamp": "2026-09-29T14:13:23Z",
"data": {
"credited": null,
"team_touch_at": null,
"first_touch_duration": null,
"contact_id": null,
"callee_id": null,
"answered_at": null,
"voicemail_url": null,
"caller_number": "+442045205757",
"missing_call_reason": null,
"call_duration": null,
"callback_time": null,
"call_flow": [
{
"action": "init",
"detail": {
"id": null,
"type": "contact"
},
"timestamp": 1790691203
}
],
"direction": "outbound",
"callee_number": "+447700900123",
"voicemail_id": null,
"callback_user_id": null,
"callee_type": "contact",
"ended_at": null,
"missing_call": null,
"channel_type": "number",
"callback_cdr_uuid": null,
"voicemail_type": null,
"caller_id": null,
"started_at": "2026-09-29T14:13:23Z",
"bridged_at": null,
"channel_id": 942,
"caller_type": null,
"user_id": 4200,
"hangup_by": null,
"uuid": "410c92c5-2b61-4dd2-aa75-xxxxxxxxxxxx",
"record_url": null,
"number_id": 942,
"company_id": 80719
}
}

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, skip the Insight Card call entirely and return an immediate 200 OK response to the webhook.

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 active call.

Endpoint:

POST https://use.hipcall.com/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.

Supported row types:

Row Type Fields Description
title type, text, link Main card header. Clickable when link is provided.
shortText type, text, label, link, ios, android Two-column data row with label on the left and value on the right.
user type, label, user_id Displays the name of a specific agent from their Hipcall user ID.

Important considerations

  • Each row type accepts only its predefined fields. For instance, sending user_id in a shortText row results in a 422 Unprocessable Entity response. Do not include null or irrelevant properties in row objects.
  • Do not send cards after a call ends. The API may accept the card, but the agent will not be able to view it.
  • Acknowledge webhooks promptly. Return 200 OK in under 50 milliseconds and push the card asynchronously.

Tools used

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

Next steps

  • Match the caller's phone number with your CRM records and automatically route calls to different extensions based on customer status.
  • Webhooks documentation: Subscribe to events, configure retry logic, verify signatures.
  • REST API authentication: Set up API keys or OAuth 2.0 for your server.

Was this article helpful?