Overview
Not every caller deserves the same experience. Registered customers should reach your support team instantly; unknown numbers should go to a general queue. Managing routing rules in the phone system by hand does not scale — and it breaks the moment your CRM data changes.
This guide shows you how to use Web Service-Based Smart Routing to query your CRM in real time before the call is answered and return a routing decision.
How it works
When a call comes in, Hipcall's Smart Routing feature calls your HTTP endpoint with the caller's phone number. Your server looks the number up in your CRM and responds with an extension number. Hipcall routes the call accordingly — all of this happens within milliseconds, before the caller hears a single ring.
Step 2: Receive the webhook
As soon as the call arrives, Hipcall sends a POST request to your endpoint, along with the caller's phone number. Under Webhook v2 and the Standard Webhooks specification, the request delivers the full details of the incoming call.
Example request from Hipcall:
{
"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": "+447700900123",
"missing_call_reason": null,
"call_duration": null,
"callback_time": null,
"call_flow": [
{
"action": "init",
"detail": {
"id": null,
"type": "contact"
},
"timestamp": 1790691203
}
],
"direction": "inbound",
"callee_number": "+442045205757",
"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": "564aff1e-2141-4925-9c2e-b7dd28b87c16",
"record_url": null,
"number_id": 942,
"company_id": 80719
}
}
- data.caller_number: your customer's number in E.164 format
- data.callee_number: your number in Hipcall
- timestamp: timestamp of the operation
- data.uuid: the call's unique UUID
The data.caller_number field contains the caller's phone number in E.164 format. Your endpoint must respond within the timeout period: keep your CRM lookup fast.
Step 3: Look up the caller
Normalize the phone number to match your database format, then query your CRM.
Example normalization (Python):
def normalize_phone(phone):
# Remove non-numeric characters
phone = ''.join(filter(str.isdigit, phone))
# Handle Turkish local formats
if phone.startswith('0') and len(phone) == 11:
phone = '9' + phone
elif len(phone) == 10:
phone = '90' + phone
return phone
Query your database using the normalized number:
caller = data.get('caller')
normalized = normalize_phone(caller)
customer = db.execute(
'SELECT id FROM customers WHERE phone = ?',
(normalized,)
).fetchone()
Step 4: Return the routing decision
Respond with a JSON object containing the extension value the call should be routed to. Use one extension for registered customers and another for unknown callers.
Registered customer:
{ "extension": "1093" }
Unknown caller:
{ "extension": "1094" }
Hipcall reads the extension value and transfers the call to that extension immediately. The caller experiences no delay.
Tools used
| Tool | Purpose |
|---|---|
| Web Service-Based Smart Routing | Triggers your endpoint on incoming calls and routes them based on the response |
Next steps
- Smart Routing documentation — Configure route types, timeouts, and fallback behavior
- How To Get A Hipcall API Key And Make Your First Request — Secure your endpoint with API keys or Basic Authentication
- Webhooks documentation — Combine it with call events for post-call logging and analytics