Connecting Ad Platforms

Before creating campaigns, each brand needs a connected ad platform account. This page covers how to obtain access tokens from Meta and TikTok, and how to register them with Symphony.

Meta (Facebook & Instagram)

Step 1: Implement Facebook Login

Use Symphony's connect SDK to launch the Facebook Login dialog and obtain an access token.

Add the SDK to your page:

<script src="https://cdn.symphonyos.co/symphony-connect.min.js"></script>

Step 2: Initialize and Launch Login

<button id="connect-meta">Connect Facebook Ad Account</button>

<script>
  document.getElementById('connect-meta').addEventListener('click', () => {
    SymphonyConnect.loginWithFacebook({
      onSuccess: (response) => {
        // response.accessToken — the Facebook user access token
        // response.userId — the Facebook user ID
        console.log('Facebook connected:', response);
        registerTokenWithSymphony('meta', response.accessToken);
      },
      onError: (error) => {
        console.error('Facebook login failed:', error);
      }
    });
  });
</script>

Step 3: Handle the Response

The onSuccess callback receives a FacebookUserResponse:

interface FacebookUserResponse {
  accessToken: string;   // Facebook user access token
  userId: string;        // Facebook user ID
  expiresIn: number;     // Token expiration in seconds
}

Step 4: Register with Symphony

Send the access token to Symphony:

async function registerTokenWithSymphony(platform, accessToken) {
  const response = await fetch('https://api.symphonyos.co/api/sym/v2/brands', {
    method: 'PUT',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      brandId: 12345,
      adPlatform: platform,
      accessToken: accessToken
    })
  });
  const data = await response.json();
  console.log('Platform connected:', data);
}

curl -X PUT https://api.symphonyos.co/api/sym/v2/brands \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": 12345,
    "adPlatform": "meta",
    "accessToken": "EAAxxxxxxx..."
  }'

Response:

{
  "success": true,
  "message": "Brand 12345 updated successfully"
}

TikTok

Step 1: Obtain a TikTok Access Token

Use TikTok's Marketing API OAuth flow to obtain an access token:

Register your app on TikTok for Business
Implement the OAuth authorization flow
Exchange the authorization code for an access token

Step 2: Register with Symphony

curl -X PUT https://api.symphonyos.co/api/sym/v2/brands \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": 12345,
    "adPlatform": "tiktok",
    "accessToken": "your-tiktok-access-token"
  }'

await fetch('https://api.symphonyos.co/api/sym/v2/brands', {
  method: 'PUT',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    brandId: 12345,
    adPlatform: 'tiktok',
    accessToken: 'your-tiktok-access-token'
  })
});

Verifying Connection

After connecting a platform, verify the brand is properly set up:

curl "https://api.symphonyos.co/api/sym/v2/brands?brandId=12345" \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "id": 12345
  }
}

Beta Note

Note: The PUT /brands endpoint for registering platform tokens is in active development. During the beta period, ad platform setup may require coordination with the Symphony team. Contact [email protected] if you encounter issues during setup.

Supported Platforms Summary

Platform	adPlatform value	Token Type	Notes
Meta (Facebook/Instagram)	`"meta"`	Facebook user access token	Obtained via Facebook Login SDK
TikTok	`"tiktok"`	TikTok Marketing API access token	Obtained via TikTok OAuth flow

Next Steps

Integration Guide — full setup walkthrough
Common Use Cases — create your first campaign