Documentation Index Fetch the complete documentation index at: https://developers.nlpearl.ai/llms.txt
Use this file to discover all available pages before exploring further.
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.
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.
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 idstringThe unique identifier of the call. pearlIdstringThe unique identifier of the Pearl used during this call. startTimedatetimeThe date and time when the call processing started. conversationStatusint (enum)The status of the conversation. See Conversation Statuses below. statusint (enum)The overall technical status of the call. See Call Statuses below. fromstringThe phone number from which the call was made. tostringThe phone number to which the call was made. namestringThe name associated with the call, if available. durationintegerThe duration of the call in seconds. recordingstring (URL) A URL to the call recording, if recording is enabled. transcriptobject[]The full conversation transcript as a list of messages. See Transcript Message below. summarystringA concise AI-generated summary of the conversation. collectedInfoobject[]Structured data points collected during the call. See Collected Info below. tagsstring[]Tags or labels triggered during the conversation based on your Pearl configuration. isCallTransferredbooleanWhether the call was transferred to a human agent or external number. overallSentimentint (enum)The overall emotional tone detected from the client. See Sentiment Values below. leadIdstringThe unique identifier of the associated lead, if the call is linked to one. Otherwise null.
Conversation Statuses Value Code Description NeedRetry10 The call will be retried. InCallQueue20 The call is queued and waiting to be placed. OnCall40 The call is currently in progress. VoiceMailLeft70 Pearl reached voicemail and left a message. Success100 The conversation ended with a successful outcome as defined in the Pearl. NotSuccessful110 The conversation ended without achieving the defined success criteria. Completed130 The conversation was completed (neutral outcome). Unreachable150 The lead could not be reached after all attempts. Blacklisted220 The number is blacklisted and will not be contacted. QueueAbandon300 The call was abandoned while in the queue. Error500 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 InProgress3 The call is currently active. Completed4 The call ended normally. Busy5 The line was busy when the call was placed. Failed6 The call could not be connected due to a technical issue. NoAnswer7 The call was not answered within the configured ring duration. Canceled8 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 roleint (enum)The speaker: Pearl (2) or Client (3). contentstringThe text content of the message. startTimefloatThe timestamp (in seconds) when the message started. endTimefloatThe 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 idstringThe ID of the variable as configured in your Pearl. namestringThe display name of the variable. valueanyThe value collected for this variable during the call.
Sentiment Values Value Code Description Negative1 Clear signals of anger, disappointment, or distress. SlightlyNegative2 Some negative emotions present, but overall tone remains close to neutral. Neutral3 Balanced, objective, or factual - no significant positive or negative leanings. SlightlyPositive4 More positive cues than negative, though enthusiasm is mild. Positive5 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 idstring (ObjectId) The unique identifier of the lead in the NLPearl.AI system. pearlIdstringThe unique identifier of the Pearl associated with this lead. externalIdstringThe ID from an external system such as a CRM, for cross-referencing. phoneNumberstringThe phone number of the lead. timeZonestringThe time zone assigned to the lead. statusint (enum)The current status of the lead. See Lead Statuses below. createddatetimeThe date and time when the lead was created. callsIdstring[]A list of all call IDs associated with this lead. callDataobject (key-value) Custom variables provided before the call to personalize the Pearl conversation. collectedDataobject (key-value) Data collected during the call. Keys correspond to variable IDs configured in the Pearl.
callData vs collectedDatacallDatacollectedDataWhen 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 New1 The lead has just been added, no call attempted yet. NeedRetry10 The call will be retried according to the retry configuration. InCallQueue20 The lead is queued and waiting for a call to be placed. WrongCountryCode30 The phone number does not match the campaign’s country code. OnCall40 The lead is currently in an active call. VoiceMailLeft70 Pearl reached voicemail and left a personalized message. Success100 The conversation ended with a successful outcome as defined in the Pearl. NotSuccessful110 The conversation ended without achieving the success criteria. Completed130 All attempts are done (neutral outcome). Unreachable150 The lead could not be reached after all retry attempts. Blacklisted220 The number is blacklisted and will not be contacted. QueueAbandon300 The call was abandoned while in the queue. Error500 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 IdstringThe unique identifier of the call. PearlIdstringThe unique identifier of the Pearl used during this call. RelatedIdstringThe unique identifier of the related inbound or outbound entity (e.g. campaign ID). StartTimedatetimeThe date and time when the call processing started. ConversationStatusint (enum)The status of the conversation. See Conversation Statuses below. Statusint (enum)The overall technical status of the call. See Call Statuses below. FromstringThe phone number from which the call was made. TostringThe phone number to which the call was made. NamestringThe name associated with the call, if available. DurationintegerThe duration of the call in seconds. Recordingstring (URL) A URL to the call recording, if recording is enabled. Transcriptobject[]The full conversation transcript as a list of messages. See Transcript Message below. SummarystringA concise AI-generated summary of the conversation. CollectedInfoobject[]Structured data points collected during the call. See Collected Info below. Tagsstring[]Tags or labels triggered during the conversation. IsCallTransferredbooleanWhether the call was transferred to a human agent or external number. OverallSentimentint (enum)The overall emotional tone detected from the client. See Sentiment Values below. LeadIdstringThe 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 NeedRetry10 The call will be retried. InCallQueue20 The call is queued and waiting to be placed. OnCall40 The call is currently in progress. VoiceMailLeft70 Pearl reached voicemail and left a message. Success100 The conversation ended with a successful outcome as defined in the Pearl. NotSuccessful110 The conversation ended without achieving the defined success criteria. Completed130 The conversation was completed (neutral outcome). Unreachable150 The lead could not be reached after all attempts. Blacklisted220 The number is blacklisted and will not be contacted. QueueAbandon300 The call was abandoned while in the queue. Error500 An error occurred during the conversation.
Call Statuses Value Code Description InProgress3 The call is currently active. Completed4 The call ended normally. Busy5 The line was busy when the call was placed. Failed6 The call could not be connected due to a technical issue. NoAnswer7 The call was not answered within the configured ring duration. Canceled8 The call was canceled before being connected.
Transcript Message Field Type Description Roleint (enum)The speaker: Pearl (2) or Client (3). ContentstringThe text content of the message. StartTimefloatThe timestamp (in seconds) when the message started. EndTimefloatThe timestamp (in seconds) when the message ended.
Collected Info Field Type Description IdstringThe ID of the variable as configured in your Pearl. NamestringThe display name of the variable. ValueanyThe value collected for this variable during the call.
Sentiment Values Value Code Description Negative1 Clear signals of anger, disappointment, or distress. SlightlyNegative2 Some negative emotions present, but overall tone remains close to neutral. Neutral3 Balanced, objective, or factual - no significant positive or negative leanings. SlightlyPositive4 More positive cues than negative, though enthusiasm is mild. Positive5 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 Idstring (ObjectId) The unique identifier of the lead in the NLPearl.AI system. OutboundIdstringThe unique identifier of the outbound campaign or configuration associated with this lead. ExternalIdstringThe ID from an external system such as a CRM, for cross-referencing. PhoneNumberstringThe phone number of the lead. TimeZonestringThe time zone assigned to the lead. Statusint (enum)The current status of the lead. See Lead Statuses below. CreateddatetimeThe date and time when the lead was created. CallsIdstring[]A list of all call IDs associated with this lead. CallDataobject (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 New1 The lead has just been added, no call attempted yet. NeedRetry10 The call will be retried according to the retry configuration. InCallQueue20 The lead is queued and waiting for a call to be placed. WrongCountryCode30 The phone number does not match the campaign’s country code. OnCall40 The lead is currently in an active call. VoiceMailLeft70 Pearl reached voicemail and left a personalized message. Success100 The conversation ended with a successful outcome as defined in the Pearl. NotSuccessful110 The conversation ended without achieving the success criteria. Completed130 All attempts are done (neutral outcome). Unreachable150 The lead could not be reached after all retry attempts. Blacklisted220 The number is blacklisted and will not be contacted. QueueAbandon300 The call was abandoned while in the queue. Error500 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 PascalCasecamelCaseLead: campaign reference OutboundIdpearlIdLead: 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.
Enter Your Webhook URLs
Provide the endpoint URLs for the webhooks you want to receive:
Call Webhook - available for Inbound and Outbound Pearls.Lead Webhook - available for Outbound Pearls only. Your server must respond with an HTTP 200 OK to acknowledge receipt. 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.
