Skip to content
Radioso Docs home
Open app

Connectors and webhooks

Connectors link a workspace to external systems. The exact config shape depends on the connector type. The connector routes take a workspace token and answer on the host that issued it — see Workspaces and tokens.

How it works

  1. List the connectors available to the workspace.
  2. Read one connector’s current detail.
  3. Save connector-specific config.
  4. Enable the connector when the config is ready.
  5. Run a manual sync when the connector supports it.

Connector config is not one global schema. The body depends on the connector you are configuring, so the API Reference is the authoritative place for the exact shape.

Connector detail responses also include syncState. This shows whether a sync is queued or running, the latest backfill completion time, latest sync attempt, upstream modified cursor, count ingested by the last sync, and the operator-safe lastError from the latest failed sync. A successful sync clears lastError.

Built-in connectors

Radioso ships with these connector types:

  • wordpress: syncs WordPress pages and posts into workspace documents. It supports push webhooks and optional manual sync.
  • whatsapp: receives WhatsApp Business Cloud API messages, sends them through assistant chat, and replies through WhatsApp. It does not support manual sync.

For WordPress, each post is ingested from its rendered content. The author’s display name is stored as document metadata (author) — drawn from the embedded author on REST sync and from the push payload on webhooks — and included in searchable and answer context, so assistants can find and identify an author even when WordPress omits the byline from the post body. The publish date is stored the same way: the raw timestamp under published_at and its day under dateFrom, so posts are searchable by date and usable in date metadata rules. Existing documents only pick up the author and publish date after a re-sync.

For WhatsApp, configure the phone number ID, access token, app secret, business account ID, and generated webhook verify token. Use the connector detail’s webhookUrl as the Meta webhook callback URL. Radioso verifies X-Hub-Signature-256, ignores duplicate message IDs, and stores message logs for retry and recovery.

WhatsApp text messages are sent through assistant chat. Non-text WhatsApp messages are not converted into assistant user turns. If you configure an unsupported-message reply, Radioso sends that exact reply through WhatsApp; otherwise those messages are recorded as skipped.

Save connector config

Use:

text
PUT /api/v1/connectors/{connectorId}

Then enable it with:

text
POST /api/v1/connectors/{connectorId}/enable

Disable it with:

text
POST /api/v1/connectors/{connectorId}/disable

Run a manual sync

Use:

text
POST /api/v1/connectors/{connectorId}/sync

The response returns 202 when the sync has been accepted:

json
{
  "accepted": true
}

The sync continues after the HTTP request returns. Re-read the connector detail to see updated syncState. Not every connector supports manual sync. Unsupported or already-running syncs return 409.

For WordPress, the connector creates its source record before it calls the WordPress REST API. This keeps failed syncs visible under Knowledge → Sources, including failures that happen before WordPress returns the first post.

A workspace WordPress connector accepts one configured site. Companion-plugin webhooks include a signed site URL, and Radioso rejects events when that URL or the post permalink does not belong to the configured site. Changing the WordPress site URL rotates the generated webhook secret; copy the new secret into the plugin settings for the new site.

Endpoint reference

text
GET  /api/v1/connectors
GET  /api/v1/connectors/{connectorId}
PUT  /api/v1/connectors/{connectorId}
POST /api/v1/connectors/{connectorId}/enable
POST /api/v1/connectors/{connectorId}/disable
POST /api/v1/connectors/{connectorId}/sync

Common failure modes

  • 400 usually means the connector config is incomplete or invalid.
  • 401 means the authenticated workspace context is missing for connector-management routes.
  • 404 means the connector or workspace was not found.
  • 409 usually means the connector is in a conflicting state for the requested save or enable action, does not support manual sync, or already has a sync running.