VoipNow for Developers

Page tree

This page describes how you can trigger events each time an extension receives or places a phone call.

Overview

This is the Call Events Guide. It explains the Service interface and the responses of the service. The Call Events is a web service that enables developers to interact with the system every time an Extension receives, terminates or places a call.

The following events are supported by the service:

  • Dial-In is an event that occurs when a call is received by an extension;
  • Dial-Out is an event that occurs when a call is made by an extension;
  • Hangup is an event that occurs when a call the extension is involved in is terminated;
  • Answer on incoming call: The request will be sent when an incoming phone call is answered;
  • Answer on outgoing call (by the other party): The request will be sent when an outgoing phone call is answered by the other party.

How It Works

A Call Event has the following properties:

NameDescription
Event type
This is the event on which the associated script is executed.
Can be set to Dial-In, Dial-Out or Hangup.
Request method

HTTP method that is used when executing the script.
Can be set to GET or POST.

Script URL
URL address of the script that is executed when the event occurs.


And occurs as described below:

STEP 1: When a event occurs on an Extension, the system verifies if that event requires that a request is made.

STEP 2: If there is an event, the system will make a HTTP request to URL using the associated HTTP method .

The system adds extra parameters to the request depending on the method used:

  • GET - parameters are added to the query part of the request.
  • POST - parameters are added to the body of the request.

Extra Parameters

NameOccurrenceTypeDescription

CallID

1

String

The call's unique identifier.

CallerIDNum

1

String

The caller's CallerID number.

CallerIDName

1

String

The caller's CallerID name.

CalledDID

1

String

The public number of the called extension (if available).

CalledExtension

1

String

The extension that received the call. Supported format: extended extension number (e.g. yyyy*zzz).

CallStatus

1

String

The call status. This parameter is set to the following values, depending on the event type.

For the Dial-In and the Dial-Out event types, the parameter is set to CALLING.

For the Hangup event type, the parameter can have one of the following values:

  • ANSWER - The call is answered, the caller reached the callee; this is a successful call;
  • BUSY - A busy signal is played to the caller; the dial command reached its number, but the number is busy;
  • NOANSWER - The call is not answered; the dial command reached its number, the number rang for too long and the dial timed out;
  • CANCEL - The call is canceled; the dial command reached its number, but the caller hung up before the callee picked up;
  • CONGESTION - Congestion; this status is usually a sign that the dialed number is not recognized;
  • CHANUNAVAIL - Channel unavailable; on SIP, peer may not be registered.

CallFlow

1

String

The call flow:

  • IN - for the calls received by the extension;
  • OUT - for the calls made by the extension.

CallerExtension

1

String

The extension that made the call. Supported format: extended extension number (e.g. yyyy*zzz).

CalledNumber

1

String

The number that was dialed by the caller (can be an external number: 003258422544, the extended IVR number: 0003*001 or the short IVR number: 001.)

CallAPIID

1

String

The call ID that is auto-generated and maintained for the entire duration of the call, no matter how many transfers are performed. This variable can be used to identify in the events the calls started using a UnifiedAPI request.

How to Add a Call Event

In order to be able to use Call Events, you must first assign it on an Extension. The system supports two methods to assign a Call Event.

Add via the Voipnow Web Management Interface

The system allows you to add call events using the web management interface. More details can be found here.

Add via UnifiedAPI

A Call Event can be added using the UnifiedAPI PhoneCallEvents Service.

Example

Check how it can be used in the TrackMyCalls example.

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.