TikTok

What this TikTok integration covers

TikTok is present in the current OrcaPulse project as a real integration path, but it is not as deep yet as Instagram, WhatsApp, or LinkedIn. The code already supports OAuth connection, connected-profile storage, platform visibility in the social leads area, and token revocation during disconnect.

At the same time, the webhook side is still treated as sandbox-level and the code openly acknowledges that production lead-gen behavior is not fully implemented yet.

OAuth and identity setup

The TikTok flow begins with a dedicated OAuth route that validates the requesting user, generates a state token, sends the user to TikTok authorization, and then exchanges the callback code for access credentials.

After token exchange, OrcaPulse loads TikTok user info, stores the open ID and union ID, saves the display name and avatar, and marks the integration as active in the shared social-media integration model.

• State validation: the auth flow uses a generated state token before accepting the callback.
• Profile-backed save: open ID, display name, avatar URL, access token, refresh token, and expiry are saved on the integration.
• Shared integration model: TikTok sits inside the same platform model used by Instagram, LinkedIn, and other social channels.

Platform state and social-lead visibility

Even though TikTok capture depth is still limited, the rest of the product already knows about TikTok as a first-class platform. It appears in the social-leads views, filter controls, integration lists, and platform configuration mappings used by the AI front end.

The social lead model also includes TikTok-specific capture-source values, which gives the project a schema-level place to store TikTok comments or direct-message style events as the channel grows.

• Visible in operations UI: TikTok shows up as a selectable platform in the social-leads experience.
• Model support exists: the lead schemas already define `tiktok` as a platform and include TikTok capture-source types.
• Ready for expansion: the current project structure leaves room to deepen TikTok capture without redesigning the data model.

Webhook behavior and sandbox boundaries

TikTok webhook support is intentionally limited right now. The route exists and the controller acknowledges inbound webhook calls, but the implementation mainly logs the payload and returns a successful response while sandbox mode is in effect.

That limitation is worth documenting directly because it explains why TikTok currently behaves more like a connected identity and future-ready platform than a fully automated live capture channel.

• Webhook route exists: the API has a TikTok webhook endpoint in the social-media routes.
• Sandbox behavior: the controller logs received payloads and responds successfully without a deeper event-processing pipeline yet.
• Honest boundary: this is a good candidate for future expansion, but the docs should not imply parity with Instagram or LinkedIn today.

Disconnect and token revoke flow

TikTok already has a stronger disconnect path than many early integrations. When a TikTok integration is deleted, the backend attempts to revoke the live TikTok token through TikTok’s OAuth revoke endpoint before removing the record from the database.

This is important operationally because it means the project does not treat disconnect as just a local delete. It tries to clean up the external credential too.

• Remote revoke attempt: OrcaPulse calls TikTok’s revoke endpoint before final deletion.
• Graceful failure handling: if revoke fails, the backend logs the problem but still completes the local cleanup path.
• Operational hygiene: this makes TikTok safer to test and disconnect during iteration.

How to use TikTok in the current project

Right now, TikTok is best understood as a connected platform layer with visible operational scaffolding rather than a fully finished capture engine. Teams can connect the account, surface it in integrations and social-lead operations, and use the shared platform model as a base for future TikTok capture work.

If you want the next product step here, the most valuable expansion would be converting webhook events into stored TikTok social leads and then linking those records to the same qualification and routing pipeline used by the stronger channels.

Next steps

After TikTok, the next useful page is usually Web Forms, because that route will cover direct site capture and complements the social-channel docs you’ve been building.