Docs

Call progress events

https://api.apifonica.com/v2/accounts/{accountSID}/calls

Overview

Call controllers allow you to be informed of the current call statuses on each leg of the call. They can also send XML instructions in response to statuses.
You will need to create an Application and specify a controller URL for it. This application's SID should then be used when executing the makeCall request.
If you enable the events=all parameter, Apifonica will notify you every time a call status changes.

For inbound calls, you can modify the events reception mode in the properties of the Application. The possible values of the "events" parameter are "all" for all statuses, "none" for none, or a pipe-separated list of specific statuses (e.g. "answered|completed", etc.).

Request examples

The following example demonstrates making a call with events that are sent to the controller (call_app_sid parameter).

curl –X POST https://api.apifonica.com/v2/accounts/{accountSID}/calls \
-H ‘Content-Type: application/json’ \
-d ‘{ 
     "from": "35315313424", 
     "to": "447860041755", 
     "events": "all", 
     "call_app_sid": "app1f255680-95dd-34c6-b83f-c86b8095adcb" 
    }’ \
-u {accountSID}:{authToken}

Response example

{
    "status_code": 201,
    "status_message": "CREATED",
    "uri": "/v2/accounts/{accountSID}/calls/{callSID}"
}

Apifonica request parameters being sent to controller URL

When using the events=all option, the application should send a response to all status notifications it receives. An empty response or an Apifonica XML file is expected in response to each HTTP request.

Option 1. Changing the call flow

You must send an XML file in response. The Apifonica XML file will break the current scenario and the call will be modified

Option 2. Continue the call without any changes

Your application must give an HTTP response with status code 200 OK and an empty body. This response will signify no action

The following parameters are sent to the controller URL, if it is provided:

Parameter name

Description

call_sid

Unique call identifier.

channel

The call channel. The possible values are "number" (for calling local/mobile/SIP numbers) or "viber" (for Viber calls).

created

Date and time the call was added to the queue.

status

Call (A-leg) status.

from

Caller phone number (conventional or virtual).

to

Recipient’s phone number (conventional or virtual).

direction

Call direction.

Either inbound or outbound.

leg_status

B-leg status.

leg_from

The phone or virtual number of the caller for the B-leg.

leg_to

The phone or virtual number which is used in the B-leg to receive the call.

leg_call_sid

Identifier of the call leg

tag

Optional string field; can be used for custom filtering of the calls.

Description

Call unique identifier.

Description

Date and time of the adding the call to queue.

Description

Call (A-leg) status.

Description

Caller phone number (conventional or virtual).

Description

Recipient’s phone number (conventional or virtual).

Description

Call direction.

Either inbound or outbound.

Description

B-leg status.

Description

The phone number or virtual number of the caller for B-leg.

Description

The phone number or virtual number which is used in B-leg to receive the call.

Description

The call channel. The possible values are "number" (for calling on local/mobile/SIP numbers), "viber" (for calling on Viber).

Description

Optional string field; can be used for custom filtering of the calls

Example of request from Apifonica to controller URL

{
        "call_sid":"calf3efd4c0-f11e-37cd-ba44-085e81f8381c",
        "channel": "number",
        "created":"2017-04-24 09:12:09",
        "status":"answered",
        "from":"883140100000086",
        "to":"358451215221",
        "direction":"outbound",
        "leg_status":"ringing",
        "leg_from":"883140100000086",
        "leg_to":"883140100000099",
        "leg_call_sid": "cal1369a705-7568-3487-9c5a-1111111111",
        "tag": "Calls from client1"
}