Chat OA open-api: OA broadcast API Documentation

Version: v2.0 Last Updated: February 09, 2026

Overview

This document describes the OA (Official Account) Push Message APIs, which allow OAs to send messages to users or broadcast to all followers.

Tài liệu này mô tả các API OA Push Message, cho phép OA gửi tin nhắn tới người dùng hoặc broadcast tới tất cả followers.

Integration Architecture

Direct Chat Service vs Mulesoft Gateway

UAT, PROD All traffic must be routed through Mulesoft Gateway for security, monitoring, and compliance purposes.

Key Features

Feature	V1 API	V2 API
Send to specific users	Yes	Yes
Broadcast to all followers	Yes	Yes
Multi-language support	No	Yes
User language preference	No	Yes

References docs templates & widgets

Authentication Chat OA OPEN API

All API requests require Bearer token authentication.

Tất cả API requests yêu cầu xác thực bằng Bearer token.

Headers:

Authorization: Bearer <your_access_token>
Content-Type: application/json

Authentication MULESOFT

CHAT Base URL

SIT: https://api.sit.vsf.services/chat/oa-service
UAT: https://api.uat.vsf.services/chat/oa-service

MULESOFT Base URL

UAT: https://test-api.vingroup.net:7445/common-service/chat/api/v1/oa/messages
UAT: https://test-api.vingroup.net:7445/common-service/chat/api/v2/oa/messages

PROD: https://api-cloud-internal.vingroup.net/common-service/chat/api/v1/oa/messages
PROD: https://api-cloud-internal.vingroup.net/common-service/chat/api/v2/oa/messages

Endpoints

V1 APIs (Single Language)

Method	Endpoint	Description
POST	`/api/v1/oa/messages`	Send message to specific users (sync)
POST	`/api/v1/oa/broadcast`	Broadcast to all followers (async)

V2 APIs (Multi-Language Support)

Method	Endpoint	Description
POST	`/api/v2/oa/messages`	Send multi-language message to specific users (sync)
POST	`/api/v2/oa/broadcast`	Broadcast multi-language message to all followers (async)

V1 API Reference

POST /api/v1/oa/messages

Send a template message to one or more users.

Gửi tin nhắn template tới một hoặc nhiều người dùng.

Request Body

Field	Type	Required	Description
request_id	string	No	Unique request identifier (UUID format recommended)
message_type	string	Yes	Must be `"template"`
template_id	string	Yes	Template ID for the message widget
payload	object	Yes	Template data containing `noti_tag` and content
user_uuids	array[string]	Yes*	List of user UUIDs to receive the message

Note: API supports both user_uuids (UUID format) and user_ids. Maximum 1000 users per request.

Lưu ý: API hỗ trợ cả user_uuids (định dạng UUID) và user_ids. Tối đa 1000 users mỗi request.

Payload Structure

{
  "noti_desc": "Message description for notification",
  "noti_tag": <number>,
  "id": "widget_template_id",
  "noti_title": "Notification title",
  "content": {
    "description": "Content description",
    "title": "Content title"
  }
}

Field	Type	Required	Description
noti_desc	string	Yes	Description shown in push notification
noti_tag	number	Yes	Notification tag for rate limiting (1-6)
id	string	Yes	Widget template ID
noti_title	string	Yes	Title shown in push notification
content	object	Yes	Content object for widget rendering

Notification Tags (noti_tag)

ID	Name	Description	Rate Limited
1	Transaction	Transaction info, invoices, billing	No
2	Service	Service processing, operational notifications	No
3	Violation	Warnings, violation notices	No
4	Promotion	Promotional campaigns	Yes (5/user/day)
5	News	News and updates	Yes (5/user/day)
6	General Info	General information	Yes (5/user/day)

Example Request

{
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "message_type": "template",
  "template_id": "widget_campain_action",
  "payload": {
    "noti_desc": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
    "noti_tag": 3,
    "id": "widget_campain_action",
    "noti_title": "Bắt đầu sạc pin",
    "content": {
      "description": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
      "title": "Bắt đầu sạc pin"
    }
  },
  "user_uuids": [
    "7fa72ebe-ad73-45f2-84d4-02880c1d99ea",
    "8ab83fcf-be84-46g3-95e5-13991d2e00fb"
  ]
}

Example cURL

curl --request POST \
  --url https://api.dev.vsf.services/chat/oa-service/api/v1/oa/messages \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
    "message_type": "template",
    "template_id": "widget_campain_action",
    "payload": {
      "noti_desc": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
      "noti_tag": 3,
      "id": "widget_campain_action",
      "noti_title": "Bắt đầu sạc pin",
      "content": {
        "description": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
        "title": "Bắt đầu sạc pin"
      }
    },
    "user_uuids": ["7fa72ebe-ad73-45f2-84d4-02880c1d99ea"]
  }'

Success Response (HTTP 200)

{
  "status": "success",
  "code": "OA-200",
  "timestamp": 1737043200000,
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "data": {
    "total_sent": 2,
    "total_skipped": 0
  }
}

Response Fields

Field	Type	Description
total_sent	number	Number of users successfully sent
total_skipped	number	Number of users skipped (rate limited)
skipped_reason	string	Reason for skipping (if any)

POST /api/v1/oa/broadcast

NOTICE (09/02/2026): Broadcast API is currently disabled. The API still accepts requests but will always return HTTP 202 with oa_status: "turned_off" without actually sending any broadcast messages.

THÔNG BÁO (09/02/2026): API Broadcast hiện đang bị tắt. API vẫn nhận request nhưng sẽ luôn trả về HTTP 202 với oa_status: "turned_off" mà không thực sự gửi broadcast.

Broadcast a template message to all OA followers. This is an asynchronous operation.

Broadcast tin nhắn template tới tất cả followers của OA. Đây là operation bất đồng bộ.

Request Body

Field	Type	Required	Description
request_id	string	No	Unique request identifier
message_type	string	Yes	Must be `"template"`
template_id	string	Yes	Template ID for the message widget
payload	object	Yes	Template data containing `noti_tag` and content

Note: No user list required - message will be sent to all followers.

Lưu ý: Không cần danh sách user - tin nhắn sẽ được gửi tới tất cả followers.

Example Request

{
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "message_type": "template",
  "template_id": "widget_campain_action",
  "payload": {
    "noti_desc": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
    "noti_tag": 3,
    "id": "widget_campain_action",
    "noti_title": "Bắt đầu sạc pin",
    "content": {
      "description": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
      "title": "Bắt đầu sạc pin"
    }
  }
}

Success Response (HTTP 202 Accepted)

{
  "status": "success",
  "code": "OA-200",
  "timestamp": 1737043200000,
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "data": {
    "status": "accepted",
    "message": "Broadcast request accepted and processing in background"
  }
}

Important: HTTP 202 indicates the request has been accepted for processing. The broadcast will be executed asynchronously in the background.

Quan trọng: HTTP 202 cho biết request đã được chấp nhận xử lý. Broadcast sẽ được thực thi bất đồng bộ trong background.

V2 API Reference (Multi-Language)

Multi-Language Feature

V2 APIs support sending messages in multiple languages using the payloads array. The system automatically selects the appropriate language based on user preferences.

V2 APIs hỗ trợ gửi tin nhắn đa ngôn ngữ sử dụng mảng payloads. Hệ thống tự động chọn ngôn ngữ phù hợp dựa trên preference của user.

Language Selection Logic

Scenario	Behavior
Only Vietnamese payload in `payloads`	Vietnamese message sent to all users
Only English payload in `payloads`	English message sent to all users
Both Vietnamese and English in `payloads`	System checks user's `preferred_language` and sends accordingly (default: Vietnamese)

User Language Preference

Value	Language
`"vi"`	Vietnamese (default)
`"en"`	English

POST /api/v2/oa/messages

Send a multi-language template message to one or more users.

Gửi tin nhắn template đa ngôn ngữ tới một hoặc nhiều người dùng.

Request Body

Field	Type	Required	Description
request_id	string	No	Unique request identifier
message_type	string	Yes	Must be `"template"`
template_id	string	Yes	Template ID for the message widget
payloads	array[PayloadItem]	Yes	Array of language-specific payloads
user_uuids	array[string]	Yes*	List of user UUIDs to receive the message

Note: API supports both user_uuids and user_ids. Maximum 1000 users per request.

PayloadItem Structure

Each item in the payloads array must contain:

Field	Type	Required	Description
language	string	Yes	Language code: `"vi"` or `"en"`
noti_desc	string	Yes	Description shown in push notification
noti_tag	number	Yes	Notification tag for rate limiting (1-6)
id	string	Yes	Widget template ID
noti_title	string	Yes	Title shown in push notification
content	object	Yes	Content object for widget rendering

Content Object:

Field	Type	Required	Description
title	string	Yes	Title displayed in widget
description	string	Yes	Description displayed in widget

Example Request — Vietnamese Only

{
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "message_type": "template",
  "template_id": "widget_campain_action",
  "payloads": [
    {
      "language": "vi",
      "noti_desc": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
      "noti_tag": 3,
      "id": "widget_campain_action",
      "noti_title": "Bắt đầu sạc pin",
      "content": {
        "description": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
        "title": "Bắt đầu sạc pin"
      }
    }
  ],
  "user_uuids": ["7fa72ebe-ad73-45f2-84d4-02880c1d99ea"]
}

Example Request — English Only

{
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "message_type": "template",
  "template_id": "widget_campain_action",
  "payloads": [
    {
      "language": "en",
      "noti_desc": "Charging process has started at 08/12/2025 05:43.",
      "noti_tag": 3,
      "id": "widget_campain_action",
      "noti_title": "Charging Started",
      "content": {
        "description": "Charging process has started at 08/12/2025 05:43.",
        "title": "Charging Started"
      }
    }
  ],
  "user_uuids": ["7fa72ebe-ad73-45f2-84d4-02880c1d99ea"]
}

Example Request — Multi-Language (Vietnamese & English)

{
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "message_type": "template",
  "template_id": "widget_campain_action",
  "payloads": [
    {
      "language": "vi",
      "noti_desc": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
      "noti_tag": 3,
      "id": "widget_campain_action",
      "noti_title": "Bắt đầu sạc pin",
      "content": {
        "description": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
        "title": "Bắt đầu sạc pin"
      }
    },
    {
      "language": "en",
      "noti_desc": "Charging process has started at 08/12/2025 05:43.",
      "noti_tag": 3,
      "id": "widget_campain_action",
      "noti_title": "Charging Started",
      "content": {
        "description": "Charging process has started at 08/12/2025 05:43.",
        "title": "Charging Started"
      }
    }
  ],
  "user_uuids": [
    "7fa72ebe-ad73-45f2-84d4-02880c1d99ea",
    "8ab83fcf-be84-46g3-95e5-13991d2e00fb",
    "9bc94gdg-cf95-57h4-06f6-24002e3f11gc"
  ]
}

Example cURL

curl --request POST \
  --url https://api.dev.vsf.services/chat/oa-service/api/v2/oa/messages \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
    "message_type": "template",
    "template_id": "widget_campain_action",
    "payloads": [
      {
        "language": "vi",
        "noti_desc": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
        "noti_tag": 3,
        "id": "widget_campain_action",
        "noti_title": "Bắt đầu sạc pin",
        "content": {
          "description": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
          "title": "Bắt đầu sạc pin"
        }
      },
      {
        "language": "en",
        "noti_desc": "Charging process has started at 08/12/2025 05:43.",
        "noti_tag": 3,
        "id": "widget_campain_action",
        "noti_title": "Charging Started",
        "content": {
          "description": "Charging process has started at 08/12/2025 05:43.",
          "title": "Charging Started"
        }
      }
    ],
    "user_uuids": ["7fa72ebe-ad73-45f2-84d4-02880c1d99ea"]
  }'

Success Response (HTTP 200)

{
  "status": "success",
  "code": "OA-200",
  "timestamp": 1737043200000,
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "data": {
    "total_sent": 3,
    "total_skipped": 0,
    "sent_by_language": {
      "vi": 2,
      "en": 1
    }
  }
}

Response Fields

Field	Type	Description
total_sent	number	Total users successfully sent
total_skipped	number	Number of users skipped
sent_by_language	object	Breakdown of messages sent by language
sent_by_language.vi	number	Messages sent in Vietnamese
sent_by_language.en	number	Messages sent in English

POST /api/v2/oa/broadcast

NOTICE (09/02/2026): Broadcast API is currently disabled. The API still accepts requests but will always return HTTP 202 with oa_status: "turned_off" without actually sending any broadcast messages.

THÔNG BÁO (09/02/2026): API Broadcast hiện đang bị tắt. API vẫn nhận request nhưng sẽ luôn trả về HTTP 202 với oa_status: "turned_off" mà không thực sự gửi broadcast.

Broadcast a multi-language template message to all OA followers. This is an asynchronous operation.

Broadcast tin nhắn template đa ngôn ngữ tới tất cả followers của OA. Đây là operation bất đồng bộ.

Request Body

Field	Type	Required	Description
request_id	string	No	Unique request identifier
message_type	string	Yes	Must be `"template"`
template_id	string	Yes	Template ID for the message widget
payloads	array[PayloadItem]	Yes	Array of language-specific payloads

Note: No user list required - message will be sent to all followers based on their language preference.

Example Request — Multi-Language Broadcast

{
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "message_type": "template",
  "template_id": "widget_campain_action",
  "payloads": [
    {
      "language": "vi",
      "noti_desc": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
      "noti_tag": 3,
      "id": "widget_campain_action",
      "noti_title": "Bắt đầu sạc pin",
      "content": {
        "description": "Quá trình sạc đã bắt đầu vào lúc 08/12/2025 05:43.",
        "title": "Bắt đầu sạc pin"
      }
    },
    {
      "language": "en",
      "noti_desc": "Charging process has started at 08/12/2025 05:43.",
      "noti_tag": 3,
      "id": "widget_campain_action",
      "noti_title": "Charging Started",
      "content": {
        "description": "Charging process has started at 08/12/2025 05:43.",
        "title": "Charging Started"
      }
    }
  ]
}

Response — Broadcast Disabled (HTTP 202 Accepted)

Since 09/02/2026, this is the only response returned. Broadcast is disabled and no messages are sent.

{
  "status": "success",
  "code": "OA-200",
  "timestamp": 1737043200000,
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "data": {
    "status": "accepted",
    "oa_status": "turned_off",
    "message": "Broadcast is currently disabled since 09/02/2026, broadcast not sent"
  }
}

Response — OA Turned Off (HTTP 202 Accepted)

When OA is turned off via OA status configuration:

{
  "status": "success",
  "code": "OA-200",
  "timestamp": 1737043200000,
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "data": {
    "status": "accepted",
    "oa_status": "turned_off",
    "message": "OA is currently turned off, broadcast not sent"
  }
}

Success Response (HTTP 202 Accepted) — When Broadcast is Enabled

Note: This response is currently not returned as broadcast is disabled since 09/02/2026.

{
  "status": "success",
  "code": "OA-200",
  "timestamp": 1737043200000,
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "data": {
    "status": "accepted",
    "message": "Broadcast request accepted and processing in background",
    "multi_language": true,
    "languages": ["vi", "en"]
  }
}

Response Fields

Field	Type	Description
status	string	Request status (`"accepted"`)
oa_status	string	OA status (`"turned_off"` when broadcast is disabled)
message	string	Status description
multi_language	boolean	`true` if multiple language payloads are provided
languages	array[string]	List of languages in the request

Error Responses

HTTP 400 — Bad Request

Invalid request payload or validation errors.

Request payload không hợp lệ hoặc lỗi validation.

{
  "status": "error",
  "code": "OA-400",
  "timestamp": 1737043200000,
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "message": "Invalid request payload",
  "details": [
    "message_type must be 'template'",
    "template_id is required",
    "payloads array is required and must not be empty",
    "payloads[0].language is required",
    "payloads[0].noti_tag is required"
  ]
}

Common Validation Errors

Error	Description
`message_type must be 'template'`	The `message_type` field must be exactly `"template"`
`template_id is required`	Missing required `template_id` field
`payload is required`	Missing payload (V1 API)
`payloads array is required and must not be empty`	Missing or empty payloads array (V2 API)
`payloads[n].language is required`	Missing language in payload item
`payloads[n].noti_tag is required`	Missing noti_tag in payload item
`payloads[n].content is required`	Missing content in payload item
`user_uuids limit 1000`	Exceeded maximum 1000 users per request

HTTP 401 — Unauthorized

Authentication failed or OA not authorized.

Xác thực thất bại hoặc OA không được phép.

{
  "status": "error",
  "code": "OA-401",
  "timestamp": 1737043200000,
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "message": "Unauthorized: OA ID missing"
}

HTTP 429 — Rate Limit Exceeded

All target users have reached their daily message limit for the specified noti_tag.

Tất cả users đã đạt giới hạn tin nhắn hàng ngày cho noti_tag được chỉ định.

{
  "status": "error",
  "code": "OA-429",
  "timestamp": 1737043200000,
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "message": "All users have reached daily limit for Promotion",
  "data": {
    "noti_tag": 4,
    "noti_tag_name": "Promotion",
    "limit": 5,
    "total_users": 10,
    "skipped_users": 10
  }
}

HTTP 500 — Internal Server Error

Unexpected server error occurred.

Lỗi server không mong đợi.

{
  "status": "error",
  "code": "OA-500",
  "timestamp": 1737043200000,
  "request_id": "7f5bb3d2-fa5c-40ce-95bc-15c260b77512",
  "message": "Internal server error"
}

Rate Limiting

Rate limits are applied based on noti_tag type per OA-User pair.

Giới hạn gửi tin được áp dụng dựa trên loại noti_tag cho mỗi cặp OA-User.

noti_tag	Type	Daily Limit
1	Transaction	Unlimited
2	Service	Unlimited
3	Violation	Unlimited
4	Promotion	5 messages(Promotion, News, General Info)/user/day
5	News	5 messages(Promotion, News, General Info)/user/day
6	General Info	5 messages(Promotion, News, General Info)/user/day

Note: Rate limits reset daily at 00:00 UTC+7.

Lưu ý: Giới hạn được reset hàng ngày lúc 00:00 UTC+7.

Best Practices

Use request_id — Always include a unique request_id for tracking and debugging.
Choose appropriate noti_tag — Select the correct notification tag to ensure proper delivery and avoid rate limiting.
Batch users wisely — For large user lists, batch requests with up to 1000 users each.
Use V2 for international users — If your users have different language preferences, use V2 APIs with the payloads array containing both Vietnamese and English content.
Handle async responses — For broadcast APIs (HTTP 202), the request is processed asynchronously. Do not wait for completion.

Support

For technical support or questions, please contact your account manager or submit a support ticket.

OA Chat: [email protected]
MuleSoft: [email protected]

Overview​

Integration Architecture​

Direct Chat Service vs Mulesoft Gateway​

Key Features​

References docs templates & widgets​

Authentication Chat OA OPEN API​

Authentication MULESOFT​

CHAT Base URL​

MULESOFT Base URL​

Endpoints​

V1 APIs (Single Language)​

V2 APIs (Multi-Language Support)​

V1 API Reference

POST /api/v1/oa/messages​

Request Body​

Payload Structure​

Notification Tags (noti_tag)​

Example Request​

Example cURL​

Success Response (HTTP 200)​

Response Fields​

POST /api/v1/oa/broadcast​

Request Body​

Example Request​

Success Response (HTTP 202 Accepted)​

V2 API Reference (Multi-Language)

Multi-Language Feature​

Language Selection Logic​

User Language Preference​

POST /api/v2/oa/messages​

Request Body​

PayloadItem Structure​

Example Request — Vietnamese Only​

Example Request — English Only​

Example Request — Multi-Language (Vietnamese & English)​

Example cURL​

Success Response (HTTP 200)​

Response Fields​

POST /api/v2/oa/broadcast​

Request Body​

Example Request — Multi-Language Broadcast​

Response — Broadcast Disabled (HTTP 202 Accepted)​

Response — OA Turned Off (HTTP 202 Accepted)​

Success Response (HTTP 202 Accepted) — When Broadcast is Enabled​

Response Fields​

Error Responses

HTTP 400 — Bad Request​

Common Validation Errors​

HTTP 401 — Unauthorized​

HTTP 429 — Rate Limit Exceeded​

HTTP 500 — Internal Server Error​

Rate Limiting

Best Practices

Support

Overview

Integration Architecture

Direct Chat Service vs Mulesoft Gateway

Key Features

References docs templates & widgets

Authentication Chat OA OPEN API

Authentication MULESOFT

CHAT Base URL

MULESOFT Base URL

Endpoints

V1 APIs (Single Language)

V2 APIs (Multi-Language Support)

POST /api/v1/oa/messages

Request Body

Payload Structure

Notification Tags (noti_tag)

Example Request

Example cURL

Success Response (HTTP 200)

Response Fields

POST /api/v1/oa/broadcast

Request Body

Example Request

Success Response (HTTP 202 Accepted)

Multi-Language Feature

Language Selection Logic

User Language Preference

POST /api/v2/oa/messages

Request Body

PayloadItem Structure

Example Request — Vietnamese Only

Example Request — English Only

Example Request — Multi-Language (Vietnamese & English)

Example cURL

Success Response (HTTP 200)

Response Fields

POST /api/v2/oa/broadcast

Request Body

Example Request — Multi-Language Broadcast

Response — Broadcast Disabled (HTTP 202 Accepted)

Response — OA Turned Off (HTTP 202 Accepted)

Success Response (HTTP 202 Accepted) — When Broadcast is Enabled

Response Fields

HTTP 400 — Bad Request

Common Validation Errors

HTTP 401 — Unauthorized

HTTP 429 — Rate Limit Exceeded

HTTP 500 — Internal Server Error