Skip to main content
Use an official Plainrouter SDK to send consented conversions from your server and inspect their delivery. The SDKs call the Plainrouter Conversion API; they do not call Meta’s Graph API directly.

​
Do generated methods establish availability?

No. Current published packages can still contain models or methods for retired Actions Tests, Legacy Launcher import and the sandbox. Those operations are removed from the current service; an SDK type or method cannot restore them. Check the current tool availability, Launcher migration and sandbox migration before reusing an older integration.

​
Choose your language

Each language guide covers installation, authentication, requests, and verification.

TypeScript

Typed operations and Zod schemas for server-side Node.js applications.

Python

Synchronous and asynchronous clients with typed request models.

Ruby

A client facade for sending events and reading delivery results.

PHP

Composer client for consented events and delivery reads.

Go

Typed requests with context-based authentication and error handling.
For a terminal workflow, start with the CLI quickstart, then use the command reference. To connect an AI agent to governed advertising workflows, use MCP setup.

​
Before you begin

Production Conversion API requests require a Server secret stored on your server. Published clients retain names such as signalTrackerSecret and “tracker token” for this credential. An MCP Workspace key is a separate credential and cannot authenticate Conversion API requests. See Authentication. To deliver conversions to Meta, connect the intended dataset and capture the required event consent. Review the published event schema before sending; the unauthenticated sandbox is retired.

​
What changed in the current releases?

The server has retired the unauthenticated API and MCP sandbox. Published SDKs can still contain generated sandbox methods, but calling them returns HTTP 410 with sandbox_retired. Remove those calls from setup checks and use the matching workspace credential for supported operations. No new package release is implied. Migration guidance. TypeScript, Python and CLI 0.10.1, Ruby 0.6.1, PHP 0.4.1, and Go v0.7.1 are published. The patch releases correct workspace and inventory error models and the Launcher import route. Ruby also fixes standalone multipart loading, and PHP improves asynchronous error decoding. The preceding minor releases introduced the bounded response models and request-validation changes below. The API contract still reports version 0.5.0; package versions have their own release sequence. The refreshed models include current Actions reads and destination/delivery states. New Actions Read access uses a read-actions grant; upgrading a package does not upgrade an older credential. Use a Server secret for Signals and an appropriately scoped Workspace key for Actions. A generated method or enum does not enable a gated product workflow. The server’s current action schema refuses set_status, adjust_budget, replace_creative, shift_spend, and rollback, even when an installed generated model still includes those names. Update proposal and preview payloads to supported action types and handle field-level validation errors. Check the current compatibility boundary.

​
What should I check before upgrading?

These 0.x releases include source compatibility changes. Pin one version, update your lockfile and compile or run your integration before rollout. Review the release notes linked from your language guide.
  • Follow continuation metadata. Actions and plan responses can contain only part of a collection. Follow the returned cursor with the same scope and filters; a short page is not proof of completion. Read saved proposal continuations rather than resubmitting a write.
  • Handle current response states and models. Destination attention and held delivery states need explicit handling. Hand-built response models may require new fields, including nullable fields. Generated plan and creative model names can change.
  • Check request validation and transport errors. Supply only documented keys and integer values. Omit optional page fields for defaults. The current TypeScript, Python, Ruby and PHP clients default to JSON responses and reject API redirects; inspect the original status and response headers before changing the URL or credentials.
See the upgrade notes for TypeScript, Python, Ruby, PHP, and Go. Package updates do not enable gated workflows or widen a Workspace key’s grant.

​
Build your first integration

  1. Install and configure one client. Follow your language guide above. Pin its package version and keep the Signals secret out of browser bundles.
  2. Check access. Read recent events using the guide’s authenticated client. A successful empty response is valid; it does not prove that browser collection is installed.
  3. Verify ingestion. Use the SDK’s ingestion diagnostic. It records an identity-free verification event; it does not establish real arrival evidence or complete onboarding. See Verify Signal ingestion.
  4. Send a conversion and inspect delivery. Follow the Node.js and TypeScript recipe, or the purchase example in the Python, Ruby, PHP, or Go guide. Preserve the original event ID and payload on retries.
A new event’s 202 acknowledgement confirms ingestion. Check the event’s delivery trace separately: a delivery with status: "accepted" confirms destination acceptance. Acceptance does not establish attribution or improved advertising performance. See delivery status meanings.

​
What do the clients cover?

All five published SDKs target signed API contract 0.5.0 and cover event creation and retrieval, ingestion verification, destination testing, delivery replay, reports, and user-data deletion. Package versions are independent of the API contract version. Review release notes before upgrading. For compatibility in published 0.5.x clients, see Read workspace identifiers. The CLI exposes nine API commands. It has no ingestion-verification or cursor-based event-listing command; use an SDK or REST for those operations. Install the CLI from npm, PyPI, or the official Homebrew tap. Choose one global installation so your shell runs the intended executable.

​
What if the integration does not work?

​
Why does an Actions request fail validation?

The current server contract applies even when your installed generated client accepts a broader object. Supply only the documented action parameters, use actual integers where required, and omit optional pagination fields when you want the default. Do not send booleans as numbers or copy server-owned fields from a stored response into a new request. Inspect HTTP 422 field errors before retrying. A package upgrade does not change credential permissions, and a repository change is not necessarily in your installed release. Compare the published version above with your lockfile and the current API contract. The language guides describe each client’s response and error handling. For terminal-specific failures, see CLI troubleshooting.