What Is Hipcall External Management and How Is It Used?

In this article, we cover the Hipcall External Management system. This feature lets you hand call routing decisions over to your own web service. When an incoming call reaches an External Manager, Supervisor POSTs the call details to your URL and applies the commands in the returned JSON in order.

You can share your feedback with our engineering team at https://community.hipcall.com/c/turkce/gelistiriciler/12.

Setting up an external manager

In the Hipcall panel, go to Settings > Developer > External managements and create a new entry. Have the following information ready:

• Name (Ad): A name that lets you tell the entry apart in the panel
• Extension number (Dahili numara): The extension number of this external management entry
• Web service URL (Web servis URL'i): The endpoint Hipcall will POST the call details to
• Basic Auth credentials (Basic Auth bilgileri) (optional): The username and password, if your web service is protected with Basic Auth
• Default target (Varsayılan hedef): Where the call is routed if your web service returns an error or does not respond
  To route calls to this entry, go to Settings > Phone System > Phone Numbers (Ayarlar > Telefon sistemi > Telefon numaraları) and assign the entry to the Business hours target (Mesai içi hedef) field of the relevant number.

To debug during development, turn on "Debug Mode" from the Logs (Kayıtlar) tab of your external management entry. This mode stays active for up to 2 hours and deletes the logs when the time is up.

How it works

When a call reaches the external management module, Hipcall sends a JSON POST to the web service you provided:

{
  "caller": "+90850XXXXXXX",
  "callee": "90850XXXXXXX",
  "direction": "inbound",
  "timestamp": 1729721495,
  "external_manager_id": 2,
  "uuid": "8bcfdf1d-d7b9-434d-9207-d33a8e73ac47",
  "data": {},
  "call_flow": [
    {
      "timestamp": 1729721495,
      "action": "init",
      "detail": {
        "id": 2,
        "type": "external_manager"
      }
    }
  ]
}

Field	Type	Description
caller	string	Caller's phone number (E.164)
callee	string	Called number
direction	string	Call direction
timestamp	integer	Unix timestamp
external_manager_id	integer	ID of the External Manager
uuid	string	Unique call identifier
data	object	Key-value data kept on the External Manager
call_flow	array	Call flow history up to this point

Your web service must respond with HTTP status 200 and a JSON body in the following format:

{
  "version": "1",
  "seq": [
    {
      "action": "say",
      "args": {
        "text": "Hipcall'a hoş geldiniz. Satış için 1, destek için 2'ye basın.",
        "language": "tr-TR"
      }
    },
    {
      "action": "gather",
      "args": {
        "min_digits": 1,
        "max_digits": 1,
        "ask": "http://example.com/sessizlik.wav",
        "variable_name": "departman"
      }
    },
    {
      "action": "connect",
      "args": {
        "destination": "1000"
      }
    }
  ]
}

The commands in seq are processed in the order they are given.

Features available in External Management

play — Play an audio file

Plays the MP3/WAV file at the given URL to the caller.

{ "action": "play", "args": { "url": "https://example.com/karsilama.mp3" } }

say — Convert text to speech (TTS) (new)

Converts the text you provide to speech with the Hipcall TTS service and plays it to the caller.

{
  "action": "say",
  "args": {
    "text": "Siparişiniz hazır.",
    "language": "tr-TR"
  }
}

• text: Up to 1000 characters
• language: In BCP-47 format (e.g. tr-TR, en-US, de)

dial — Route to an external number

Connects the call to an external phone number.

{ "action": "dial", "args": { "destination": "+90532XXXXXXX" } }

connect — Route to an internal line

Connects the call to a target that has an extension number (a user, a team/queue, smart routing, a greeting announcement, etc.).

{ "action": "connect", "args": { "destination": "1000" } }

gather — Collect keypresses

Plays a prompt and collects the caller's DTMF keypresses. The collected value is stored in the External Manager's data map under the variable name you provide and is sent back to you on the next web service call.

There are two ways to use it:

With a ready-made audio file:

{
  "action": "gather",
  "args": {
    "min_digits": 1,
    "max_digits": 4,
    "ask": "https://example.com/pin-girin.wav",
    "variable_name": "pin_kodu"
  }
}

With TTS:

{
  "action": "gather",
  "args": {
    "min_digits": 1,
    "max_digits": 4,
    "text": "Lütfen PIN kodunuzu girin.",
    "language": "tr-TR",
    "variable_name": "pin_kodu"
  }
}

ask and text cannot be used at the same time. variable_name is limited to letters, digits, and underscores, and can be at most 32 characters long.

Warning: If the URL of the audio file you provide with ask is unreachable (for example, it returns a 404), Hipcall cannot play the prompt and calls your web service back with an empty data. If your code sends gather again whenever it sees an empty value, this loop can repeat many times per second. Make sure the audio file is reachable.

set_caller_name — Change the caller identity (new)

Changes the caller name/number that the other party sees when the call is connected.

{ "action": "set_caller_name", "args": { "caller_name": "SatisEkibi" } }

caller_name is limited to alphanumeric characters and can be at most 32 characters long.

hangup — End the call

Ends the call normally.

{ "action": "hangup" }

reject — Reject the call (new)

Ends the call with a rejected (busy) signal.

{ "action": "reject" }

Important ordering rules

Because of how FreeSWITCH works, some commands invalidate the commands that come after them. Keep these rules in mind:

1. dial and connect must always come last in the sequence. The remaining command queue is cleared the moment the call is connected, so later commands do not run.
2. hangup and reject end the call. Commands after them never run. Play the goodbye message first, then send hangup.
3. gather must also come last. When the caller finishes entering digits, Hipcall sends a new request to your web service (this time with the collected value in data). The new seq list your web service returns replaces the remaining commands.
4. Put set_caller_name at the beginning. To take effect before the call is connected, it must come before dial/connect.

Recommended ordering

Position	Suitable actions
Start	set_caller_name
Middle	play, say (as many as you need)
End	dial, connect, gather, hangup, or reject (exactly one)

Error cases

In the following cases, the call is routed to the default target you defined for the External Manager:

• The web service returns an HTTP response other than 200
• The web service does not respond within 15 seconds (timeout)
• The response is not valid JSON
• The JSON does not match the expected format (missing field, wrong type, etc.)
• The web service cannot be reached (network error)
  All errors are recorded in the External Manager logs; check these logs to troubleshoot. When a response contains invalid JSON or does not match the expected format, the logs show a 422 Invalid payload format error.

Next steps

To see a real-world use of External Management step by step, check out the example scenarios:

• : Identify the caller with CRM data and route the call to different queues based on PIN verification.
• : Verify callers by phone number and PIN, and route them to different extensions based on the result.