Voice IN Call Events

Voice IN Call Events allow you to receive real-time call events for calls to DID numbers using the HTTP protocol. Events are delivered individually with no batching delays. All events are sent via an HTTP POST request, and content can optionally be gzipped.

Available event types:

Call Start Event – Triggered when the call routing process is completed, and the system attempts to connect the call.
Call Connect Event – Triggered when a 200 OK/Connect response is received from the destination.
Call End Event – Triggered when the call is terminated.

Request Header Example

The following is an example of an HTTP POST request header used to send Voice IN Call Events. It includes details such as the destination server, content type, encoding, and request size.

POST /call-events HTTP/1.1
Host: 192.0.2.5
User-Agent: CDR-streamer
Accept: */*
Content-Type: application/vnd.api+json
Content-Encoding: gzip
Content-Length: 2358

Call Start Event

A Call Start Event is triggered when the call routing process is completed by DIDWW, and the system attempts to connect the call to the destination. At this stage, a SIP INVITE is sent from DIDWW to initiate the call connection.

When is this event triggered?

After DIDWW completes call routing.
Before the call is answered or connected.
When a SIP INVITE is sent to the call destination.

HTTP Request Payload Example

The following JSON payload represents a Call Start Event, providing details such as the event type, unique identifier, start time, and involved phone numbers.

{
    "type": "incoming-call-start-event",
    "id": "10-10282FC6-5F632C460006A397-AC8C7700",
    "attributes": {
        "time_start": "2020-03-05T11:05:33.879559+00:00",
        "did_number": "123456789123",
        "src_number": "111111222222"
    }
}

Call Connect Event

A Call Connect Event is triggered when a 200 OK/Connect response is received from the destination (call leg B). This indicates that the call has been successfully answered or connected.

When is this event triggered?

After the call destination responds with 200 OK.
When the call moves from the ringing state to an active conversation.

Note

If the call is terminated before this handshake, the Call Connect Event will not be sent.

HTTP Request Payload Example

The following JSON payload represents a Call Connect Event, providing details such as event type, call identifier, timestamps, and involved phone numbers.

{
    "type": "incoming-call-connect-event",
    "id": "10-10282FC6-5F632C460006A397-AC8C7700",
    "attributes": {
        "time_start": "2020-03-05T11:05:33.879559+00:00",
        "time_connect": "2020-03-05T11:05:38.879559+00:00",
        "did_number": "123456789123",
        "src_number": "111111222222",
        "call_id": "26-26-3F1808BB-61090891000DD511-EA83C700"
    }
}

Call End Event

A Call End Event is triggered when the call is terminated, regardless of whether it was answered or not. This event provides details such as the start time, connection time (if applicable), end time, and total call duration.

When is this event triggered?

When the call is disconnected by either party.
Whether the call was answered (connected) or not.

HTTP Request Payload Example

The following JSON payload represents a Call End Event, including timestamps, call duration, and involved phone numbers.

{
    "type": "incoming-call-end-event",
    "id": "10-10282FC6-5F632C460006A397-AC8C7700",
    "attributes": {
        "time_start": "2020-03-05T11:05:33.879559+00:00",
        "time_connect": "2020-03-05T11:05:38.879559+00:00",
        "time_end": "2020-03-05T11:05:58.879559+00:00",
        "duration": 20,
        "did_number": "123456789123",
        "src_number": "111111222222",
        "call_id": "26-26-3F1808BB-61090891000DD511-EA83C700"
    }
}

Call Event Attributes

Voice IN (inbound) Call Event Descriptions and Examples
Attribute	Type	Description	Example
type	String	Event type. Possible values: incoming-call-start-event incoming-call-connect-event incoming-call-end-event	“incoming-call-start-event”
id	String	Unique call identifier. All related events share the same id.	“10-10282FC6-5F632C460006A397-AC8C7700”
attributes	Hash	Structure containing all event attributes.	See below for attribute details.
time_start	Timestamp	Timestamp when the initial SIP INVITE is received.	“2024-03-05T11:05:33.879559+00:00”
time_connect	Timestamp	Time when the call was successfully connected (200 OK SIP response). If the call was never connected, this value is null in the Call End Event.	“2024-03-05T11:05:38.879559+00:00”
time_end	Timestamp	Timestamp when the call was disconnected.	“2024-03-05T11:05:58.879559+00:00”
call_id	String	SIP Call-ID for the call leg between the customer’s equipment and DIDWW. Since DIDWW supports call rerouting (see trunk group configuration), it is not possible to determine the connected call leg at the incoming-call-start-event step. Therefore, the call_id attribute is not present in the incoming-call-start-event payload.	“26-26-3F1808BB-61090891000DD511-EA83C700”
duration	Integer	Call duration in seconds. For unconnected calls, this value is 0.	20
src_number	String	Caller ID (originating phone number).	“111111222222”
did_number	String	The DID number receiving the call.	“123456789123”