Viacurso

Help ›

Taking calls from your phone system

When the dispatcher's phone rings, the app shows a box with the caller's name, their addresses and recent rides — and a new ride can be created from it in a single click. No more asking "who's calling?" and searching through a list.

This page explains how to connect it. The company administrator can do it alone, without us. It takes a few minutes, provided you have something that can call us — and that is the one prerequisite, so let's get it out of the way first.

First things first: what you need

The app cannot find out that your phone is ringing by itself. Something has to tell it. You therefore need a phone system or VoIP provider that can call a web address when a call comes in — this is known as a webhook.

Systems that can do this include:

  • Asterisk and front-ends such as FreePBX or Issabel,
  • 3CX,
  • many VoIP providers, who offer it under names like "webhook",

"HTTP notification" or "callback URL" for incoming calls.

An ordinary mobile phone cannot do this. A mobile has no way of telling anyone that it is ringing. The same goes for a landline plugged straight into a handset. If you take bookings on a mobile, this feature unfortunately will not help you — better to know that now than after an hour spent hunting through settings.

Not sure what you have? Ask whoever looks after your phones, or your provider: "Can our phone system send an HTTP request (a webhook) to a given address when a call comes in?" A yes or no settles it.

Step 1: Generate a password

In the app, open Telephony (in the top menu — only the company administrator sees it) and click Generate a password.

The password is shown only once. Copy it straight away: the database keeps nothing but a hash of it, so not even we can show it again. If you lose it, simply generate a new one and update your phone system.

What it is for: it stops anyone else from sending calls into your account. The address is public; the password is what protects it.

Step 2: Enter the details into your phone system

The same screen shows you two addresses — one for the start of a call, one for the end. They look like this (<your-key> will be an actual string):

POST https://viacurso.com/api/telephony/<your-key>/incoming-call
POST https://viacurso.com/api/telephony/<your-key>/call-ended

Each request needs:

  • the header X-Telephony-Secret: <your password from step 1>
  • the header Content-Type: application/json
  • a JSON body:
{ "number": "+420777123456", "line": "main" }

number is the caller's number and may arrive in any common format (+420777123456, 777123456, 777 123 456) — the app normalises it. line is optional and serves only as a note about which line the call came in on.

The end of a call (call-ended) is optional too. Everything works without it; the call record simply will not say when it ended.

Give the address and the password to whoever looks after your phones. They do not need access to the app — those two details are enough.

Example: Asterisk / FreePBX

In your dialplan (extensions.conf), add a curl call at the start of the incoming-call context:

exten => _X.,1,NoOp(Incoming call from ${CALLERID(num)})
 same => n,System(curl -s -m 3 -X POST \
   -H "Content-Type: application/json" \
   -H "X-Telephony-Secret: YOUR_PASSWORD" \
   -d "{\"number\":\"${CALLERID(num)}\",\"line\":\"main\"}" \
   https://viacurso.com/api/telephony/YOUR_KEY/incoming-call)
 same => n,Dial(SIP/dispatch,30)
 same => n,System(curl -s -m 3 -X POST \
   -H "Content-Type: application/json" \
   -H "X-Telephony-Secret: YOUR_PASSWORD" \
   -d "{\"number\":\"${CALLERID(num)}\"}" \
   https://viacurso.com/api/telephony/YOUR_KEY/call-ended)
 same => n,Hangup()

In FreePBX the same goes into Admin → Config Edit → extensions_custom.conf, or you can use a module that runs a command on an incoming call.

Two things to watch out for:

  • Keep the -m 3 (a three-second timeout). If our server ever fails to

answer, it must not hold up the ringing.

  • System() runs synchronously. If even that brief pause bothers you,

use TrySystem() or send the request in the background (curl … &).

Example: 3CX

3CX has Settings → CRM Integration (Admin → Integrations in newer versions). Create a custom template with an HTTP request:

  • URL: https://viacurso.com/api/telephony/YOUR_KEY/incoming-call
  • Method: POST
  • Headers: X-Telephony-Secret: YOUR_PASSWORD,

Content-Type: application/json

  • Body: {"number":"[Number]","line":"3CX"}

The placeholder for the caller's number is written [Number] in 3CX; some versions use %CallerNumber%. Your version's documentation will tell you which applies.

Another phone system or provider

Anything that can send an HTTP POST with a custom header will do. Give your technician three things: the address, the header with the password and the shape of the body from step 2. Nothing else is needed.

Step 3: Switch incoming calls on

Back in the app, on the Telephony screen, click Switch on. While it is off, calls are rejected even with a valid password. That is deliberate: it lets you prepare the configuration in peace and go live when you are ready.

Step 4: Check that it works

There are two separate checks and both are worth doing:

  1. A test call in the app — the Make a test call button shows

dispatchers the box exactly as a real call would. It confirms the box appears and that the customer is found by their number.

  1. A real call — ring your own number from another phone. The

last received call then appears at the bottom of the Telephony screen. That is how you know your phone system really is reaching us.

If the second check stays silent, the problem is on the phone system's side — most often a typo in the address, a missing password header, or a firewall that will not let HTTPS out.

When something needs to change

  • You have changed phone systems, or the password has leaked:

generate a new password. The old one stops working immediately. The address stays the same, so only the password changes in your system.

  • You want to pause the connection: the Switch off button is

enough; nothing is deleted.

  • You are done with it for good: *Invalidate the password and switch

off*.

Questions people ask us

Will the dispatcher see the number of an unknown caller too? Yes — the box always appears. For an unknown number there simply will not be a name, and you will be offered the option of creating a new customer.

Do you record calls? No. Neither the content nor any audio is stored. All that is recorded is when the call came in, from which number, who handled it in the app and whether a ride came out of it.

How long are the records kept? Ninety days, after which they delete themselves.

Does this need anything extra in our contract? The caller's phone number is personal data and is processed under the data processing agreement you already have. There is nothing further to sign.

Can several companies use it at once? Yes. Every company has its own key and password, and calls are never mixed up between them.

Still stuck? Get in touch — we will help, even when the problem is on your side of the line.