> For the complete documentation index, see [llms.txt](https://api.omicall.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.omicall.com/omicall-api/da-kenh.md).

# Đa kênh

## Khởi tạo cuộc trò chuyện

<mark style="color:green;">`POST`</mark> `[URL]/api/social/{channel}/new_room`

Khởi tạo cuộc trò chuyện

**Path Variable**

| Name       | Description                              |
| ---------- | ---------------------------------------- |
| channel \* | Nguồn chat của khách hàng : **livetalk** |

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |
| X-API-KEY    | `<API KEY>`        |

**Body**

<table><thead><tr><th width="170">Name</th><th width="115">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>uuid</code></td><td>string</td><td>Id của cuộc trò chuyện bên đối tác . Trường hợp empty hệ thống tự khởi tạo</td></tr><tr><td><code>guest_info</code></td><td>object</td><td><p>Thông tin khách hàng chat</p><p></p><pre class="language-postman_json"><code class="lang-postman_json">{
"phone": "0395*****",
"full_name": "Nguyen Van Hien",
"domain": "" //Nguồn định danh
}
</code></pre><p></p><p></p></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "instance_id": "stg",
    "payload": {
        "conversation": {
            "created_date": 1738723737112,
            "last_updated_date": 1738723737112,
            "_id": "67a2d199beda7563afac23c6",
            "guest_info": {
                "phone": "0395*****",
                "full_name": "Nguyen Van Hien",
                "email": null,
                "contact_id": null,
                "new_contact": false,
                "uuid": "000000000000-1",
                "domain": "support130",
                "browser": null,
                "ip": null,
                "address": null,
                "lat": null,
                "lon": null,
                "other_info": {
                    "full_name": "Nguyen Van Hien",
                    "mail": null,
                    "phone_number": "0395*****"
                }
            },
            "last_message": null,
            "web_navigate": null,
            "status": "active",
            "uuid": "000000000000-1",
            "name": "Nguyen Van Hien",
            "name_unsigned": "0395*****",
            "start_type": "script",
            "members": [
            ],
            "last_message_info": {
                "sender": "guest",
                "send_time": 1738723737036,
                "create_by": null,
                "last_agent_sent_time": null,
                "last_customer_sent_time": 1738723737036
            },
            "customer_project_id": null,
            "customer_app_id": null,
            "user_app_ids": null
        }
    },
    "instance_version": "1.2.164",
    "key_enabled": false,
    "status_code": 9999
}
```

{% endtab %}
{% endtabs %}

## Gửi tin nhắn

<mark style="color:green;">`POST`</mark> `[URL]/api/social/{channel}/guest_send_message`

**Path Variable**

| Name       | Description                              |
| ---------- | ---------------------------------------- |
| channel \* | Nguồn chat của khách hàng : **livetalk** |

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |
| X-API-KEY    | `<API KEY>`        |

**Body**

<table><thead><tr><th width="167">Name</th><th width="138">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>uuid *</code></td><td>String</td><td>Id của cuộc trò chuyện đã khởi tạo trước đó</td></tr><tr><td><code>content *</code></td><td>String</td><td>Nội dung tin nhắn</td></tr><tr><td><code>multimedias</code></td><td>Array Object</td><td><p><code>[{"name":"",</code></p><p>  <code>"url:"",</code></p><p>  <code>"content_type":""</code></p><p><code>}]</code></p><p>Danh sách tập tin đính kèm</p></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "instance_id": "stg",
    "payload": {
        "created_date": 1738723776704,
        "last_updated_date": 1738723776704,
        "_id": "67a2d1c0beda7563afac23f4",
        "created_by": {},
        "last_updated_by": {},
        "tenant_id": "67064126273def645101f76c",
        "is_deleted": false,
        "room_id": "67a2d199beda7563afac23c6",
        "member_type": "guest",
        "type": "chat",
        "action": null,
        "content": "Tôi cần nâng cấp mở rộng số lượng đơn hàng 222",
        "multimedias": null,
        "kind": "normal",
        "receiving_group_id": "6706412f868af156014afa11",
        "change_group_info": null,
        "uuid": "f44ef584-fecf-4ecb-bcd8-c23bee387233",
        "conv_uuid": "000000000000-1",
        "activity": null,
        "new_members": null,
        "old_members": null,
        "guest_info": null,
        "template": null,
        "user_reactions": null,
        "reactions": [],
        "quote_id": null,
        "quote_message": null,
        "gpt_key": null,
        "total_token": null,
        "amount_chat_gpt": null,
        "first_message_gpt": null,
        "prompt_tokens": null,
        "completion_tokens": null,
        "chat_gpt_model": null,
        "omi_bot_node_id": null,
        "interactive_id": null,
        "interactive_start": null,
        "interactive_end": null,
        "meeting_member": null,
        "relative_message_id": null,
        "tp_response": null,
        "omi_ai_bot_info": null,
        "file_analyze_usage": null,
        "total_prompt_tokens": null,
        "total_completion_tokens": null,
        "total_total_token": null
    },
    "instance_version": "1.2.164",
    "key_enabled": false,
    "status_code": 9999
}
```

{% endtab %}
{% endtabs %}

## Gửi file đính kèm

<mark style="color:green;">`POST`</mark> `[URL]/api/social/livetalk/send_media`

**Path Variable**

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |
| X-API-KEY    | `<API KEY>`        |

**Form data**

<table><thead><tr><th width="167">Name</th><th width="138">Type</th><th>Description</th></tr></thead><tbody><tr><td>room_id*</td><td>String</td><td>Id của cuộc trò chuyện</td></tr><tr><td>content</td><td>String</td><td>Nội dung tin nhắn</td></tr><tr><td>uuid*</td><td>String</td><td>Id của cuộc trò chuyện đã khởi tạo trước đó</td></tr><tr><td>kind</td><td>String</td><td>Loại file đính kèm: normal</td></tr><tr><td>files[0]*</td><td>File</td><td>File cần gửi</td></tr><tr><td>files[0].width</td><td>Integer</td><td>Chiều rộng hình ảnh</td></tr><tr><td>files[0].height</td><td>Integer</td><td>Chiều cao hình ảnh</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status_code": 9999,
  "instance_id": "stg-localnew",
  "instance_version": "1.0.0",
  "key_enabled": false,
  "payload": {
    "_id": "667bc9f0a1b2c3d4e5f67***",
    "tenant_id": "tenant_123",
    "room_id": "65f0abc1234567890abcd***",
    "member_type": "agent",
    "type": "chat",
    "content": "Gửi kèm hình ảnh",
    "kind": "normal",
    "uuid": "req-20260624-001",
    "multimedias": [
      {
        "name": "image.jpg",
        "url": "https://cdn.omicrm.com/crm/tenant_123/meeting_message_media/2026/06/550e8400-e29b-41d4-a716-446655440000.jpg",
        "content_type": "image/jpeg",
        "width": 1280,
        "height": 720,
        "size": 245678,
        "duration": null
      }
    ],
    "is_deleted": false
  }
}
```

{% endtab %}
{% endtabs %}

## Lấy danh sách tin nhắn

<mark style="color:green;">`POST`</mark> `[URL]/api/social/message/list?page=1&size=15`

**Query Parameters**

<table><thead><tr><th width="171.7578125">Name</th><th width="169.578125">Type</th><th>Description</th></tr></thead><tbody><tr><td>page<mark style="color:red;">*</mark></td><td>Number</td><td>Chỉ số trang, bắt đầu bằng 1</td></tr><tr><td>size<mark style="color:red;">*</mark></td><td>Number</td><td>Kích thước trang, mặc định là 15</td></tr></tbody></table>

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |
| X-API-KEY    | `<API KEY>`        |

**Body**

<table><thead><tr><th width="167">Name</th><th width="138">Type</th><th>Description</th></tr></thead><tbody><tr><td>conv_id<mark style="color:red;">*</mark></td><td>String</td><td>Id của cuộc trò chuyện</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200 - Zalo" %}

```json
{
  "instance_id": "stg",
  "payload": [
    {
      "created_date": 1765772258738, // Ngày tạo
      "last_updated_date": 1765772258738, // Ngày cập nhật
      "_id": "693f8be2da2bec46dd8ab37e", // id tin nhắn
      "create_by": { // Thông tin người tạo
        "id"        : "6487dbe7572b7b17fcc8e123",
        "name"      : "Nhan vien",
        "contact_id": "6487dbeb1a309849f7205982",
      },
      "oa_id": "...", // Zalo OA id
      "zl_user_id": "...", // Zalo user id
      "message": {
        "text": "Xin chao", // Nội dung tin nhắn
        "msg_id": "4bed65845d871edf4790", // Id tin nhắn zalo
        "attachments": [ // Thông tin file đính kèm
          {
            "payload": {
              "thumbnail": "https://photo-stal-1.zdn.vn/no/jpg/thumbnail.jpg",
              "description": null,
              "url": "https://photo-stal-1.zdn.vn/no/jpg/image.jpg"
            },
            "type": "image" // Loại file đính kèm
          }
          // ...
        ]
      },
      "mg_conv_id": "68e4846e09db484ee2c21bc4" // Id cuộc trò chuyện
    }
    // ...
  ],
  "instance_version": "1.2.164",
  "key_enabled": false,
  "status_code": 9999
}

```

{% endtab %}

{% tab title="200 - Facebook" %}

```json
{
  "instance_id": "stg",
  "payload": [
    {
      "_id": "693f8f64658ba8325ccd1123", // Id tin nhắn
      "created_date": 1765773156248, // Thời gian tạo
      "last_updated_date": 1765773156248, // Thời gian cập nhật
      "create_by": { // Thông tin người tạo
        "id"        : "6487dbe7572b7b17fcc8e123",
        "name"      : "Nhan vien",
        "contact_id": "6487dbeb1a309849f7205982"
      },
      "conversation_id": "t_2878170819047206", // Id cuộc trò chuyện Facebook
      "page_id": "864321776764029", // Id Facebook page
      "message_id": "m_8sBrUAkFL0P9aRHouPFHMY0e_CHigHjcTkLCwfmkY210X70phq8hzk9ioDCO-3itNUMQC9nZRjRYh3kL5RiW0w", // Id tin nhắn Facebook
      "message": "Xin chao", // Nội dung tin nhắn
      "created_time": 1765773155000, // Thời gian gửi tin nhắn
      "from": { // Thông tin người gửi
        "name" : "Page",
        "id"   : "864321776764029",
        "email": "..."
      },
      "to": { // Thông tin người nhận
        "data": [
          {
            "name" : "User 1",
            "id"   : "25083385744656928",
            "email": "..."
          }
        ]
      },
      "attachments": { // Thông tin file đính kèm
        "data": [
          {
            "image_data": {
              "max_width": 1536,
              "width": 1536,
              "height": 2048,
              "image_type": 1,
              "max_height": 2048,
              "render_as_sticker": false,
              "preview_url": "https://scontent.fdad3-4.fna.fbcdn.net/v/t1.15752-9/598204145_899822159393061_570583991430178553_n.jpg?stp=dst-jpg_p280x280_tt6&_nc_cat=104&ccb=1-7&_nc_sid=fc17b8&_nc_ohc=bMcPQpv4U3cQ7kNvwFnuEGo&_nc_oc=AdmiTOi0tVFRhzJuEHerl2yWwxGOdQUNGIqKPrVMkLu6PLT9Y4P3aSNke466zvvpZuQ&_nc_zt=23&_nc_ht=scontent.fdad3-4.fna&edm=AKVc4UAEAAAA&_nc_tpa=Q5bMBQEFlJCiiNpboBLElLmGar8yNeSXJkNx8SS1Dm1ljnpslxiEjwRz2_iAKjL-RslwFnB1t8PvEKR2&oh=03_Q7cD4AEyqkKpZ1ayn4NUHaOBaLbgFMXgJ-nnSP4GvDvqWSz3zw&oe=6966FD55",
              "url": "https://scontent.fdad3-4.fna.fbcdn.net/v/t1.15752-9/598204145_899822159393061_570583991430178553_n.jpg?_nc_cat=104&ccb=1-7&_nc_sid=fc17b8&_nc_ohc=bMcPQpv4U3cQ7kNvwFnuEGo&_nc_oc=AdmiTOi0tVFRhzJuEHerl2yWwxGOdQUNGIqKPrVMkLu6PLT9Y4P3aSNke466zvvpZuQ&_nc_zt=23&_nc_ht=scontent.fdad3-4.fna&edm=AKVc4UAEAAAA&_nc_tpa=Q5bMBQGao6NGG81V2pmAW6XJL8KuEsdr4wnVDLSivRTclbpl2amrBYSTiRolh7Zz74-w03dc2pRWLj7O&oh=03_Q7cD4AEgqmIRGPJTFUx97x8cv3xSaa4H8GkSObQY2_bzSJppQg&oe=6966FD55"
            },
            "video_data": null,
            "name": "image-899822156059728",
            "id": "899822156059728",
            "file_url": null
          }
          // ...
        ]
      },
      "fb_user_id": "25083385744656591", // Facebook user id
      "mg_conv_id": "69008574f3ee302076703fb9", // Id cuộc trò chuyện
    }
    // ...
  ],
  "instance_version": "1.2.164",
  "key_enabled": false,
  "status_code": 9999
}

```

{% endtab %}

{% tab title="200 - LikeTalk" %}

```json
{
  "instance_id": "stg",
  "payload": [
    {
      "created_date": 1765774051614, // Ngày tạo
      "last_updated_date": 1765774051614, // Ngày cập nhật
      "_id": "693f92e3e0b8c1763ba48322", // ID tin nhắn
      "create_by": { // Thông tin người tạo
        "id"        : "6487dbe7572b7b17fcc8e123",
        "name"      : "Nhan vien",
        "contact_id": "6487dbeb1a309849f7205982"
      },
      "content": "Xin chao", // Nội dung tin nhắn
      "multimedias": [ // Thông tin file đính kèm
        {
          "name": "image.png",
          "url": "683e512eaf630b1c89a97026/meeting_message_media/2025/12/ca3ad66b-60f6-4595-af55-5c8e46f9055a.png",
          "content_type": "image/png",
          "width": null,
          "height": null,
          "size": 45887,
          "duration": null
        }
        // ...
      ],
      "guest_info": { // Thông tin khách hàng
        "phone": "0837972132",
        "full_name": "Guest",
        "email": "...",
        "contact_id": null,
        "new_contact": false,
        "uuid": "0187JKxn275V4xvRm674b7c2",
        "other_info": {
          "full_name"   : "User",
          "phone_number": "0837972132",
          "mail"        : "..."
        }
      }
    }
    // ...
  ],
  "instance_version": "1.2.164",
  "key_enabled": false,
  "status_code": 9999
}

```

{% endtab %}
{% endtabs %}

## Chuyển đổi nhân viên tiếp nhận cuộc trò chuyện

<mark style="color:green;">`POST`</mark> `[URL]/api/v3/agent/conversation/transfer`&#x20;

Chuyển toàn bộ cuộc trò chuyện trong vòng 6 tháng gần nhất do nhân viên gốc tiếp nhận hoặc được chỉ định cho nhân viên gốc sang cho nhân viên mới

#### Headers

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| x-api-key | String | API Key     |

#### Request Body

<table><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>sourceEmail<mark style="color:red;">*</mark></td><td>String</td><td>Email nhân viên gốc</td></tr><tr><td>targetEmail<mark style="color:red;">*</mark></td><td>String</td><td>Email nhân viên mới</td></tr><tr><td>previewChanges</td><td>Boolean</td><td><ul><li>true: Xem trước số lượng cuộc trò chuyện sẽ bị thay đổi sau cập nhật (không khởi tạo tiến trình cập nhật) </li><li>false (mặc định): Khởi tạo tiến trình cập nhật</li></ul></td></tr><tr><td>replaceExistingMembers</td><td>Boolean</td><td><p></p><ul><li>true: nhân viên mới sẽ thay thế toàn bộ danh sách nhân viên tiếp nhận hiện tại của cuộc trò chuyện </li><li>false (mặc định): nhân viên mới sẽ được thêm vào cuộc trò chuyện</li></ul></td></tr><tr><td>callbackResultConfig</td><td>Object</td><td><p>Thông tin hook nhận kết quả sau khi hoàn tất tiến trình:</p><ul><li>url: url nhận hook</li><li>headers (optional): danh sách headers muốn gửi kèm khi nhận hook</li></ul><pre class="language-json"><code class="lang-json">{
    "url": "https://...",
    "headers": {
        "key1": "value1"
    }
}
</code></pre></td></tr><tr><td>convIds</td><td>String[]</td><td>Chỉ định danh sách id cuộc trò chuyện (do nhân viên gốc phụ trách)</td></tr></tbody></table>

{% tabs %}
{% tab title="202 Khởi tạo tiến trình thành công " %}

```json
{
    "instance_id": "stg",
    "payload": {
        "requestId": "270ea881-a6e1-44fb-9400-a89eb4ceab4b" // unique request id, trả về kèm theo webhook nếu có khai báo "callbackResultConfig"
    },
    "instance_version": "1.2.164",
    "key_enabled": false,
    "status_code": 9999
}
```

{% endtab %}

{% tab title="Webhook" %}

```json
{
  "requestId": "270ea881-a6e1-44fb-9400-a89eb4ceab4b", // unique request id
  "requestTimeMs": 1769163675593, // thời gian request
  "action": "CONVERSATION_AGENT_TRANSFER", // loại tiến trình
  "status": "SUCCESS", // trạng thái SUCCESS/ERROR
  "responseTimeMs": 1769163675890, // thời gian kết thúc
  "payload": {
    "updatedRecords": 8 // Số lượng record được cập nhật
  }
}
```

{% endtab %}
{% endtabs %}

## Webhook

* Đối tác / Khách hàng cung cấp API để OMI callback tin nhắn trở lại khi ChatBot trả lời hoặc nhân viên trả lời từ OMI
* API dạng POST
* Body là thông tin nội dung tin nhắn
* API Timeout tối đa 2(s)