Laravel Meta Ads

https://github.com/jeffersongoncalves/laravel-meta-ads
Admin
Laravel Meta Ads is a Laravel package that provides integration with the Meta Ads Graph API to...
Tokens:24,444
Snippets:161
Trust Score:9.6
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Laravel Meta Ads via Composer

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/README.md

Install the package using Composer.

```bash
composer require jeffersongoncalves/laravel-meta-ads
```

--------------------------------

### Get campaign insights with campaignInsights()

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves insight metrics for a campaign using the GET /{campaignId}/insights endpoint. The method returns a Response object; call ->json('data') to get the data array. The date preset defaults to 'last_30d' if not specified.

```php
$insights = LaravelMetaAds::campaignInsights('120099', 'last_7d')->json('data');
```

--------------------------------

### Use Laravel Meta Ads Facade

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/README.md

Example usage of the LaravelMetaAds facade to interact with the Meta Ads API. Each method returns an Illuminate\Http\Client\Response.

```php
use Jeffersongoncalves\LaravelMetaAds\Facades\LaravelMetaAds;

LaravelMetaAds::accounts();

LaravelMetaAds::campaigns(); // uses META_AD_ACCOUNT_ID by default
LaravelMetaAds::campaigns('123456789'); // or pass an ad account id explicitly

LaravelMetaAds::campaignInsights(campaignId: '120099', datePreset: 'last_30d');

LaravelMetaAds::createCampaign(name: 'My Campaign', objective: 'OUTCOME_TRAFFIC', status: 'PAUSED');

LaravelMetaAds::updateCampaignStatus(campaignId: '120099', status: 'ACTIVE');

LaravelMetaAds::adSets();

LaravelMetaAds::ads(adSetId: '120088');

LaravelMetaAds::audiences();

LaravelMetaAds::createLookalikeAudience(sourceId: '120077', country: 'US');
```

--------------------------------

### Get Ad Sets

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Calls the GET /act_{adAccountId}/adsets endpoint to retrieve ad sets for a given ad account. The fields parameter requests id, name, status, targeting, daily_budget, and bid_amount. The response is a JSON data array of ad set objects.

```php
$adSets = LaravelMetaAds::adSets('123456789')->json('data');
```

--------------------------------

### get and post method signatures

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Protected method signatures for GET and POST wrappers that delegate to the shared PendingRequest.

```php
protected function get(string $path, array $query = []): Response
protected function post(string $path, array $data = []): Response
```

--------------------------------

### Fetch ad accounts with accounts()

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Calls GET /me/adaccounts. Returns JSON with a data array of ad account objects containing the requested fields (id, name, account_status).

```php
$response = LaravelMetaAds::accounts();
$accounts = $response->json('data');
```

--------------------------------

### Fetch campaigns with campaigns()

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Calls GET /act_{adAccountId}/campaigns. The adAccountId is resolved by resolveAccountId() from the method argument or META_AD_ACCOUNT_ID, prefixed with act_. Returns JSON data array of campaign objects.

```php
$campaigns = LaravelMetaAds::campaigns('123456789')->json('data');
```

--------------------------------

### Meta API Error Response JSON

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Example of a typical error response from the Meta API, containing fields like message, type, code, error_subcode, and fbtrace_id. This package does not transform these errors.

```json
{
  "error": {
    "message": "...",
    "type": "...",
    "code": 100,
    "error_subcode": 0,
    "fbtrace_id": "..."
  }
}
```

--------------------------------

### Get Ads

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Calls the GET /{adSetId}/ads endpoint to retrieve ads for a given ad set. The fields parameter requests id, name, status, and creative. The response is a JSON data array of ad objects.

```php
$ads = LaravelMetaAds::ads('120088')->json('data');
```

--------------------------------

### GET /{adSetId}/ads

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves ads for a given ad set. Called by the ads() method. Returns a JSON array of ad objects.

```APIDOC
## GET /{adSetId}/ads

### Description
Retrieves ads for a given ad set. Called by the ads() method. Returns a JSON array of ad objects.

### Method
GET

### Endpoint
/{adSetId}/ads

### Parameters
#### Path Parameters
- **adSetId** (string) - Required - The ID of the ad set.

#### Query Parameters
- **fields** (string) - Required - Comma-separated properties requested on each ad: `id,name,status,creative`.

### Response
#### Success Response (200)
- **data** (array) - Array of ad objects.

#### Response Example
{
  "data": [
    {
      "id": "120088",
      "name": "Ad Name",
      "status": "ACTIVE"
    }
  ]
}

### Example
```php
$ads = LaravelMetaAds::ads('120088')->json('data');
```
```

--------------------------------

### GET /me/adaccounts

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves the list of ad accounts for the authenticated user. This endpoint is called by the accounts() method and returns a JSON array of ad account objects.

```APIDOC
## GET /me/adaccounts

### Description
Retrieves the list of ad accounts for the authenticated user. This endpoint is called by the accounts() method and returns a JSON array of ad account objects.

### Method
GET

### Endpoint
/me/adaccounts

### Parameters
#### Query Parameters
- **fields** (string) - Required - Comma-separated properties requested on each ad account. Value sent: `id,name,account_status`.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - Array of ad account objects containing the requested fields.

#### Response Example
{
  "data": [
    {
      "id": "act_123456789",
      "name": "My Ad Account",
      "account_status": 1
    }
  ]
}
```

--------------------------------

### GET /{adSetId}/ads

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves the list of ads for a specific ad set. This endpoint is called by the ads() method.

```APIDOC
## GET /{adSetId}/ads

### Description
Retrieves the list of ads for a specific ad set. This endpoint is called by the ads() method.

### Method
GET

### Endpoint
/{adSetId}/ads

### Parameters
#### Path Parameters
- **adSetId** (string) - Required - The ID of the ad set.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - Array of ad objects.

#### Response Example
{
  "data": [
    {
      "id": "123456789",
      "name": "Ad 1"
    }
  ]
}
```

--------------------------------

### GET /act_{adAccountId}/adsets

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves ad sets for a given ad account. Called by the adSets() method. Returns a JSON array of ad set objects.

```APIDOC
## GET /act_{adAccountId}/adsets

### Description
Retrieves ad sets for a given ad account. Called by the adSets() method. Returns a JSON array of ad set objects.

### Method
GET

### Endpoint
/act_{adAccountId}/adsets

### Parameters
#### Path Parameters
- **adAccountId** (string) - Required - The ID of the ad account.

#### Query Parameters
- **fields** (string) - Required - Comma-separated properties requested on each ad set: `id,name,status,targeting,daily_budget,bid_amount`.

### Response
#### Success Response (200)
- **data** (array) - Array of ad set objects.

#### Response Example
{
  "data": [
    {
      "id": "120088",
      "name": "Ad Set Name",
      "status": "ACTIVE"
    }
  ]
}

### Example
```php
$adSets = LaravelMetaAds::adSets('123456789')->json('data');
```
```

--------------------------------

### Fetch audiences with GET /act_{adAccountId}/customaudiences

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves a list of custom audiences for the ad account. The response is a JSON array under the 'data' key, accessible via the 'json' method.

```php
$audiences = LaravelMetaAds::audiences()->json('data');
```

--------------------------------

### GET /act_{adAccountId}/adsets

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves the list of ad sets for a specific ad account. This endpoint is called by the adSets() method.

```APIDOC
## GET /act_{adAccountId}/adsets

### Description
Retrieves the list of ad sets for a specific ad account. This endpoint is called by the adSets() method.

### Method
GET

### Endpoint
/act_{adAccountId}/adsets

### Parameters
#### Path Parameters
- **adAccountId** (string) - Required - The ad account ID, with or without the 'act_' prefix.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - Array of ad set objects.

#### Response Example
{
  "data": [
    {
      "id": "123456789",
      "name": "Ad Set 1"
    }
  ]
}
```

--------------------------------

### accounts(): Response

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Lists the ad accounts the access token can see. Issues GET /me/adaccounts with fields=id,name,account_status.

```APIDOC
## accounts(): Response

### Description
Lists the ad accounts the access token can see. Issues `GET /me/adaccounts` with `fields=id,name,account_status`.

### Method
GET

### Endpoint
`/me/adaccounts`

### Parameters
#### Path Parameters
- *(none)*

#### Query Parameters
- `fields` (string) - Required - Comma-separated list of fields: `id,name,account_status`

### Request Example
No request body required.

### Response
#### Success Response (200)
- `data` (array) - Array of ad account objects, each containing `id`, `name`, and `account_status`.

#### Response Example
```json
{
  "data": [
    {
      "id": "act_123456",
      "name": "My Ad Account",
      "account_status": 1
    }
  ]
}
```

### Error Handling
Non-2xx responses are returned as-is; use `$response->throw()` to raise an exception.
```

--------------------------------

### GET /act_{adAccountId}/campaigns

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves the list of campaigns for a specific ad account. The ad account ID is resolved from the method argument or the configured META_AD_ACCOUNT_ID, prefixed with 'act_'.

```APIDOC
## GET /act_{adAccountId}/campaigns

### Description
Retrieves the list of campaigns for a specific ad account. The ad account ID is resolved from the method argument or the configured META_AD_ACCOUNT_ID, prefixed with 'act_'.

### Method
GET

### Endpoint
/act_{adAccountId}/campaigns

### Parameters
#### Path Parameters
- **adAccountId** (string) - Required - The ad account ID, with or without the 'act_' prefix.

#### Query Parameters
- **fields** (string) - Required - Comma-separated properties requested on each campaign. Value sent: `id,name,status,objective,daily_budget`.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - Array of campaign objects containing the requested fields.

#### Response Example
{
  "data": [
    {
      "id": "123456789",
      "name": "Campaign 1",
      "status": "ACTIVE",
      "objective": "OUTCOME_TRAFFIC",
      "daily_budget": "1000"
    }
  ]
}
```

--------------------------------

### Import LaravelMetaAds Facade

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAdsFacade.md

Use this import to access the LaravelMetaAds facade statically. The alias is also registered in composer.json, so the use statement may be optional in most Laravel setups.

```php
use Jeffersongoncalves\LaravelMetaAds\Facades\LaravelMetaAds;
```

--------------------------------

### ads(string $adSetId): Response

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Lists ads belonging to one ad set. Issues a GET request to the Meta API and returns the response containing the ads.

```APIDOC
## ads(string $adSetId): Response

### Description
Lists ads belonging to one ad set. Issues `GET /{adSetId}/ads` with `fields=id,name,status,creative`.

### Method
GET

### Endpoint
`/{adSetId}/ads`

### Parameters
#### Path Parameters
- `adSetId` (string) - Required - Ad set id (e.g. `120088`).

#### Query Parameters
- `fields` (string) - Required - Comma-separated list of fields: `id,name,status,creative`.

### Request Example
```
GET /{adSetId}/ads?fields=id,name,status,creative
```

### Response
#### Success Response (200)
- `data` (array) - Array of ad objects.

#### Response Example
```json
{
  "data": [
    {
      "id": "120077",
      "name": "Ad 1",
      "status": "ACTIVE",
      "creative": {}
    }
  ]
}
```

### Errors
- Never throws via the package (no ad account id involved).
```

--------------------------------

### campaignInsights(string $campaignId, string $datePreset = 'last_30d'): Response

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Fetches performance insights for one campaign. Issues GET /{campaignId}/insights with fields=impressions,clicks,spend,actions,cost_per_action_type and date_preset={$datePreset}.

```APIDOC
## campaignInsights(string $campaignId, string $datePreset = 'last_30d'): Response

### Description
Fetches performance insights for one campaign. Issues `GET /{campaignId}/insights` with `fields=impressions,clicks,spend,actions,cost_per_action_type` and `date_preset={$datePreset}`.

### Method
GET

### Endpoint
`/{campaignId}/insights`

### Parameters
#### Path Parameters
- `campaignId` (string) - Required - Campaign id (e.g. `120099`).

#### Query Parameters
- `fields` (string) - Required - Comma-separated list of fields: `impressions,clicks,spend,actions,cost_per_action_type`
- `date_preset` (string) - Optional - Meta `date_preset` value, e.g. `today`, `yesterday`, `last_7d`, `last_30d`, `lifetime`. Default: `last_30d`.

### Request Example
No request body required.

### Response
#### Success Response (200)
- `data` (array) - Array of insight objects keyed by the requested fields.

#### Response Example
```json
{
  "data": [
    {
      "impressions": "1000",
      "clicks": "10",
      "spend": "5.00",
      "actions": [],
      "cost_per_action_type": []
    }
  ]
}
```

### Error Handling
Non-2xx responses are returned as-is; use `$response->throw()` to raise an exception.
```

--------------------------------

### adSets(?string $adAccountId = null): Response

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Lists ad sets of an ad account. Issues a GET request to the Meta API and returns the response containing the ad sets.

```APIDOC
## adSets(?string $adAccountId = null): Response

### Description
Lists ad sets of an ad account. Issues `GET /act_{adAccountId}/adsets` with `fields=id,name,status,targeting,daily_budget,bid_amount`.

### Method
GET

### Endpoint
`/act_{adAccountId}/adsets`

### Parameters
#### Path Parameters
- `adAccountId` (string) - Optional - Ad account id; falls back to the configured one.

#### Query Parameters
- `fields` (string) - Required - Comma-separated list of fields: `id,name,status,targeting,daily_budget,bid_amount`.

### Request Example
```
GET /act_{adAccountId}/adsets?fields=id,name,status,targeting,daily_budget,bid_amount
```

### Response
#### Success Response (200)
- `data` (array) - Array of ad set objects.

#### Response Example
```json
{
  "data": [
    {
      "id": "120088",
      "name": "Ad Set 1",
      "status": "ACTIVE",
      "targeting": {},
      "daily_budget": "1000",
      "bid_amount": "100"
    }
  ]
}
```

### Errors
- `InvalidArgumentException` - When no ad account id is resolvable.
```

--------------------------------

### Run Laravel Meta Ads Tests

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/README.md

Execute the package test suite.

```bash
composer test
```

--------------------------------

### Create campaign with createCampaign()

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Creates a campaign via POST /act_{adAccountId}/campaigns. The status defaults to 'PAUSED' if not provided. The response contains the created campaign id; call ->json('id') to extract it.

```php
$id = LaravelMetaAds::createCampaign('Spring Sale', 'OUTCOME_TRAFFIC', 'PAUSED')->json('id');
```

--------------------------------

### configurePackage method

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAdsServiceProvider.md

Configures the package name and config file for publication.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('laravel-meta-ads')
        ->hasConfigFile('laravel-meta-ads');
}
```

--------------------------------

### GET /{campaignId}/insights

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves insights for a specific campaign. This endpoint is called by the campaignInsights() method.

```APIDOC
## GET /{campaignId}/insights

### Description
Retrieves insights for a specific campaign. This endpoint is called by the campaignInsights() method.

### Method
GET

### Endpoint
/{campaignId}/insights

### Parameters
#### Path Parameters
- **campaignId** (string) - Required - The ID of the campaign.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - Array of insight objects.

#### Response Example
{
  "data": [
    {
      "impressions": "1000",
      "clicks": "10",
      "spend": "5.00"
    }
  ]
}
```

--------------------------------

### Basic usage - instantiate LaravelMetaAds

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Create a new client instance with an access token, ad account ID, and API version.

```php
use Jeffersongoncalves\LaravelMetaAds\LaravelMetaAds;

$client = new LaravelMetaAds(
    accessToken: 'EAAG...',
    adAccountId: 'act_123456789',
    apiVersion: 'v18.0',
);
```

--------------------------------

### Resolve client via alias and FQCN

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/configuration.md

Shows how to resolve the client from the container using the alias 'laravel-meta-ads' or the fully qualified class name, both returning the same singleton instance.

```php
$client = app('laravel-meta-ads');          // alias
$same   = app(LaravelMetaAds::class);        // FQCN — identical instance
```

--------------------------------

### packageRegistered method

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAdsServiceProvider.md

Registers the main client as a singleton and an alias.

```php
public function packageRegistered(): void
{
    $this->app->singleton(LaravelMetaAds::class, fn () => new LaravelMetaAds(
        config('laravel-meta-ads.access_token'),
        config('laravel-meta-ads.ad_account_id'),
        config('laravel-meta-ads.api_version'),
    ));

    $this->app->alias(LaravelMetaAds::class, 'laravel-meta-ads');
}
```

--------------------------------

### GET /act_{adAccountId}/customaudiences

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves the list of custom audiences for a specific ad account. This endpoint is called by the audiences() method.

```APIDOC
## GET /act_{adAccountId}/customaudiences

### Description
Retrieves the list of custom audiences for a specific ad account. This endpoint is called by the audiences() method.

### Method
GET

### Endpoint
/act_{adAccountId}/customaudiences

### Parameters
#### Path Parameters
- **adAccountId** (string) - Required - The ad account ID, with or without the 'act_' prefix.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - Array of custom audience objects.

#### Response Example
{
  "data": [
    {
      "id": "123456789",
      "name": "Audience 1"
    }
  ]
}
```

--------------------------------

### Create lookalike audience with POST /act_{adAccountId}/customaudiences

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Creates a new lookalike audience based on a source audience. The method requires a source ID, country code, and name, and returns the new audience's ID from the JSON response.

```php
$id = LaravelMetaAds::createLookalikeAudience('120077', 'US', 'US Lookalike')->json('id');
```

--------------------------------

### Publish Laravel Meta Ads Config

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/README.md

Publish the package configuration file using the artisan command.

```bash
php artisan vendor:publish --tag="laravel-meta-ads-config"
```

--------------------------------

### client method implementation

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Builds a PendingRequest with base URL and token. withToken() is applied unconditionally; null token results in empty token. No retries, timeouts, or throw() configured.

```php
return Http::baseUrl("https://graph.facebook.com/{$this->apiVersion}")
    ->withToken($this->accessToken);
```

--------------------------------

### Config file content

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/configuration.md

The default configuration file with access_token, ad_account_id, and api_version keys. Values are read from environment variables with defaults.

```php
<?php

return [
    'access_token' => env('META_ACCESS_TOKEN'),

    'ad_account_id' => env('META_AD_ACCOUNT_ID'),

    'api_version' => env('META_ADS_API_VERSION', 'v18.0'),
];
```

--------------------------------

### Set Meta Ads Credentials in .env

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/README.md

Define the required environment variables for the Meta Ads API.

```env
META_ACCESS_TOKEN=
META_AD_ACCOUNT_ID=
META_ADS_API_VERSION=v18.0
```

--------------------------------

### createCampaign basic usage

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Creates a campaign with named arguments and retrieves the new campaign id from the JSON response.

```php
$response = LaravelMetaAds::createCampaign(
    name: 'My Campaign',
    objective: 'OUTCOME_TRAFFIC',
    status: 'PAUSED',
);

$newId = $response->json('id');
```

--------------------------------

### GET /act_{adAccountId}/customaudiences

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves a list of custom audiences for the specified ad account. This endpoint is called by the audiences() method and returns an array of audience objects with the requested fields.

```APIDOC
## [GET] /act_{adAccountId}/customaudiences

### Description
Retrieves a list of custom audiences for the specified ad account. This endpoint is called by the audiences() method and returns an array of audience objects with the requested fields.

### Method
GET

### Endpoint
/act_{adAccountId}/customaudiences

### Parameters
#### Path Parameters
- **adAccountId** (string) - Required - The ad account ID, prefixed with 'act_'.

#### Query Parameters
- **fields** (string) - Required - Comma-separated properties requested on each audience. Value sent: `id,name,approximate_count`.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (array) - Array of audience objects, each containing the requested fields.

#### Response Example
```json
{
  "data": [
    {
      "id": "123456",
      "name": "My Audience",
      "approximate_count": 1000
    }
  ]
}
```
```

--------------------------------

### __construct

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Creates a new LaravelMetaAds client instance. The constructor accepts an access token, ad account ID, and API version, which are used for all subsequent HTTP requests to the Meta Ads Graph API.

```APIDOC
## __construct

### Description
Creates a new LaravelMetaAds client instance. The constructor accepts an access token, ad account ID, and API version, which are used for all subsequent HTTP requests to the Meta Ads Graph API.

### Method
Constructor

### Signature
```php
public function __construct(
    protected ?string $accessToken,
    protected ?string $adAccountId,
    protected string $apiVersion,
) {}
```

### Parameters
- **$accessToken** (?string) - Required - Meta Graph API access token. Sent as a Bearer token on every request via `Http::withToken()`.
- **$adAccountId** (?string) - Required - Default ad account id used whenever a method's `$adAccountId` argument is omitted. May be `null` if every call passes the id explicitly.
- **$apiVersion** (string) - Required - Graph API version segment embedded in the base URL, e.g. `v18.0`.

### Returns
A new client instance (constructor; no return value).

### Usage Example
```php
use Jeffersongoncalves\LaravelMetaAds\LaravelMetaAds;

$client = new LaravelMetaAds(
    accessToken: 'EAAG...',
    adAccountId: 'act_123456789',
    apiVersion: 'v18.0',
);
```

### Container Resolution
```php
$client = app('laravel-meta-ads');          // alias
$same = app(LaravelMetaAds::class);         // FQCN, same singleton instance
```
```

--------------------------------

### Import LaravelMetaAdsServiceProvider

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAdsServiceProvider.md

Import the service provider class for manual registration or reference.

```php
use Jeffersongoncalves\LaravelMetaAds\LaravelMetaAdsServiceProvider;
```

--------------------------------

### GET /{campaignId}/insights

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Retrieves campaign insights from the Meta Graph API. This endpoint is called by the campaignInsights() method and returns a JSON data array of insight objects keyed by the requested metrics.

```APIDOC
## GET /{campaignId}/insights

### Description
Retrieves campaign insights from the Meta Graph API. This endpoint is called by the campaignInsights() method and returns a JSON data array of insight objects keyed by the requested metrics.

### Method
GET

### Endpoint
/{campaignId}/insights

### Parameters
#### Path Parameters
- **campaignId** (string) - Required - The raw campaign ID interpolated into the path.

#### Query Parameters
- **fields** (string) - Required - Comma-separated insight metrics requested. Value sent: `impressions,clicks,spend,actions,cost_per_action_type`.
- **date_preset** (string) - Optional - Meta date preset selector, e.g. `today`, `last_7d`, `last_30d`, `lifetime`. Default: `last_30d`.

### Response
#### Success Response (200)
- **data** (array) - Array of insight objects keyed by the requested metrics.

#### Response Example
{
  "data": [
    {
      "impressions": "12345",
      "clicks": "123",
      "spend": "45.67",
      "actions": [
        {
          "action_type": "link_click",
          "value": "123"
        }
      ],
      "cost_per_action_type": [
        {
          "action_type": "link_click",
          "value": "0.37"
        }
      ]
    }
  ]
}
```

--------------------------------

### Handling Meta API Errors in PHP

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Shows how to handle a failed response from LaravelMetaAds::campaigns() by checking failed() and accessing the error details via json('error'). The package only throws an InvalidArgumentException for a missing ad account id.

```php
$response = LaravelMetaAds::campaigns('123456789');

if ($response->failed()) {
    $error = $response->json('error');
    // $error['message'], $error['code'], ...
}
```

--------------------------------

### campaigns(?string $adAccountId = null): Response

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Lists campaigns of an ad account. Issues GET /act_{adAccountId}/campaigns with fields=id,name,status,objective,daily_budget.

```APIDOC
## campaigns(?string $adAccountId = null): Response

### Description
Lists campaigns of an ad account. Issues `GET /act_{adAccountId}/campaigns` with `fields=id,name,status,objective,daily_budget`.

### Method
GET

### Endpoint
`/act_{adAccountId}/campaigns`

### Parameters
#### Path Parameters
- `adAccountId` (string) - Optional - Ad account id (with or without `act_` prefix). Falls back to configured `ad_account_id` when omitted.

#### Query Parameters
- `fields` (string) - Required - Comma-separated list of fields: `id,name,status,objective,daily_budget`

### Request Example
No request body required.

### Response
#### Success Response (200)
- `data` (array) - Array of campaign objects, each containing `id`, `name`, `status`, `objective`, `daily_budget`.

#### Response Example
```json
{
  "data": [
    {
      "id": "120099",
      "name": "Campaign 1",
      "status": "ACTIVE",
      "objective": "OUTCOME_TRAFFIC",
      "daily_budget": "1000"
    }
  ]
}
```

### Error Handling
Throws `InvalidArgumentException` when neither `$adAccountId` nor configured id is present. Non-2xx responses are returned as-is; use `$response->throw()` to raise an exception.
```

--------------------------------

### Error Handling Through the Facade

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAdsFacade.md

Shows how to catch exceptions when calling the facade without an ad account ID. Throws InvalidArgumentException if META_AD_ACCOUNT_ID is not set, and RequestException for 4xx/5xx responses from the Meta Graph API.

```php
use Jeffersongoncalves\LaravelMetaAds\Facades\LaravelMetaAds;

try {
    $response = LaravelMetaAds::campaigns(); // META_AD_ACCOUNT_ID not set
    $response->throw();
} catch (InvalidArgumentException $e) {
    // "ad_account_id required (pass explicitly or set META_AD_ACCOUNT_ID)"
} catch (Illuminate\Http\Client\RequestException $e) {
    // Meta Graph API returned 4xx/5xx
}
```

--------------------------------

### POST /act_{adAccountId}/campaigns

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Creates a new campaign for a specific ad account. This endpoint is called by the createCampaign() method.

```APIDOC
## POST /act_{adAccountId}/campaigns

### Description
Creates a new campaign for a specific ad account. This endpoint is called by the createCampaign() method.

### Method
POST

### Endpoint
/act_{adAccountId}/campaigns

### Parameters
#### Path Parameters
- **adAccountId** (string) - Required - The ad account ID, with or without the 'act_' prefix.

#### Request Body
- **name** (string) - Required - The name of the campaign.
- **objective** (string) - Required - The campaign objective.
- **status** (string) - Required - The campaign status (e.g., ACTIVE, PAUSED).
- **daily_budget** (string) - Required - The daily budget in account currency.

### Request Example
{
  "name": "New Campaign",
  "objective": "OUTCOME_TRAFFIC",
  "status": "ACTIVE",
  "daily_budget": "1000"
}

### Response
#### Success Response (200)
- **id** (string) - The ID of the created campaign.

#### Response Example
{
  "id": "123456789"
}
```

--------------------------------

### Resolve from container

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Typical Laravel usage: resolve the singleton instance via the alias or FQCN.

```php
$client = app('laravel-meta-ads');          // alias
$same = app(LaravelMetaAds::class);         // FQCN, same singleton instance
```

--------------------------------

### Basic usage of accounts()

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Calls accounts() and iterates over the returned data array to print account IDs and names.

```php
$response = LaravelMetaAds::accounts();

foreach ($response->json('data') as $account) {
    echo $account['id'] . ' ' . $account['name'];
}
```

--------------------------------

### audiences(?string $adAccountId = null): Response

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Lists custom audiences of an ad account. Issues a GET request to the Meta Graph API endpoint for custom audiences with specific fields.

```APIDOC
## [GET] /act_{adAccountId}/customaudiences

### Description
Lists custom audiences of an ad account. Issues `GET /act_{adAccountId}/customaudiences` with `fields=id,name,approximate_count`.

### Method
GET

### Endpoint
`/act_{adAccountId}/customaudiences`

### Parameters
#### Path Parameters
- `adAccountId` (string) - Required - Ad account id; falls back to the configured one.

#### Query Parameters
- `fields` (string) - Required - Comma-separated list of fields: `id,name,approximate_count`.

### Request Example
```
GET /act_{adAccountId}/customaudiences?fields=id,name,approximate_count
```

### Response
#### Success Response (200)
- `data` (array) - Array of audience objects.

#### Response Example
```json
{
  "data": [
    {
      "id": "123456",
      "name": "My Audience",
      "approximate_count": 1000
    }
  ]
}
```

### Error Handling
- `InvalidArgumentException` when no ad account id is resolvable.
- `Illuminate\Http\Client\RequestException` on Meta access/scope error.
```

--------------------------------

### Constructor signature

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Exact constructor signature from src/LaravelMetaAds.php:12-16. Parameters are promoted to protected properties.

```php
public function __construct(
    protected ?string $accessToken,
    protected ?string $adAccountId,
    protected string $apiVersion,
) {}
```

--------------------------------

### audiences() method signature

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Method signature for listing custom audiences of an ad account. Issues GET /act_{adAccountId}/customaudiences with fields=id,name,approximate_count. Throws InvalidArgumentException when no ad account id is resolvable.

```php
public function audiences(?string $adAccountId = null): Response
```

--------------------------------

### POST /act_{adAccountId}/campaigns

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Creates a new campaign in the Meta Graph API. This endpoint is called by the createCampaign() method and returns a JSON object containing the created campaign ID.

```APIDOC
## POST /act_{adAccountId}/campaigns

### Description
Creates a new campaign in the Meta Graph API. This endpoint is called by the createCampaign() method and returns a JSON object containing the created campaign ID.

### Method
POST

### Endpoint
/act_{adAccountId}/campaigns

### Parameters
#### Path Parameters
- **adAccountId** (string) - Required - The ad account ID, resolved as in endpoint 2.

#### Request Body (form data)
- **name** (string) - Required - Campaign name.
- **objective** (string) - Required - Meta campaign objective.
- **status** (string) - Optional - Campaign status, e.g. `ACTIVE`, `PAUSED`. Default: `PAUSED`.
- **special_ad_categories** (array) - Required - Empty special ad categories array (required by Meta for the create call).

### Request Example
{
  "name": "Spring Sale",
  "objective": "OUTCOME_TRAFFIC",
  "status": "PAUSED",
  "special_ad_categories": []
}

### Response
#### Success Response (200)
- **id** (string) - The ID of the created campaign.

#### Response Example
{
  "id": "120099"
}
```

--------------------------------

### getFacadeAccessor() Method

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAdsFacade.md

Returns the container binding key for the facade, which is the FQCN of the underlying LaravelMetaAds class. This method is required by the base Facade class.

```php
protected static function getFacadeAccessor(): string
{
    return \Jeffersongoncalves\LaravelMetaAds\LaravelMetaAds::class;
}
```

--------------------------------

### createCampaign error handling

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Wraps createCampaign in a try/catch to handle missing ad account id (InvalidArgumentException) and Meta request rejection (RequestException).

```php
try {
    $response = LaravelMetaAds::createCampaign('Q3 Sale', 'OUTCOME_TRAFFIC', 'ACTIVE');
    $response->throw();
} catch (InvalidArgumentException $e) {
    // missing ad account id
} catch (Illuminate\Http\Client\RequestException $e) {
    // Meta rejected the request (invalid objective, permissions, etc.)
}
```

--------------------------------

### createCampaign(string $name, string $objective, string $status = 'PAUSED', ?string $adAccountId = null): Response

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Creates a campaign in the Meta ad account. Issues a POST request to the Meta API with the campaign details and returns the response.

```APIDOC
## createCampaign(string $name, string $objective, string $status = 'PAUSED', ?string $adAccountId = null): Response

### Description
Creates a campaign. Issues `POST /act_{adAccountId}/campaigns` with form data `name`, `objective`, `status` and `special_ad_categories=[]`.

### Method
POST

### Endpoint
`/act_{adAccountId}/campaigns`

### Parameters
#### Path Parameters
- `adAccountId` (string) - Optional - Ad account id; falls back to the configured one.

#### Request Body
- `name` (string) - Required - Campaign name.
- `objective` (string) - Required - Meta objective, e.g. `OUTCOME_TRAFFIC` (must match the API version's allowed objectives).
- `status` (string) - Optional - Campaign status, e.g. `ACTIVE`, `PAUSED`. Default: `'PAUSED'`.
- `special_ad_categories` (array) - Required - Empty array `[]`.

### Request Example
```json
{
  "name": "My Campaign",
  "objective": "OUTCOME_TRAFFIC",
  "status": "PAUSED",
  "special_ad_categories": []
}
```

### Response
#### Success Response (200)
- `id` (string) - The created campaign id.

#### Response Example
```json
{
  "id": "120099"
}
```

### Errors
- `InvalidArgumentException` - When no ad account id is resolvable.
- `Illuminate\Http\Client\RequestException` - When Meta rejects the request (invalid objective, permissions, etc.).
```

--------------------------------

### adSets basic usage

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Lists ad sets and retrieves the 'data' array from the JSON response.

```php
$adSets = LaravelMetaAds::adSets()->json('data');
```

--------------------------------

### Singleton registration in service provider

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/configuration.md

Registers the LaravelMetaAds singleton in the container, passing config values positionally to the constructor.

```php
$this->app->singleton(LaravelMetaAds::class, fn () => new LaravelMetaAds(
    config('laravel-meta-ads.access_token'),
    config('laravel-meta-ads.ad_account_id'),
    config('laravel-meta-ads.api_version'),
));
```

--------------------------------

### Error handling for createLookalikeAudience()

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Shows how to catch InvalidArgumentException (missing ad account id) and RequestException (e.g., source audience too small or not eligible for lookalikes) when calling createLookalikeAudience().

```php
try {
    LaravelMetaAds::createLookalikeAudience('120077', 'US')->throw();
} catch (InvalidArgumentException $e) {
    // ad account id missing
} catch (Illuminate\Http\Client\RequestException $e) {
    // e.g. source audience too small or not eligible for lookalikes
}
```

--------------------------------

### ads basic usage

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Lists ads for a given ad set and retrieves the 'data' array from the JSON response.

```php
$ads = LaravelMetaAds::ads(adSetId: '120088')->json('data');
```

--------------------------------

### Basic Usage of LaravelMetaAds Facade

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAdsFacade.md

Calls the campaigns() method statically through the facade, passing an ad account ID, and retrieves the 'data' key from the JSON response.

```php
use Jeffersongoncalves\LaravelMetaAds\Facades\LaravelMetaAds;

$response = LaravelMetaAds::campaigns('123456789');

$campaigns = $response->json('data');
```

--------------------------------

### updateCampaignStatus chained usage with throw()

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Updates a campaign status and immediately throws an exception if the request fails, using the chained ->throw() method.

```php
LaravelMetaAds::updateCampaignStatus('120099', 'PAUSED')->throw();
```

--------------------------------

### Basic usage of createLookalikeAudience()

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Creates a lookalike audience with named arguments and echoes the new audience id from the JSON response.

```php
$response = LaravelMetaAds::createLookalikeAudience(
    sourceId: '120077',
    country: 'US',
    name: 'US Lookalike — VIP Customers',
);

echo $response->json('id');
```

--------------------------------

### campaignInsights() with failure check

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Uses a different preset and calls throw() to raise an exception on HTTP errors, then accesses a specific data field.

```php
$response = LaravelMetaAds::campaignInsights('120099', 'lifetime');

$response->throw(); // raises an Illuminate\Http\Client\HttpClientException on 4xx/5xx

$spend = $response->json('data.0.spend');
```

--------------------------------

### Basic usage of campaignInsights()

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Calls campaignInsights() with named arguments and retrieves the data array from the response.

```php
$insights = LaravelMetaAds::campaignInsights(
    campaignId: '120099',
    datePreset: 'last_30d',
)->json('data');
```

--------------------------------

### POST /act_{adAccountId}/customaudiences

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Creates a new lookalike audience for a specific ad account. This endpoint is called by the createLookalikeAudience() method.

```APIDOC
## POST /act_{adAccountId}/customaudiences

### Description
Creates a new lookalike audience for a specific ad account. This endpoint is called by the createLookalikeAudience() method.

### Method
POST

### Endpoint
/act_{adAccountId}/customaudiences

### Parameters
#### Path Parameters
- **adAccountId** (string) - Required - The ad account ID, with or without the 'act_' prefix.

#### Request Body
- **name** (string) - Required - The name of the lookalike audience.
- **subtype** (string) - Required - The subtype of the audience (e.g., LOOKALIKE).
- **origin_audience_id** (string) - Required - The ID of the source audience.
- **lookalike_spec** (object) - Required - The lookalike specification.

### Request Example
{
  "name": "Lookalike Audience",
  "subtype": "LOOKALIKE",
  "origin_audience_id": "123456789",
  "lookalike_spec": {
    "ratio": 0.01,
    "country": "US"
  }
}

### Response
#### Success Response (200)
- **id** (string) - The ID of the created audience.

#### Response Example
{
  "id": "123456789"
}
```

--------------------------------

### POST /{campaignId}

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/endpoints.md

Updates the status of a specific campaign. This endpoint is called by the updateCampaignStatus() method.

```APIDOC
## POST /{campaignId}

### Description
Updates the status of a specific campaign. This endpoint is called by the updateCampaignStatus() method.

### Method
POST

### Endpoint
/{campaignId}

### Parameters
#### Path Parameters
- **campaignId** (string) - Required - The ID of the campaign.

#### Request Body
- **status** (string) - Required - The new status for the campaign (e.g., ACTIVE, PAUSED).

### Request Example
{
  "status": "PAUSED"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the update was successful.

#### Response Example
{
  "success": true
}
```

--------------------------------

### createCampaign method signature

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Declares the createCampaign method with parameters for name, objective, status (default 'PAUSED'), and optional adAccountId. Returns an Illuminate\Http\Client\Response.

```php
public function createCampaign(string $name, string $objective, string $status = 'PAUSED', ?string $adAccountId = null): Response
```

--------------------------------

### campaigns() error handling

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Catches InvalidArgumentException when no ad account ID is configured or passed.

```php
try {
    $response = LaravelMetaAds::campaigns(); // no account configured
} catch (InvalidArgumentException $e) {
    // "ad_account_id required (pass explicitly or set META_AD_ACCOUNT_ID)"
}
```

--------------------------------

### accounts() method signature

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Declares the public method that lists ad accounts. Returns a Laravel HTTP client response.

```php
public function accounts(): Response
```

--------------------------------

### Override singleton in consumer code

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAdsServiceProvider.md

Rebind the singleton in your own service provider, e.g., for tests.

```php
$this->app->singleton(LaravelMetaAds::class, fn () => new LaravelMetaAds(
    accessToken: 'test-token',
    adAccountId: 'act_123',
    apiVersion: 'v18.0',
));
```

--------------------------------

### Basic usage of campaigns()

Source: https://github.com/jeffersongoncalves/laravel-meta-ads/blob/main/_autodocs/api-reference/LaravelMetaAds.md

Calls campaigns() with an explicit account ID or falls back to the configured META_AD_ACCOUNT_ID.

```php
$campaigns = LaravelMetaAds::campaigns('123456789')->json('data'); // explicit account
// or
$campaigns = LaravelMetaAds::campaigns()->json('data');            // uses META_AD_ACCOUNT_ID
```
Tokens:
Raw