# Cuộc gọi

## Lịch sử cuộc gọi

Api  truy xuất lịch sử cuộc gọi  điện thoại trên nền tảng CareSoft. 

### Thông tin trường dữ liệu của cuộc gọi

<table><thead><tr><th width="102.33333333333331" data-type="number">Stt</th><th width="169">Tên trường</th><th width="142">Kiểu <select><option value="677a1bddfdbf41dc93c2e98d54dc768c" label="INT" color="blue"></option><option value="09e2cd7cb62c4ebb837ee7ace4f1365d" label="TEXT" color="blue"></option><option value="48baa45513d54325a42fd2d6bcb3d73b" label="DATETIME" color="blue"></option><option value="e9405356d62e428eaeda5e19696c5821" label="STRING" color="blue"></option><option value="5ed04b5dec8d48058d7a13b82608e28b" label="TIME" color="blue"></option><option value="423df29d3c0c40aaaa2e4e19994c90bd" label="URL" color="blue"></option></select></th><th></th></tr></thead><tbody><tr><td>1</td><td>call_id</td><td><span data-option="e9405356d62e428eaeda5e19696c5821">STRING</span></td><td>ID cuộc gọi, duy nhất trên toàn hệ thống</td></tr><tr><td>2</td><td>caller</td><td><span data-option="e9405356d62e428eaeda5e19696c5821">STRING</span></td><td>Người gọi</td></tr><tr><td>3</td><td>called</td><td><span data-option="e9405356d62e428eaeda5e19696c5821">STRING</span></td><td>Người nghe</td></tr><tr><td>4</td><td>user_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>ID chuyên viên</td></tr><tr><td>5</td><td>agent_id</td><td><span data-option="09e2cd7cb62c4ebb837ee7ace4f1365d">TEXT</span></td><td>Số IP phone của chuyên viên</td></tr><tr><td>6</td><td>group_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>Id của bộ phận của chuyên viên</td></tr><tr><td>7</td><td>call_type</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>Kiểu cuộc gọi có 2 giá trị 0 hoặc 1 <a data-footnote-ref href="#user-content-fn-1"> (?)</a></td></tr><tr><td>8</td><td>start_time</td><td><span data-option="48baa45513d54325a42fd2d6bcb3d73b">DATETIME</span></td><td>Thời điểm bắt đầu </td></tr><tr><td>9</td><td>end_time</td><td><span data-option="48baa45513d54325a42fd2d6bcb3d73b">DATETIME</span></td><td>Thời điểm kết thúc</td></tr><tr><td>10</td><td>call_status</td><td><span data-option="e9405356d62e428eaeda5e19696c5821">STRING</span></td><td><p>Tình trạng cuộc gọi  có 2 giá trị</p><p>miss, metAgent <a data-footnote-ref href="#user-content-fn-2"> (?)</a></p></td></tr><tr><td>11</td><td>wait_time</td><td><span data-option="5ed04b5dec8d48058d7a13b82608e28b">TIME</span></td><td>Thời gian chờ nhận cuộc gọi</td></tr><tr><td>12</td><td>hold_time</td><td><span data-option="5ed04b5dec8d48058d7a13b82608e28b">TIME</span></td><td>Thời gian giữ máy (khi chuyên viên bấm Hold) </td></tr><tr><td>13</td><td>talk_time</td><td><span data-option="5ed04b5dec8d48058d7a13b82608e28b">TIME</span></td><td>Thời giam đàm thoại </td></tr><tr><td>14</td><td>end_status</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>Trạng thái kết thúc, có 2 giá trị "cus", system" <a data-footnote-ref href="#user-content-fn-3">(?)</a></td></tr><tr><td>15</td><td>ticket_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>ID phiếu ghi</td></tr><tr><td>16</td><td>missed_reason</td><td><span data-option="e9405356d62e428eaeda5e19696c5821">STRING</span></td><td>Trạng thái nhỡ có 4 trạng thái (missed_customer , missed_agent_device , missed_agent_reject , missed_agent_timeout )  <a data-footnote-ref href="#user-content-fn-4">(?)</a><br>Khai thác trường dữ liệu này nếu trường "call_status" có giá trị là "miss"</td></tr><tr><td>17</td><td>last_agent_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>Chuyên viên cuối cùng nhận cuộc gọi <a data-footnote-ref href="#user-content-fn-5">(?)</a></td></tr><tr><td>18</td><td>path</td><td><span data-option="423df29d3c0c40aaaa2e4e19994c90bd">URL</span></td><td>Đường dẫn file ghi âm (streaming) <br><a data-footnote-ref href="#user-content-fn-6">(*) </a></td></tr><tr><td>19</td><td>path_download</td><td><span data-option="423df29d3c0c40aaaa2e4e19994c90bd">URL</span></td><td>Đường dẫn file ghi âm (dùng để tải về) <a data-footnote-ref href="#user-content-fn-6">(*) </a></td></tr><tr><td>20</td><td>service_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>Id <a href="dich-vu">dịch vụ</a> thoại trên CareSoft</td></tr><tr><td>21</td><td>last_user_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>ID chuyên viên cuối cùng nhận cuộc gọi</td></tr><tr><td>22</td><td>dtmf</td><td><span data-option="09e2cd7cb62c4ebb837ee7ace4f1365d">TEXT</span></td><td>Dữ liệu phím bấm của khách hàng</td></tr><tr><td>23</td><td>call_survey</td><td><span data-option="09e2cd7cb62c4ebb837ee7ace4f1365d">TEXT</span></td><td>Khảo sát khách hàng thông qua kênh thoại. Khi cấu hình theo khảo sát sau cuộc gọi thì sẽ phát ghi âm để khảo sát, KH đánh giá theo nội dung ghi âm bằng cách bấm phím. </td></tr><tr><td>24</td><td>call_survey_result</td><td><span data-option="09e2cd7cb62c4ebb837ee7ace4f1365d">TEXT</span></td><td>Dữ liệu kết quả khảo sát</td></tr></tbody></table>

#### Ví dụ minh họa lấy lịch sử cuộc gọi theo ID cuộc gọi.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F7uChdD5T2ytRSiYp3oiD%2FPostMan_ApiCall.png?alt=media&#x26;token=8751994e-4da1-41ee-be51-2dba32ae31dd" alt=""><figcaption><p>Mẫu Postman điển hình  trong trường hợp này đang tìm lịch sử cuộc gọi có id "20221008233814-LSKMQKWP-43"</p></figcaption></figure>

#### Ví dụ minh họa lấy lịch sử cuộc gọi theo số điện thoại của khách của 1 chuyên viên

{% code title="Mẫu curl minh họa" %}

```powershell
curl --location \
--globoff 'https://api.caresoft.vn/{{domain}}/api/v1/calls?start_time_to=2022-10-11T10%3A00%3A00Z&phone=0868887835&agent_id=5000&start_time_since=2022-9-11T10%3A00%3A00Z' \
--header 'Authorization: Bearer {{apiToken}}'
```

{% endcode %}

{% hint style="info" %}
Mẫu curl trên tìm danh sách cuộc gọi  cho số máy 0868887835  của chuyên viên có iphone= 5000,  Có thời điểm bắt đầu gọi trong khoảng thời gian từ 2022-08-11 tới 2022-10-11
{% endhint %}

{% hint style="warning" %}
**Lưu ý:** Một thuật toán tối ưu lệnh tìm kiếm phiếu ghi sẽ được thực hiện theo mô hình sau

1. Khi gọi API không cung cấp khoảng ngày kết thúc (chỉ truyền ngày bắt đầu:  start\_time\_since hoặc end\_time\_since). Mà ngày bắt đầu trước  ngày hiện tại hơn 31 ngày thì hệ thống sẽ tự động chọn khoảng ngày kết thúc là ngày hiện tại và trả về kết quả trong 31 ngày tính từ ngày hiện tại.  Nếu ngày bắt đầu nhỏ hơn ngày hiện tại dưới 31 ngày thì hệ thống giữ nguyên ngày bắt đầu và tiến hành lọc dữ liệu theo tham số trên
2. Khi gọi API cung cấp khoảng ngày kết thúc (param: start\_time\_to hoặc end\_time\_to). Mà ngày kết thúc sau ngày bắt đầu quá 31 ngày thì hệ thống tự chọn lại khoảng ngày bắt đầu bằng ngày kết thúc - 31 ngày
3. Khi gọi API cung cấp cả hai tham số Bắt đầu và Kết thúc cách nhau không quá 31 ngày thì hệ thống lọc phiếu ghi theo giá trị truyền vào này và trả về kết quả tương ứng.
4. Trong trường hợp cặp điều kiện start\_time\_since  và end\_time\_since đều được cung cấp hệ thống sẽ ưu tiên xử lý theo điều kiện end\_time\_since&#x20;

&#x20;  *`(Nội dung sẽ Áp dụng từ 02/03/2024)`*&#x20;
{% endhint %}

## Api lấy lịch sử cuộc gọi&#x20;

<mark style="color:blue;">`GET`</mark> `{domain}/api/v1/calls`

**Lưu ý:** Trong trường hợp cần lấy thông tin cuộc gọi trượt qua nhánh IVR thì sử dụng parameter `call_type:3` để lọc dữ liệu.&#x20;

#### Query Parameters

<table><thead><tr><th width="249">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>start_time_since<a data-footnote-ref href="#user-content-fn-7"><sup><mark style="color:$danger;">(*)</mark></sup></a></td><td>DateTime (ISO8601)</td><td>Thời gian bắt đầu cuộc gọi từ <br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</td></tr><tr><td>start_time_to</td><td>DateTime (ISO8601)</td><td>Thời gian bắt đầu cuộc gọi tới<br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</td></tr><tr><td>call_id</td><td>String</td><td>ID cuộc gọi của caresoft</td></tr><tr><td>end_time_since</td><td>DateTime (ISO8601)</td><td>Thời gian kết thúc cuộc gọi từ <br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</td></tr><tr><td>end_time_to</td><td>DateTime (ISO8601)</td><td>Thời gian kết thúc cuộc gọi tới<br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</td></tr><tr><td>call_type</td><td>Int</td><td>Kiểu cuộc gọi có 3 giá trị 0 hoặc 1 hoặc 3 <a data-footnote-ref href="#user-content-fn-8"> (?)</a></td></tr><tr><td>call_status</td><td>String</td><td><p>Tình trạng cuộc gọi  có 2 giá trị</p><p>miss, metAgent <a data-footnote-ref href="#user-content-fn-2"> (?)</a></p></td></tr><tr><td>phone</td><td>String</td><td>Số điện thoại của khách hàng</td></tr><tr><td>page</td><td>Int</td><td>Trang số</td></tr><tr><td>count</td><td>Int</td><td>Số lượng bản ghi / trang (tối đa 500)</td></tr><tr><td>agent_id</td><td>Int</td><td>Số ipPhone của <a href="chuyen-vien">chuyên viên</a></td></tr><tr><td>order_by</td><td>String</td><td>Sắp xếp dữ liệu <a data-footnote-ref href="#user-content-fn-9">(?)</a></td></tr><tr><td>order_type</td><td>String</td><td>Kiểu sắp xếp. Là 1 trong 2 giá trị<a data-footnote-ref href="#user-content-fn-10">...</a></td></tr><tr><td>service_id</td><td>Int</td><td>Id dịch vụ trên <a href="dich-vu">caresoft</a></td></tr></tbody></table>

#### Headers

| Name | Type   | Description                                                                                |
| ---- | ------ | ------------------------------------------------------------------------------------------ |
| \*\* | String | [Thông tin xác thực chung ](https://docs.caresoft.vn/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "code": "OK",
    "numFound": 74,
    "calls": [
        {
            "id": 425647,
            "customer_id": 63204960,
            "call_id": "20221008233814-LSKMQKWP-43",
            "caller": "0868887835",
            "called": "1068",
            "service_id":"100155",
            "user_id": "1",
            "agent_id": "5000",
            "group_id": 1,
            "call_type": 0,
            "start_time": "2022-10-08 23:38:14",
            "call_status": "miss",
            "end_time": "2022-10-08 23:38:29",
            "wait_time": "00:00:15",
            "hold_time": "00:00:00",
            "talk_time": "00:00:00",
            "end_status": "cus",
            "ticket_id": 315053,
            "last_agent_id": "5000",
            "last_user_id": 1,
            "call_survey": "NO",
            "call_survey_result": null,
            "missed_reason": "missed_customer"
        },{
            "id": 425885,
            "customer_id": 29370843,
            "call_id": "20221104143655-LSKMQKWP-268",
            "path": "https://caresoft.vn:19991/f/b6a0d15a9cf87c6cef402e5131f24f6b//6364c13c7569dc76dc5ee57e/6b0e12c9b3304d8e787****194/4bae18d9c8a3ab403210ae724b8f37ab.mp3",
            "path_download": "https://caresoft.vn:19991/f/b6a0d15a9cf87c6cef402e5131f24f6b//6364c13c7569dc76dc5ee57e/cd0490cefca753*****9/4bae18d9c8a3ab403210ae78f37ab.mp3",
            "caller": "0901774143",
            "called": "1066",
            "service_id":"100155",
            "user_id": "63150156",
            "agent_id": "1444",
            "group_id": 65,
            "call_type": 0,
            "start_time": "2022-11-04 14:36:55",
            "call_status": "meetAgent",
            "end_time": "2022-11-04 14:37:19",
            "wait_time": "00:00:01",
            "hold_time": "00:00:00",
            "talk_time": "00:00:23",
            "end_status": "system",
            "ticket_id": 317946,
            "last_agent_id": "1444",
            "last_user_id": 63150156,
            "call_survey": "NO",
            "call_survey_result": null,
            "missed_reason": null
        },

        ...
      ]
    }
```

{% endtab %}

{% tab title="Mô tả kết quả" %}

<table><thead><tr><th width="76">STT</th><th width="177">Trường thông tin</th><th width="101">Kiểu</th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>String</td><td>Trạng thái thành công </td></tr><tr><td>2</td><td>numFound</td><td>Int</td><td>Số lượng bản ghi tìm thấy, sử dụng phân trang dữ liệu</td></tr><tr><td>3</td><td>calls</td><td>Array</td><td>Mảng thông tin cuộc gọi.<br>Các trường dữ liệu mô tả trong <a data-mention href="#thong-tin-truong-du-lieu-cua-cuoc-goi">#thong-tin-truong-du-lieu-cua-cuoc-goi</a></td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized Mã token không đúng" %}

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

[^1]: 0: Gọi vào\
    1: Gọi ra

[^2]: miss: Gọi nhỡ\
    metAgent: Gặp chuyên viên

[^3]: cus: Do khách hàng hạ máy

    system: Do chuyên viên dập máy

[^4]: `missed_customer`  Nhỡ bởi khách

    `missed_agent_device` Nhỡ bởi thiết bị của agent\
    `missed_agent_reject`   Nhỡ bởi chuyên viên dập máy

    `missed_agent_timeout` Nhỡ bởi không tìm thấy chuyên viên<br>

[^5]: Trong trường hợp cuộc gọi được chuyển qua nhiều chuyên viên để xử lý thì trường này lưu lại số ipPhone của chuyên viên cuối cùng.

[^6]: Cần tối thiểu 5 phút sau khi kết thúc cuộc gọi để hệ thống tạo file ghi âm

[^7]:

[^8]: 0: Gọi vào\
    1: Gọi ra

    3: Cuộc gọi IVR

[^9]: Mặc định sắp xếp giảm dần theo trường  `start_time`

[^10]: ASC: Tăng dần,\
    DESC: Giảm dần (Mặc định)