> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Quảng cáo
> Quản lý quảng cáo được boost thông qua Ayrshare GraphQL API bằng một bộ thao tác duy nhất nhận nền tảng quảng cáo làm đối số.
Các thao tác quảng cáo nhận nền tảng quảng cáo làm đối số, vì vậy cùng một thao tác hoạt động trên mọi nền tảng quảng cáo mà Ayrshare hỗ trợ. Hiện tại đó là `FACEBOOK` và `INSTAGRAM`.
Mỗi thao tác gọi [endpoint quảng cáo REST](/docs/apis/ads/overview) tương ứng và trả về phản hồi của nó mà không thay đổi. Xác thực và giới hạn giống như REST. Một lệnh gọi thất bại trả về lỗi GraphQL: `extensions.status` chứa trạng thái REST, và `extensions.code` chứa mã lỗi Ayrshare khi lỗi REST có mã đó. Xem [Lỗi](/docs/apis/graphql/errors). Các thao tác quảng cáo yêu cầu tiện ích bổ sung Ads. Nếu không có, mọi lệnh gọi đều trả về lỗi với `extensions.status` `403` và `extensions.code` `399`.
## Các thao tác
| Thao tác | Loại | Endpoint REST |
| - | - | - |
| `adAccounts` | Query | `GET /ads/{platform}/accounts` |
| `adTargetingSearch` | Query | `GET /ads/{platform}/interests`, `/regions` hoặc `/cities` |
| `ads` | Query | `GET /ads/{platform}/ads` |
| `adHistory` | Query | `GET /ads/{platform}/history` |
| `updateAd` | Mutation | `PUT /ads/{platform}/ads` |
| `boostPost` | Mutation | `POST /ads/{platform}/boost` |
Mọi thao tác cũng nhận một `profileKey` tùy chọn để thao tác trên một User Profile. Tất cả đều trả về phản hồi REST dưới dạng JSON, vì vậy chúng không nhận lựa chọn trường (field selection).
## Liệt kê tài khoản quảng cáo
Hãy bắt đầu từ đây. Dùng các giá trị `accountId` trong phản hồi ở bất kỳ đâu một thao tác yêu cầu `accountId`.
```graphql theme={"system"}
query {
adAccounts(platform: FACEBOOK, limit: 10)
}
```
## Tìm kiếm tùy chọn nhắm mục tiêu
`kind` chọn loại tìm kiếm: `INTERESTS` cho nhắm mục tiêu đối tượng, `REGIONS` hoặc `CITIES` cho vị trí. Mỗi loại chỉ nhận các đối số riêng của nó. Ví dụ, `countryCode` và `regionId` chỉ hoạt động với `CITIES`, và `INTERESTS` yêu cầu `search`.
```graphql theme={"system"}
query {
adTargetingSearch(platform: INSTAGRAM, kind: INTERESTS, search: "running")
}
```
```graphql theme={"system"}
query {
adTargetingSearch(platform: FACEBOOK, kind: CITIES, search: "Austin", countryCode: "US")
}
```
## Liệt kê quảng cáo
Truyền ít nhất một trong các giá trị `campaignId`, `accountId`, `adId`, `postId` hoặc `socialPostId`. `socialPostId` là id bài đăng riêng của mạng xã hội, dành cho các bài đăng không được xuất bản qua Ayrshare.
```graphql theme={"system"}
query {
ads(platform: FACEBOOK, accountId: "act_1234567890")
}
```
## Xem chi phí của một quảng cáo
```graphql theme={"system"}
query {
adHistory(platform: FACEBOOK, startDate: "2026-09-01", endDate: "2026-09-30")
}
```
## Tạm dừng hoặc tiếp tục một quảng cáo
`updateAd` thay đổi chi tiêu quảng cáo thực tế. `PAUSED` dừng chi tiêu, `ACTIVE` tiếp tục chi tiêu, và `DELETED` hoặc `ARCHIVED` ngừng quảng cáo vĩnh viễn. Cùng trạng thái đó cũng được đặt cho nhóm quảng cáo và chiến dịch của quảng cáo, vì vậy mọi quảng cáo khác trong nhóm quảng cáo hoặc chiến dịch đó cũng thay đổi theo. Chiến dịch hoặc nhóm quảng cáo mà lượt boost được gắn vào bằng `attachTo` giữ trạng thái riêng của nó, và quảng cáo chỉ chạy khi chiến dịch và nhóm quảng cáo phía trên nó đang hoạt động.
```graphql theme={"system"}
mutation {
updateAd(platform: FACEBOOK, adId: "120210000000000000", status: PAUSED)
}
```
Boost một bài đăng
`boostPost` chi tiêu tiền thật từ tài khoản quảng cáo. Thao tác này biến một bài đăng đã xuất bản thành quảng cáo.
* Truyền `postId` (id bài đăng Ayrshare) hoặc `socialPostId` (id bài đăng riêng của mạng xã hội).
* Lấy `accountId` từ `adAccounts`.
* `budget.amount` được tính theo đơn vị tiền tệ của tài khoản quảng cáo. Chỉ bỏ qua `budget` khi `attachTo.adSetId` thêm quảng cáo vào một nhóm quảng cáo bạn đang chạy, vốn giữ ngân sách riêng của nó. Khi đó cũng bỏ qua `targeting`: nhóm quảng cáo giữ thiết lập riêng của nó. Xem [Boost vào một chiến dịch hoặc nhóm quảng cáo hiện có](/docs/apis/ads/facebook/boost-post#attach-to).
* `schedule`, `targeting`, `callToAction`, `attachTo` và `status` là tùy chọn. Nếu bạn bỏ qua `status` và `schedule`, quảng cáo sẽ **hoạt động, bắt đầu ngay và không có ngày kết thúc**, vì vậy nó tiếp tục chi tiêu cho đến khi bạn tạm dừng. Đặt `status: PAUSED` hoặc `schedule.end` để giới hạn.
* Đặt các thiết lập chỉ một nền tảng có vào `platformOptions`, với khóa là nền tảng. Trên Facebook và Instagram, `adName` và `bidAmount` là **bắt buộc** ở đó, ví dụ `platformOptions: { facebook: { adName: "Autumn sale", bidAmount: 2 } }`. Nếu thiếu chúng, lệnh boost trả về lỗi thiếu trường. Khi dùng `attachTo.adSetId`, hãy bỏ qua `bidAmount`: nhóm quảng cáo giữ giá thầu riêng của nó.
```graphql theme={"system"}
mutation {
boostPost(
platform: FACEBOOK
accountId: "act_1234567890"
postId: "RNlSOkyxl9G3EDhlPuCK"
goal: "engagement"
budget: { amount: 20, type: DAILY }
schedule: { start: "2026-10-10T09:00:00Z", end: "2026-10-17T09:00:00Z" }
targeting: { ageMin: 25, ageMax: 45, locations: { countries: ["US"] } }
platformOptions: { facebook: { adName: "Autumn sale", bidAmount: 2 } }
idempotencyKey: "4f9c2a7e-1b3d-4c8e-9a6f-2d5b7e0c1a34"
)
}
```
Một số đối số nhận nhiều hơn một dạng, vì vậy chúng dùng kiểu `JSON`:
* `accountId` nhận một chuỗi hoặc một số.
* Các ngày trong `schedule` nhận ngày hoặc ngày giờ theo ISO 8601, chẳng hạn `"2026-10-10T09:00:00Z"`. Hãy dùng dạng đó thay vì một số. `schedule.end` cũng nhận `0` để không có ngày kết thúc.
* Các khóa vị trí nhận một giá trị hoặc một danh sách.
* `targeting.interests` nhận id dưới dạng chuỗi hoặc số.
* `platformOptions` nhận một đối tượng.
Gửi một `idempotencyKey` mới, chẳng hạn một UUID, với mỗi lần boost. Nếu một lệnh gọi hết thời gian chờ hoặc thất bại, hãy thử lại với cùng khóa và cùng đối số.
* Nếu lần boost đầu tiên đã hoàn tất, lần thử lại trả về phản hồi của nó thay vì tạo và trả tiền cho một quảng cáo thứ hai.
* Nếu lần boost đầu tiên vẫn đang xử lý, lần thử lại trả về lỗi với `extensions.status` `409`. Hãy chờ, rồi thử lại với cùng khóa. Không chuyển sang khóa mới.
* Dùng lại một khóa với các đối số khác cũng trả về `409`.
Để dừng chi tiêu quảng cáo, hãy gọi `updateAd` với `status: PAUSED`. `boostFacebookPost` và `instagramBoostPost` vẫn hoạt động.
Các thao tác theo từng nền tảng, chẳng hạn `facebookAdAccounts` và `instagramAds`, vẫn hoạt động và không thay đổi.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.