# 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](../voice/inbound-trunks/creating-a-new-trunk-group.html#user-panel-trunk-group)),  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" |

On this page