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. On a stream call, the `endUserId` (empty without one) on an inbound Pearl, `PearlStream` on an outbound one.
`to`	`string`	The phone number to which the call was made. On a stream call, `PearlStream` on an inbound Pearl, the `endUserId` (empty without one) on an outbound one.
`channel`	`string`	`phone` for a phone call, `stream` for a stream call.
`audioQuality`	`string`	`hd` for a stream call made in `pcm_24000` or `opus_24000`, `phone` for every other call.
`name`	`string`	The name associated with the call, if available.
`duration`	`integer`	The duration of the conversation with Pearl, in seconds (queue and transfer time excluded).
`queueDuration`	`integer`	The time in seconds the caller waited in the inbound queue before Pearl picked up (the whole wait if they hung up while still queued). `null` if the call did not go through the queue.
`transferCallDuration`	`integer`	The duration in seconds of the transferred part of the call, after Pearl handed it over. `null` if the call was not transferred.
`creditDebited`	`integer`	The number of credits debited for the call when the webhook is sent. `0` in the webhook sent at the start of the call.
`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`.

Transferred calls send one more Call Webhook. The one sent when Pearl hands the call over has status InProgress and transferCallDuration set to null. A final webhook follows once the transferred part ends, with the final status, the transferCallDuration and the updated creditDebited.
creditDebited only counts the credits charged before the webhook is sent. A later charge, such as an SMS sent by a Post-Call Action, is not included: the Get Call endpoint returns the final amount.

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",
  "channel": "phone",
  "audioQuality": "phone",
  "name": "John Doe",
  "duration": 142,
  "queueDuration": null,
  "transferCallDuration": null,
  "creditDebited": 24,
  "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. On a stream call, the `endUserId` (empty without one) on an inbound Pearl, `PearlStream` on an outbound one.
`To`	`string`	The phone number to which the call was made. On a stream call, `PearlStream` on an inbound Pearl, the `endUserId` (empty without one) on an outbound one.
`Channel`	`string`	`phone` for a phone call, `stream` for a stream call.
`AudioQuality`	`string`	`hd` for a stream call made in `pcm_24000` or `opus_24000`, `phone` for every other call.
`Name`	`string`	The name associated with the call, if available.
`Duration`	`integer`	The duration of the conversation with Pearl, in seconds (queue and transfer time excluded).
`QueueDuration`	`integer`	The time in seconds the caller waited in the inbound queue before Pearl picked up (the whole wait if they hung up while still queued). `null` if the call did not go through the queue.
`TransferCallDuration`	`integer`	The duration in seconds of the transferred part of the call, after Pearl handed it over. `null` if the call was not transferred.
`CreditDebited`	`integer`	The number of credits debited for the call when the webhook is sent. `0` in the webhook sent at the start of the call.
`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.

Transferred calls send one more Call Webhook. The one sent when Pearl hands the call over has Status InProgress and TransferCallDuration set to null. A final webhook follows once the transferred part ends, with the final Status, the TransferCallDuration and the updated CreditDebited.
CreditDebited only counts the credits charged before the webhook is sent. A later charge, such as an SMS sent by a Post-Call Action, is not included: the Get Call endpoint returns the final amount.

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",
  "Channel": "phone",
  "AudioQuality": "phone",
  "Name": "John Doe",
  "Duration": 142,
  "QueueDuration": null,
  "TransferCallDuration": null,
  "CreditDebited": 24,
  "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 any HTTP 2xx status 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 10 seconds. When a delivery fails (a non-2xx response, an error, or a timeout), NLPearl.AI tries again up to 3 attempts in total, 30 seconds apart. Since a delivery can arrive more than once, make your endpoint idempotent.

If your endpoint is behind a firewall, allow the NLPearl IP addresses listed in IP Whitelisting.

Checking Webhook Deliveries

Every webhook sent for a call appears in that call’s event timeline, in the call details. Each Call Webhook or Lead Webhook event shows the endpoint URL, the number of attempts, and the final status code, or Not sent when the delivery could not leave (for example, when its credential was deleted). Expand the event to see each attempt: its time, its status code, the response time, and the error returned by your server, if any. Use it to check that your endpoint received the data, or to find out why it did not.

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

​Checking Webhook Deliveries

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

Checking Webhook Deliveries