Skip to main content

​
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

Log in to Starleads

Go to app.starleads.co and sign in to your account.

Open your Campaign settings

Navigate to the campaign you want to receive webhooks for, and open its Settings panel.

Enter your webhook URL

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 and test

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: 
{
  "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: 
{
  "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: 
// 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"));

​
Properties

​
Id
string
required
Unique identifier of the campaign item.
​
CampaignId
string
required
Identifier of the campaign this item belongs to.
​
CreatedAt
DateTime
required
Date and time the campaign item was created.
​
ProcessedAt
DateTime
Date and time the item was processed.
​
LastCallDate
DateTime
Date and time of the last call attempt.
​
RunningStatus
RunningStatus
required
Current status of the campaign item. See RunningStatus.
​
AttemptCount
int
required
Number of attempts made for this item.
​
PhoneNumber
string
required
Phone number associated with this campaign item.
​
NextTryDate
DateTime
Date and time of the next call or processing attempt.
​
DataBag
object
Dictionary containing additional information specific to this item (e.g. firstname, email). Keys correspond to the fields configured in your campaign.
​
Result
Result object
Result of the task associated with this item, including the tag, conversation, summary, and metadata. See Result.
​
IsArchived
boolean
required
Whether the campaign item has been archived.
​
EventList
TaskEvent[]
List of events recorded during the lifecycle of this item. See TaskEvent.

​
Nested objects

Result

Represents the result of a task or call associated with the campaign item.
FieldTypeDescription
TagobjectCall classification tag. See Tag below.
ConversationobjectMessages exchanged during the call. See Conversation below.
SummarystringAI-generated summary of the call.
IsSystembooleanWhether the result was generated by the system (e.g. no answer, invalid number).
MetadataobjectKey-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.
FieldTypeDescription
_idstringUnique identifier of the tag.
NamestringTag name (e.g. Appointment, Not interested).
ColorstringTag color in hexadecimal format (e.g. #1ee5a6).
The conversation object contains the full transcript of the call.Conversation fields:
FieldTypeDescription
_idstringUnique identifier of the conversation.
MessagesMessage[]Ordered list of messages exchanged during the call.
Message fields:
FieldTypeDescription
TimestampDateTimeDate and time of the message.
Rolestringuser (the prospect) or assistant (the Starleads agent).
TextstringText content of the message.
IntentstringDetected intent of the message (can be empty).
Events recorded during the lifecycle of the campaign item.
FieldTypeDescription
TypeEventEvent type. See Event.
DateDateTimeDate and time when the event occurred.
DescriptionstringOptional description of the event.

​
Enums

​
Enum: RunningStatus

Indicates the current status of the campaign item.
ValueDescription
PendingWaiting — the task has not started yet.
CallingThe task is in progress (e.g. call in progress).
ProcessedThe task completed successfully.
ProcessingResultThe result is being processed.
ErrorAn error occurred during processing.

​
Enum: Event

Represents the different event types that can occur during the lifecycle of a campaign item.
ValueDescription
LaunchCallCall started.
ResetCallCall reset.
EndCallCall ended.
ProcessingResultResult processing.
ErrorAn error occurred.
PickUpThe call was picked up by the user.