CRM Integration Guide

This guide walks you through connecting Oktivo to your CRM so you can trigger AI voice calls from your sales pipeline and receive structured results back.

Architecture Overview

┌─────────────┐       API Token        ┌──────────────────┐
│   Your CRM  │ ─────────────────────▶ │  Oktivo CRM API  │
│             │                         │                  │
│             │ ◀───── Webhook ──────── │  Voice Agents    │
└─────────────┘                         └──────────────────┘

Your CRM triggers a call via the API when a lead enters a specific pipeline stage
Oktivo’s AI agent makes the call and extracts structured data
Oktivo sends results back to your CRM via webhook

Step 1: Generate an API Token

Create a token from the Oktivo dashboard or via API:

curl -X POST https://client-backend.oktivo.com/api/v1/crm/tokens \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "salesforce-prod",
    "expiresInDays": 90
  }'

const response = await fetch('https://client-backend.oktivo.com/api/v1/crm/tokens', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'salesforce-prod',
    expiresInDays: 90,
  }),
});

const { data } = await response.json();
// Save data.plainToken securely it won't be shown again

import requests

response = requests.post(
    "https://client-backend.oktivo.com/api/v1/crm/tokens",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "name": "salesforce-prod",
        "expiresInDays": 90,
    },
)

data = response.json()["data"]
# Save data["plainToken"] securely it won't be shown again

Store the plainToken value in your CRM’s secure credential store. It cannot be retrieved after this response.

Step 2: Configure Your CRM

Add the API token to your CRM’s HTTP integration settings:

Base URL: https://client-backend.oktivo.com
Header: Authorization: Bearer okt_your_token_here
Content-Type: application/json

Step 3: Trigger Calls from Your Pipeline

When a lead enters the appropriate stage, trigger a call:

curl -X POST https://client-backend.oktivo.com/api/v1/crm/calls \
  -H "Authorization: Bearer okt_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155551234",
    "name": "Jane Smith",
    "agentId": "agent_qualification_v2",
    "dynamicVariables": {
      "company": "Acme Corp",
      "deal_value": "$50,000",
      "last_contact": "2025-01-10"
    },
    "retryConfig": {
      "retryCount": 2,
      "retryDelays": [5, 15]
    }
  }'

async function triggerOktivoCall(lead) {
  const response = await fetch('https://client-backend.oktivo.com/api/v1/crm/calls', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.OKTIVO_API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      phone: lead.phone,
      name: lead.fullName,
      agentId: 'agent_qualification_v2',
      dynamicVariables: {
        company: lead.company,
        deal_value: lead.dealValue,
        last_contact: lead.lastContactDate,
      },
      retryConfig: {
        retryCount: 2,
        retryDelays: [5, 15],
      },
    }),
  });

  const result = await response.json();

  if (!result.success) {
    console.error('Call trigger failed:', result.message);
    return null;
  }

  return result.data.contactUID;
}

import requests
import os

def trigger_oktivo_call(lead):
    response = requests.post(
        "https://client-backend.oktivo.com/api/v1/crm/calls",
        headers={
            "Authorization": f"Bearer {os.environ['OKTIVO_API_TOKEN']}",
            "Content-Type": "application/json",
        },
        json={
            "phone": lead["phone"],
            "name": lead["full_name"],
            "agentId": "agent_qualification_v2",
            "dynamicVariables": {
                "company": lead["company"],
                "deal_value": lead["deal_value"],
                "last_contact": lead["last_contact_date"],
            },
            "retryConfig": {
                "retryCount": 2,
                "retryDelays": [5, 15],
            },
        },
    )

    result = response.json()

    if not result["success"]:
        print(f"Call trigger failed: {result['message']}")
        return None

    return result["data"]["contactUID"]

Step 4: Set Up a Webhook for Results

Create an endpoint to receive call analysis back into your CRM:

curl -X POST https://client-backend.oktivo.com/webhooks/endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-crm.com/webhooks/oktivo-results",
    "eventTypes": ["call.analysis_ready", "call.completed"],
    "agentId": "agent_qualification_v2"
  }'

Step 5: Process Webhook Payloads

Handle incoming webhook events to update your CRM records:

const crypto = require('crypto');

app.post('/webhooks/oktivo-results', (req, res) => {
  // Verify signature
  const signature = req.headers['x-oktivo-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.OKTIVO_WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const { event, data } = req.body;

  if (event === 'call.analysis_ready') {
    // Update CRM with analysis results
    updateLeadInCRM(data.contactUID, {
      interested: data.analysis.interested,
      notes: data.analysis.reason,
      callbackTime: data.analysis.callback_time,
    });
  }

  res.status(200).send('OK');
});

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/oktivo-results', methods=['POST'])
def handle_oktivo_webhook():
    # Verify signature
    signature = request.headers.get('x-oktivo-signature')
    expected = hmac.new(
        os.environ['OKTIVO_WEBHOOK_SECRET'].encode(),
        request.data,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "Invalid signature"}), 401

    # Process the event
    payload = request.json
    event = payload["event"]
    data = payload["data"]

    if event == "call.analysis_ready":
        update_lead_in_crm(data["contactUID"], {
            "interested": data["analysis"]["interested"],
            "notes": data["analysis"]["reason"],
            "callback_time": data["analysis"]["callback_time"],
        })

    return "OK", 200

Error Handling

HTTP Code	Meaning	Action
400	Validation error	Fix the request body
402	Insufficient credits	Top up your balance
404	Agent not found	Verify the `agentId`
429	Rate limited	Back off and retry after the `Retry-After` header
503	Service unavailable	Retry with exponential backoff

Next Steps

Retry Logic Guide configure automatic retries
Webhook Filtering route events per agent
API Reference full endpoint documentation

Getting Started

Core Concepts

Guides

CRM Integration

CRM Integration Guide

Architecture Overview

Step 1: Generate an API Token

Step 2: Configure Your CRM

Step 3: Trigger Calls from Your Pipeline

Step 4: Set Up a Webhook for Results

Step 5: Process Webhook Payloads

Error Handling

Next Steps

​CRM Integration Guide

​Architecture Overview

​Step 1: Generate an API Token

​Step 2: Configure Your CRM

​Step 3: Trigger Calls from Your Pipeline

​Step 4: Set Up a Webhook for Results

​Step 5: Process Webhook Payloads

​Error Handling

​Next Steps

CRM Integration Guide

Architecture Overview

Step 1: Generate an API Token

Step 2: Configure Your CRM

Step 3: Trigger Calls from Your Pipeline

Step 4: Set Up a Webhook for Results

Step 5: Process Webhook Payloads

Error Handling

Next Steps