# Connect a knowledge base chat to an agent
Source: https://docs.starleads.co/api-reference/agent/connect-a-knowledge-base-chat-to-an-agent
PUT /Agent/{agentId}/chat
Connects a knowledge base chat to an agent. Each agent can have at most one chat connected at a time. The agent and chat must belong to the same company as the API key used for authentication.
# Detach the chat from an agent
Source: https://docs.starleads.co/api-reference/agent/detach-the-chat-from-an-agent
DELETE /Agent/{agentId}/chat
Detaches the currently connected knowledge base chat from an agent. The chat itself is not deleted. The agent must belong to the same company as the API key used for authentication.
# Get the chat connected to an agent
Source: https://docs.starleads.co/api-reference/agent/get-the-chat-connected-to-an-agent
GET /Agent/{agentId}/chat
Retrieves the knowledge base chat currently connected to an agent. Returns 204 No Content if no chat is connected. The agent must belong to the same company as the API key used for authentication.
# Get the prompt of an agent
Source: https://docs.starleads.co/api-reference/agent/get-the-prompt-of-an-agent
GET /Agent/{agentId}/prompt
Retrieves the current prompt configured for an agent. The agent must belong to the same company as the API key used for authentication.
# Update the prompt of an agent
Source: https://docs.starleads.co/api-reference/agent/update-the-prompt-of-an-agent
PUT /Agent/{agentId}/prompt
Replaces the current prompt of an agent with a new value. The agent must belong to the same company as the API key used for authentication. The prompt must not be empty and cannot exceed 50,000 characters.
# Create a campaign
Source: https://docs.starleads.co/api-reference/campaign/create-a-campaign
POST /Campaign
Creates a new campaign associated with an AI agent. The campaign is created in an inactive state (`isActive: false`). A phone number is required when the agent's channel is `Phone`. Default values are applied for optional fields not provided.
# Get all campaigns
Source: https://docs.starleads.co/api-reference/campaign/get-all-campaigns
GET /Campaign
# Get campaign's fields
Source: https://docs.starleads.co/api-reference/campaignfield/get-campaigns-fields
GET /CampaignField/{campaignId}
# Add a new campaign item to a campaign
Source: https://docs.starleads.co/api-reference/campaignitem/add-a-new-campaign-item-to-a-campaign
POST /CampaignItem/{campaignId}
# Add multiple items to a campaign
Source: https://docs.starleads.co/api-reference/campaignitem/add-multiple-items-to-a-campaign
POST /CampaignItem/{campaignId}/bulk-add-items
Allows adding multiple items to a specific campaign identified by `campaignId`. Authentication is required using an API key passed in the `X-Api-Key` header. You can retrieve your API key from your profile when logged in to [Starleads](https://app.starleads.co/).
# Delete an item from a campaign
Source: https://docs.starleads.co/api-reference/campaignitem/delete-an-item-from-a-campaign
DELETE /CampaignItem/{campaignId}/{itemId}
# Get all items by phone number
Source: https://docs.starleads.co/api-reference/campaignitem/get-all-items-by-phone-number
GET /CampaignItem/{campaignId}/{phoneNumber}
# Get campaign items with filters
Source: https://docs.starleads.co/api-reference/campaignitem/get-campaign-items-with-filters
GET /CampaignItem/{campaignId}/items
Retrieves campaign items with optional filters including status, archived state, and pagination.
# Create a dataset
Source: https://docs.starleads.co/api-reference/dataset/create-a-dataset
POST /Dataset
Creates a new dataset for storing and organizing documents used by the RAG (Retrieval-Augmented Generation) knowledge base.
# Delete a dataset
Source: https://docs.starleads.co/api-reference/dataset/delete-a-dataset
DELETE /Dataset/{datasetId}
Deletes a dataset and cascades: detaches it from all linked chats.
# Get a dataset
Source: https://docs.starleads.co/api-reference/dataset/get-a-dataset
GET /Dataset/{datasetId}
Retrieves the details of a specific dataset by its identifier.
# List datasets
Source: https://docs.starleads.co/api-reference/dataset/list-datasets
GET /Dataset
Retrieves a paginated list of datasets belonging to the authenticated company.
# Update a dataset
Source: https://docs.starleads.co/api-reference/dataset/update-a-dataset
PATCH /Dataset/{datasetId}
Partially updates a dataset. Only the provided fields are updated; omitted fields remain unchanged.
# Delete a document
Source: https://docs.starleads.co/api-reference/document/delete-a-document
DELETE /Dataset/{datasetId}/document/{documentId}
Deletes a document from a dataset.
# Download a document file
Source: https://docs.starleads.co/api-reference/document/download-a-document-file
GET /Dataset/{datasetId}/document/{documentId}/download
Downloads the original file of a document. The response is the binary file stream with appropriate Content-Type and Content-Disposition headers.
# List documents in a dataset
Source: https://docs.starleads.co/api-reference/document/list-documents-in-a-dataset
GET /Dataset/{datasetId}/document
Retrieves a paginated list of documents in a dataset, with optional keyword search and status filter.
# Stop document parsing
Source: https://docs.starleads.co/api-reference/document/stop-document-parsing
DELETE /Dataset/{datasetId}/document/parse
Stops parsing on one or more selected documents within a dataset.
# Trigger document parsing
Source: https://docs.starleads.co/api-reference/document/trigger-document-parsing
POST /Dataset/{datasetId}/document/parse
Triggers parsing on one or more selected documents within a dataset. Documents must not already be in a parsing state.
# Update a document
Source: https://docs.starleads.co/api-reference/document/update-a-document
PUT /Dataset/{datasetId}/document/{documentId}
Updates document metadata such as name, chunking method, parser configuration, and enabled status.
# Upload documents to a dataset
Source: https://docs.starleads.co/api-reference/document/upload-documents-to-a-dataset
POST /Dataset/{datasetId}/document
Uploads one or more documents to a dataset. Accepts 1 to 10 files, each with a maximum size of 5 MB.
# API Reference
Source: https://docs.starleads.co/api-reference/introduction
Base URL, authentication, pagination and error handling for the Starleads public API.
Every endpoint of the Starleads public API is documented in this section, grouped by resource.
**Base URL**: `https://api.starleads.co` — every request requires the `X-Api-Key` header.
## Where to start
Most integrations only need the campaign endpoints: create a campaign, push your prospects into it, then receive the results via webhook.
List and create the campaigns your AI agents run.
Add, retrieve and remove the prospects of a campaign.
Read the custom fields expected in an item's `databag`.
Read and update an agent's prompt, and connect it to a knowledge base.
## Knowledge base (RAG)
Optional. Use these endpoints only if you want your agents to answer from your own documents. Start with the [Knowledge Base guide](/documentation/rag-knowledge-base) rather than the raw endpoints — the objects have to be created in order.
Containers holding the documents your agents draw answers from.
Upload, parse and manage the files inside a dataset.
The retrieval configuration an agent is connected to.
Extract entities and relations from a dataset.
## Conventions
**Authentication** — pass your key in the `X-Api-Key` header on every call. See the [Authentication guide](/documentation/authentification) to retrieve it.
**Pagination** — list endpoints accept `pageNumber` (starts at 1) and `pageSize` (1 to 100, default 50). Responses carry `data`, `total`, `pageNumber` and `pageSize`.
**Errors** — failures return an [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem object.
| Status | Meaning |
| ------ | ----------------------------------------------------------- |
| `400` | The request payload or a parameter is invalid. |
| `401` | The `X-Api-Key` header is missing, unknown or inactive. |
| `403` | The resource exists but your API key cannot act on it. |
| `404` | The resource does not exist, or belongs to another company. |
| `429` | Rate limit exceeded — see `Retry-After`. |
A resource owned by another company answers `404`, not `403`, so the API never discloses that it exists.
**Rate limiting** — responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Heavy operations (uploads, parsing, knowledge graph builds) have tighter limits than plain CRUD calls.
# Create a knowledge base chat
Source: https://docs.starleads.co/api-reference/knowledgebasechat/create-a-knowledge-base-chat
POST /KnowledgeBaseChat
Creates a new knowledge base chat linked to one or more datasets. The chat can be configured with custom LLM and prompt settings. The model name field is not exposed; it is managed internally.
# Delete a knowledge base chat
Source: https://docs.starleads.co/api-reference/knowledgebasechat/delete-a-knowledge-base-chat
DELETE /KnowledgeBaseChat/{chatId}
Deletes a knowledge base chat and cascades: detaches it from all connected agents.
# Get a knowledge base chat
Source: https://docs.starleads.co/api-reference/knowledgebasechat/get-a-knowledge-base-chat
GET /KnowledgeBaseChat/{chatId}
Retrieves the details of a specific knowledge base chat. LLM model name is excluded from the response.
# List knowledge base chats
Source: https://docs.starleads.co/api-reference/knowledgebasechat/list-knowledge-base-chats
GET /KnowledgeBaseChat
Retrieves a paginated list of knowledge base chats belonging to the authenticated company. LLM model names are excluded from the response.
# Update a knowledge base chat
Source: https://docs.starleads.co/api-reference/knowledgebasechat/update-a-knowledge-base-chat
PATCH /KnowledgeBaseChat/{chatId}
Partially updates a knowledge base chat. Only the provided fields are updated; omitted fields remain unchanged. The model name field is not accepted.
# Delete the knowledge graph
Source: https://docs.starleads.co/api-reference/knowledgegraph/delete-the-knowledge-graph
DELETE /Dataset/{datasetId}/knowledge-graph
Deletes the knowledge graph associated with a dataset.
# Enable knowledge graph on a dataset
Source: https://docs.starleads.co/api-reference/knowledgegraph/enable-knowledge-graph-on-a-dataset
POST /Dataset/{datasetId}/knowledge-graph/enable
Enables the knowledge graph feature on a dataset. This is available only on the Business plan. Optionally specify entity types to extract.
# Get knowledge graph build status
Source: https://docs.starleads.co/api-reference/knowledgegraph/get-knowledge-graph-build-status
GET /Dataset/{datasetId}/knowledge-graph/status
Retrieves the current build status of the knowledge graph for a dataset.
# Get the knowledge graph
Source: https://docs.starleads.co/api-reference/knowledgegraph/get-the-knowledge-graph
GET /Dataset/{datasetId}/knowledge-graph
Retrieves the knowledge graph data for a dataset. Returns 204 No Content if no knowledge graph exists.
# Trigger knowledge graph construction
Source: https://docs.starleads.co/api-reference/knowledgegraph/trigger-knowledge-graph-construction
POST /Dataset/{datasetId}/knowledge-graph/build
Triggers an asynchronous knowledge graph construction on a dataset. The knowledge graph must be enabled first.
# Authentication
Source: https://docs.starleads.co/documentation/authentification
Learn how to authenticate your API requests using your API key.
All requests to the Starleads API must include a valid API key in the `X-Api-Key` header.
API keys are **secrets** shared only between you and Starleads. Never expose them in client-side code, public repositories, or share them with anyone.
## Get your API key
Go to [app.starleads.co](https://app.starleads.co) and sign in to your account.
In the sidebar, navigate to **Configuration → API Access**.
![API Access menu]()
Copy the API key displayed on the page. You'll need it for every request.
## Using your API key
Include the `X-Api-Key` header in every request:
```bash cURL theme={null}
curl -X GET https://api.starleads.co/Campaign \
-H "X-Api-Key: YOUR_API_KEY"
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.starleads.co/Campaign",
headers={"X-Api-Key": "YOUR_API_KEY"}
)
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.starleads.co/Campaign", {
headers: { "X-Api-Key": "YOUR_API_KEY" }
});
```
You're all set! Head over to the [API Reference](/api-reference/introduction) to explore the available endpoints.
# Welcome to Starleads
Source: https://docs.starleads.co/documentation/get-started
Conversational AI platform — phone, web-widget, SMS & WhatsApp. Integrate with our API to manage campaigns, prospects, and receive results in real-time.
Starleads is a **conversational AI platform** that deploys intelligent agents across multiple channels — **phone** (inbound & outbound), **web-widget**, **SMS**, and **WhatsApp**. From customer support to marketing and sales, Starleads handles your conversations at scale. Our public API lets you manage campaigns, add and remove prospects, and receive conversation results — all programmatically.
**New here?** Follow the steps below to get up and running in 5 minutes.
## Getting Started
Sign up at [app.starleads.co](https://app.starleads.co) and retrieve your API key from your account settings. You'll need it for every API request — it goes in the `X-Api-Key` header. Check the [Authentication guide](/documentation/authentification) for details.
Use the API to list your campaigns, add prospects, or retrieve campaign data. Explore the available endpoints in the [API Reference](#api-reference) section below.
Set up a webhook to get notified whenever one of your AI agents completes a conversation. You'll receive the full result — including classification, transcript, and summary. See the [Receive Conversation Results](/documentation/receive-conversation-results) guide for setup instructions.
## Guides
Deep-dive into key features:
Learn how to authenticate your API requests using your API key.
Get your agents' conversation results in real-time via webhooks.
Build AI-powered knowledge bases with datasets, documents, and chat assistants for your voice agents.
## API Reference
Explore the available endpoints:
**Base URL**: `https://api.starleads.co` — All requests require the `X-Api-Key` header.
Create a new campaign associated with an AI agent
List all your campaigns.
Retrieve the fields of a specific campaign.
Find all prospect entries for a phone number.
Add a new prospect to a campaign.
Remove a prospect entry from a campaign.
Retrieve the current prompt of an AI agent
Update the prompt that drives your agent's behavior
# Knowledge Base (RAG)
Source: https://docs.starleads.co/documentation/rag-knowledge-base
Build and manage AI-powered knowledge bases. Create datasets, upload documents, configure chat assistants, and connect them to your voice agents.
## Introduction
Starleads integrates **Retrieval-Augmented Generation (RAG)** to give your AI agents access to your own knowledge. Instead of relying solely on a static prompt, your agents can search through your documents in real-time during conversations -- retrieving the most relevant information to answer questions accurately and naturally.
A knowledge base in Starleads is built around **datasets** that contain your uploaded documents (PDFs, text files, etc.). Once uploaded and parsed, these documents are indexed and made searchable. You then create a **chat assistant** that connects to one or more datasets, defining how the AI retrieves and uses your content -- including similarity thresholds, prompt templates, and response behavior.
The general workflow follows four steps: **Dataset** (create a container) then **Documents** (upload and parse your files) then **Chat** (configure retrieval settings) then **Agent** (connect the knowledge base to your voice agent). Once connected, your agent can draw on your documents during live conversations, providing precise and context-aware responses.
## Getting Started
A dataset is a container for your documents. Give it a descriptive name that reflects its content (e.g. "Product Documentation", "FAQ 2026").
You can configure parser settings at creation time or update them later. See [Advanced Configuration](#advanced-configuration) for parser options.
**Endpoint**: `POST /Dataset`
Upload files to your dataset using multipart/form-data. Starleads accepts common document formats such as PDF, TXT, DOCX, and more.
There are two limits enforced at the gateway level:
* **Maximum 5 MB** per file
* **Maximum 10 files** per request
Files exceeding these limits are rejected immediately without being forwarded to the backend.
**Endpoint**: `POST /Dataset/{datasetId}/document`
After uploading, documents need to be parsed to extract and index their content. Parsing is **asynchronous** -- the API returns immediately and processing continues in the background.
You can check the parsing status by listing the documents in your dataset. Each document includes a status field indicating whether parsing is pending, in progress, or complete.
**Endpoint**: `POST /Dataset/{datasetId}/document/parse`
A chat assistant ties together one or more datasets with retrieval configuration. It defines how your knowledge base searches for relevant content and how the LLM generates responses.
You can configure similarity thresholds, the number of top results to consider, and a custom prompt template to control response formatting.
The LLM model is managed by the Starleads platform and cannot be changed via the API. The model name does not appear in API requests or responses.
**Endpoint**: `POST /KnowledgeBaseChat`
Finally, connect your chat assistant to a voice agent. Once linked, the agent will use the knowledge base during conversations to retrieve relevant information and answer questions.
An agent can be connected to **one chat assistant at a time**. Connecting a new chat replaces the previous one.
**Endpoint**: `PUT /Agent/{agentId}/chat`
## Code Examples
### Create a dataset
```bash cURL theme={null}
curl -X POST https://api.starleads.co/Dataset \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"name": "My Knowledge Base"}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.starleads.co/Dataset",
headers={"X-Api-Key": "your-api-key"},
json={"name": "My Knowledge Base"}
)
dataset = response.json()
```
### Upload documents
```bash cURL theme={null}
curl -X POST https://api.starleads.co/Dataset/{datasetId}/document \
-H "X-Api-Key: your-api-key" \
-F "files=@document.pdf"
```
```python Python theme={null}
import requests
with open("document.pdf", "rb") as f:
response = requests.post(
"https://api.starleads.co/Dataset/{datasetId}/document",
headers={"X-Api-Key": "your-api-key"},
files={"files": ("document.pdf", f, "application/pdf")}
)
documents = response.json()
```
### Create a chat assistant
```bash cURL theme={null}
curl -X POST https://api.starleads.co/KnowledgeBaseChat \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"name": "Support Bot", "datasetIds": ["ds_123"]}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.starleads.co/KnowledgeBaseChat",
headers={"X-Api-Key": "your-api-key"},
json={
"name": "Support Bot",
"datasetIds": ["ds_123"]
}
)
chat = response.json()
```
### Connect to an agent
```bash cURL theme={null}
curl -X PUT https://api.starleads.co/Agent/{agentId}/chat \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"chatId": "chat_456"}'
```
```python Python theme={null}
import requests
response = requests.put(
"https://api.starleads.co/Agent/{agentId}/chat",
headers={"X-Api-Key": "your-api-key"},
json={"chatId": "chat_456"}
)
```
## Advanced Configuration
### Parser configuration
When creating or updating a dataset, you can configure how documents are parsed and chunked:
| Parameter | Type | Description |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `chunkTokenNum` | integer | Number of tokens per chunk. Controls how documents are split into searchable segments. |
| `layoutRecognize` | boolean | Enable layout recognition for structured documents (tables, columns, headers). Improves accuracy for complex PDFs. |
| `delimiter` | string | Custom delimiter for splitting text. Use this when your documents have a consistent separator (e.g. `\n---\n`). |
### LLM settings
You can fine-tune how the LLM generates responses from retrieved content:
| Parameter | Type | Description |
| ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `temperature` | number | Controls randomness in responses. Lower values (e.g. 0.1) produce more focused answers; higher values (e.g. 0.9) produce more creative ones. |
| `topP` | number | Nucleus sampling threshold. Controls the diversity of token selection. |
| `presencePenalty` | number | Penalizes tokens that have already appeared, encouraging the model to cover new topics. |
| `frequencyPenalty` | number | Penalizes tokens based on their frequency, reducing repetition. |
The LLM model itself is managed by the Starleads platform. You can adjust generation parameters but cannot select or change the underlying model.
### Prompt settings
Control how retrieved documents are used to generate responses:
| Parameter | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `similarityThreshold` | number | Minimum similarity score (0 to 1) for a document chunk to be considered relevant. Higher values return fewer but more precise results. |
| `topN` | integer | Maximum number of document chunks to retrieve and include in the context. |
| `prompt` | string | Custom prompt template. Use `{knowledge}` as a placeholder where retrieved content will be injected. |
## Knowledge Graph
Knowledge Graph is available on the **Business** plan only.
Knowledge graphs provide a structured, relational view of your documents. Instead of searching through flat text chunks, a knowledge graph extracts entities and relationships, enabling more precise and context-aware retrieval.
The knowledge graph lifecycle follows four steps:
1. **Enable** -- Activate the knowledge graph feature on a dataset (`POST /Dataset/{datasetId}/knowledge-graph/enable`).
2. **Build** -- Trigger the graph construction. This is an asynchronous operation that processes all parsed documents in the dataset (`POST /Dataset/{datasetId}/knowledge-graph/build`).
3. **Check status** -- Monitor the build progress (`GET /Dataset/{datasetId}/knowledge-graph/status`). The status indicates whether the build is in progress, complete, or encountered an error.
4. **Retrieve** -- Once built, retrieve the knowledge graph data (`GET /Dataset/{datasetId}/knowledge-graph`).
You can also delete a knowledge graph to rebuild it from scratch (`DELETE /Dataset/{datasetId}/knowledge-graph`).
## API Reference
Explore all RAG-related endpoints:
Create, list, update, and delete datasets that hold your documents.
Upload, download, parse, and manage documents within your datasets.
Configure chat assistants that connect your datasets to AI retrieval.
Build and manage knowledge graphs for advanced document retrieval.
# Receive Conversation Results
Source: https://docs.starleads.co/documentation/receive-conversation-results
Get your agents' conversation results in real-time via webhooks.
## Introduction
Starleads sends you conversation results **in real-time** via webhooks. Every time one of your AI agents completes a conversation, Starleads sends a `POST` request to a URL of your choice containing the full campaign item data — including the classification tag, the conversation transcript, an AI-generated summary, and any custom metadata you configured.
## How to set up
Go to [app.starleads.co](https://app.starleads.co) and sign in to your account.
Navigate to the campaign you want to receive webhooks for, and open its **Settings** panel.
Paste the public URL of your webhook endpoint (e.g. `https://yourserver.com/webhook`). Your endpoint must accept `POST` requests and return a `200` status code.
Save the configuration. Starleads will send a test payload to your endpoint to verify it responds correctly. Once confirmed, you'll receive all future call results automatically.
## Payload
### Annotated example
The webhook sends a JSON payload representing a processed campaign item. Here's the full structure with annotations:
```jsonc theme={null}
{
"Id": "66e47083637b020bcd9865a9", // unique campaign item identifier
"CampaignId": "66f1b2d0016e6d3e9353ab85",
"CreatedAt": "2024-09-13T17:04:03.515Z",
"ProcessedAt": "2024-09-13T17:04:05.795Z",
"LastCallDate": "2024-09-13T17:04:05.795Z",
"RunningStatus": "Processed",
"AttemptCount": 1,
"PhoneNumber": "+3300000000",
"NextTryDate": "2024-09-13T17:04:03.515Z",
"DataBag": {
"id": "",
"firstname": "Paul",
"email": "paul@gmail.com"
},
// — call classification result —
"Result": {
// tag assigned by your reporting rules
"Tag": {
"_id": "Appointment_88B8DB86",
"Name": "Appointment",
"Color": "#1ee5a6"
},
// full conversation transcript
"Conversation": {
"_id": "24ef5fc9-9d20-4dcb-bd8b-f83e4929d36d",
"Messages": [
// one message per turn — only 2 shown for brevity
{
"Timestamp": "2024-09-13T17:04:17.000Z",
"Role": "user",
"Text": "oui bonjour",
"Intent": ""
},
{
"Timestamp": "2024-09-13T17:04:18.000Z",
"Role": "assistant",
"Text": "Oui bonjour Paul ?",
"Intent": ""
}
]
},
// AI-generated call summary
"Summary": "La discussion s'est conclue par un consentement explicite de l'utilisateur pour prendre rendez-vous avec Anthony.",
"IsSystem": false,
// custom metadata extracted per your reporting config
"Metadata": {
"Informations": "L'utilisateur a déjà eu un contact avec Anthony sur LinkedIn.",
"Date rendez-vous": "flexible"
}
},
"IsArchived": false,
// lifecycle events
"EventList": [
{ "Type": "LaunchCall", "Date": "2024-09-13T17:04:05.824Z", "Description": "" },
{ "Type": "ProcessingResult", "Date": "2024-09-13T17:06:38.403Z", "Description": "" },
{ "Type": "EndCall", "Date": "2024-09-13T17:06:40.426Z", "Description": "ProcessingResult DONE" }
]
}
```
The **Tag** and **Metadata** fields are configurable in the **Reporting** section of your campaign settings.
### Complete example
Here is the complete payload for copy-paste integration:
```json theme={null}
{
"Id": "66e47083637b020bcd9865a9",
"CampaignId": "66f1b2d0016e6d3e9353ab85",
"CreatedAt": "2024-09-13T17:04:03.515Z",
"ProcessedAt": "2024-09-13T17:04:05.795Z",
"LastCallDate": "2024-09-13T17:04:05.795Z",
"RunningStatus": "Processed",
"AttemptCount": 1,
"PhoneNumber": "+3300000000",
"NextTryDate": "2024-09-13T17:04:03.515Z",
"DataBag": {
"id": "",
"firstname": "Paul",
"email": "paul@gmail.com"
},
"Result": {
"Tag": {
"_id": "Appointment_88B8DB86",
"Name": "Appointment",
"Color": "#1ee5a6"
},
"Conversation": {
"_id": "24ef5fc9-9d20-4dcb-bd8b-f83e4929d36d",
"Messages": [
{
"Timestamp": "2024-09-13T17:04:17.000Z",
"Role": "user",
"Text": "oui bonjour",
"Intent": ""
},
{
"Timestamp": "2024-09-13T17:04:18.000Z",
"Role": "assistant",
"Text": "Oui bonjour Paul ?",
"Intent": ""
},
{
"Timestamp": "2024-09-13T17:04:52.000Z",
"Role": "user",
"Text": "ouais carrément bonne soirée ça m'intéresse beaucoup",
"Intent": ""
},
{
"Timestamp": "2024-09-13T17:05:35.000Z",
"Role": "user",
"Text": "j'aimerais bien que tu me préqualifies une liste d'appels",
"Intent": ""
},
{
"Timestamp": "2024-09-13T17:06:21.000Z",
"Role": "user",
"Text": "je veux bien prendre un rendez-vous avec Anthony",
"Intent": ""
}
]
},
"Summary": "La discussion s'est conclue par un consentement explicite de l'utilisateur pour prendre rendez-vous avec Anthony.",
"IsSystem": false,
"Metadata": {
"Informations": "L'utilisateur a déjà eu un contact avec Anthony sur LinkedIn et est flexible pour le rendez-vous.",
"Date rendez-vous": "flexible"
}
},
"IsArchived": false,
"EventList": [
{
"Type": "LaunchCall",
"Date": "2024-09-13T17:04:05.824Z",
"Description": ""
},
{
"Type": "ProcessingResult",
"Date": "2024-09-13T17:06:38.403Z",
"Description": ""
},
{
"Type": "EndCall",
"Date": "2024-09-13T17:06:40.426Z",
"Description": "ProcessingResult DONE"
}
]
}
```
## Receive the webhook
Here's how to receive and parse the webhook payload in your application:
```javascript server.js theme={null}
// npm install express
const express = require("express");
const app = express();
app.use(express.json());
app.post("/webhook", (req, res) => {
const item = req.body;
// Extract key fields
const phone = item.PhoneNumber;
const tag = item.Result?.Tag?.Name;
const summary = item.Result?.Summary;
console.log(`Call processed for ${phone}`);
console.log(`Tag: ${tag}`);
console.log(`Summary: ${summary}`);
// Access the conversation transcript
const messages = item.Result?.Conversation?.Messages || [];
messages.forEach((msg) => {
console.log(`[${msg.Role}] ${msg.Text}`);
});
// Access custom metadata
const metadata = item.Result?.Metadata || {};
Object.entries(metadata).forEach(([key, value]) => {
console.log(`${key}: ${value}`);
});
res.sendStatus(200);
});
app.listen(3000, () => console.log("Webhook server running on port 3000"));
```
```python server.py theme={null}
# pip install flask
from flask import Flask, request
app = Flask(__name__)
@app.route("/webhook", methods=["POST"])
def webhook():
item = request.get_json()
# Extract key fields
phone = item.get("PhoneNumber")
tag = item.get("Result", {}).get("Tag", {}).get("Name")
summary = item.get("Result", {}).get("Summary")
print(f"Call processed for {phone}")
print(f"Tag: {tag}")
print(f"Summary: {summary}")
# Access the conversation transcript
messages = item.get("Result", {}).get("Conversation", {}).get("Messages", [])
for msg in messages:
print(f"[{msg['Role']}] {msg['Text']}")
# Access custom metadata
metadata = item.get("Result", {}).get("Metadata", {})
for key, value in metadata.items():
print(f"{key}: {value}")
return "", 200
if __name__ == "__main__":
app.run(port=3000)
```
## Properties
Unique identifier of the campaign item.
Identifier of the campaign this item belongs to.
Date and time the campaign item was created.
Date and time the item was processed.
Date and time of the last call attempt.
Current status of the campaign item. See [RunningStatus](#enum-runningstatus).
Number of attempts made for this item.
Phone number associated with this campaign item.
Date and time of the next call or processing attempt.
Dictionary containing additional information specific to this item (e.g. `firstname`, `email`). Keys correspond to the fields configured in your campaign.
Result of the task associated with this item, including the tag, conversation, summary, and metadata. See [Result](#nested-objects).
Whether the campaign item has been archived.
List of events recorded during the lifecycle of this item. See [TaskEvent](#nested-objects).
## Nested objects
Represents the result of a task or call associated with the campaign item.
| Field | Type | Description |
| -------------- | ------- | -------------------------------------------------------------------------------- |
| `Tag` | object | Call classification tag. See **Tag** below. |
| `Conversation` | object | Messages exchanged during the call. See **Conversation** below. |
| `Summary` | string | AI-generated summary of the call. |
| `IsSystem` | boolean | Whether the result was generated by the system (e.g. no answer, invalid number). |
| `Metadata` | object | Key-value pairs of custom metadata extracted from the call. |
**Tag** and **Metadata** are configurable in the **Reporting** section of your campaign settings.
Categorization information assigned to the call based on your reporting rules.
| Field | Type | Description |
| ------- | ------ | ------------------------------------------------- |
| `_id` | string | Unique identifier of the tag. |
| `Name` | string | Tag name (e.g. `Appointment`, `Not interested`). |
| `Color` | string | Tag color in hexadecimal format (e.g. `#1ee5a6`). |
The conversation object contains the full transcript of the call.
**Conversation fields:**
| Field | Type | Description |
| ---------- | ---------- | --------------------------------------------------- |
| `_id` | string | Unique identifier of the conversation. |
| `Messages` | Message\[] | Ordered list of messages exchanged during the call. |
**Message fields:**
| Field | Type | Description |
| ----------- | -------- | ----------------------------------------------------------- |
| `Timestamp` | DateTime | Date and time of the message. |
| `Role` | string | `user` (the prospect) or `assistant` (the Starleads agent). |
| `Text` | string | Text content of the message. |
| `Intent` | string | Detected intent of the message (can be empty). |
Events recorded during the lifecycle of the campaign item.
| Field | Type | Description |
| ------------- | -------- | -------------------------------------- |
| `Type` | Event | Event type. See [Event](#enum-event). |
| `Date` | DateTime | Date and time when the event occurred. |
| `Description` | string | Optional description of the event. |
## Enums
### Enum: RunningStatus
Indicates the current status of the campaign item.
| Value | Description |
| ------------------ | ------------------------------------------------ |
| `Pending` | Waiting — the task has not started yet. |
| `Calling` | The task is in progress (e.g. call in progress). |
| `Processed` | The task completed successfully. |
| `ProcessingResult` | The result is being processed. |
| `Error` | An error occurred during processing. |
### Enum: Event
Represents the different event types that can occur during the lifecycle of a campaign item.
| Value | Description |
| ------------------ | ----------------------------------- |
| `LaunchCall` | Call started. |
| `ResetCall` | Call reset. |
| `EndCall` | Call ended. |
| `ProcessingResult` | Result processing. |
| `Error` | An error occurred. |
| `PickUp` | The call was picked up by the user. |