Skip to content

Commit e696495

Browse files
waleedlatif1waleedlatif1
committed
feat(meta-ads): add meta ads integration for campaign and ad performance queries
- Add 5 tools: get_account, list_campaigns, list_ad_sets, list_ads, get_insights - Add account and campaign selectors with cascading dropdown support - Add OAuth config with ads_read scope - Generate docs
1 parent d84cba6 commit e696495

File tree

26 files changed

+1741
-15
lines changed

26 files changed

+1741
-15
lines changed

‎apps/docs/components/icons.tsx‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4107,6 +4107,52 @@ export function LumaIcon(props: SVGProps<SVGSVGElement>) {
41074107
)
41084108
}
41094109

4110+
export function MetaAdsIcon(props: SVGProps<SVGSVGElement>) {
4111+
return (
4112+
<svg {...props} xmlns='http://www.w3.org/2000/svg' viewBox='0 0 287.56 191'>
4113+
<defs>
4114+
<linearGradient
4115+
id='meta-lg1'
4116+
x1='62.34'
4117+
y1='101.45'
4118+
x2='260.34'
4119+
y2='91.45'
4120+
gradientTransform='matrix(1, 0, 0, -1, 0, 192)'
4121+
gradientUnits='userSpaceOnUse'
4122+
>
4123+
<stop offset='0' stopColor='#0064e1' />
4124+
<stop offset='0.4' stopColor='#0064e1' />
4125+
<stop offset='0.83' stopColor='#0073ee' />
4126+
<stop offset='1' stopColor='#0082fb' />
4127+
</linearGradient>
4128+
<linearGradient
4129+
id='meta-lg2'
4130+
x1='41.42'
4131+
y1='53'
4132+
x2='41.42'
4133+
y2='126'
4134+
gradientTransform='matrix(1, 0, 0, -1, 0, 192)'
4135+
gradientUnits='userSpaceOnUse'
4136+
>
4137+
<stop offset='0' stopColor='#0082fb' />
4138+
<stop offset='1' stopColor='#0064e0' />
4139+
</linearGradient>
4140+
</defs>
4141+
<path
4142+
fill='#0081fb'
4143+
d='M31.06,126c0,11,2.41,19.41,5.56,24.51A19,19,0,0,0,53.19,160c8.1,0,15.51-2,29.79-21.76,11.44-15.83,24.92-38,34-52l15.36-23.6c10.67-16.39,23-34.61,37.18-47C181.07,5.6,193.54,0,206.09,0c21.07,0,41.14,12.21,56.5,35.11,16.81,25.08,25,56.67,25,89.27,0,19.38-3.82,33.62-10.32,44.87C271,180.13,258.72,191,238.13,191V160c17.63,0,22-16.2,22-34.74,0-26.42-6.16-55.74-19.73-76.69-9.63-14.86-22.11-23.94-35.84-23.94-14.85,0-26.8,11.2-40.23,31.17-7.14,10.61-14.47,23.54-22.7,38.13l-9.06,16c-18.2,32.27-22.81,39.62-31.91,51.75C84.74,183,71.12,191,53.19,191c-21.27,0-34.72-9.21-43-23.09C3.34,156.6,0,141.76,0,124.85Z'
4144+
/>
4145+
<path
4146+
fill='url(#meta-lg1)'
4147+
d='M24.49,37.3C38.73,15.35,59.28,0,82.85,0c13.65,0,27.22,4,41.39,15.61,15.5,12.65,32,33.48,52.63,67.81l7.39,12.32c17.84,29.72,28,45,33.93,52.22,7.64,9.26,13,12,19.94,12,17.63,0,22-16.2,22-34.74l27.4-.86c0,19.38-3.82,33.62-10.32,44.87C271,180.13,258.72,191,238.13,191c-12.8,0-24.14-2.78-36.68-14.61-9.64-9.08-20.91-25.21-29.58-39.71L146.08,93.6c-12.94-21.62-24.81-37.74-31.68-45C107,40.71,97.51,31.23,82.35,31.23c-12.27,0-22.69,8.61-31.41,21.78Z'
4148+
/>
4149+
<path
4150+
fill='url(#meta-lg2)'
4151+
d='M82.35,31.23c-12.27,0-22.69,8.61-31.41,21.78C38.61,71.62,31.06,99.34,31.06,126c0,11,2.41,19.41,5.56,24.51L10.14,167.91C3.34,156.6,0,141.76,0,124.85,0,94.1,8.44,62.05,24.49,37.3,38.73,15.35,59.28,0,82.85,0Z'
4152+
/>
4153+
</svg>
4154+
)
4155+
}
41104156
export function MailchimpIcon(props: SVGProps<SVGSVGElement>) {
41114157
return (
41124158
<svg

‎apps/docs/components/ui/icon-mapping.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ import {
9595
MailgunIcon,
9696
MailServerIcon,
9797
Mem0Icon,
98+
MetaAdsIcon,
9899
MicrosoftDataverseIcon,
99100
MicrosoftExcelIcon,
100101
MicrosoftOneDriveIcon,
@@ -263,6 +264,7 @@ export const blockTypeToIconMap: Record<string, IconComponent> = {
263264
mailgun: MailgunIcon,
264265
mem0: Mem0Icon,
265266
memory: BrainIcon,
267+
meta_ads: MetaAdsIcon,
266268
microsoft_dataverse: MicrosoftDataverseIcon,
267269
microsoft_excel_v2: MicrosoftExcelIcon,
268270
microsoft_planner: MicrosoftPlannerIcon,

‎apps/docs/content/docs/en/tools/grain.mdx‎

Lines changed: 27 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,26 @@ Get the full transcript of a recording
138138
| ↳ `end` | number | End timestamp in ms |
139139
| ↳ `text` | string | Transcript text |
140140

141+
### `grain_list_views`
142+
143+
List available Grain views for webhook subscriptions
144+
145+
#### Input
146+
147+
| Parameter | Type | Required | Description |
148+
| --------- | ---- | -------- | ----------- |
149+
| `apiKey` | string | Yes | Grain API key \(Personal Access Token\) |
150+
| `typeFilter` | string | No | Optional view type filter: recordings, highlights, or stories |
151+
152+
#### Output
153+
154+
| Parameter | Type | Description |
155+
| --------- | ---- | ----------- |
156+
| `views` | array | Array of Grain views |
157+
| ↳ `id` | string | View UUID |
158+
| ↳ `name` | string | View name |
159+
| ↳ `type` | string | View type: recordings, highlights, or stories |
160+
141161
### `grain_list_teams`
142162

143163
List all teams in the workspace
@@ -185,15 +205,9 @@ Create a webhook to receive recording events
185205
| --------- | ---- | -------- | ----------- |
186206
| `apiKey` | string | Yes | Grain API key \(Personal Access Token\) |
187207
| `hookUrl` | string | Yes | Webhook endpoint URL \(e.g., "https://example.com/webhooks/grain"\) |
188-
| `hookType` | string | Yes | Type of webhook: "recording_added" or "upload_status" |
189-
| `filterBeforeDatetime` | string | No | Filter: recordings before this ISO8601 date \(e.g., "2024-01-15T00:00:00Z"\) |
190-
| `filterAfterDatetime` | string | No | Filter: recordings after this ISO8601 date \(e.g., "2024-01-01T00:00:00Z"\) |
191-
| `filterParticipantScope` | string | No | Filter: "internal" or "external" |
192-
| `filterTeamId` | string | No | Filter: specific team UUID \(e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890"\) |
193-
| `filterMeetingTypeId` | string | No | Filter: specific meeting type UUID \(e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890"\) |
194-
| `includeHighlights` | boolean | No | Include highlights in webhook payload |
195-
| `includeParticipants` | boolean | No | Include participants in webhook payload |
196-
| `includeAiSummary` | boolean | No | Include AI summary in webhook payload |
208+
| `viewId` | string | Yes | Grain view ID from GET /_/public-api/views |
209+
| `actions` | array | No | Optional list of actions to subscribe to: added, updated, removed |
210+
| `items` | string | No | No description |
197211

198212
#### Output
199213

@@ -202,9 +216,8 @@ Create a webhook to receive recording events
202216
| `id` | string | Hook UUID |
203217
| `enabled` | boolean | Whether hook is active |
204218
| `hook_url` | string | The webhook URL |
205-
| `hook_type` | string | Type of hook: recording_added or upload_status |
206-
| `filter` | object | Applied filters |
207-
| `include` | object | Included fields |
219+
| `view_id` | string | Grain view ID for the webhook |
220+
| `actions` | array | Configured actions for the webhook |
208221
| `inserted_at` | string | ISO8601 creation timestamp |
209222

210223
### `grain_list_hooks`
@@ -225,9 +238,8 @@ List all webhooks for the account
225238
| ↳ `id` | string | Hook UUID |
226239
| ↳ `enabled` | boolean | Whether hook is active |
227240
| ↳ `hook_url` | string | Webhook URL |
228-
| ↳ `hook_type` | string | Type: recording_added or upload_status |
229-
| ↳ `filter` | object | Applied filters |
230-
| ↳ `include` | object | Included fields |
241+
| ↳ `view_id` | string | Grain view ID |
242+
| ↳ `actions` | array | Configured actions |
231243
| ↳ `inserted_at` | string | Creation timestamp |
232244

233245
### `grain_delete_hook`

‎apps/docs/content/docs/en/tools/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@
9292
"mailgun",
9393
"mem0",
9494
"memory",
95+
"meta_ads",
9596
"microsoft_dataverse",
9697
"microsoft_excel",
9798
"microsoft_planner",

‎apps/docs/content/docs/en/tools/meta_ads.mdx‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Meta Ads
3+
description: Query campaigns, ad sets, ads, and performance insights
4+
---
5+
6+
import { BlockInfoCard } from "@/components/ui/block-info-card"
7+
8+
<BlockInfoCard
9+
type="meta_ads"
10+
color="#1877F2"
11+
/>
12+
13+
## Usage Instructions
14+
15+
Connect to Meta Ads to view account info, list campaigns, ad sets, and ads, and get performance insights and metrics.
16+
17+
18+
19+
## Tools
20+
21+
### `meta_ads_get_account`
22+
23+
Get information about a Meta Ads account
24+
25+
#### Input
26+
27+
| Parameter | Type | Required | Description |
28+
| --------- | ---- | -------- | ----------- |
29+
| `accountId` | string | Yes | Meta Ads account ID \(numeric, without act_ prefix\) |
30+
31+
#### Output
32+
33+
| Parameter | Type | Description |
34+
| --------- | ---- | ----------- |
35+
| `id` | string | Ad account ID |
36+
| `name` | string | Ad account name |
37+
| `accountStatus` | number | Account status code |
38+
| `currency` | string | Account currency \(e.g., USD\) |
39+
| `timezone` | string | Account timezone |
40+
| `amountSpent` | string | Total amount spent |
41+
| `spendCap` | string | Spending limit for the account |
42+
| `businessCountryCode` | string | Country code for the business |
43+
44+
### `meta_ads_list_campaigns`
45+
46+
List campaigns in a Meta Ads account with optional status filtering
47+
48+
#### Input
49+
50+
| Parameter | Type | Required | Description |
51+
| --------- | ---- | -------- | ----------- |
52+
| `accountId` | string | Yes | Meta Ads account ID \(numeric, without act_ prefix\) |
53+
| `status` | string | No | Filter by campaign status \(ACTIVE, PAUSED, ARCHIVED, DELETED\) |
54+
| `limit` | number | No | Maximum number of campaigns to return |
55+
56+
#### Output
57+
58+
| Parameter | Type | Description |
59+
| --------- | ---- | ----------- |
60+
| `campaigns` | array | List of campaigns in the account |
61+
| ↳ `id` | string | Campaign ID |
62+
| ↳ `name` | string | Campaign name |
63+
| ↳ `status` | string | Campaign status \(ACTIVE, PAUSED, etc.\) |
64+
| ↳ `objective` | string | Campaign objective |
65+
| ↳ `dailyBudget` | string | Daily budget in account currency cents |
66+
| ↳ `lifetimeBudget` | string | Lifetime budget in account currency cents |
67+
| ↳ `createdTime` | string | Campaign creation time \(ISO 8601\) |
68+
| ↳ `updatedTime` | string | Campaign last update time \(ISO 8601\) |
69+
| `totalCount` | number | Total number of campaigns returned |
70+
71+
### `meta_ads_list_ad_sets`
72+
73+
List ad sets in a Meta Ads account or campaign
74+
75+
#### Input
76+
77+
| Parameter | Type | Required | Description |
78+
| --------- | ---- | -------- | ----------- |
79+
| `accountId` | string | Yes | Meta Ads account ID \(numeric, without act_ prefix\) |
80+
| `campaignId` | string | No | Filter ad sets by campaign ID |
81+
| `status` | string | No | Filter by ad set status \(ACTIVE, PAUSED, ARCHIVED, DELETED\) |
82+
| `limit` | number | No | Maximum number of ad sets to return |
83+
84+
#### Output
85+
86+
| Parameter | Type | Description |
87+
| --------- | ---- | ----------- |
88+
| `adSets` | array | List of ad sets |
89+
| ↳ `id` | string | Ad set ID |
90+
| ↳ `name` | string | Ad set name |
91+
| ↳ `status` | string | Ad set status |
92+
| ↳ `campaignId` | string | Parent campaign ID |
93+
| ↳ `dailyBudget` | string | Daily budget in account currency cents |
94+
| ↳ `lifetimeBudget` | string | Lifetime budget in account currency cents |
95+
| ↳ `startTime` | string | Ad set start time \(ISO 8601\) |
96+
| ↳ `endTime` | string | Ad set end time \(ISO 8601\) |
97+
| `totalCount` | number | Total number of ad sets returned |
98+
99+
### `meta_ads_list_ads`
100+
101+
List ads in a Meta Ads account, campaign, or ad set
102+
103+
#### Input
104+
105+
| Parameter | Type | Required | Description |
106+
| --------- | ---- | -------- | ----------- |
107+
| `accountId` | string | Yes | Meta Ads account ID \(numeric, without act_ prefix\) |
108+
| `campaignId` | string | No | Filter ads by campaign ID |
109+
| `adSetId` | string | No | Filter ads by ad set ID |
110+
| `status` | string | No | Filter by ad status \(ACTIVE, PAUSED, ARCHIVED, DELETED\) |
111+
| `limit` | number | No | Maximum number of ads to return |
112+
113+
#### Output
114+
115+
| Parameter | Type | Description |
116+
| --------- | ---- | ----------- |
117+
| `ads` | array | List of ads |
118+
| ↳ `id` | string | Ad ID |
119+
| ↳ `name` | string | Ad name |
120+
| ↳ `status` | string | Ad status |
121+
| ↳ `adSetId` | string | Parent ad set ID |
122+
| ↳ `campaignId` | string | Parent campaign ID |
123+
| ↳ `createdTime` | string | Ad creation time \(ISO 8601\) |
124+
| ↳ `updatedTime` | string | Ad last update time \(ISO 8601\) |
125+
| `totalCount` | number | Total number of ads returned |
126+
127+
### `meta_ads_get_insights`
128+
129+
Get performance insights and metrics for Meta Ads campaigns, ad sets, or ads
130+
131+
#### Input
132+
133+
| Parameter | Type | Required | Description |
134+
| --------- | ---- | -------- | ----------- |
135+
| `accountId` | string | Yes | Meta Ads account ID \(numeric, without act_ prefix\) |
136+
| `level` | string | Yes | Aggregation level for insights \(account, campaign, adset, ad\) |
137+
| `campaignId` | string | No | Filter insights by campaign ID |
138+
| `adSetId` | string | No | Filter insights by ad set ID |
139+
| `datePreset` | string | No | Predefined date range \(today, yesterday, last_7d, last_14d, last_28d, last_30d, last_90d, this_month, last_month\) |
140+
| `startDate` | string | No | Custom start date in YYYY-MM-DD format |
141+
| `endDate` | string | No | Custom end date in YYYY-MM-DD format |
142+
| `limit` | number | No | Maximum number of insight rows to return |
143+
144+
#### Output
145+
146+
| Parameter | Type | Description |
147+
| --------- | ---- | ----------- |
148+
| `insights` | array | Performance insight rows |
149+
| ↳ `accountId` | string | Ad account ID |
150+
| ↳ `campaignId` | string | Campaign ID |
151+
| ↳ `campaignName` | string | Campaign name |
152+
| ↳ `adSetId` | string | Ad set ID |
153+
| ↳ `adSetName` | string | Ad set name |
154+
| ↳ `adId` | string | Ad ID |
155+
| ↳ `adName` | string | Ad name |
156+
| ↳ `impressions` | string | Number of impressions |
157+
| ↳ `clicks` | string | Number of clicks |
158+
| ↳ `spend` | string | Amount spent in account currency |
159+
| ↳ `ctr` | string | Click-through rate |
160+
| ↳ `cpc` | string | Cost per click |
161+
| ↳ `cpm` | string | Cost per 1,000 impressions |
162+
| ↳ `reach` | string | Number of unique users reached |
163+
| ↳ `frequency` | string | Average number of times each person saw the ad |
164+
| ↳ `conversions` | number | Total conversions from actions |
165+
| ↳ `dateStart` | string | Start date of the reporting period |
166+
| ↳ `dateStop` | string | End date of the reporting period |
167+
| `totalCount` | number | Total number of insight rows returned |
168+
169+

0 commit comments

Comments
 (0)