Hootsuite CI Integration

Overview

Set up CI/CD for Hootsuite social media management integrations: run unit tests with mocked post scheduling and analytics responses on every PR, validate live API connectivity for social profile queries on merge to main. Hootsuite's API handles scheduled posts, social analytics, and multi-network publishing, so CI pipelines verify scheduling logic, content validation rules, and analytics data aggregation.

GitHub Actions Workflow

# .github/workflows/hootsuite-ci.yml
name: Hootsuite CI
on:
  pull_request:
    paths: ['src/hootsuite/**', 'tests/**']
  push:
    branches: [main]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm test -- --reporter=verbose

  integration-tests:
    if: github.ref == 'refs/heads/main'
    needs: unit-tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:integration
        env:
          HOOTSUITE_CLIENT_ID: ${{ secrets.HOOTSUITE_CLIENT_ID }}
          HOOTSUITE_CLIENT_SECRET: ${{ secrets.HOOTSUITE_CLIENT_SECRET }}
          HOOTSUITE_REFRESH_TOKEN: ${{ secrets.HOOTSUITE_REFRESH_TOKEN }}

Mock-Based Unit Tests

// tests/hootsuite-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { schedulePost, getPostAnalytics } from '../src/hootsuite-service';

vi.mock('../src/hootsuite-client', () => ({
  HootsuiteClient: vi.fn().mockImplementation(() => ({
    createMessage: vi.fn().mockResolvedValue({
      id: 'msg_abc123',
      state: 'SCHEDULED',
      scheduledSendTime: '2026-04-07T14:00:00Z',
      socialProfileIds: ['sp_twitter', 'sp_linkedin'],
    }),
    getAnalytics: vi.fn().mockResolvedValue({
      postId: 'msg_abc123',
      metrics: { impressions: 1200, clicks: 85, engagement_rate: 0.071 },
    }),
    listSocialProfiles: vi.fn().mockResolvedValue({
      profiles: [
        { id: 'sp_twitter', type: 'TWITTER', name: '@company' },
        { id: 'sp_linkedin', type: 'LINKEDIN', name: 'Company Page' },
      ],
    }),
  })),
}));

describe('Hootsuite Service', () => {
  it('schedules a multi-network post', async () => {
    const result = await schedulePost('Launch day!', {
      profiles: ['sp_twitter', 'sp_linkedin'],
      scheduledTime: '2026-04-07T14:00:00Z',
    });
    expect(result.state).toBe('SCHEDULED');
    expect(result.socialProfileIds).toHaveLength(2);
  });

  it('retrieves post analytics'…

Hootsuite Common Errors

Error Reference

401 Unauthorized

Cause: Access token expired (tokens last ~1 hour). Fix: Refresh token via OAuth:

curl -X POST https://platform.hootsuite.com/oauth2/token \
  -u "$HOOTSUITE_CLIENT_ID:$HOOTSUITE_CLIENT_SECRET" \
  -d "grant_type=refresh_token&refresh_token=$HOOTSUITE_REFRESH_TOKEN"

403 Forbidden

Cause: App lacks required permissions or user doesn't own the resource. Fix: Check app scopes in developer portal. Ensure user has access to the social profile.

422 Unprocessable Entity — scheduledSendTime

Cause: Scheduled time is in the past or invalid ISO 8601 format. Fix: Always use future dates in ISO 8601: new Date(Date.now() + 3600000).toISOString()

422 — socialProfileIds

Cause: Profile ID invalid or disconnected. Fix: List profiles first: GET /v1/socialProfiles and verify IDs.

429 Too Many Requests

Cause: Rate limit exceeded. Fix: Implement exponential backoff. See hootsuite-rate-limits.

Media Upload — State REJECTED

Cause: File too large, wrong format, or exceeds platform limits. Fix: Check per-platform limits: Twitter images 5MB, Facebook 10MB, video varies.

invalid_grant — Token Exchange

Cause: Authorization code expired (30 second lifetime) or already used. Fix: Re-initiate OAuth flow — codes are single-use and expire in 30s.

redirect_uri_mismatch

Cause: Redirect URI doesn't exactly match app registration. Fix: Must match character-for-character, including trailing slash.

Quick Diagnostics

# Test token validity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $HOOTSUITE_ACCESS_TOKEN" \
  https://platform.hootsuite.com/v1/me

# List profiles (verifies full API access)
curl -s -H "Authorization: Bearer $HOOTSUITE_ACCESS_TOKEN" \
  https://platform.hootsuite.com/v1/socialProfiles | python3 -m json.tool

Overview

This reference triages profile, schedule, approval, audience, and quota failures through redacted status and opaque IDs. It does not authorize copying post content, media, handles, or account metadata into a ticket.

Prerequisites

• A draft-only sandbox probe, redacted correlation ID, endpoint class, and HTTP or terminal schedule status.
• A scoped read-only diagnostic credential and named owner for account, audience, or approval changes.

Instructions

1. Classify authentication, authorization, profile look…

Hootsuite Publishing — Schedule Posts with Media

Overview

Schedule social media posts with images and videos using the Hootsuite REST API. The publishing workflow involves: uploading media to get a media ID, then scheduling a message referencing that media.

Prerequisites

• Completed hootsuite-install-auth setup
• Social profiles connected in Hootsuite
• Media files (images/videos) for upload

Instructions

Step 1: Upload Media

// publishing.ts
import 'dotenv/config';
import fs from 'fs';

const TOKEN = process.env.HOOTSUITE_ACCESS_TOKEN!;
const BASE = 'https://platform.hootsuite.com/v1';

// Step 1a: Create upload URL
async function createMediaUpload(sizeBytes: number, mimeType: string) {
  const response = await fetch(`${BASE}/media`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ sizeBytes, mimeType }),
  });
  const { data } = await response.json();
  console.log('Upload URL:', data.uploadUrl);
  console.log('Media ID:', data.id);
  return data; // { id, uploadUrl, uploadUrlDurationSeconds }
}

// Step 1b: Upload file to the S3 URL
async function uploadFile(uploadUrl: string, filePath: string, mimeType: string) {
  const fileBuffer = fs.readFileSync(filePath);
  const response = await fetch(uploadUrl, {
    method: 'PUT',
    headers: { 'Content-Type': mimeType },
    body: fileBuffer,
  });
  if (response.status !== 200) throw new Error(`Upload failed: ${response.status}`);
  console.log('File uploaded successfully');
}

// Step 1c: Check media status
async function getMediaStatus(mediaId: string) {
  const response = await fetch(`${BASE}/media/${mediaId}`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();
  console.log('Media state:', data.state); // PENDING, READY, REJECTED
  return data;
}

Step 2: Schedule Post with Media

async function scheduleWithMedia(config: {
  profileIds: string[];
  text: string;
  mediaIds: string[];
  scheduledAt: Date;
}) {
  const response = await fetch(`${BASE}/messages`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text: config.text,
      socialProfileIds: config.profileIds,
      scheduledSendTime: config.scheduledAt.toISOString(),
      mediaUrls: config.mediaIds.map(id => ({ id })),
      emailNotification: false,
    }),
  });

  const result = await response.json();
  for (const msg of result.data) {
    console.log(`Message ${msg.id}: ${msg.state} → ${msg.scheduledSendTime}`);
  }
  return…

Hootsuite Analytics & URL Shortening

Overview

Retrieve social media analytics and use Ow.ly URL shortening via the Hootsuite API. Track post performance, engagement metrics, and click-through rates.

Prerequisites

• Completed hootsuite-install-auth setup
• Published posts with engagement data

Instructions

Step 1: Get Organization Analytics

import 'dotenv/config';
const TOKEN = process.env.HOOTSUITE_ACCESS_TOKEN!;
const BASE = 'https://platform.hootsuite.com/v1';

async function getOrganization() {
  const response = await fetch(`${BASE}/me/organizations`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();
  return data[0]; // Primary organization
}

Step 2: Shorten URLs with Ow.ly

async function shortenUrl(fullUrl: string) {
  const response = await fetch(`${BASE}/shorteners/owly`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url: fullUrl }),
  });
  const { data } = await response.json();
  console.log(`${fullUrl} → ${data.shortUrl}`);
  return data;
}

// Shorten multiple URLs
async function shortenBatch(urls: string[]) {
  return Promise.all(urls.map(url => shortenUrl(url)));
}

Step 3: Retrieve Message Analytics

async function getMessageAnalytics(messageId: string) {
  const response = await fetch(`${BASE}/messages/${messageId}`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();
  console.log(`Message: ${data.text?.substring(0, 50)}...`);
  console.log(`State: ${data.state}`);
  console.log(`Sent: ${data.sentAt}`);
  return data;
}

// List sent messages and their performance
async function getSentMessages(profileId: string) {
  const response = await fetch(
    `${BASE}/messages?socialProfileIds=${profileId}&state=SENT&limit=20`,
    { headers: { 'Authorization': `Bearer ${TOKEN}` } },
  );
  const { data } = await response.json();
  for (const msg of data) {
    console.log(`[${msg.sentAt}] ${msg.text?.substring(0, 60)}`);
  }
  return data;
}

Step 4: Social Profile Metrics

async function getProfileDetails(profileId: string) {
  const response = await fetch(`${BASE}/socialProfiles/${profileId}`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();
  console.log(`Profile: @${data.socialNetworkUsername}`);
  console.log(`Network: ${data.type}`);
  console.log(`ID: ${data.id}`);
  return data;
}

Output

• Organization analytics retrieved
• URLs shortened…

Hootsuite Cost Tuning

Hootsuite Plans

Cost Optimization

Step 1: Minimize API Calls

// Cache profile lists (don't refetch every request)
// Batch schedule posts (one session, many messages)
// Use bulk endpoints where available

Step 2: Right-Size Your Plan

// Audit actual profile usage
async function auditUsage() {
  const profiles = await getCachedProfiles();
  console.log(`Active profiles: ${profiles.length}`);
  console.log(`Networks: ${[...new Set(profiles.map(p => p.type))].join(', ')}`);
  // If using < 10 profiles, Professional plan may suffice
}

Step 3: Track API Usage

let apiCallCount = 0;
const originalFetch = fetch;
globalThis.fetch = async (...args) => {
  if (String(args[0]).includes('hootsuite.com')) apiCallCount++;
  return originalFetch(...args);
};
// Log periodically
setInterval(() => { console.log(`Hootsuite API calls: ${apiCallCount}`); apiCallCount = 0; }, 3600000);

Overview

Tune social operations using aggregate volume and quota data. A cost saving is invalid if it widens account access, removes approval, changes audience targeting, or causes duplicate/public posts.

Prerequisites

• An approved budget, account inventory, baseline API/quota metrics, and named owner for each social profile.
• A sandbox/draft-only rehearsal, rollback revision for schedule/cache/concurrency, and an approval path for any audience change.

Instructions

1. Measure aggregate publish, schedule, retry, and quota counts before proposing a control; never export unpublished copy merely to assess cost.
2. Classify candidates as duplicate, expired, nonessential, or owner-review, retaining draft and approval state.
3. Dry-run the change against draft-only content, compare aggregate counts and approval/audience assertions, then canary one non-production profile.
4. Promote only with owner approval; roll back for duplicate posting, target drift, approval bypass, or increased failures.
5. State savings as a range and preserve a reversible schedule/configuration revision.

Output

Return a cost-change receipt with baseline/projected counts, control revision, owner approval, draft/canary result, approval/audience asser…

Hootsuite Debug Bundle

Overview

Collect Hootsuite API connectivity status, social profile health, scheduled post state, and OAuth token validity into a single diagnostic archive. This bundle helps troubleshoot failed post scheduling, disconnected social accounts, media upload errors, and API authentication problems.

Debug Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE="debug-hootsuite-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Hootsuite Debug Bundle ===" | tee "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "HOOTSUITE_API_KEY: ${HOOTSUITE_API_KEY:+[SET]}" >> "$BUNDLE/summary.txt"
echo "HOOTSUITE_ACCESS_TOKEN: ${HOOTSUITE_ACCESS_TOKEN:+[SET]}" >> "$BUNDLE/summary.txt"

# API connectivity — user profile endpoint
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${HOOTSUITE_ACCESS_TOKEN}" \
  https://platform.hootsuite.com/v1/me 2>/dev/null || echo "000")
echo "API Status: HTTP $HTTP" >> "$BUNDLE/summary.txt"

# User profile and social profiles
curl -s -H "Authorization: Bearer ${HOOTSUITE_ACCESS_TOKEN}" \
  https://platform.hootsuite.com/v1/me > "$BUNDLE/me.json" 2>&1 || true
curl -s -H "Authorization: Bearer ${HOOTSUITE_ACCESS_TOKEN}" \
  https://platform.hootsuite.com/v1/socialProfiles > "$BUNDLE/profiles.json" 2>&1 || true

# Scheduled posts and rate limit headers
curl -s -D "$BUNDLE/rate-headers.txt" -H "Authorization: Bearer ${HOOTSUITE_ACCESS_TOKEN}" \
  "https://platform.hootsuite.com/v1/messages?limit=10&state=SCHEDULED" > "$BUNDLE/scheduled-posts.json" 2>&1 || true

tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

Analyzing the Bundle

tar -xzf debug-hootsuite-*.tar.gz
cat debug-hootsuite-*/summary.txt                  # Auth + connectivity
jq '.data[] | {id, type, socialNetworkId}' debug-hootsuite-*/profiles.json  # Connected accounts
jq '.data[] | {id, state, scheduledSendTime}' debug-hootsuite-*/scheduled-posts.json
grep -i "ratelimit\|retry" debug-hootsuite-*/rate-headers.txt

Common Issues

Hootsuite Deploy Integration

Overview

Deploy Hootsuite social media management backends. Key consideration: OAuth refresh tokens must persist across deployments — use a database or key-value store, not environment variables.

Instructions

Step 1: Vercel Deployment

// api/schedule.ts — Vercel serverless
import type { VercelRequest, VercelResponse } from '@vercel/node';

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== 'POST') return res.status(405).end();

  // Get token from persistent store (not env var — tokens rotate)
  const token = await getStoredToken();

  const response = await fetch('https://platform.hootsuite.com/v1/messages', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(req.body),
  });

  const result = await response.json();
  res.json(result);
}

vercel env add HOOTSUITE_CLIENT_ID production
vercel env add HOOTSUITE_CLIENT_SECRET production
vercel --prod

Step 2: Token Persistence

// Use Redis, database, or KV store for token persistence
// Tokens refresh every ~1 hour and refresh_token changes each time
import { kv } from '@vercel/kv';

async function getStoredToken(): Promise<string> {
  let token = await kv.get('hootsuite:access_token');
  const expiresAt = await kv.get('hootsuite:expires_at') as number;

  if (!token || Date.now() > expiresAt - 60000) {
    const refreshToken = await kv.get('hootsuite:refresh_token') as string;
    const newTokens = await refreshHootsuiteToken(refreshToken);
    await kv.set('hootsuite:access_token', newTokens.access_token);
    await kv.set('hootsuite:refresh_token', newTokens.refresh_token);
    await kv.set('hootsuite:expires_at', Date.now() + newTokens.expires_in * 1000);
    token = newTokens.access_token;
  }
  return token as string;
}

Prerequisites

• An approved deployment change, secret references, profile/destination allowlist, and pinned client/configuration revision.
• A draft-only canary profile, baselines for health/quota/schedule behavior, and tested rollback/cancel procedures.

Output

Produce a deployment receipt with artifact digest, environment, canary profile, health/quota/draft assertions, owner approval, rollout state, and rollback reference. Exclude post copy, media, handles, and secrets.

Error Handling

Halt for unknown profile/destination, missing approval, public-post path in a canary, unbounded retry, or leaked copy in telemetry. Cancel/revert the schedule and restore the previous revision.

Examples

artifact=sha256:opaque; env=stag…

Hootsuite Hello World

Overview

List your social media profiles and schedule a post using the Hootsuite REST API. The API base URL is https://platform.hootsuite.com/v1/.

Prerequisites

• Completed hootsuite-install-auth setup
• Valid access token
• At least one social profile connected in Hootsuite

Instructions

Step 1: List Social Profiles

// hello-hootsuite.ts
import 'dotenv/config';

const TOKEN = process.env.HOOTSUITE_ACCESS_TOKEN!;
const BASE = 'https://platform.hootsuite.com/v1';

async function listProfiles() {
  const response = await fetch(`${BASE}/socialProfiles`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();

  for (const profile of data) {
    console.log(`${profile.type}: @${profile.socialNetworkUsername} (ID: ${profile.id})`);
  }
  return data;
}

listProfiles().catch(console.error);

Step 2: Schedule a Post

async function schedulePost(socialProfileId: string, text: string, scheduledAt: Date) {
  const response = await fetch(`${BASE}/messages`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text,
      socialProfileIds: [socialProfileId],
      scheduledSendTime: scheduledAt.toISOString(),
      emailNotification: false,
    }),
  });

  const result = await response.json();
  console.log('Scheduled message ID:', result.data[0]?.id);
  console.log('State:', result.data[0]?.state);
  console.log('Scheduled for:', result.data[0]?.scheduledSendTime);
  return result;
}

// Schedule a post 1 hour from now
const profiles = await listProfiles();
if (profiles.length > 0) {
  const oneHourLater = new Date(Date.now() + 3600000);
  await schedulePost(profiles[0].id, 'Hello from the Hootsuite API!', oneHourLater);
}

Step 3: List Scheduled Messages

async function listMessages() {
  const response = await fetch(`${BASE}/messages?state=SCHEDULED&limit=10`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const { data } = await response.json();
  for (const msg of data) {
    console.log(`[${msg.state}] ${msg.text?.substring(0, 60)}... → ${msg.scheduledSendTime}`);
  }
}

Step 4: curl Quick Test

# List profiles
curl -s -H "Authorization: Bearer $HOOTSUITE_ACCESS_TOKEN" \
  https://platform.hootsuite.com/v1/socialProfiles | python3 -m json.tool

# Get current user
curl -s -H "Authorization: Bearer $HOOTSUITE_ACCESS_TOKEN" \
  https://platform.hootsuite.com/v1/me | python3 -m json.tool

Output

• Listed so…

Hootsuite Install & Auth

Overview

Configure Hootsuite REST API OAuth 2.0 authentication. Hootsuite uses OAuth 2.0 with Bearer tokens. You register an app in the Hootsuite Developer Portal, get client credentials, and exchange authorization codes for access tokens.

Prerequisites

• Hootsuite account (Business plan or higher for API access)
• Registered app at https://developer.hootsuite.com
• Client ID and Client Secret from your app

Instructions

Step 1: Register Your App

1. Go to https://developer.hootsuite.com
2. Create a new app
3. Note your Client ID and Client Secret
4. Set redirect URI to https://your-app.com/callback

Step 2: Configure Environment

# .env (NEVER commit)
HOOTSUITE_CLIENT_ID=your_client_id
HOOTSUITE_CLIENT_SECRET=your_client_secret
HOOTSUITE_REDIRECT_URI=https://your-app.com/callback
HOOTSUITE_ACCESS_TOKEN=  # Populated after OAuth flow

# .gitignore
.env
.env.local

Step 3: OAuth 2.0 Authorization Flow

// auth.ts — OAuth 2.0 authorization code flow
import 'dotenv/config';

const { HOOTSUITE_CLIENT_ID, HOOTSUITE_CLIENT_SECRET, HOOTSUITE_REDIRECT_URI } = process.env;

// Step 1: Redirect user to authorize
function getAuthUrl(): string {
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: HOOTSUITE_CLIENT_ID!,
    redirect_uri: HOOTSUITE_REDIRECT_URI!,
    scope: 'offline',
  });
  return `https://platform.hootsuite.com/oauth2/auth?${params}`;
}

// Step 2: Exchange authorization code for tokens
async function exchangeCode(code: string) {
  const response = await fetch('https://platform.hootsuite.com/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${HOOTSUITE_CLIENT_ID}:${HOOTSUITE_CLIENT_SECRET}`).toString('base64')}`,
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: HOOTSUITE_REDIRECT_URI!,
    }),
  });

  const tokens = await response.json();
  console.log('Access Token:', tokens.access_token);
  console.log('Refresh Token:', tokens.refresh_token);
  console.log('Expires In:', tokens.expires_in, 'seconds');
  return tokens;
}

// Step 3: Refresh expired token
async function refreshToken(refreshToken: string) {
  const response = await fetch('https://platform.hootsuite.com/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${HOOTSUITE_CLIENT_ID}:${HOOTSUITE_CLIENT_SECRET}`).toString('base64')}`,
    },
    body: new URLSearchParams(…

Hootsuite Local Dev Loop

Overview

Set up a development workflow for Hootsuite API integrations with mocked API responses, token management, and testing.

Instructions

Step 1: Project Structure

hootsuite-integration/
├── src/
│   ├── hootsuite/
│   │   ├── client.ts       # API client with token refresh
│   │   ├── auth.ts         # OAuth 2.0 flow
│   │   ├── publishing.ts   # Message scheduling
│   │   └── analytics.ts    # Metrics retrieval
│   └── index.ts
├── tests/
│   ├── fixtures/           # Mock API responses
│   │   ├── profiles.json
│   │   └── messages.json
│   └── publishing.test.ts
├── .env.local
└── package.json

Step 2: API Client with Auto Token Refresh

// src/hootsuite/client.ts
import 'dotenv/config';

class HootsuiteClient {
  private accessToken: string;
  private refreshToken: string;
  private expiresAt: number;
  private base = 'https://platform.hootsuite.com/v1';

  constructor() {
    this.accessToken = process.env.HOOTSUITE_ACCESS_TOKEN!;
    this.refreshToken = process.env.HOOTSUITE_REFRESH_TOKEN!;
    this.expiresAt = Date.now() + 3600000;
  }

  async request(path: string, options: RequestInit = {}) {
    if (Date.now() > this.expiresAt - 60000) await this.refresh();
    const response = await fetch(`${this.base}${path}`, {
      ...options,
      headers: { 'Authorization': `Bearer ${this.accessToken}`, 'Content-Type': 'application/json', ...options.headers },
    });
    if (!response.ok) throw new Error(`Hootsuite API ${response.status}: ${await response.text()}`);
    return response.json();
  }

  private async refresh() {
    const res = await fetch('https://platform.hootsuite.com/oauth2/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Authorization': `Basic ${Buffer.from(`${process.env.HOOTSUITE_CLIENT_ID}:${process.env.HOOTSUITE_CLIENT_SECRET}`).toString('base64')}` },
      body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: this.refreshToken }),
    });
    const tokens = await res.json();
    this.accessToken = tokens.access_token;
    this.refreshToken = tokens.refresh_token;
    this.expiresAt = Date.now() + tokens.expires_in * 1000;
  }
}

export const hootsuite = new HootsuiteClient();

Step 3: Mocked Tests

// tests/publishing.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';

const mockFetch = vi.fn();
vi.stubGlobal('fetch', mockFetch);

describe('Hootsuite Publishing', () => {
  beforeEach(() => vi.clearAllMocks());

  it('should schedule a message', async () => {
    mockFetch.mockResolvedValueOnce({
      ok: true,
      json: async () => ({ data: [{ id: 'msg_123', state: 'SC…

Hootsuite Performance Tuning

Instructions

Step 1: Cache Social Profiles

import { LRUCache } from 'lru-cache';

const profileCache = new LRUCache<string, any>({ max: 100, ttl: 3600000 });

async function getCachedProfiles(): Promise<any[]> {
  const cached = profileCache.get('profiles');
  if (cached) return cached;

  const response = await fetch('https://platform.hootsuite.com/v1/socialProfiles', {
    headers: { 'Authorization': `Bearer ${await getStoredToken()}` },
  });
  const { data } = await response.json();
  profileCache.set('profiles', data);
  return data;
}

Step 2: Batch Message Scheduling

import PQueue from 'p-queue';

const scheduleQueue = new PQueue({ concurrency: 2, interval: 1000, intervalCap: 2 });

async function batchSchedule(posts: Array<{ text: string; profileId: string; time: Date }>) {
  const results = await Promise.allSettled(
    posts.map(post =>
      scheduleQueue.add(() =>
        fetch('https://platform.hootsuite.com/v1/messages', {
          method: 'POST',
          headers: { 'Authorization': `Bearer ${process.env.HOOTSUITE_ACCESS_TOKEN}`, 'Content-Type': 'application/json' },
          body: JSON.stringify({ text: post.text, socialProfileIds: [post.profileId], scheduledSendTime: post.time.toISOString() }),
        }).then(r => r.json())
      )
    )
  );
  const succeeded = results.filter(r => r.status === 'fulfilled').length;
  console.log(`Scheduled ${succeeded}/${posts.length} posts`);
}

Step 3: Connection Reuse

import { Agent } from 'https';
const agent = new Agent({ keepAlive: true, maxSockets: 5 });
// Pass agent to fetch/axios for connection reuse to platform.hootsuite.com

Overview

Tune scheduling latency and throughput through draft-only sandbox fixtures and aggregate metrics. A gain is invalid if it changes account scope, audience, approval, publication state, or rollback ability.

Prerequisites

• Baseline latency/quota metrics, draft-only fixture revision, error budget, and rollback revision for cache, concurrency, scheduling, and retry policy.

Output

Return a tuning receipt with baseline/canary bands, cache/concurrency/schedule revisions, quota/error outcomes, draft/approval assertions, owner approval, and rollback reference. Use aggregates only.

Error Handling

Roll back for quota saturation, increased errors, audience/approval drift, duplicate schedules, or a public-post path. Do not increase concurrency or cache duration to hide failure.

Examples

env=sandbox; p95=420ms->310ms; concurrency=2; schedule=r4; quota=within-budget; draft=pass; public_posts=0; rollback=perf-r3 doc…

Hootsuite Production Checklist

Overview

Hootsuite manages social media publishing, scheduling, and analytics across multiple platforms (Twitter/X, LinkedIn, Facebook, Instagram). A production integration automates post scheduling, monitors engagement, and syncs analytics. Failures mean posts go out at wrong times, media uploads get rejected, or social profile disconnections go undetected, creating gaps in your publishing calendar.

Authentication & Secrets

• [ ] HOOTSUITE_API_KEY and OAuth client secret in secrets manager
• [ ] OAuth app reviewed and approved in Hootsuite developer portal
• [ ] Token refresh logic tested with deliberately expired tokens
• [ ] Separate OAuth app for production vs development
• [ ] Key rotation schedule documented (before annual app review)

API Integration

• [ ] Production base URL configured (https://platform.hootsuite.com/v1)
• [ ] Rate limit handling with exponential backoff
• [ ] Message scheduling tested with all connected social profiles
• [ ] Media upload validated (images, video, carousel per platform)
• [ ] Character limits enforced per platform (X: 280, LinkedIn: 3000, FB: 63K)
• [ ] Timezone handling verified for scheduled posts across regions
• [ ] Social profile health check detects disconnected accounts

Error Handling & Resilience

• [ ] Circuit breaker configured for Hootsuite API outages
• [ ] Retry with backoff for 429/5xx responses
• [ ] REJECTED media states handled with user notification
• [ ] Social profile disconnection detected and alerted within 1 hour
• [ ] Scheduled post failure queued for retry (not silently dropped)
• [ ] Content moderation filter on automated posts (banned words, compliance)

Monitoring & Alerting

• [ ] API latency tracked per endpoint (publish, schedule, analytics)
• [ ] Error rate alerts set (threshold: >3% over 10 minutes)
• [ ] Token refresh failures trigger immediate notification
• [ ] Failed post scheduling reported with platform and error detail
• [ ] Engagement analytics sync monitored for completeness

Validation Script

async function checkHootsuiteReadiness(): Promise<void> {
  const checks: { name: string; pass: boolean; detail: string }[] = [];
  // API connectivity
  try {
    const res = await fetch('https://platform.hootsuite.com/v1/me', {
      headers: { Authorization: `Bearer ${process.env.HOOTSUITE_API_KEY}` },
    });
    checks.push({ name: 'Hootsuite API', pass: res.ok, detail: res.ok ? 'Connected' : `HTTP ${res.status}` });
  } catch (e: any) { checks.push({ name: 'Hootsuite API', pass: false, detail: e.message }); }
  // Credentials present
  checks.push(…

Hootsuite Rate Limits

Overview

Handle Hootsuite API rate limits. The API returns 429 Too Many Requests with Retry-After headers when limits are exceeded.

Rate Limits

Instructions

Step 1: Respect Retry-After Header

async function rateLimitedRequest(url: string, options: RequestInit = {}) {
  const response = await fetch(url, {
    ...options,
    headers: { 'Authorization': `Bearer ${process.env.HOOTSUITE_ACCESS_TOKEN}`, ...options.headers },
  });

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    console.log(`Rate limited. Retrying in ${retryAfter}s`);
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return rateLimitedRequest(url, options); // Retry
  }

  return response;
}

Step 2: Queue-Based Scheduling

import PQueue from 'p-queue';

const hootsuiteQueue = new PQueue({
  concurrency: 1,
  interval: 1000,
  intervalCap: 2, // 2 requests per second
});

async function queuedSchedule(profileId: string, text: string, time: Date) {
  return hootsuiteQueue.add(() =>
    fetch('https://platform.hootsuite.com/v1/messages', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${process.env.HOOTSUITE_ACCESS_TOKEN}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ text, socialProfileIds: [profileId], scheduledSendTime: time.toISOString() }),
    })
  );
}

Prerequisites

• An approved API budget, header baseline, draft-only sandbox profile, and bounded queue.
• Idempotency keys for mutations plus a reviewed recovery path for exhausted work.

Output

Return a rate-limit receipt with account scope, requested/limited/deferred counts, retry revision, idempotency state, queue health, draft/public assertion, and rollback reference. Exclude copy, media, handles, and credentials.

Error Handling

Stop for unknown profile, quota saturation, an attempt to replay a public mutation, or a public-post path during recovery. Defer or cancel work rather than bypassing approval or account scope.

Examples

scope=sandbox-brand; requested=100; limited=3; deferred=3; retry=v2; idempotent=pass; public_posts=0; rollback=limits-r7 proves bounded handling.

Resources

• …

Hootsuite Reference Architecture

Architecture

┌──────────────────────────────────────┐
│         Your Application              │
├──────────────────────────────────────┤
│  Content Manager → Scheduler → Publisher │
├──────────────────────────────────────┤
│      Hootsuite API Client             │
│  (OAuth, Token Refresh, Rate Limit)   │
├──────────────────────────────────────┤
│      Hootsuite REST API v1            │
│  platform.hootsuite.com/v1/           │
└──────────────────────────────────────┘

Project Structure

hootsuite-integration/
├── src/
│   ├── hootsuite/
│   │   ├── client.ts        # API client with token management
│   │   ├── auth.ts          # OAuth 2.0 flow
│   │   ├── publishing.ts    # Message scheduling + media
│   │   ├── analytics.ts     # Metrics + URL shortening
│   │   └── types.ts         # TypeScript interfaces
│   ├── services/
│   │   ├── scheduler.ts     # Content calendar logic
│   │   ├── content.ts       # Post formatting per platform
│   │   └── media.ts         # Media processing + upload
│   ├── api/
│   │   └── schedule.ts      # REST endpoint
│   └── store/
│       └── tokens.ts        # Persistent token storage
├── tests/
│   ├── unit/
│   └── fixtures/
└── .env.example

Key Decisions

Overview

This architecture separates draft creation, approval, audience validation, scoped scheduling, aggregate observability, and cancellation/rollback. Post copy and media stay inside approved publishing boundaries and never become telemetry.

Prerequisites

• A profile/account owner, audience policy, approval authority, destination allowlist, and owner for every publish edge.
• Separate sandbox/staging/production configuration and documented rollback for client, scheduler, queue, and credential controls.

Instructions

1. Map every trigger-to-profile path with owner, audience, approval state, allowed operation, idempotency, observability, and rollback.
2. Begin with draft-only sandbox fixtures and fail closed on unknown profile, audience, destination, or approval state.
3. Make scheduling idempotent and bounded; quarantine uncertainty rather than posting, resubmitting, or exporting copy for debugging.
4. Canary one draft-only profile with aggregate signals before promotion and retain the previous revision.
5. Re-evaluate contr…

Hootsuite SDK Patterns

Overview

Production patterns for Hootsuite REST API: typed client, token management, scheduling helpers, and Python integration.

Instructions

Step 1: Typed API Client

// src/hootsuite/types.ts
interface SocialProfile {
  id: string;
  type: 'TWITTER' | 'FACEBOOK' | 'INSTAGRAM' | 'LINKEDIN' | 'PINTEREST' | 'YOUTUBE' | 'TIKTOK';
  socialNetworkUsername: string;
  socialNetworkId: string;
}

interface ScheduledMessage {
  id: string;
  text: string;
  state: 'SCHEDULED' | 'SENT' | 'FAILED' | 'REJECTED';
  socialProfileIds: string[];
  scheduledSendTime: string;
  sentAt?: string;
  mediaUrls?: Array<{ id: string }>;
}

interface HootsuiteResponse<T> {
  data: T;
}

Step 2: Scheduling Helper with Timezone

function scheduleForTimezone(
  hour: number,
  minute: number,
  timezone: string,
  daysFromNow = 0
): Date {
  const date = new Date();
  date.setDate(date.getDate() + daysFromNow);
  const dateStr = date.toISOString().split('T')[0];
  const timeStr = `${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')}:00`;
  return new Date(`${dateStr}T${timeStr}`);
}

// Schedule posts at optimal times per platform
const OPTIMAL_TIMES = {
  TWITTER: { hour: 9, minute: 0 },
  INSTAGRAM: { hour: 11, minute: 0 },
  LINKEDIN: { hour: 7, minute: 30 },
  FACEBOOK: { hour: 13, minute: 0 },
};

Step 3: Python Client

# hootsuite/client.py
import os, requests, time
from dotenv import load_dotenv

load_dotenv()

class HootsuiteClient:
    BASE = 'https://platform.hootsuite.com/v1'

    def __init__(self):
        self.token = os.environ['HOOTSUITE_ACCESS_TOKEN']
        self.headers = {'Authorization': f'Bearer {self.token}', 'Content-Type': 'application/json'}

    def get_profiles(self):
        r = requests.get(f'{self.BASE}/socialProfiles', headers=self.headers)
        r.raise_for_status()
        return r.json()['data']

    def schedule_message(self, profile_ids, text, scheduled_time):
        r = requests.post(f'{self.BASE}/messages', headers=self.headers, json={
            'text': text,
            'socialProfileIds': profile_ids,
            'scheduledSendTime': scheduled_time.isoformat(),
        })
        r.raise_for_status()
        return r.json()['data']

Step 4: Cross-Platform Post Formatter

function formatPost(text: string, platform: string): string {
  const limits: Record<string, number> = {
    TWITTER: 280, FACEBOOK: 63206, INSTAGRAM: 2200, LINKEDIN: 3000, TIKTOK: 2200,
  };
  const limit = limits[platform] || 2200;
  re…

Hootsuite Security Basics

Credential Inventory

Instructions

Step 1: Secure Token Storage

# .env (never commit)
HOOTSUITE_CLIENT_ID=app_client_id
HOOTSUITE_CLIENT_SECRET=app_secret
HOOTSUITE_ACCESS_TOKEN=current_token
HOOTSUITE_REFRESH_TOKEN=refresh_token

Step 2: Token Refresh Security

// Always use HTTPS for token exchange
// Store refresh tokens encrypted at rest
// Rotate refresh tokens on each use (Hootsuite returns new ones)
async function secureRefresh(refreshToken: string) {
  const res = await fetch('https://platform.hootsuite.com/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${process.env.HOOTSUITE_CLIENT_ID}:${process.env.HOOTSUITE_CLIENT_SECRET}`).toString('base64')}`,
    },
    body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken }),
  });
  const tokens = await res.json();
  // Store new refresh_token, discard old one
  return tokens;
}

Step 3: Security Checklist

• [ ] Client secret in secrets vault, never in code
• [ ] Access tokens never logged or exposed
• [ ] Refresh tokens stored encrypted
• [ ] HTTPS for all OAuth requests
• [ ] Pre-commit hook blocks HOOTSUITE_ credential leaks
• [ ] Separate OAuth apps for dev/staging/prod

Overview

Public publishing is a high-impact boundary: credentials, profile scope, audience selection, approval state, copy, and media must all be protected. This guidance keeps draft and publication paths distinct and auditable.

Prerequisites

• A threat model naming credential custodians, account owners, approved profiles/audiences, incident owner, and secret manager.
• Low-privilege sandbox credentials, draft-only fixtures, and tested revoke/disable/cancel procedures.

Output

Return a security receipt with environment, profile scope, reference version, approval/audience validation, revocation state, correlation ID, and rollback action. Never include tokens, copy, media, or account identities.

Error Handling

Stop for unknown profile/audience, absent approval, failed signature/validation, or public-post attempt from an unapproved path. Revoke credentials or disable scheduling when int…

Hootsuite Upgrade & Migration

Overview

Hootsuite REST API is versioned at /v1/. Monitor the developer changelog for deprecations and new endpoints.

Instructions

Step 1: Check Current API Usage

# List all Hootsuite API calls in your codebase
grep -r "platform.hootsuite.com" src/ --include="*.ts" --include="*.py"

Step 2: Migration Patterns

// If Hootsuite introduces v2 endpoints:
// BEFORE
const response = await fetch('https://platform.hootsuite.com/v1/messages', ...);
// AFTER
const API_VERSION = process.env.HOOTSUITE_API_VERSION || 'v1';
const response = await fetch(`https://platform.hootsuite.com/${API_VERSION}/messages`, ...);

Step 3: Social Network Changes

When Hootsuite adds/removes social network support:

const SUPPORTED_NETWORKS = ['TWITTER', 'FACEBOOK', 'INSTAGRAM', 'LINKEDIN', 'PINTEREST', 'YOUTUBE', 'TIKTOK'] as const;
type SocialNetwork = typeof SUPPORTED_NETWORKS[number];

Prerequisites

• Pinned current/target versions, compatibility assessment, draft-only fixtures, and an owner for changed account or scheduling contracts.
• Versioned configuration backups plus approved downgrade, schedule-cancel, and integration-disable procedures.

Output

Produce an upgrade receipt with from/to versions, affected contracts, fixture/draft-canary outcomes, approval/audience assertions, owner approval, compatibility decision, and rollback revision. Exclude copy, media, account identities, and credentials.

Error Handling

Stop for incompatible scheduling/approval contracts, account-scope drift, unbounded replay, or a draft-canary that reaches a public path. Restore the pinned prior revision rather than forcing migration.

Examples

from=client-r12; to=client-r13; sandbox=pass; staging=pass; draft=pass; public_posts=0; rollback=r12 is a defensible upgrade record.

Resources

• Hootsuite Developer Changelog
• API Guides

Next Steps

For CI, see hootsuite-ci-integration.

Hootsuite Webhooks & Events

Overview

Hootsuite provides webhook notifications for social stream events when building Hootsuite App Directory integrations. For API-only integrations, you poll for message state changes or implement your own scheduling system with callbacks.

Instructions

Step 1: Poll for Message Status Changes

// Since Hootsuite REST API doesn't push webhooks for message status,
// poll for changes to scheduled messages
async function pollMessageStatus(messageId: string, intervalMs = 30000) {
  const check = async () => {
    const response = await fetch(`https://platform.hootsuite.com/v1/messages/${messageId}`, {
      headers: { 'Authorization': `Bearer ${await getStoredToken()}` },
    });
    const { data } = await response.json();

    if (data.state === 'SENT') {
      console.log(`Message ${messageId} sent at ${data.sentAt}`);
      return data;
    } else if (data.state === 'FAILED' || data.state === 'REJECTED') {
      console.error(`Message ${messageId} failed: ${data.state}`);
      return data;
    }

    console.log(`Message ${messageId}: ${data.state}, checking again...`);
    await new Promise(r => setTimeout(r, intervalMs));
    return check();
  };

  return check();
}

Step 2: Build Custom Scheduling Webhook

// Your own webhook system to track scheduled post status
import express from 'express';

const app = express();
app.use(express.json());

// Cron job checks scheduled posts and fires webhooks
async function checkScheduledPosts() {
  const response = await fetch('https://platform.hootsuite.com/v1/messages?state=SENT&limit=50', {
    headers: { 'Authorization': `Bearer ${await getStoredToken()}` },
  });
  const { data } = await response.json();

  for (const msg of data) {
    // Notify your systems about sent posts
    await fetch(process.env.INTERNAL_WEBHOOK_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ event: 'post.sent', messageId: msg.id, sentAt: msg.sentAt, text: msg.text }),
    });
  }
}

Step 3: Hootsuite App Directory Webhooks

For apps listed in the Hootsuite App Directory, you receive stream events:

// Webhook handler for Hootsuite App Directory integration
app.post('/webhooks/hootsuite', async (req, res) => {
  const { type, data } = req.body;
  switch (type) {
    case 'message.sent': console.log('Post sent:', data); break;
    case 'message.failed': console.error('Post failed:', data); break;
    case 'stream.message': console.log('New social message:', data); break;
  }
  res.status(200).json({ received: true });
});

Prerequisites

…