Developer & Architecture Guide

Third-Party API Setup & Permission Acquisition Guide

Comprehensive zero-to-hero manual for developers: From registering Business Portals and creating Developer Apps, to generating Permanent Access Tokens, submitting for App Reviews, configuring Webhooks, and connecting with CtrlTasq.

Language:

Standalone HTML QA Testing Manual

Master Server URLs & Callback Endpoints

OAuth 2.0 Redirect URI (For FB, IG, LinkedIn, Twitter, Pinterest, YouTube, Google)

https://ctrltasq.com/social/callback

Meta / WhatsApp Webhook Callback URL

https://ctrltasq.com/whatsapp/webhook

https://ctrltasq.com/privacy-policy

User Data Deletion Callback URL

https://ctrltasq.com/user-data-deletion

Choose Platform Developer Setup

11 Complete Walkthroughs

WhatsApp Business Cloud API (Official Meta Platform)

Direct integration with Meta Graph API for official message templates, green badge support, automated drip triggers, and incoming message webhooks.

1 Create a Meta Developer Account & Business Portfolio

Before touching the API, you must have a registered Meta Business Account:

Open business.facebook.com and log in with your primary Facebook account.
If you don't have a Business Portfolio, click Create a Business Account, enter your legal company name, business email, and address.
Open developers.facebook.com → Click Get Started / Log In → Complete developer registration.

2 Create a Meta Developer App

Navigate to developers.facebook.com/apps → click Create App.
Under "What do you want your app to do?", select Other → Click Next.
Select App Type: Business → Click Next.
Enter App Name (e.g. CtrlTasq WhatsApp Gateway), enter your contact email, and select your Meta Business Account.
Click Create App and enter your Facebook password to confirm.

3 Add WhatsApp Product & Get Phone Number ID & WABA ID

On the App Dashboard, scroll down to "Add products to your app" → Find WhatsApp and click Set Up.
In the left sidebar, click WhatsApp > API Setup.
Here you will see:
- Phone Number ID (e.g. 104829102938192) → Copy this.
- WhatsApp Business Account ID (WABA ID) (e.g. 102938475610293) → Copy this.
Adding a Real Live Phone Number:
- Under Step 5 ("Add a phone number"), click Add Phone Number.
- Enter your Business Display Name, Category, and Business Description.
- Enter a phone number (Must NOT be currently registered on WhatsApp personal/business mobile app. If it is, delete the account inside WhatsApp mobile app first).
- Verify via SMS or Voice Call OTP.

4 Generate a Permanent (Never-Expiring) System User Token

Critical Developer Step: The token on the API Setup page expires in 24 hours. You MUST create a System User to get a permanent token that never expires!

Go to Meta Business Settings.
In the left sidebar, go to Users > System Users → Click Add.
Enter System Username: ctrltasq-api-user, Role: Admin → Click Create System User.
Click Add Assets → Select Apps → Choose your WhatsApp App → Toggle Full Control (Manage App) → Save.
Click Generate New Token → Select your WhatsApp App.
Check the following permission scopes:
whatsapp_business_messaging whatsapp_business_management
Token expiration: Select Never → Click Generate Token → Copy and save this token securely (it will only be shown once!).

5 Configure Real-Time Incoming Webhooks

In Meta Developer Portal, go to WhatsApp > Configuration (left sidebar).
Under Webhook, click Edit:
- Callback URL:
  https://ctrltasq.com/whatsapp/webhook
- Verify Token: Enter a secret random token string of your choice (e.g. CtrlTasq_Verify_Secure_2026).
Click Verify and Save. Meta will send a GET challenge to your webhook endpoint to verify it.
Under Webhook Fields, click Manage → Find messages → Click Subscribe.

6 Paste Credentials into CtrlTasq

WABA_ID = "YOUR_WHATSAPP_BUSINESS_ACCOUNT_ID"
PHONE_NUMBER_ID = "YOUR_PHONE_NUMBER_ID"
ACCESS_TOKEN = "YOUR_PERMANENT_SYSTEM_USER_TOKEN"
WEBHOOK_VERIFY_TOKEN = "YOUR_CONFIGURED_VERIFY_TOKEN"

7 Chatbot Webhook Ingestion & Automated Flow Engine

When a customer sends a WhatsApp message, the webhook payload is ingested and processed through the following architectural pipeline:

Data Processing Pipeline:

Meta Webhook Ingestion: Incoming POST /whatsapp/webhook payload parsed for entry[0].changes[0].value.messages[0].
Tenant Resolution: The recipient phone_number_id is matched against user_social_accounts (or platform_api_config) to identify the specific user tenant.
Bot Keyword Match: The inbound text string is sanitized and matched against active bots in tbl_wa_chatbots (matching exact words, comma-separated triggers, or default catch-all).
Interactive Message Dispatch: A POST https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/messages request is dispatched with the bot's configured reply text, quick-reply buttons, or dynamic links.
Conversation & CRM Sync:
- The inbound customer message and outbound bot reply are logged into tbl_wa_messages.
- The customer contact is upserted into tbl_wa_contacts.
- A new lead deal is auto-created in crm_leads and assigned to the user's active sales pipeline!

Sample Inbound Webhook Payload Schema:

{ "object": "whatsapp_business_account", "entry": [{ "id": "102938475610293", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "+91XXXXXXXXXX", "phone_number_id": "104829102938192" }, "contacts": [{ "profile": { "name": "Rahul Sharma" }, "wa_id": "919876543210" }], "messages": [{ "from": "919876543210", "id": "wamid.HBgLMOTE5ODc2NTQzMjEwFQIAEhgWM0VCMDE...", "timestamp": "1725984000", "text": { "body": "Need pricing for 2 BHK" }, "type": "text" }] }, "field": "messages" }] }] }

Common Failures, Error Codes & Solutions:

Error 131030 (Recipient phone number not in allowed list): App is in "Development Mode". You must either add the recipient number under "To" in API Setup, or complete Business Verification to go Live.
Error 190 (Invalid OAuth Access Token): You used the 24-hour temporary token instead of creating a Permanent System User Token in Business Settings.
Error 132000 (Template does not exist): Outbound broadcast template has not been approved by Meta yet, or language code mismatch (e.g. en_US vs en).
Webhook Verification Error: Ensure your WEBHOOK_VERIFY_TOKEN configured in Meta matches the token expected by your server script.

Facebook Pages & Groups (Meta Graph API)

Feed publishing, media upload, native scheduling, and insight analytics for Facebook Business Pages and Administered Groups.

📋 Prerequisites Checklist:

#	Prerequisite	How to verify
1	Facebook Business Page exists	Go to facebook.com/pages — confirm you see at least 1 Page listed. If not, create one at facebook.com/pages/create.
2	You have Admin/Content access	Open your Page → Settings → Page Access → confirm your account is listed with Full Control or Content creation access.
3	Meta App Roles (if in Dev Mode)	Go to developers.facebook.com → Your App → App Roles → Roles → ensure your Facebook user account is added as Admin, Developer, or Tester.

1 Create Business App in Meta Developer Dashboard

Go to developers.facebook.com/apps → Click Create App.
Select Other → Select App Type: Business.
Name your app (e.g. CtrlTasq Social Hub) and link your Business Account.

2 Configure Facebook Login for Business

Under Products → click Set Up on Facebook Login for Business.
Go to Facebook Login > Settings (left sidebar).
Enable: Client OAuth Login, Web OAuth Login.
Under Valid OAuth Redirect URIs, paste:
https://ctrltasq.com/social/callback
Click Save Changes.
Go to App Settings > Basic → Copy App ID and App Secret.

3 Required Permission Scopes & OAuth Configuration

pages_show_list pages_read_engagement pages_manage_posts publish_video read_insights publish_to_groups public_profile

In Development Mode, any user listed under App Roles (Admin/Tester) can connect without Meta review. For public production users, submit permissions for Meta App Review with a 2-minute video screencast.

OAuth Architecture (Forcing Page Re-selection):

Always include auth_type: 'rerequest' in the authorization dialog params. Without this parameter, Meta caches previous grants and silently skips the "Which Pages do you want to use?" dialog on subsequent connections.

Developer Troubleshooting & Meta API Errors:

Why "Which Pages do you want to use" was skipped: User has previously authorized the app. Fix by adding auth_type=rerequest or having the user remove the app in Facebook Settings > Business Integrations.
Error 200 (Permissions error): Person logging in is not an Admin/Editor of the Facebook Page, or unchecked required scopes during OAuth dialog.
Error 190 (Invalid / Expired OAuth Token): User changed their Facebook password, deauthorized the app, or the 60-day long-lived user token expired. Re-authenticate via /social/connect/facebook.
Error 100 (Unsupported post request): Target Facebook Page ID is invalid or missing from the user's token permissions.

Instagram Business & Creator Integration

Instagram Graph API setup for feed posts, carousel albums, reels, and analytics.

1 Convert Account & Link to Facebook Page

Mandatory Requirement: Meta Graph API cannot connect personal Instagram accounts. It MUST be a Professional Account linked to a Facebook Page.

Open Instagram app on phone → Settings > Account > Switch to Professional Account (Select Business).
Open your Facebook Page on desktop → Settings > Linked Accounts > Instagram → Click Connect Account and log in.

2 Add Instagram Graph API to Meta Developer App

In your existing Meta Developer App, click Add Product → Set Up Instagram Graph API.
Scopes:
instagram_basic instagram_content_publish instagram_manage_comments instagram_manage_insights
OAuth Redirect URI: https://ctrltasq.com/social/callback.

LinkedIn Business & Company Pages (Community Management API)

Publishing to corporate organization feeds, showcase pages, and corporate engagement analytics.

1 Create Developer App on LinkedIn Portal

Go to linkedin.com/developers/apps → Click Create App.
Enter App Name, associate your official verified LinkedIn Company Page URL, and upload an app logo.
Agree to legal terms → Click Create App.

2 Request Community Management API Access

Navigate to the Products tab inside your app.
Find Community Management API → Click Request Access.
Complete LinkedIn's use-case questionnaire explaining that your SaaS publishes scheduled marketing updates to company pages.
Also add Sign In with LinkedIn using OpenID Connect product.

3 Configure OAuth Redirect URI & Scopes

Under Auth tab → Authorized redirect URLs for your app:
https://ctrltasq.com/social/callback
Copy Client ID and Client Secret into CtrlTasq Admin Settings.
Organization Scopes Granted:
w_organization_social r_organization_social rw_organization_admin

LinkedIn Personal Profiles (Share on LinkedIn)

Publishing thought leadership posts, articles, and media to personal LinkedIn member feeds.

1 Setup Share on LinkedIn Product

In LinkedIn Developer Portal, open your app.
Under Products tab → Add Share on LinkedIn (Instant access, no review needed).
Under Products tab → Add Sign In with LinkedIn using OpenID Connect.
Personal Scopes: openid profile email w_member_social
Redirect URI: https://ctrltasq.com/social/callback

Twitter / X Developer Portal (v2 API & OAuth 2.0 PKCE)

Posting tweets, threads, media attachments, and automated dispatch via X API v2.

1 Create Project & App in X Developer Portal

Sign in to developer.x.com → Subscribe to Free or Basic API tier.
Create a Project and create an App inside it.
Go to App Settings > User authentication settings → Click Edit / Set Up:
- App Permissions: Select Read and write.
- Type of App: Select Web App, Automated App or Bot.
- Callback URI / Redirect URL:
  https://ctrltasq.com/social/callback
- Website URL: https://ctrltasq.com
Save settings → Under Keys and Tokens, copy OAuth 2.0 Client ID and Client Secret.

Telegram Bot API (Instant 2-Minute Setup)

No approval delay. Direct bot token generation via Telegram BotFather.

1 Create Bot via @BotFather

Open Telegram and search for @BotFather.
Send command: /newbot.
Enter Bot Name (e.g. CtrlTasq Notifier) and username ending in bot (e.g. ctrltasq_notifier_bot).
BotFather returns your HTTP API Token:
7123456789:AAFlxyz...
Add your bot as an Administrator in your Channel or Group with "Post Messages" permission.
On /social, enter the Bot Token and Channel Handle (e.g. @mychannel).

Pinterest Business (v5 REST API)

Creating pins, syncing boards, media upload, and platform-side scheduling.

1 Register App in Pinterest Developer Portal

Go to developers.pinterest.com/apps with a Pinterest Business account.
Click Connect App → Enter App Name & Description.
Under Redirect URIs, add: https://ctrltasq.com/social/callback.
Copy App ID and App Secret Key.
Scopes: boards:read boards:write pins:read pins:write

YouTube Data API v3 (Google Cloud Platform)

Uploading YouTube Shorts, scheduling video broadcasts, and analytics.

1 Google Cloud Project & API Enablement

Go to console.cloud.google.com → Create a New Project.
Go to APIs & Services > Library → Search and Enable: YouTube Data API v3.
Configure OAuth Consent Screen: Select External, add your Support Email & App Name.
Add Scopes: https://www.googleapis.com/auth/youtube.upload https://www.googleapis.com/auth/youtube.readonly
Go to Credentials > Create Credentials > OAuth Client ID:
- Application Type: Web application.
- Authorized redirect URIs: https://ctrltasq.com/social/callback
Copy Client ID and Client Secret into CtrlTasq Google API settings.

Google Business Profile (GMB API)

Publish local business updates, promotional offers, event announcements, and call-to-action buttons directly to Google Maps and Google Search listings.

What Can You Do With Google Business Profile Integration?

Local SEO Posts: Publish "What's New" updates directly visible on Google Maps & Search results.

Promotional Offers: Share discount coupon codes, seasonal sales, terms, and redemption links.

Event Announcements: Broadcast start/end times and direct registration URLs.

Actionable CTAs: Embed buttons like Book, Order Online, Shop, Learn More, Sign Up, Call Now.

Multi-Location Sync: Auto-discover all locations linked to your Google Business Account.

Centralized Scheduling: Schedule local business updates simultaneously alongside FB, IG, and LinkedIn.

1 Google Cloud Project & Enable Required APIs

Create or select a Google Cloud Project in Google Cloud Console:

Navigate to console.cloud.google.com and sign in with the Google Account that manages your Business Profile.
Create a new project (e.g. CtrlTasq Business Hub) or select an existing project.
Go to APIs & Services > Library.
Search and Enable all of the following APIs:
- Business Profile Performance API (for local post metrics & interactions)
- My Business Account Management API (for discovering accounts and listing ownership)
- My Business Business Information API (for location details, address, and category)

2 Configure OAuth Consent Screen

Set up the consent screen so users and admins can authorize their Google accounts:

Go to APIs & Services > OAuth consent screen.
Select User Type: External → Click Create.
Fill in the mandatory fields:
- App Name: CtrlTasq Marketing Automation
- User support email: Your company contact email
- Authorized domain: ctrltasq.com
- Developer contact email: Your developer email
Click Save and Continue to advance to Scopes.
Click Add or Remove Scopes and select the following scopes:
https://www.googleapis.com/auth/business.manage https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid
Click Save and Continue. If your app is in Testing mode, add your Google email under Test Users.

3 Create OAuth 2.0 Client Credentials

Generate the Client ID and Client Secret for secure OAuth 2.0 handshake:

Go to APIs & Services > Credentials.
Click + Create Credentials → Select OAuth client ID.
Configure the client:
- Application type: Web application
- Name: CtrlTasq GMB Web Client
- Authorized JavaScript origins: https://ctrltasq.com
- Authorized redirect URIs:
  https://ctrltasq.com/google-business/callback
  
  https://ctrltasq.com/social/callback
  Adding /google-business/callback prevents Apache Mod_Security false-positive blocks.
Click Create. A modal will display your Client ID and Client Secret.

4 Store Credentials in CtrlTasq Admin Panel

Save your API keys so users can connect their Google Business Profile seamlessly:

Log in to CtrlTasq Admin Panel → Navigate to Platform API Configuration (/admin/platform-api).
Click Add Platform Configuration.
Set Platform to: google_my_business.
Paste your Client ID into the App ID / Client ID field.
Paste your Client Secret into the App Secret / Client Secret field.
Ensure Status is set to Active and save.

5 Connect & Publish on CtrlTasq

Go to ctrltasq.com/social.
Locate the Google Business platform card and click Connect Account.
Grant permissions on Google's prompt. Upon return, your business name and locations count will show as Connected.
Navigate to Create Post (/social/createPost), check Google Business, write your update, choose an action button (e.g. Learn More or Call), and click Post Now or Schedule!

Google Business Profile Troubleshooting

403 Access Not Configured: Ensure both Business Profile Performance API and My Business Account Management API are enabled in the Google Cloud Console.
No Locations Found: Make sure the Google account you authorized is an Owner or Manager of a verified Google Business listing in business.google.com.
OAuth Verification Warning: In Testing status, ensure your Google email is listed under Test Users in the OAuth Consent Screen. For production public use, submit your app for Google Verification.

Snapchat Marketing & Decentralized Fediverse

Snapchat Creative Kit, Bluesky AT Protocol, and Mastodon ActivityPub posting.

1 Snapchat Marketing API

Open business.snapchat.com → Developer Apps → Create App.
Redirect URI: https://ctrltasq.com/social/callback.

2 Bluesky AT Protocol & Mastodon

Bluesky generates App Passwords via bsky.app/settings/app-passwords. Mastodon generates user tokens via instance OAuth.