Voys Telephony

With the Voys integration, Tillor sees who is calling and shows the customer details straight away. Calls, recordings and transcripts then end up under Phone Calls. Voys is a business phone provider.

Before you start:

• You need an active Voys VoIP account, and access to the call plan settings in Voys.
• You need the Manage integrations permission.
• The caller's phone number must be on the customer profile or on a contact person, otherwise Tillor cannot link the call to a customer.

Set up VoysCopy link to this section

1. Go to Settings (sidebar under Support)

2. Choose Integrations and open Voys in the list
3. On the detail page, enter your Voys details (username, password, client_uuid, token) and click Install

You need an active Voys VoIP account.

Find the URLs for VoysCopy link to this section

Tillor and Voys talk to each other through addresses (URLs). At some steps Voys asks Tillor for an answer, for example whether you are open. That answer is ACK (yes, continue) or NAK (no, follow the other path). A webhook is an address that Voys calls during a call.

For webhooks, caller name lookup and access codes, you use the URLs that Tillor generates for you.

1. Go to Settings > Integrations and open Voys
2. After installation, the URLs to configure block appears on the detail page under Settings - copy the right URL for each purpose

Among other things, you will find:

• Conversation notifications - webhook URL for call events
• Webhook for Caller Lookup - URL for caller name lookup in your Voys call plan
• XML Phonebook - URL for VoIP phones to fetch the phone book
• Access codes - URL for operating the access point (barrier, gate or door) through the call plan
• Opening hours webhook - ACK when Tillor is open, NAK when Tillor is closed
• Caller allowed webhook - ACK when the caller may be put through, NAK when the caller must go to voicemail
• Routing webhook - ACK with a destination, NAK when no destination is set

In the Voys call plan, use the same variables as listed in Tillor (such as {callerid}, {did}, {callername}, {callid} and {code}).

Configure call notifications in VoysCopy link to this section

1. In Voys, open the Call notifications module
2. Click Add
3. For package/service, choose Custom
4. Paste the Tillor URL from Conversation notifications
5. Save

Voys documentation:

• Call notifications

Configure caller names (caller lookup) in the call planCopy link to this section

For caller name lookup, you use a webhook step in the call plan in Voys.

1. In Tillor, open the Webhook for Caller Lookup URL (on Settings > Integrations > Voys, under URLs to configure) and copy it
2. In Voys, open the Webhooks module and create a webhook with this URL template
3. Activate that webhook in your call plan through the webhook step
4. In the URL template, use the variables that Voys supports ({callerid}, {did}, {callername} and, if needed, {code})
5. In the webhook routing, set Variable caller name so that the returned name is shown on handsets

The opening hours and routing webhooks do not do a caller name lookup. Use this separate step for that.

More background:

• Webhooks
• What are call notifications (difference from webhooks)

Opening hours and destinations in the call planCopy link to this section

Tillor is the source for opening hours, holidays and public holiday exceptions. Voys no longer needs to know that calendar itself.

1. On Settings > Integrations > Voys, choose the Voys handset for open and optionally for closed
2. Copy Opening hours webhook or Routing webhook from URLs to configure
3. In Voys, create a webhook with that URL template
4. Put that webhook as a step in the call plan, above any menus
5. Leave Use menu off

Two patterns:

• Opening hours webhook - status=ACK follows the HTTP and menu succeeded path (open), status=NAK follows HTTP or menu failed (closed). If an open destination is set, it is included with ACK as destination.
• Routing webhook - Tillor chooses the destination. In the succeeded step, set Variable final destination. ACK + destination when there is a destination, otherwise NAK.

On an error or timeout, Voys takes the failed path. Treat that as closed.

Voys documentation: Webhooks.

Send callers to voicemail automaticallyCopy link to this section

With the Caller allowed webhook, you let Voys decide per caller whether a call is put through. Tillor checks whether the caller's number belongs to a customer who has automatic voicemail switched on.

First set up the call plan:

1. Copy Caller allowed webhook from URLs to configure on Settings > Integrations > Voys
2. In Voys, create a webhook with that URL template
3. Put that webhook as a step in the call plan, above the steps that put the call through
4. Leave Use menu off
5. Send the HTTP and menu succeeded path on to your normal routing and the HTTP or menu failed path to voicemail
6. On Settings > Integrations > Voys, under Call routing, tick Auto voicemail in Voys

As long as that is off, you will not see Send calls to voicemail on the customer profile.

Then switch on automatic voicemail per customer:

1. Open the customer profile and go to the Communication tab
2. In Communication settings, tick the Send calls to voicemail option
3. Click Save

This is how the answer works:

• ACK - the caller may go through. This also applies to unknown numbers and to callers with a hidden number.
• NAK - the number belongs to a customer with automatic voicemail. Voys follows the failed path.

Tillor compares the caller's number with the phone number on the customer profile, regardless of spaces or country code notation. Phone numbers of contact persons do not count.

This webhook does not look at opening hours. Combine it with the opening hours or routing webhook by putting both as separate steps in the call plan.

Voys documentation: Webhooks.

Fixed routing per callerCopy link to this section

The same Routing webhook can send a caller straight to a specific Voys handset, extension or phone number. That only applies to customers for whom you have chosen a destination, and only when Static call routing in Voys is on.

1. Put the Routing webhook in the call plan, as with opening hours
2. In the succeeded step, set Variable final destination
3. On Settings > Integrations > Voys, under Call routing, tick Static call routing in Voys

As long as that is off, you will not see Static call routing on the customer profile. The webhook then only uses the handset for open or closed.

Then set the destination per customer:

1. Open the customer profile and go to the Communication tab
2. Under Static call routing, choose a Voys handset, or Other for a phone number or extension (for example 411)
3. Choose None to switch off the fixed routing
4. Click Save

This is how the routing webhook chooses the destination:

• If there is a fixed destination for this caller, that is the destination.
• Otherwise, destination is the Voys handset for open or closed.
• NAK - there is no fixed destination and no handset for the current state. This also applies to unknown numbers and to callers with a hidden number, as long as there is no open or closed handset.

Tillor compares the caller's number with the phone number on the customer profile, regardless of spaces or country code notation. Phone numbers of contact persons do not count.

On an error or timeout, Voys takes the failed path.

Voys documentation: Webhooks.

What happens next?Copy link to this section

• Every call that comes in or goes out is listed in CommunicationPhone Calls, with the customer attached if the number matches. See Phone Calls.
• For an incoming call, the caller appears as a card at the bottom right in Tillor, with the customer details.
• Recordings and transcripts follow as soon as the call has ended, if call recording is switched on in your Voys account.

Problems?Copy link to this section

See alsoCopy link to this section