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

13 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" }] }] }

7 Website Floating Chatbot Widget & Client-Side Embed API

Zero Dependencies (<5KB)

Allow external client websites (WordPress, Shopify, Webflow, custom HTML) to integrate with your Ctrl TASQ WhatsApp chatbot engine. When website visitors click the floating widget, it initiates a User-Initiated Conversation with a pre-filled trigger keyword, automatically granting opt-in consent and opening a free 24-hour interactive service session.

1. Embed Tag Syntax (HTML / WordPress / CMS):

<script src="https://ctrltasq.com/assets/js/whatsapp-widget.js" data-phone="919876543210" data-trigger="hi" data-title="Chat with our Support Bot" data-subtitle="Online • Instant Replies ⚡" data-greeting="👋 Hello! Click below to start chatting with our automated bot on WhatsApp." data-color="#25D366" data-position="right" data-btn-text="Start Chat on WhatsApp"></script>

2. JavaScript SDK Configuration Attributes:

Attribute	Required	Default	Description
`data-phone`	Yes	`-`	Meta WABA phone number (country code + number without symbols, e.g. `919876543210`).
`data-trigger`	No	`hi`	Pre-filled trigger text sent by visitor that launches the corresponding bot flow or blueprint.
`data-title`	No	`Chat with Us`	Card header title.
`data-subtitle`	No	`Online • Replies instantly ⚡`	Sub-header status badge.
`data-greeting`	No	`👋 Hi there! How can we assist you today? ...`	Teaser message displayed inside popup before opening WhatsApp.
`data-color`	No	`#25D366`	Brand theme color hex code.
`data-position`	No	`right`	Floating button dock alignment (`right` or `left`).

Meta Policy & Opt-In Compliance Note: Because the visitor actively initiates the conversation via the wa.me protocol, the interaction complies with Meta Business messaging policies and GDPR explicit opt-in requirements. The incoming message opens a 24-hour free customer care window where all interactive bot buttons, menus, and flow nodes operate without requiring paid template message pre-approvals.

Common Failures, Meta Error Codes & Architecture Solutions:

Phone Number "Pending" State (Messages accepted by API but not delivered to phone): Newly added numbers require 6-digit PIN registration via the Meta Cloud API endpoint:
POST https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/register with body {"messaging_product":"whatsapp","pin":"123456"}.
→ Solution: In Ctrl TASQ Hub, click "Register / Activate Phone (PIN)" to activate immediately.
Error #132001 (Template does not exist in translation / Language mismatch): The requested template name does not exist on Meta WABA or was created under a different language code.
→ Solution: In Ctrl TASQ, click "Sync from Meta" under Template Studio to sync real approved templates and valid language codes.
Marketing Template Delivery Hold (Meta Billing Rule): Unlike Utility/Service templates which deliver freely, Meta requires an active Payment Method (Credit/Debit Card) on the Meta Business Account or a positive platform credit balance to route Marketing messages to Indian mobile numbers.
→ Solution: Use Ctrl TASQ's in-app "Pricing & Billing" modal or /omnichannel/billing to top up credits without navigating Meta developer menus.
Error 131030 (Recipient not in allowed list): Sandbox restriction when using Meta's temporary test number. Add recipient number in Meta Developer Console > API Setup > "To" dropdown.
Error 190 (Invalid OAuth Token): Token has expired. Ensure the platform master token is configured in Admin API settings.

Meta Catalog API (`catalog_management`) & WhatsApp Commerce

Complete integration guide for Meta Commerce Manager catalogs, Server-to-Server System User Token management, 1-click WhatsApp storefront linking, and passing Meta App Review.

System Architecture: Server-to-Server System User Token vs. Client OAuth

Unlike consumer Facebook Login apps, CtrlTasq Catalog Integration operates as a robust Server-to-Server (S2S) Architecture. Business accounts authenticate via a permanent System User Access Token generated in Meta Business Suite. All catalog mutations (Product Add, Edit, Delete, Stock Update) and WhatsApp Storefront associations are executed securely server-side via Meta Graph API (v22.0).

1 Create a Product Catalog in Meta Commerce Manager

Open business.facebook.com/commerce and select your Business Portfolio.
Click Add Catalog → Select Ecommerce (Products) → Click Next.
Select Upload Product Info → Assign Catalog Owner (your business) → Enter Catalog Name (e.g. CtrlTasq Main Catalog).
Click Create. Copy your Catalog ID from Commerce Manager → Catalogs → Settings → Catalog Info.

2 Generate System User Token with Required Permissions

Go to Meta Business Settings → Users > System Users.
Click Add → Name: ctrltasq-catalog-user → Role: Admin.
Click Add Assets → Select Catalogs → Choose your Catalog → Enable Manage Catalog (Full Control) → Save.
Click Add Assets → Select Apps → Choose your Meta App → Enable Manage App (Full Control) → Save.
Click Generate New Token → Select your Meta App → Set Expiration to Never.
Select the required permission scopes:
catalog_management business_management whatsapp_business_management whatsapp_business_messaging
Copy the generated access token securely.

3 Meta Graph API Endpoints Implemented in CtrlTasq

CtrlTasq's CatalogController.php executes standard Graph API v22.0 requests:

Operation	HTTP Method & Endpoint	Key Parameters / Payload
Fetch Products	`GET /v22.0/{catalog_id}/products`	`fields=id,name,description,price,currency,retailer_id,image_url,url,availability,condition`
Add / Sync Item	`POST /v22.0/{catalog_id}/products`	`name, description, price (in cents), currency, retailer_id, url, link, image_url, availability, condition`
Update Item	`POST /v22.0/{product_id}`	`name, price, description, url, availability ('in stock' / 'out of stock')`
Delete Item	`DELETE /v22.0/{product_id}`	`access_token`
Link to WhatsApp	`POST /v22.0/{phone_number_id}/whatsapp_commerce_settings`	`is_cart_enabled=true, is_catalog_visible=true, access_token`

4 Smart WebScraper Architecture (`WebScraperService.php`)

CtrlTasq features a universal extractor that crawls websites and transforms raw HTML or JSON APIs into Meta-ready catalog items:

1. Multi-Page Pagination Crawler:

findPaginationUrls() inspects pagination DOM elements (.pagination a, .page-link, ?page=N) and automatically crawls pages 1 through N, merging and deduplicating up to 100+ items across the entire website catalog in a single click.

2. Dynamic SPA / AJAX JSON Sniffer:

extractDynamicPortalData() detects client-side rendered portals (e.g. MyAssetsHub, Next.js __NEXT_DATA__) and executes direct subrequests to internal JSON endpoints (/listing and /services) to extract complete structured records including real estate specs and consultant credentials.

3. Priority Link Scoring Engine:

extractBestLinkFromNode() scores anchor tags inside repeating cards. It prioritizes eye icons (<i class="fa fa-eye">), "View Details" / "Book Now" buttons, and title anchors while filtering out wishlist triggers (#), category links, and social shares.

4. "Ask for Price" & Graph API Attribute Mapping:

Meta Graph API requires url for the clickable Product Link attribute and integer cents for price. Items without a fixed price are mapped to nominal ₹1 (100 cents) with "Price: Contact Us / Ask for Quote" prepended to the description.

5 WhatsApp Chatbot Interactive Catalog (SPM, MPM & Order Webhooks)

How CtrlTasq chatbots and live chats dispatch native interactive catalog messages via WhatsApp Cloud API:

A. Single-Product Message (SPM) Payload:

POST https://graph.facebook.com/v22.0/{PHONE_ID}/messages { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "919876543210", "type": "interactive", "interactive": { "type": "product", "body": { "text": "Here are the details for your requested property:" }, "footer": { "text": "Ctrl TASQ Real Estate" }, "action": { "catalog_id": "1009804198892622", "product_retailer_id": "url_1789564495_aea2de" } } }

B. In-Chat Customer Order Webhook Event:

// Inbound Webhook Event when customer clicks "Send Order" { "messages": [{ "from": "919876543210", "type": "order", "order": { "catalog_id": "1009804198892622", "text": "Please confirm my order for immediate delivery.", "product_items": [ { "product_retailer_id": "url_1789564495_aea2de", "quantity": 1, "item_price": "6400000.00", "currency": "INR" } ] } }] }

6 1-Click WhatsApp Storefront & In-Chat Cart Automation

When a user clicks "Sync & Link Catalog to WhatsApp" on /catalog, CtrlTasq performs a dual-binding pipeline:

Phone Number Commerce Binding: Dispatches POST https://graph.facebook.com/v22.0/{phone_number_id}/whatsapp_commerce_settings enabling is_cart_enabled and is_catalog_visible.
WABA Catalog Association: Dispatches POST https://graph.facebook.com/v22.0/{waba_id}/whatsapp_commerce_settings with catalog_id to attach the catalog to the WABA portfolio.
WhatsApp Client Activation: WhatsApp immediately displays the Shopping Bag Icon on the business chat header, enabling customers to browse items and submit orders in-chat.

// Sample WhatsApp Commerce Settings Call $payload = [ 'is_cart_enabled' => 'true', 'is_catalog_visible' => 'true', 'access_token' => $accessToken ]; POST https://graph.facebook.com/v22.0/104829102938192/whatsapp_commerce_settings

Meta App Review Blueprint: Passing `catalog_management`

Developer Policy 1.6 & Screencast Compliance: Meta reviewers reject submissions if the screencast does not explain that authentication is Server-to-Server (System User Token) or fails to show the end-to-end sync to Meta Commerce Manager.

Submission Notes (Copy & Paste into Meta Developer Dashboard):

1. How will your app use catalog_management?

"CtrlTasq is a multi-channel business automation and WhatsApp communication suite. We use the catalog_management permission to allow business owners to create, update, manage, and delete product catalog items directly from our unified dashboard, and automatically link their catalog to their WhatsApp Business Account for in-chat shopping and customer catalog orders."

2. Note to Reviewer (Server-to-Server System User Token Notice - CRITICAL):

"NOTE TO REVIEWER (Server-to-Server Integration): Our application integrates via Meta Business System User Access Tokens rather than a client-side Facebook Login popup. Business owners generate their permanent System User Access Token in Business Settings with catalog_management and paste it in our Catalog Setup settings. All product CRUD operations and WhatsApp storefront settings are executed server-to-server."

3. Screencast Video Recording Script (2-3 Minutes):

Scene 1 (Login): Start recording at https://ctrltasq.com/login and log into the test account.
Scene 2 (Setup): Open /catalog/setup. Show Catalog ID and System User Token input fields. Click "Sync & Link Catalog to WhatsApp" to show the live green badge.
Scene 3 (Product CRUD): Go to /catalog. Click "Add Product", enter title (e.g. "Denim Jacket"), price (₹1,499), description, and upload an image. Click Save.
Scene 4 (Meta Verification): Switch browser tab to Meta Commerce Manager > Catalogs > Items. Refresh the page and show that the newly added product is live in Meta Commerce Manager!

Common Catalog API Error Codes & Fixes:

Error 200 (Permission Denied / (#200) Requires catalog_management): The access token was generated without the catalog_management scope or the system user has not been granted Asset permissions to the catalog in Business Settings.
Error 100 (Invalid Parameter / price must be integer in cents): Meta API requires currency amounts in cents/paise (e.g. ₹500.00 = 50000). CtrlTasq handles this multiplication automatically.
Subcode 2018001 (Catalog not found): Verify that the Catalog ID entered in /catalog/setup belongs to the same Meta Business Portfolio that owns the System User.
WhatsApp Storefront Not Visible: Ensure both is_catalog_visible=true and is_cart_enabled=true are sent to /{phone_number_id}/whatsapp_commerce_settings, and the WhatsApp phone number is verified.

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. What Can You Upload / Post to Google Business?

Content Type	Requirements & Best Practices	Example
Post Description / Text	• 100 to 1,500 characters. • Clear message with news, offers, updates, or announcements.	"We are excited to launch our new AI automation tools! Visit our website to explore features."
Images (Photos)	• Format: JPG or PNG. • Recommended size: 720px × 540px (4:3 aspect ratio, min 250×250). • File size: between 10 KB and 5 MB. • Must be clear, high-quality, and relevant to the business.	Storefront photo, promotional banner, product photo, service flyer.
Videos	• Format: MP4, MOV, AVI, etc. • Length: up to 30 seconds. • Resolution: 720p or higher. • File size: up to 75 MB.	15–30 sec product demo, facility tour, announcement video.
Call to Action (CTA Button)	• Direct link button displayed under the post on Google Maps. • Button types: `BOOK`, `ORDER`, `SHOP`, `LEARN_MORE`, `SIGN_UP`, `CALL`. • Requires a valid destination URL (e.g. `https://yourwebsite.com/booking`).	Button: Learn More URL: `https://ctrltasq.com/pricing`

2. The Complete End-to-End Architecture Flow

1. Connect Google

/social dashboard

→

2. OAuth 2.0 Grant

business.manage

→

3. Auto-Discovery

Verified Locations

→

4. Live Google Post

Google Search & Maps

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/social/callback
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.

Next-Gen Two-Tier Ticketing & WhatsApp Helpdesk APIs

Enterprise API specifications for Platform Support (Tier 1), End-Customer WhatsApp Ingestion (Tier 2), Dual-Mode Reply, SLA Timers, and Audio Voice Memos.

1 Two-Tier Ticketing Architecture

Ctrl TASQ separates ticketing operations into two specialized tiers sharing a unified database schema:

Tier 1: Platform Support Desk

Ctrl TASQ Business User ↔ Super Admin Support Team.

Raised at /ticket or /support
Categories: Technical, WhatsApp API, Billing, Feature Requests
Super Admin views at /admin/tickets & /admin/ticket/view/{id}
In-browser voice memo recording & SLA aging tracking

Tier 2: End-Customer Helpdesk

Ctrl TASQ Business User ↔ Their End WhatsApp Customers.

1-Click Message-to-Ticket from WhatsApp inbox
Automated triage on keywords: complaint, refund, urgent, broken
Emoji trigger: Reacting with 🎫 spawns a tracked ticket
Two-way WhatsApp sync: Customer replies auto-append to thread

2 Tier 1 API: Create Support Ticket

Submits a new ticket with optional file and in-browser voice memo attachments.

POST /ticket/ajax-create

POST /ticket/ajax-create HTTP/1.1 Content-Type: multipart/form-data; boundary=----WebKitFormBoundary... ------WebKitFormBoundary... Content-Disposition: form-data; name="subject" WhatsApp Cloud API Webhook intermittent failure ------WebKitFormBoundary... Content-Disposition: form-data; name="category" whatsapp_api ------WebKitFormBoundary... Content-Disposition: form-data; name="priority" high ------WebKitFormBoundary... Content-Disposition: form-data; name="description" Incoming webhook drops messages when payload exceeds 256KB. ------WebKitFormBoundary... Content-Disposition: form-data; name="voice_recording"; filename="voice_memo.webm" Content-Type: audio/webm [Binary Audio Data] ------WebKitFormBoundary... Content-Disposition: form-data; name="attachment"; filename="debug_error.log" Content-Type: text/plain [Binary File Data] ------WebKitFormBoundary...--

Success Response (200 OK):

{ "status": "success", "message": "Ticket created successfully! Our team will respond shortly.", "ticket_id": 142, "ticket_number": "TCK-20261022-8941" }

3 Tier 1 API: Append Ticket Reply (User / Admin)

Adds a response to an active ticket. Supports text, audio voice recording, and file attachments.

POST /ticket/ajax-reply

POST /ticket/ajax-reply HTTP/1.1 Content-Type: multipart/form-data ticket_id: 142 message: "Here is the additional server log you requested." voice_recording: [Blob: audio/webm] attachment: [File: trace.pdf]

Success Response (200 OK):

{ "status": "success", "message": "Reply posted successfully.", "ticket_id": 142, "message_data": { "sender_type": "user", "message": "Here is the additional server log you requested.", "voice_recording": "/uploads/tickets/voice_142_user_1729601234.webm", "attachment": "/uploads/tickets/att_142_user_1729601234.pdf", "created_at": "2026-10-22 16:30:00" } }

4 Tier 1 API: Fetch Real-Time Ticket Thread

Retrieves ticket metadata, SLA aging status, and full conversation timeline.

GET /ticket/ajax-details/{id}

{ "status": "success", "ticket": { "id": 142, "ticket_number": "TCK-20261022-8941", "subject": "WhatsApp Cloud API Webhook intermittent failure", "status": "In Progress", "priority": "High", "category": "WhatsApp API", "voice_recording": "/uploads/tickets/voice_142_1729601000.webm", "aging_hours": 3.4, "sla_badge": " 3.4h (Within SLA)" }, "messages": [ { "id": 201, "sender_type": "user", "sender_name": "Lakshmi Narayana", "message": "Incoming webhook drops messages when payload exceeds 256KB.", "voice_recording": "/uploads/tickets/voice_142_1729601000.webm", "is_internal_note": 0, "created_at": "2026-10-22 13:06:00" }, { "id": 202, "sender_type": "admin", "sender_name": "Senior DevOps Engineer", "message": "We have increased the body-parser limit to 5MB on your ingress proxy.", "voice_recording": null, "is_internal_note": 0, "created_at": "2026-10-22 14:15:00" } ] }

5 Tier 2 API: Convert WhatsApp Chat to Ticket

1-Click ingestion endpoint triggered directly from the WhatsApp Inbox chat bubble or automated webhook.

POST /whatsapp-business/convert-to-ticket

POST /whatsapp-business/convert-to-ticket HTTP/1.1 Content-Type: application/json { "phone": "+919876543210", "name": "Rajesh Kumar", "message": "Order #4892 was damaged in transit, please process a refund.", "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQTA4NTk3MTI4NDEz...", "channel_type": "whatsapp_chat" }

Success Response (200 OK):

{ "status": "success", "message": "Ticket #TCK-20261022-4912 created from WhatsApp conversation", "ticket_id": 143, "ticket_number": "TCK-20261022-4912" }

6 WhatsApp Webhook Automated Triage & Two-Way Sync

The Meta Webhook handler (/whatsapp/webhook) executes real-time intelligence on incoming customer messages:

Trigger	Condition	System Action
Keyword Triage	Message contains `complaint`, `refund`, `urgent`, `broken`, or `not working`	Auto-spawns a High Priority ticket assigned to active agents via Round-Robin. Dispatches WhatsApp confirmation to customer.
Emoji Reaction	Agent reacts to customer message with 🎫	Spawns tracked ticket linked to contact and message bubble.
Two-Way Sync	Customer replies to WhatsApp notification: "Hi, regarding ticket #TCK-..."	Extracts ticket number, appends reply to ticket thread, sets status to Awaiting User Reply, and notifies assigned agent.

7 Dual-Mode Replies & SLA Aging Operations

Dual-Mode Reply Architecture

Public Reply: Sent to user/customer and visible on portal. Triggers automated WhatsApp notification template to end-customer.
Internal Staff Note (is_internal_note = 1): Highlighted in amber/yellow. Strictly visible only to Super Admins and Agents. Supports @AgentName team tagging.

SLA Aging Thresholds

< 4 Hours — Healthy / Within SLA.
4 – 24 Hours — Approaching Breached SLA (Amber Warning).
> 24 Hours — Breached SLA (Urgent escalation alert).
Computes First Response Time (FRT) and Average Resolution Time (ART) in hours.

Developer Integration Checklist

Audio Upload MIME Types: The in-browser audio recorder submits audio/webm or audio/mp3. Verify PHP upload_max_filesize >= 25M and post_max_size >= 32M in your php.ini.
Audio Storage Path: Audio voice recordings are saved to /uploads/tickets/voice_*. Ensure the folder has write permissions (chmod 775).
Transactional Emails: Email notifications are dispatched via CodeIgniter EmailService. Configure SMTP credentials in app/Config/Email.php or the Super Admin General Settings.