Quickstart

Choose your integration path:

• Path A — You're a product engineer adding Retivo directly to your app with the SDK.
• Path B — You're a platform team routing events from an analytics tool like Segment or PostHog.
• Path C — You're connecting an external platform (loyalty, gamification, engagement) to receive AI-powered actions from Retivo.

Path A: SDK Integration

1. Get Your API Key

Sign up at your Retivo dashboard, then go to Settings → API Keys and create a key. You'll get a key starting with rt_live_ (production) or rt_test_ (testing).

2. Run the CLI Wizard (Recommended)

The fastest way to get started. The wizard detects your framework, installs packages, and generates integration code:

npx @retivo/cli init

It will prompt you for your API key and set everything up. See the CLI reference for details.

Prefer manual setup? Continue with the steps below.

3. Install the SDK

npm install @retivo/sdk

4. Initialize and Identify a User

import { Retivo } from '@retivo/sdk'

const retivo = new Retivo({
  apiKey: 'rt_test_...', // use a test key during development
})

retivo.identify('user-123', {
  name: 'Jane Smith',
  email: 'jane@example.com',
  plan: 'pro',
})

5. Track Your First Event

retivo.track('project_created', {
  projectName: 'My First Project',
})

Events are batched automatically — no need to manage flushing.

6. Add the In-App Widget

Show real-time intervention messages to your users:

import { RetivoWidget } from '@retivo/widget'

function App() {
  return (
    <>
      <YourApp />
      <RetivoWidget
        apiKey="rt_test_..."
        userId="user-123"
        position="bottom-right"
      />
    </>
  )
}

7. You're Done

Retivo will evaluate users as events arrive and deliver personalized interventions when your playbooks match. Create playbooks in the dashboard under Playbooks → New Playbook.

Next steps: SDK Reference · Widget docs · API Reference

Path B: Connector Integration

1. Get Your API Key

Sign up at your Retivo dashboard, then go to Settings → API Keys and create a key.

2. Point Your Analytics Tool at Retivo

Add a webhook destination in your analytics platform pointing to the appropriate Retivo connector endpoint:

Include your API key as a header:

Authorization: Bearer rt_live_...

3. Verify Events Are Flowing

Send a test event from your analytics tool, then confirm it arrived:

curl https://retivo.ai/api/customers \
  -H "Authorization: Bearer rt_live_..."

You should see the user created from your connector event.

4. Register an Outbound Webhook

To receive intervention data in your backend, register a webhook endpoint:

curl -X POST https://retivo.ai/api/webhooks/endpoints \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.com/webhooks/retivo" }'

Retivo will send signed HTTP callbacks whenever an intervention is delivered via the webhook channel.

5. You're Done

Events flow in from your analytics platform, Retivo evaluates users against your playbooks, and interventions flow out via your webhook. Create playbooks in the dashboard to define when and how Retivo should intervene.

Next steps: Connectors guide · Webhooks guide · API Reference

Path C: External Platform Integration

For loyalty, gamification, engagement, or rewards platforms that want to receive AI-powered actions from Retivo.

1. Get Your API Key

Sign up at your Retivo dashboard, then go to Settings → API Keys and create a key.

2. Register Your Action Types

Tell Retivo what your platform can do:

curl -X POST https://retivo.ai/api/external/action-types \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "grant_points",
    "description": "Award loyalty points to a customer",
    "provider": "your-platform",
    "parameters_schema": {
      "amount": { "type": "number", "required": true },
      "reason": { "type": "string" }
    },
    "delivery_webhook": "https://your-platform.com/api/retivo/dispatch",
    "domain": "loyalty"
  }'

Save the webhook_secret from the response — you'll use it to verify incoming dispatches.

3. Receive Actions from Retivo

When Retivo's AI decides to use your action type, it sends a signed POST to your delivery_webhook:

{
  "action_id": "ea_xyz789",
  "action_type": "grant_points",
  "user_id": "user-123",
  "parameters": { "amount": 500, "reason": "re-engagement bonus" },
  "confidence": "0.82"
}

Verify the X-Retivo-Signature header with your webhook secret (HMAC-SHA256).

4. Report the Outcome

After executing the action, tell Retivo what happened:

curl -X POST https://retivo.ai/api/external/actions/ea_xyz789/outcome \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed", "result": { "points_granted": 500 } }'

5. You're Done

Retivo learns from every outcome. The more actions you report, the smarter the recommendations get. You can also push events from your platform and ask for on-demand recommendations.

Next steps: External Integrations guide · API Reference