What Is Quick Dial and How Is It Done?

Overview

Hipcall's speed dial feature determines the destination number for an incoming call by asking your web service. For example, a courier needs to call the person who placed an order, but data protection law means they must not know that person's number. The courier dials the speed dial's extension and enters the order number; Hipcall sends this information to your server and calls the destination number it returns. The courier talks to the customer but never sees the number.

Before you start

The API feature must be active on your Hipcall plan.
Your service must be reachable over the internet. During development, you can use ngrok or a similar tunneling tool.

Step 1: Create a speed dial entry

In the Hipcall panel, go to Settings → Developer → Speed Dial and click the New button. Fill in the following fields in the form that opens:

Field	Description
Name	The name you give the speed dial entry (e.g. "Order Call").
Extension number	An extension number from 10 to 9999 (e.g. `72`). The courier dials this number to start the speed dial.
URL	The address of your web service (e.g. `https://xxxx.ngrok-free.app/hizli-arama`). Hipcall sends a POST request to this address.
Web service authentication	Optional. If you check it, the Username and Password fields appear. Hipcall sends its requests with the `Authorization: Basic <Base64>` header.

You also need to upload two announcements:

Intro announcement before calling the number: The audio file played to the user for the digit entry (e.g. "Please enter the order number.").
Announcement to play if the service fails: The audio file played when the web service fails.

Step 2: Route a phone number to the speed dial

Creating the speed dial entry is not enough on its own. To route incoming calls to this entry, you need to assign a phone number to the speed dial:

Go to Settings → Phone System → Phone Numbers.
Select the number you want to route to the speed dial.
Switch to the Business Hours tab.
In the Business hours target field, select the speed dial extension number you created.
Once this is set, calls that reach the number play the announcement first and are then routed to your web service.

How it works

The user dials the speed dial's extension number (e.g. 72).
Hipcall sends a call_init event to your webhook URL.
The system plays the intro announcement you uploaded (e.g. "Please enter the order number.").
The user enters the order number (e.g. 1234).
Hipcall sends the entered value to your web service with an HTTP POST.
Your web service returns the destination number.
Hipcall calls the destination number and connects the user.

Request format from Hipcall

After the user finishes entering digits, Hipcall sends a POST request with the following structure to your web service URL:

{
  "timestamp": 1791891730,
  "number": "1234",
  "uuid": "e785****-****-****-****-********87e5",
  "user_id": null,
  "speed_dial_id": 19
}

Request fields

Field	Type	Description
`timestamp`	integer	Unix timestamp of the request.
`number`	string	The DTMF digits the user entered. Your order code is in this field.
`uuid`	string	Unique ID of the call.
`user_id`	integer / null	ID of the Hipcall user who started the call. Can be `null` if the call comes in over an external line.
`speed_dial_id`	integer	ID of the speed dial entry that was triggered.

Note: If you enabled authentication, Hipcall sends the value Basic <Base64> in the request's Authorization header. Your web service must validate this header.

Expected response from your web service

Hipcall expects the destination number to call in the destination field of your web service's response:

{ "destination": "90530XXXXXXX" }

Return the phone number with its area code, as a string made up of digits and nothing else (e.g. 90530XXXXXXX).

Webhook events

During the speed dial process, Hipcall sends events that report the call's lifecycle to your webhook URL. These events occur in this order: call_init, call_bridged, and call_hangup.

call_init — Call started

The event sent when the call first starts. The call_flow array contains an init action of type speed_dial:

{
  "data": {
    "caller_number": "+90551XXXXXXX",
    "callee_number": "+90850XXXXXXX",
    "uuid": "e785****-****-****-****-********87e5",
    "direction": "inbound",
    "channel_id": 942,
    "number_id": 942,
    "channel_type": "number",
    "caller_type": "contact",
    "callee_type": null,
    "caller_id": null,
    "callee_id": null,
    "user_id": null,
    "started_at": "2026-10-13T11:42:04Z",
    "answered_at": null,
    "bridged_at": null,
    "ended_at": null,
    "call_duration": null,
    "first_touch_duration": null,
    "has_recording": false,
    "record_url": null,
    "missing_call": null,
    "missing_call_reason": null,
    "hangup_by": null,
    "credited": null,
    "contact_id": null,
    "company_id": null,
    "voicemail_id": null,
    "voicemail_url": null,
    "voicemail_type": null,
    "callback_time": null,
    "callback_user_id": null,
    "callback_cdr_uuid": null,
    "team_touch_at": null,
    "call_flow": [
      {
        "action": "init",
        "detail": {
          "id": 19,
          "type": "speed_dial"
        },
        "timestamp": 1791891724
      }
    ]
  },
  "event": "call_init"
}

call_bridged — Call connected

The event sent when the connection is established after the destination number is dialed. route and bridge actions are added to the call_flow array:

{
  "data": {
    "caller_number": "+90551XXXXXXX",
    "callee_number": "+90850XXXXXXX",
    "uuid": "e785****-****-****-****-********87e5",
    "direction": "inbound",
    "started_at": "2026-10-13T11:42:04Z",
    "answered_at": null,
    "bridged_at": null,
    "call_flow": [
      {
        "action": "bridge",
        "detail": { "id": null, "type": "contact" },
        "timestamp": 1791891731
      },
      {
        "action": "route",
        "detail": { "id": null, "type": "contact" },
        "timestamp": 1791891730
      },
      {
        "action": "init",
        "detail": { "id": 19, "type": "speed_dial" },
        "timestamp": 1791891724
      }
    ]
  },
  "event": "call_bridged"
}

call_hangup — Call ended

The event sent when the call ends. Fields such as call_duration, record_url, and hangup_by are populated:

{
  "data": {
    "caller_number": "+90551XXXXXXX",
    "callee_number": "+90850XXXXXXX",
    "uuid": "e785****-****-****-****-********87e5",
    "direction": "inbound",
    "started_at": "2026-10-13T11:42:04Z",
    "answered_at": "2026-10-13T11:42:04Z",
    "bridged_at": "2026-10-13T11:42:17Z",
    "ended_at": "2026-10-13T11:42:43Z",
    "call_duration": 39,
    "first_touch_duration": 13,
    "has_recording": true,
    "record_url": "https://storage.hipcall.com.tr/recordings/.../e785****-****-****-****-********87e5.mp3?...",
    "missing_call": false,
    "hangup_by": "user",
    "credited": false,
    "callee_id": 19,
    "callee_type": "speed_dial",
    "call_flow": [
      {
        "action": "hangup",
        "detail": { "hangup_by": "user" },
        "timestamp": 1791891763
      },
      {
        "action": "bridge",
        "detail": { "id": null, "type": "contact" },
        "timestamp": 1791891731
      },
      {
        "action": "route",
        "detail": { "id": null, "type": "contact" },
        "timestamp": 1791891730
      },
      {
        "action": "init",
        "detail": { "id": 19, "type": "speed_dial" },
        "timestamp": 1791891724
      }
    ]
  },
  "event": "call_hangup"
}

When it fails

If communication with the web service fails for any reason, the system plays the error announcement to the user and ends the call.

The following cases count as failures:

The HTTP status code of the response is not 200
The HTTP request is not answered within 3 seconds
The Basic Auth username or password for the web service is incorrect
The JSON in the response is not valid
The destination number in the JSON is not a number that can be dialed (e.g. 3ASDASDF)

Technical support

Our company does not provide technical support for third-party software. Instead, you can ask your questions to the developers in the community, in Turkish or English.

Next steps

To see real-world use cases of the Hipcall API step by step, check out the other example scenarios:

Work through the Place Calls by Order Number Without Seeing the Customer's Phone Number guide to learn how to implement the speed dial integration with a Python web service, how to find the customer's phone number from the order number, and how to test the call flow.