Skip to main content

Documentation Index

Fetch the complete documentation index at: https://setup.cevro.ai/llms.txt

Use this file to discover all available pages before exploring further.

Custom integrations let you connect Cevro to any system with an API. Your back-office, CRM, internal tools, payment processors, third-party services—if it has an API, your AI agent can use it.

​
Why Custom Integrations?

You’re not limited by what Cevro supports out of the box. Custom integrations give your AI agent the ability to:
  • Fetch data from any system — player info, transaction history, account status, inventory, anything
  • Take actions — issue bonuses, update records, trigger workflows, send notifications
  • Make decisions using real-time information from your actual systems
This is how your AI agent goes from “I can look that up for you” to actually doing the work. The same capabilities your human agents have, now available to your AI.

​
Overview

Navigate to Settings → Integrations to view your integrations. Custom integrations appear in their own section.
If you don’t see custom integrations, reach out to your CSM to enable this feature.
Each custom integration is a container for operations—individual API endpoints the AI can invoke. For example, a “Back-Office API” integration might contain:
  • Player Info
  • Player Balances
  • Active Bonuses
  • Deposits
  • Withdrawals

​
Getting Started

​
Creating an Integration

  1. Click Add Custom Integration
  2. Enter a name and optional description
  3. Add operations (see below)

​
Configuring Operations

Each operation represents a single API endpoint. Click an operation to configure it through these tabs:

​
Create Tab

SettingDescription
Display LabelHuman-readable name (e.g., “Player Deposits”)
NameAuto-generated identifier from the label
Data TypeREAD for fetching data, WRITE for actions that modify data
Available FromWhere this operation can be used: AIP (AI Procedures), Rule Trigger (automation rules)

​
Integrate Tab

SettingDescription
EndpointThe API URL—supports dynamic values like {{workspace.boApiUrl}}/v1/player
HTTP MethodGET, POST, PUT, PATCH, or DELETE
ParametersRequest parameters (see Parameters below)
AI InstructionsDescribe what this operation does—helps the AI know when and how to use it
HeadersOptional custom HTTP headers

​
Authenticate Tab

SettingDescription
IP AllowlistCevro’s outbound IPs—add these to your API’s firewall if needed
Requires AuthenticationWhen enabled, players must be authenticated before this operation runs
Use Workspace AuthenticationWhen enabled (default), the workspace’s authentication strategy is applied to this operation’s requests. Disable for operations that connect to a different API with their own authentication. See Workspace-Level Settings.

​
Preview Tab

Test your operation:
  1. Choose Run API to test against your real API, or Manual JSON to paste a sample response
  2. Fill in test values for dynamic parameters
  3. Click Run Test
  4. Review the response
Run API mode calls your production API. Be careful with operations that modify data.

​
Code Transformation Tab

Transform API responses before they reach the AI:
  • RAW mode passes the response through unchanged (recommended for most cases)
  • CODE mode lets you write JavaScript to transform the response

​
Save Tab

Review and save your configuration.

​
Parameters

Parameters define what data gets sent with each API request.

​
Internal Parameters

Values the system provides automatically. Set a value using:
  • Fixed values (e.g., 50 for a limit)
  • Dynamic values (e.g., {{contact.email}}, {{brand.slug}}, {{workspace.boApiUrl}})
See Dynamic Values for the full reference of available tags.

​
External Parameters

Values the AI determines at runtime based on the conversation. Leave the value empty and write a clear description so the AI knows what to ask the player or infer from context. Example: A “transaction lookup” operation might have an external transaction_id parameter with description: “The transaction ID the player wants to inquire about.”
Need nested JSON bodies (GraphQL mutations, Jira/Monday-style APIs)? Cevro supports this, but the configuration isn’t fully exposed in the dashboard today. Reach out to your CSM and we’ll wire it up for you.

​
Field Catalog

The field catalog defines what data from API responses is available to the AI.

​
Auto-Discovery

After running a test in the Preview tab:
  1. Click Auto-Discover
  2. Cevro analyzes the response and creates fields with AI-generated labels and descriptions
  3. Review and customize as needed
Fields are also discovered at runtime—when an operation returns new fields, they’re automatically cataloged.

​
Customizing Fields

For each field, you can:
  • Edit the label (display name)
  • Edit the description (helps the AI understand the field)
  • Change the type (String, Number, Boolean, Date, etc.)

​
Hiding Fields from the AI

Not every field your API returns should be visible to the AI agent. Internal IDs, debug data, or sensitive fields can be hidden so the AI never sees or references them. Click the eye icon on any field to hide it. Hidden fields:
  • Are excluded from the AI’s view — the agent cannot see, reference, or mention the data
  • Stay in the catalog — they appear in a collapsed “Hidden” section so you can restore them anytime
  • Survive auto-discovery — re-running discovery won’t un-hide fields you’ve hidden
  • Can be restored by clicking the eye icon in the hidden section
Use this to keep your API integration clean without modifying your API. If your endpoint returns 50 fields but the AI only needs 10, hide the rest. Less noise means better AI responses.

​
Dynamic Object Fields

Some APIs return objects where the keys are data values, not fixed field names. For example, a player segments endpoint might return: 
{
  "segments": {
    "bonus_segment": "Keep",
    "value_segment": "SVP",
    "activity_segment": "Active"
  }
}
Different players have different segment names. If left as a regular Object, the catalog will grow indefinitely as new key names appear — each treated as a separate field. Dynamic Object fixes this by converting the object into a stable array format at runtime: 
{ "bonus_segment": "Keep", "value_segment": "SVP" }

→ [{ "segment_name": "bonus_segment", "value": "Keep" },
   { "segment_name": "value_segment", "value": "SVP" }]
The AI always sees the same structure (segment_name + value), regardless of what keys each player has.
Auto-discovery detects some dynamic patterns automatically — numeric ranges like 20.00-100.00, UUIDs, numeric IDs, and dates are caught and set to Dynamic Object. However, human-readable keys like bonus_segment or EUR look like normal field names and won’t be auto-detected.

​
When to Use Dynamic Object

Look for these signs:
  • The field catalog keeps growing with new field names that all come from the same parent object
  • The same operation works for one player but shows different fields for another
  • Keys represent categories, currencies, IDs, or labels that vary per player
Common examples: player segments, currency breakdowns, game categories, bonus statuses keyed by ID.

​
How to Change a Field to Dynamic Object

  1. Open the operation and go to the field catalog
  2. Find the parent field (e.g., segments)
  3. Change the type from Object to Dynamic Object
  4. Set the Key Label — this names the key column in the output (e.g., segment_name)
  5. Save
Once you set a field to Dynamic Object, auto-discovery will preserve that setting. It won’t revert it back to Object when new data comes in.

​
Workspace-Level Settings

Some settings apply across the entire workspace and are configured on the primary integration’s sidebar. These appear under Authentication, Base Environment, and Settings in the integration sidebar.

​
Back-Office API URL

A base URL for your primary back-office API. Once set, reference it in any operation’s endpoint using {{workspace.boApiUrl}}: 
{{workspace.boApiUrl}}/v1/player/account/profile
This avoids duplicating the base URL across every operation. If your API base URL changes, update it in one place. The Base API URL field itself supports dynamic values — type @ in the field to pick from available tags. This is how you handle multi-brand back-offices where each brand has its own API host: 
https://{{brand.apiDomain|default:'platform.example.com'}}/platform/player
At runtime, {{workspace.boApiUrl}} is resolved first, then any nested {{brand.*}} tags inside it are resolved against the current conversation’s brand. The |default:'...' filter provides a fallback host when a brand doesn’t define apiDomain. Only brand.* and workspace.* tags are available in this field — request-scoped tags like {{contact.*}}, {{param.*}}, or {{date.*}} don’t apply to a workspace-wide base URL.

​
Authentication Strategy

The workspace authentication strategy controls how Cevro authenticates outbound API requests. This is configured once and applies to all operations that have Use Workspace Authentication enabled. Common strategies include:
StrategyHow It Works
API KeyA static key attached as a header (default: Authorization: Bearer <token>). Advanced options let you customize the header name and disable the Bearer prefix.
Contact Bearer TokenA per-player token captured during authentication, attached automatically
Signing HashRequests are cryptographically signed with a shared secret
Your CSM configures the authentication strategy during onboarding. The API Credentials section on the Authentication sidebar page lets workspace admins manage the API key directly. Click Advanced to customize the header name or disable the Bearer prefix.

​
How Authentication Applies to Operations

The workspace authentication strategy is applied to every operation where Use Workspace Authentication is enabled (which is the default). This means:
  • The strategy adds authentication headers or parameters to the outgoing request
  • Any Authorization header you set manually on the operation may be overwritten by the workspace strategy
Connecting to multiple APIs? If your workspace has integrations that connect to different back-office systems, each with different authentication, disable Use Workspace Authentication on operations that don’t use the workspace’s primary API. Those operations should manage their own authentication through custom headers on the Integrate tab.

​
Player Authentication

Controls how players verify their identity before the AI can access their data. See Player Authentication for full details.

​
Troubleshooting

​
Fields not appearing in AIP builder

  • Enable Available From: AIP on the Create tab
  • Check the field isn’t hidden in the catalog
  • Run Auto-Discover after testing

​
Test returns unexpected results

  • Check the Endpoint URL (no missing slashes)
  • Verify parameter names match your API exactly (camelCase vs snake_case)
  • Review the full response in Preview

​
Wrong authentication token on requests

If an operation is sending the wrong token or getting authentication errors:
  1. Check if Use Workspace Authentication is enabled on the operation’s Authenticate tab
  2. When enabled, the workspace authentication strategy overrides custom Authorization headers
  3. Fix: If this operation connects to a different API, disable Use Workspace Authentication and set your authentication headers manually on the Integrate tab

​
Preview returns errors but live requests work

The Preview/Test feature runs from Cevro’s servers and may behave differently from live requests in some cases:
  • IP restrictions: Preview requests may come from a different IP than live requests. Check your API’s firewall settings.
  • Player-level authentication: Strategies that use per-player tokens (like Contact Bearer Token) cannot be tested in Preview because there’s no active player session. The Preview will show a clear error message explaining this.

​
Building Your API

If you’re building a custom API for Cevro to consume, see Connect Your Back-Office for endpoint patterns, authentication flows, and best practices.