Webhooks - NLPearl Documentation

Overview

When configuring a Pearl, you can set up webhooks to receive real-time notifications at key moments of the call lifecycle. The webhooks available to you depend on whether your Pearl is configured for Inbound or Outbound activity.

Inbound Pearl

Access to the Call Webhook only.

Outbound Pearl

Access to both the Call Webhook and the Lead Webhook.

The Call Webhook payload is identical whether it originates from an Inbound or Outbound Pearl. The Lead Webhook is exclusive to Outbound campaigns, as leads are a concept specific to outbound call management.

Use webhooks only when an external tool needs event notifications. For actual automations tied to how a call ended, rely on Post-Call Actions instead.

Webhook Types

Call Webhook

Triggered at the start and end of every call. Available for both Inbound and Outbound Pearls.

Lead Webhook

Triggered every time a lead changes status. Available for Outbound Pearls only.

Webhook Version

Select the version that matches your Pearl configuration. V2 is the recommended version and is selected by default.

V2 (Latest)
V1

In V2, all JSON payload keys use camelCase (e.g. pearlId, phoneNumber, collectedData).

Call Webhook Payload

The Call Webhook is triggered at the start and at the end of every call. It provides comprehensive data about the call, including its outcome, duration, transcript, and any information collected during the conversation.

Available for both Inbound and Outbound Pearls.

Payload Fields

Field	Type	Description
`id`	`string`	The unique identifier of the call.
`pearlId`	`string`	The unique identifier of the Pearl used during this call.
`startTime`	`datetime`	The date and time when the call processing started.
`conversationStatus`	`int (enum)`	The status of the conversation. See Conversation Statuses below.
`status`	`int (enum)`	The overall technical status of the call. See Call Statuses below.
`from`	`string`	The phone number from which the call was made.
`to`	`string`	The phone number to which the call was made.
`name`	`string`	The name associated with the call, if available.
`duration`	`integer`	The duration of the call in seconds.
`recording`	`string` (URL)	A URL to the call recording, if recording is enabled.
`transcript`	`object[]`	The full conversation transcript as a list of messages. See Transcript Message below.
`summary`	`string`	A concise AI-generated summary of the conversation.
`collectedInfo`	`object[]`	Structured data points collected during the call. See Collected Info below.
`tags`	`string[]`	Tags or labels triggered during the conversation based on your Pearl configuration.
`isCallTransferred`	`boolean`	Whether the call was transferred to a human agent or external number.
`overallSentiment`	`int (enum)`	The overall emotional tone detected from the client. See Sentiment Values below.
`leadId`	`string`	The unique identifier of the associated lead, if the call is linked to one. Otherwise `null`.

Conversation Statuses

Value	Code	Description
`NeedRetry`	10	The call will be retried.
`InCallQueue`	20	The call is queued and waiting to be placed.
`OnCall`	40	The call is currently in progress.
`VoiceMailLeft`	70	Pearl reached voicemail and left a message.
`Success`	100	The conversation ended with a successful outcome as defined in the Pearl.
`NotSuccessful`	110	The conversation ended without achieving the defined success criteria.
`Completed`	130	The conversation was completed (neutral outcome).
`Unreachable`	150	The lead could not be reached after all attempts.
`Blacklisted`	220	The number is blacklisted and will not be contacted.
`QueueAbandon`	300	The call was abandoned while in the queue.
`Error`	500	An error occurred during the conversation.

The definition of Success and NotSuccessful is configured at the Pearl level. Refer to the Create a Pearl page for more details.

Call Statuses

Value	Code	Description
`InProgress`	3	The call is currently active.
`Completed`	4	The call ended normally.
`Busy`	5	The line was busy when the call was placed.
`Failed`	6	The call could not be connected due to a technical issue.
`NoAnswer`	7	The call was not answered within the configured ring duration.
`Canceled`	8	The call was canceled before being connected.

Transcript Message

Each entry in the transcript array represents a single message in the conversation.

Field	Type	Description
`role`	`int (enum)`	The speaker: `Pearl` (2) or `Client` (3).
`content`	`string`	The text content of the message.
`startTime`	`float`	The timestamp (in seconds) when the message started.
`endTime`	`float`	The timestamp (in seconds) when the message ended.

Collected Info

Each entry in the collectedInfo array represents a variable captured during the call.

Field	Type	Description
`id`	`string`	The ID of the variable as configured in your Pearl.
`name`	`string`	The display name of the variable.
`value`	`any`	The value collected for this variable during the call.

Sentiment Values

Value	Code	Description
`Negative`	1	Clear signals of anger, disappointment, or distress.
`SlightlyNegative`	2	Some negative emotions present, but overall tone remains close to neutral.
`Neutral`	3	Balanced, objective, or factual - no significant positive or negative leanings.
`SlightlyPositive`	4	More positive cues than negative, though enthusiasm is mild.
`Positive`	5	Positive emotions, enthusiasm, satisfaction, or gratitude.

Example Payload

{
  "id": "64f3c300e4b0d3a5f1c9e299",
  "pearlId": "64f3b9ffe4b0d3a5f1c9e100",
  "startTime": "2024-06-01T10:15:00Z",
  "conversationStatus": "Success",
  "status": "Completed",
  "from": "+18005550100",
  "to": "+14155552671",
  "name": "John Doe",
  "duration": 142,
  "recording": "https://recordings.nlpearl.ai/calls/64f3c300e4b0d3a5f1c9e299.mp3",
  "transcript": [
    {
      "role": "Pearl",
      "content": "Hi John, this is Pearl calling on behalf of Acme Corp. How are you today?",
      "startTime": 0.0,
      "endTime": 4.2
    },
    {
      "role": "Client",
      "content": "I'm good, thanks. What's this about?",
      "startTime": 4.8,
      "endTime": 7.1
    }
  ],
  "summary": "The lead was informed about the Premium plan and expressed interest in a follow-up.",
  "collectedInfo": [
    {
      "id": "var_001",
      "name": "Interested In Plan",
      "value": "Premium"
    }
  ],
  "tags": ["interested", "callback-requested"],
  "isCallTransferred": false,
  "overallSentiment": "SlightlyPositive",
  "leadId": "64f3c2a1e4b0d3a5f1c9e271"
}

Lead Webhook Payload

The Lead Webhook is triggered every time a lead changes status - at the beginning and at the end of a call. It contains all relevant information about the lead and its current state.

Available for Outbound Pearls only.

Payload Fields

Field	Type	Description
`id`	`string` (ObjectId)	The unique identifier of the lead in the NLPearl.AI system.
`pearlId`	`string`	The unique identifier of the Pearl associated with this lead.
`externalId`	`string`	The ID from an external system such as a CRM, for cross-referencing.
`phoneNumber`	`string`	The phone number of the lead.
`timeZone`	`string`	The time zone assigned to the lead.
`status`	`int (enum)`	The current status of the lead. See Lead Statuses below.
`created`	`datetime`	The date and time when the lead was created.
`callsId`	`string[]`	A list of all call IDs associated with this lead.
`callData`	`object` (key-value)	Custom variables provided before the call to personalize the Pearl conversation.
`collectedData`	`object` (key-value)	Data collected during the call. Keys correspond to variable IDs configured in the Pearl.

`callData` vs `collectedData`

	`callData`	`collectedData`
When	Provided before the call	Filled during the call
Purpose	Personalizes the Pearl’s script and opening	Captures outcomes and responses from the conversation
Example	`{ "firstName": "John", "plan": "Premium" }`	`{ "confirmBooking": true, "rideTime": "Friday 12:00" }`

Lead Statuses

Value	Code	Description
`New`	1	The lead has just been added, no call attempted yet.
`NeedRetry`	10	The call will be retried according to the retry configuration.
`InCallQueue`	20	The lead is queued and waiting for a call to be placed.
`WrongCountryCode`	30	The phone number does not match the campaign’s country code.
`OnCall`	40	The lead is currently in an active call.
`VoiceMailLeft`	70	Pearl reached voicemail and left a personalized message.
`Success`	100	The conversation ended with a successful outcome as defined in the Pearl.
`NotSuccessful`	110	The conversation ended without achieving the success criteria.
`Completed`	130	All attempts are done (neutral outcome).
`Unreachable`	150	The lead could not be reached after all retry attempts.
`Blacklisted`	220	The number is blacklisted and will not be contacted.
`QueueAbandon`	300	The call was abandoned while in the queue.
`Error`	500	An error occurred while processing this lead.

The definition of Success and NotSuccessful is set at the Pearl level. Refer to the Create a Pearl page for details.

Example Payload

{
  "id": "64f3c2a1e4b0d3a5f1c9e271",
  "pearlId": "64f3b9ffe4b0d3a5f1c9e100",
  "externalId": "crm-lead-00482",
  "phoneNumber": "+14155552671",
  "timeZone": "America/New_York",
  "status": "Success",
  "created": "2024-06-01T09:00:00Z",
  "callsId": [
    "64f3c300e4b0d3a5f1c9e299"
  ],
  "callData": {
    "firstName": "John",
    "email": "john.doe@example.com",
    "plan": "Premium"
  },
  "collectedData": {
    "confirmBooking": true,
    "dropOffLocation": "Orly Airport",
    "rideTime": "Friday at 12:00",
    "userIntent": "Book a taxi to the airport"
  }
}

V1 is a legacy version. We recommend migrating to V2 for access to additional fields like collectedData on leads and a more consistent structure.

In V1, all JSON payload keys use PascalCase (e.g. PearlId, PhoneNumber, CollectedInfo).

Call Webhook Payload

The Call Webhook is triggered at the start and at the end of every call.

Available for both Inbound and Outbound Pearls.

Payload Fields

Field	Type	Description
`Id`	`string`	The unique identifier of the call.
`PearlId`	`string`	The unique identifier of the Pearl used during this call.
`RelatedId`	`string`	The unique identifier of the related inbound or outbound entity (e.g. campaign ID).
`StartTime`	`datetime`	The date and time when the call processing started.
`ConversationStatus`	`int (enum)`	The status of the conversation. See Conversation Statuses below.
`Status`	`int (enum)`	The overall technical status of the call. See Call Statuses below.
`From`	`string`	The phone number from which the call was made.
`To`	`string`	The phone number to which the call was made.
`Name`	`string`	The name associated with the call, if available.
`Duration`	`integer`	The duration of the call in seconds.
`Recording`	`string` (URL)	A URL to the call recording, if recording is enabled.
`Transcript`	`object[]`	The full conversation transcript as a list of messages. See Transcript Message below.
`Summary`	`string`	A concise AI-generated summary of the conversation.
`CollectedInfo`	`object[]`	Structured data points collected during the call. See Collected Info below.
`Tags`	`string[]`	Tags or labels triggered during the conversation.
`IsCallTransferred`	`boolean`	Whether the call was transferred to a human agent or external number.
`OverallSentiment`	`int (enum)`	The overall emotional tone detected from the client. See Sentiment Values below.
`LeadId`	`string`	The unique identifier of the associated lead, if applicable. Otherwise `null`.

V1 includes an additional RelatedId field referencing the inbound or outbound entity. This field does not exist in V2.

Conversation Statuses

Value	Code	Description
`NeedRetry`	10	The call will be retried.
`InCallQueue`	20	The call is queued and waiting to be placed.
`OnCall`	40	The call is currently in progress.
`VoiceMailLeft`	70	Pearl reached voicemail and left a message.
`Success`	100	The conversation ended with a successful outcome as defined in the Pearl.
`NotSuccessful`	110	The conversation ended without achieving the defined success criteria.
`Completed`	130	The conversation was completed (neutral outcome).
`Unreachable`	150	The lead could not be reached after all attempts.
`Blacklisted`	220	The number is blacklisted and will not be contacted.
`QueueAbandon`	300	The call was abandoned while in the queue.
`Error`	500	An error occurred during the conversation.

Call Statuses

Value	Code	Description
`InProgress`	3	The call is currently active.
`Completed`	4	The call ended normally.
`Busy`	5	The line was busy when the call was placed.
`Failed`	6	The call could not be connected due to a technical issue.
`NoAnswer`	7	The call was not answered within the configured ring duration.
`Canceled`	8	The call was canceled before being connected.

Transcript Message

Field	Type	Description
`Role`	`int (enum)`	The speaker: `Pearl` (2) or `Client` (3).
`Content`	`string`	The text content of the message.
`StartTime`	`float`	The timestamp (in seconds) when the message started.
`EndTime`	`float`	The timestamp (in seconds) when the message ended.

Collected Info

Field	Type	Description
`Id`	`string`	The ID of the variable as configured in your Pearl.
`Name`	`string`	The display name of the variable.
`Value`	`any`	The value collected for this variable during the call.

Sentiment Values

Value	Code	Description
`Negative`	1	Clear signals of anger, disappointment, or distress.
`SlightlyNegative`	2	Some negative emotions present, but overall tone remains close to neutral.
`Neutral`	3	Balanced, objective, or factual - no significant positive or negative leanings.
`SlightlyPositive`	4	More positive cues than negative, though enthusiasm is mild.
`Positive`	5	Positive emotions, enthusiasm, satisfaction, or gratitude.

Example Payload

{
  "Id": "64f3c300e4b0d3a5f1c9e299",
  "PearlId": "64f3b9ffe4b0d3a5f1c9e100",
  "RelatedId": "64f3c1ffe4b0d3a5f1c9e200",
  "StartTime": "2024-06-01T10:15:00Z",
  "ConversationStatus": "Success",
  "Status": "Completed",
  "From": "+18005550100",
  "To": "+14155552671",
  "Name": "John Doe",
  "Duration": 142,
  "Recording": "https://recordings.nlpearl.ai/calls/64f3c300e4b0d3a5f1c9e299.mp3",
  "Transcript": [
    {
      "Role": "Pearl",
      "Content": "Hi John, this is Pearl calling on behalf of Acme Corp. How are you today?",
      "StartTime": 0.0,
      "EndTime": 4.2
    },
    {
      "Role": "Client",
      "Content": "I'm good, thanks. What's this about?",
      "StartTime": 4.8,
      "EndTime": 7.1
    }
  ],
  "Summary": "The lead was informed about the Premium plan and expressed interest in a follow-up.",
  "CollectedInfo": [
    {
      "Id": "var_001",
      "Name": "Interested In Plan",
      "Value": "Premium"
    }
  ],
  "Tags": ["interested", "callback-requested"],
  "IsCallTransferred": false,
  "OverallSentiment": "SlightlyPositive",
  "LeadId": "64f3c2a1e4b0d3a5f1c9e271"
}

Lead Webhook Payload

The Lead Webhook is triggered every time a lead changes status - at the beginning and at the end of a call.

Available for Outbound Pearls only.

Payload Fields

Field	Type	Description
`Id`	`string` (ObjectId)	The unique identifier of the lead in the NLPearl.AI system.
`OutboundId`	`string`	The unique identifier of the outbound campaign or configuration associated with this lead.
`ExternalId`	`string`	The ID from an external system such as a CRM, for cross-referencing.
`PhoneNumber`	`string`	The phone number of the lead.
`TimeZone`	`string`	The time zone assigned to the lead.
`Status`	`int (enum)`	The current status of the lead. See Lead Statuses below.
`Created`	`datetime`	The date and time when the lead was created.
`CallsId`	`string[]`	A list of all call IDs associated with this lead.
`CallData`	`object` (key-value)	Custom variables provided before the call to personalize the Pearl conversation.

V1 uses OutboundId to reference the campaign. V2 replaces this with pearlId and adds the collectedData field to expose data collected during the call.

Lead Statuses

Value	Code	Description
`New`	1	The lead has just been added, no call attempted yet.
`NeedRetry`	10	The call will be retried according to the retry configuration.
`InCallQueue`	20	The lead is queued and waiting for a call to be placed.
`WrongCountryCode`	30	The phone number does not match the campaign’s country code.
`OnCall`	40	The lead is currently in an active call.
`VoiceMailLeft`	70	Pearl reached voicemail and left a personalized message.
`Success`	100	The conversation ended with a successful outcome as defined in the Pearl.
`NotSuccessful`	110	The conversation ended without achieving the success criteria.
`Completed`	130	All attempts are done (neutral outcome).
`Unreachable`	150	The lead could not be reached after all retry attempts.
`Blacklisted`	220	The number is blacklisted and will not be contacted.
`QueueAbandon`	300	The call was abandoned while in the queue.
`Error`	500	An error occurred while processing this lead.

Example Payload

{
  "Id": "64f3c2a1e4b0d3a5f1c9e271",
  "OutboundId": "64f3c1ffe4b0d3a5f1c9e200",
  "ExternalId": "crm-lead-00482",
  "PhoneNumber": "+14155552671",
  "TimeZone": "America/New_York",
  "Status": "Success",
  "Created": "2024-06-01T09:00:00Z",
  "CallsId": [
    "64f3c300e4b0d3a5f1c9e299"
  ],
  "CallData": {
    "FirstName": "John",
    "Email": "john.doe@example.com",
    "Plan": "Premium"
  }
}

Differences Between V1 and V2

	V1	V2
JSON key format	`PascalCase`	`camelCase`
Lead: campaign reference	`OutboundId`	`pearlId`
Lead: post-call collected data	❌ Not available	✅ `collectedData`
Call: entity reference	`RelatedId`	❌ Removed

Setting Up Webhooks

You can configure webhook URLs directly in your Pearl or outbound campaign settings.

Open Your Campaign Settings

Navigate to the Pearl or outbound campaign you want to configure and open its settings panel.

Locate the Webhook Section

Scroll to the Webhooks section in the configuration form.

Turn Webhooks On

Toggle the Webhooks setting to On. Webhooks are off by default, and the URL fields only appear once it’s enabled.

Enter Your Webhook URLs

Provide the endpoint URLs for the webhooks you want to receive. Your server must respond with an HTTP 200 OK to acknowledge receipt.

Call Webhook - available for Inbound and Outbound Pearls.
Lead Webhook - available for Outbound Pearls only.

Authenticate Your Webhooks (Optional)

For each webhook (Call and Lead), you can attach a Credential so NLPearl.AI authenticates its requests to your endpoint:

Enable the Credentials toggle under the webhook URL.
Select an existing Token, or create one with Add New (use Edit to update an existing one).

The selected credential is sent with every webhook delivery, letting your server verify the request genuinely originates from NLPearl.AI. Available for both Inbound (Call Webhook) and Outbound (Call + Lead Webhook) Pearls.

Credentials work the same way as in the API Node. A token created here can be reused across your webhooks.

Make sure your webhook endpoint is publicly accessible and responds within a reasonable timeout. NLPearl.AI does not retry failed webhook deliveries by default.

Outbound Campaigns

Learn how to create and configure outbound campaigns, including webhook setup.

API Reference – Get Calls

Explore the full call object structure returned by the API.

​Overview

Inbound Pearl

Outbound Pearl

​Webhook Types

Call Webhook

Lead Webhook

​Webhook Version

​Call Webhook Payload

​Payload Fields

​Conversation Statuses

​Call Statuses

​Transcript Message

​Collected Info

​Sentiment Values

​Example Payload

​Lead Webhook Payload

​Payload Fields

​callData vs collectedData

​Lead Statuses

​Example Payload

​Call Webhook Payload

​Payload Fields

​Conversation Statuses

​Call Statuses

​Transcript Message

​Collected Info

​Sentiment Values

​Example Payload

​Lead Webhook Payload

​Payload Fields

​Lead Statuses

​Example Payload

​Differences Between V1 and V2

​Setting Up Webhooks

Outbound Campaigns

API Reference – Get Calls

Overview

Webhook Types

Webhook Version

Call Webhook Payload

Payload Fields

Conversation Statuses

Call Statuses

Transcript Message

Collected Info

Sentiment Values

Example Payload

Lead Webhook Payload

Payload Fields

`callData` vs `collectedData`

Lead Statuses

Example Payload

Call Webhook Payload

Payload Fields

Conversation Statuses

Call Statuses

Transcript Message

Collected Info

Sentiment Values

Example Payload

Lead Webhook Payload

Payload Fields

Lead Statuses

Example Payload

Differences Between V1 and V2

Setting Up Webhooks