# Quick Start
Source: https://developers.nlpearl.ai/api-reference/api_quickstart

Get started with the NLPearl.AI API by following these simple steps to set up your subscription, API secret key, and authentication.

<div>
  <Frame>
    <div>
      <img alt="NLPearl.AI API cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="NLPearl.AI API cover" />
    </div>
  </Frame>
</div>

## Quick Start with NLPearl.AI API

Getting started with the NLPearl.AI API is straightforward. Follow these steps to set up your subscription, create an API secret key, and authenticate your API requests.

### Step 1: Choose a Subscription

Before you can use the NLPearl.AI API, you need to select a subscription plan that suits your needs. See [Billing](/pages/billing) to view and choose the plan that best fits your requirements.

### Step 2: Create Your Credentials

To interact with the NLPearl.AI API, you need credentials. Open **Settings** on the platform, select the **API Access** page, and create one of the two:

* An [**API secret key**](/api-reference/api_secret_key) - full access to your workspace, for code you own and run yourself. Store it securely.
* An [**OAuth 2.0 app**](/api-reference/oauth) - a Client ID and Client Secret with only the [scopes](/api-reference/oauth#scopes) you select, for a third-party integration or an app that should reach only part of your workspace.

If you are not sure, start with an API secret key and follow the steps below.

### Step 3: Find Your Account ID

Your Account ID is required to authenticate with an API secret key. Open **Settings**, then **General Settings**, and copy it from the **Account ID** field. (An OAuth 2.0 app does not need it - the workspace is already part of its access token.)

### Step 4: Set Up API Authentication

To authenticate your API requests, include your credentials in the header of each request. Check the guide that matches the credentials you created:

<CardGroup>
  <Card title="API Secret Key" icon="key" href="/api-reference/api_secret_key">
    Send your Account ID and secret key as a bearer token.
  </Card>

  <Card title="OAuth 2.0" icon="shield-check" href="/api-reference/oauth">
    Request an access token and scope what an integration can reach.
  </Card>
</CardGroup>

## Conclusion

Starting with the NLPearl.AI API is easy and straightforward. By following these steps, you can quickly set up your account and begin integrating powerful AI capabilities into your applications.


# API Secret Key
Source: https://developers.nlpearl.ai/api-reference/api_secret_key

Authenticate your own backend code with one key: your Account ID and a secret key, sent as a bearer token.

<Note>
  Handing access to someone else? An **OAuth 2.0 app** has its own client ID and
  secret, reaches only the scopes you grant it, and can be rotated on its own -
  see [OAuth 2.0](/api-reference/oauth).
</Note>

## Overview

An API secret key is the simplest way to call the NLPearl API: one key, created in your workspace settings, sent on every request. It carries **full access** to the workspace, which makes it the right credential for code you own and run yourself, and the wrong one to give to a third party.

<Info>
  API keys live on the **API Access** page of your workspace settings. Creating
  one requires an active subscription.
</Info>

***

## Creating an API Key

<Steps>
  <Step title="Open the API Access page">
    Click your **profile card** at the bottom-left corner of the sidebar, open **Settings**, then select **API Access** in the settings menu. You can also go there directly: [platform.nlpearl.ai/app/settings/api](https://platform.nlpearl.ai/app/settings/api).
  </Step>

  <Step title="Open Add API Key">
    Click **Create API Key**. The window that opens holds a **Name** and the
    **Secret Key** itself.
  </Step>

  <Step title="Name it and copy the key">
    Give it a name that identifies where the key will be used - up to 15
    characters - then copy the secret key with the button at the end of the field.
  </Step>

  <Step title="Create the key">
    Click **Create Key**. The key appears in the credentials list, marked with a key glyph and showing its first characters.
  </Step>
</Steps>

You can copy a key again at any time with the **copy** button on its row, and the **delete** button revokes it immediately.

<Warning>
  A secret key carries **full access** to your workspace and cannot be
  restricted to part of it. Keep it server-side, never ship it in a browser, a
  mobile app or a public repository, and never share it with a third party -
  create an [OAuth 2.0 app](/api-reference/oauth) for that instead.
</Warning>

***

## Finding Your Account ID

The header carries two values: your Account ID and the secret key. The **Account ID** identifies your workspace and is on the **General Settings** page of your workspace settings, under that name. It is also shown, with a copy button, in the workspace switcher.

***

## Authorization Header

Send both values as a bearer token, separated by a colon:

```http theme={null}
Authorization: Bearer AccountId:SecretKey
```

For example:

```http theme={null}
Authorization: Bearer 66552698d60e456235eae520:tWPqr5EEZv2dxqutv58NsCg7NuqGc1tX
```

### Example request

```bash theme={null}
curl -X GET "https://api.nlpearl.ai/v2/Pearl" \
     -H "Authorization: Bearer 66552698d60e456235eae520:tWPqr5EEZv2dxqutv58NsCg7NuqGc1tX"
```

Replace `66552698d60e456235eae520` with your Account ID and `tWPqr5EEZv2dxqutv58NsCg7NuqGc1tX` with your secret key.

<Note>
  The key does not expire and there is no token to request first: send the same
  header on every call. Deleting the key on the API Access page is what ends its
  access.
</Note>

***

## Errors

| Status | Meaning                                                                                                                    |
| ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `401`  | The `Authorization` header is missing or malformed, the Account ID and key do not belong together, or the key was deleted. |


# API Authorization
Source: https://developers.nlpearl.ai/api-reference/authorization

Every API request carries an Authorization header. Choose the credential that matches who is making the calls.

## API Authorization Guide

Every request to the NLPearl API must carry an `Authorization` header. There are two kinds of credential behind it, and both are accepted on every `/v2` endpoint - so an integration built against one works against the other without changing a single call.

<CardGroup>
  <Card title="API Secret Key" icon="key" href="/api-reference/api_secret_key">
    One key with full access to your workspace. Best for **your own** backend
    code.
  </Card>

  <Card title="OAuth 2.0" icon="shield-check" href="/api-reference/oauth">
    An app with its own client ID and secret, limited to the **scopes** you
    grant and rotatable on its own. Best for a **third-party** integration.
  </Card>
</CardGroup>

***

## Choosing Between Them

|                      | API secret key                             | OAuth 2.0 app                                                      |
| -------------------- | ------------------------------------------ | ------------------------------------------------------------------ |
| What you send        | `Bearer AccountId:SecretKey` on every call | `Bearer <access_token>`, after requesting a token                  |
| Reach                | The whole workspace, always                | Only the scopes you granted the app                                |
| Lifetime             | The key does not expire                    | Access tokens last one hour; request a new one when they expire    |
| If the secret leaks  | Delete the key and create a new one        | Rotate the app's secret; its client ID and scopes stay as they are |
| Readable again later | Yes, copy it from the credentials list     | No, the client secret is shown once                                |

Both are created on the **API Access** page of your workspace settings, and creating either one requires an active subscription.

***

## Next Steps

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/api-reference/api_quickstart">
    Set up your account and make your first API call.
  </Card>

  <Card title="Python Wrapper" icon="python" href="/api-reference/python_wrapper">
    Call the API from Python without writing the HTTP layer yourself.
  </Card>
</CardGroup>


# Building a Pearl Flow
Source: https://developers.nlpearl.ai/api-reference/building_a_flow

How to build a Pearl as a graph of nodes and transitions through the API, for both Voice and Text.

A **Pearl** can be driven in one of two ways:

* A **Simple Pearl**: a single opening sentence plus a flow script. Created with [Create Pearl](/api-reference/v2/pearlFlow/add-pearl-flow).
* A **Pearl** (the focus of this guide): a **graph of nodes** connected by **transitions**, giving you full control over the conversation, branching, integrations, and post-call automation.

This page explains the node logic: how nodes connect, how the entry point and IDs work, how transitions branch, and what differs between the **Voice** and **Text** channels.

<Note>
  Endpoints for node-graph Pearls:

  * **Voice**: [Create Voice Pearl](/api-reference/v2/pearlFlow/add-voice-pearl), [Update Voice Pearl](/api-reference/v2/pearlFlow/update-voice-pearl)
  * **Text**: [Create Text Pearl](/api-reference/v2/pearlFlow/add-text-pearl), [Update Text Pearl](/api-reference/v2/pearlFlow/update-text-pearl)
  * **Read back**: [Get Pearl Settings](/api-reference/v2/pearlFlow/get-pearl-flow)
</Note>

***

## The mental model

A Pearl flow is a **directed graph**:

* Each **node** does one thing (say something, call an API, send an email, transfer, end the call, ...).
* Each **transition** is a labeled edge from one node to another. The label is a plain-language **condition** that decides when that edge is taken.
* The conversation starts at a single **entry point** and every path eventually reaches the one **EndCall** node.

You send the whole graph in the `pearl.nodes` array. You do not draw the graph visually, you describe it: every node lists its outgoing transitions, and each transition names the `toNodeId` it leads to. The nodes reference each other by ID, so the order inside the array does not matter.

<Note>
  The words "call" and "EndCall" are kept for both channels. On a Text Pearl they simply mean the conversation and the end-of-conversation node.
</Note>

***

## Node types

Every node has a `nodeType` (an integer). This is the single most important field: it decides what the node does and which settings object it must carry.

| `nodeType` | Name                | Channel                    | Carries                                             |
| ---------- | ------------------- | -------------------------- | --------------------------------------------------- |
| `2`        | OpeningSentence     | Both                       | `script` (+ optional `instructions`)                |
| `3`        | PreCallAPI          | Both                       | `apiSettings`                                       |
| `10`       | Dialogue            | Both                       | `script` (+ optional `instructions`)                |
| `31`       | HandoffChatToHuman  | **Text only**              | `handOffAction` (+ optional `script`)               |
| `40`       | API                 | Both                       | `apiSettings`                                       |
| `50`       | SMS                 | **Voice only** (as a node) | `smsSettings`                                       |
| `51`       | Email               | Both                       | `emailSettings`                                     |
| `60`       | TransferCall        | **Voice only**             | `transferCallSettings`                              |
| `65`       | StartCallRecording  | **Voice only**             | nothing (its presence is the whole configuration)   |
| `80`       | SearchKnowledgeBase | Both                       | searches the knowledge base, branches on the result |
| `100`      | EndCall             | Both                       | transitions to post-call containers only            |
| `200`      | PostCallActions     | Both                       | `postCallActions` (a container of actions)          |

<Note>
  Sending a node type that is not allowed for the channel is rejected. For example an SMS node (`50`) or a TransferCall node (`60`) in a Text Pearl, or a HandoffChatToHuman node (`31`) in a Voice Pearl.
</Note>

***

## Anatomy of a node

```json theme={null}
{
  "nodeId": "triage",
  "name": "Triage the caller",
  "nodeType": 10,
  "script": "Are you calling to book a new appointment or to reschedule an existing one?",
  "instructions": "Stay friendly. If the caller is unsure, briefly explain both options.",
  "transitions": [
    { "name": "Wants to book", "toNodeId": "booking" },
    { "name": "Wants to reschedule", "toNodeId": "reschedule" }
  ]
}
```

| Field                                                                    | Meaning                                                                                                 |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `nodeId`                                                                 | **You choose it.** A unique ID for the node within the flow. Transitions reference it.                  |
| `name`                                                                   | A human-readable label for the node (shown in the editor).                                              |
| `nodeType`                                                               | What the node does (see the table above).                                                               |
| `transitions`                                                            | The outgoing edges. Each has a `name` (the condition) and a `toNodeId` (the target).                    |
| `script`                                                                 | `🧩 May support variables` The text for OpeningSentence and Dialogue nodes.                             |
| `instructions`                                                           | `🧩 May support variables` Optional guidance on tone, exceptions, and how closely to follow the script. |
| `apiSettings` / `smsSettings` / `emailSettings` / `transferCallSettings` | The settings object matching the node type.                                                             |
| `handOffAction` / `postCallActions`                                      | Nested lists of action nodes (see below).                                                               |

<Note>
  Only fields marked `🧩 May support variables` accept the `{variableId}` syntax. See [Flow Variables](/api-reference/flow_variables) for the full variable system.
</Note>

***

## Node IDs and transitions

This is the part people get wrong most often, so read it carefully. There are **two kinds of IDs**, and they behave differently.

### Node IDs: you provide them

* **You choose `nodeId`.** It is how the graph wires itself together: a transition points at a node through `toNodeId`, which must equal that node's `nodeId`.
* The `nodeId` must be **unique** within the flow and is capped at **20 characters**. The `name` does **not** have to be unique.
* Pick short, stable, meaningful IDs (`opening`, `triage`, `booking`, `endCall`). You will reuse them across every transition that leads to the node.
* **A node needs at least one of `nodeId` or `name`, and the platform derives the missing one.** Send only a `nodeId` and the `name` is generated from it (`verifyCustomer` → "Verify Customer", `endCall` → "End Call"); send only a `name` and the `nodeId` is generated from it in camelCase ("Verify Customer" → `verifyCustomer`). Send neither and the request is rejected.

<Warning>
  A name-only node gets an **auto-generated `nodeId`** (the camelCase of its `name`, made unique). Because a transition's `toNodeId` must match that id, any node another node points to should carry an explicit `nodeId`, it is the robust path and you still get the `name` for free. Deriving the id from the name is most convenient for nodes nothing transitions to (post-call actions, hand-off sub-actions).
</Warning>

### Transition IDs: you do NOT provide them

A transition only needs two things from you:

| Field      | Meaning                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`     | `🧩 May support variables` The condition, written in plain language ("Caller is a VIP", "Wants to reschedule", "Always"). Must be unique within the node. |
| `toNodeId` | The `nodeId` this transition leads to.                                                                                                                    |

You never send a transition ID. The platform **generates it from the transition `name`** in camelCase ("is successful" becomes `isSuccessful`), adding a numeric suffix on collisions (`isSuccessful1`, `isSuccessful2`). This is why the transition `name` must be unique inside a node.

<Warning>
  Write transition names as readable **conditions**, not code. Use "Age greater than 60", not `{customerAge} > 60`.
</Warning>

**A single transition:**

```json theme={null}
{ "name": "Wants to reschedule", "toNodeId": "reschedule" }
```

***

## The opening

Every flow needs an entry point. In most flows that is a single **OpeningSentence** node (`nodeType: 2`).

```json theme={null}
{
  "nodeId": "opening",
  "name": "Greeting",
  "nodeType": 2,
  "script": "Hi {firstName}, this is {agentName} from Bright Dental. How can I help you today?",
  "transitions": [
    { "name": "Caller states their reason", "toNodeId": "triage" }
  ]
}
```

<Note>
  **The opening script is spoken as written.** Whatever you put in an OpeningSentence node's `script` is what the agent says to open the conversation, close to verbatim. This is different from a **Dialogue** node, where the `script` is a guide that the agent adapts in real time to what the customer says.
</Note>

### The entry point is derived, not sent

You do **not** tell the API which node is first. The entry point is resolved automatically:

* If the flow contains a **PreCallAPI** node, that node is the entry point.
* Otherwise, the single **OpeningSentence** node is the entry point.

Because of this, the opening rules are strict:

* **Without a PreCallAPI**: exactly **one** OpeningSentence node.
* **With a PreCallAPI**: **one or two** OpeningSentence nodes (see the next section).

***

## Pre-call API

A **PreCallAPI** node (`nodeType: 3`) runs an API call **before** the conversation starts, typically to look the customer up so the opening can be personalized. A flow may contain **at most one** PreCallAPI node.

Its transitions are special: each one must set `apiResult`, and each one must lead to an **OpeningSentence** node.

| `apiResult` | Meaning                                       | Generated transition ID |
| ----------- | --------------------------------------------- | ----------------------- |
| `1`         | Success (the API call succeeded)              | `sapisuccess`           |
| `2`         | Failure (the call failed or returned nothing) | `sapinotsuccess`        |

<Note>
  `apiResult` is only valid on the transitions of a PreCallAPI node, and it is required there. It must not appear on any other node's transitions.
</Note>

**One opening (continue on both outcomes):** the Success transition leads to the opening. A Failure transition, if present, must point at that same opening.

**Two openings (branch on the outcome):** the Success transition leads to the "known customer" opening, the Failure transition to the "unknown customer" opening. They must point at two different OpeningSentence nodes.

```json theme={null}
{
  "nodeId": "lookup",
  "name": "Customer lookup",
  "nodeType": 3,
  "apiSettings": {
    "name": "Find customer",
    "method": 1,
    "endpointUrl": "https://crm.example.com/customers?phone={phoneNumber}",
    "description": "Looks up the caller by phone number before greeting.",
    "outputBody": [
      { "key": "firstName", "variableId": "firstName" }
    ]
  },
  "transitions": [
    { "name": "Customer found", "toNodeId": "openingKnown", "apiResult": 1 },
    { "name": "Customer not found", "toNodeId": "openingUnknown", "apiResult": 2 }
  ]
}
```

Here `method: 1` is a GET (see the method codes under [Action nodes](#action-nodes)). `outputBody` maps a field of the API response onto a flow variable so the opening can use `{firstName}`.

***

## Connecting nodes into a sequence

A flow is only valid when it is fully connected. The rules:

* **Exactly one EndCall node** (`nodeType: 100`), and **every path must be able to reach it**.
* **Every non-entry node needs at least one incoming transition.** A node nobody points to is unreachable and rejected. (The one exception is a floating TransferCall node, see below.)
* Transitions may only point at node IDs that exist in the flow.

A simple linear chain looks like this (order in the array does not matter, the `toNodeId` links do the wiring):

```json theme={null}
"nodes": [
  {
    "nodeId": "opening",
    "name": "Greeting",
    "nodeType": 2,
    "script": "Hi {firstName}, how can I help?",
    "transitions": [ { "name": "Continue", "toNodeId": "triage" } ]
  },
  {
    "nodeId": "triage",
    "name": "Triage",
    "nodeType": 10,
    "script": "Do you want to book or reschedule?",
    "transitions": [
      { "name": "Wants to book", "toNodeId": "booking" },
      { "name": "Wants to reschedule", "toNodeId": "endCall" }
    ]
  },
  {
    "nodeId": "booking",
    "name": "Take the booking",
    "nodeType": 10,
    "script": "Great, what day works best for you?",
    "transitions": [ { "name": "Continue", "toNodeId": "endCall" } ]
  },
  {
    "nodeId": "endCall",
    "name": "End",
    "nodeType": 100,
    "transitions": []
  }
]
```

<Tip>
  Give the EndCall node a stable ID like `endCall` and point every terminal branch at it. It keeps the graph easy to reason about, and every action node (transfer, SMS, email) should ultimately continue to it.
</Tip>

***

## Action nodes

Action nodes do work instead of talking. Each carries the settings object that matches its `nodeType`.

| Node               | `nodeType` | Settings object        | Notes                                                      |
| ------------------ | ---------- | ---------------------- | ---------------------------------------------------------- |
| API                | `40`       | `apiSettings`          | Calls an HTTP endpoint mid-conversation.                   |
| SMS                | `50`       | `smsSettings`          | Voice only as a standalone node.                           |
| Email              | `51`       | `emailSettings`        | Sends an email.                                            |
| TransferCall       | `60`       | `transferCallSettings` | Voice only. Hands the call to a phone number.              |
| StartCallRecording | `65`       | none                   | Voice only. Its presence starts recording from that point. |

`apiSettings` (`method` codes: `1` GET, `2` POST, `3` PUT, `4` DELETE, `5` PATCH):

```json theme={null}
{
  "nodeId": "checkAvail",
  "name": "Check availability",
  "nodeType": 40,
  "apiSettings": {
    "name": "Availability",
    "method": 1,
    "endpointUrl": "https://booking.example.com/slots?day={preferredDay}",
    "description": "Returns open appointment slots for the requested day.",
    "outputBody": [ { "key": "slots", "variableId": "availableSlots" } ]
  },
  "transitions": [
    { "name": "Slots available", "toNodeId": "confirm" },
    { "name": "No slots", "toNodeId": "offerCallback" }
  ]
}
```

<Note>
  Action node settings on a node graph carry **no trigger description**: the transitions decide when an action runs, so there is nothing to describe. (The one exception is a *floating* TransferCall, see below.) For the full API body, headers, credentials, and output-schema options, see the [API node](/pages/api_action) guide and [Flow Variables](/api-reference/flow_variables).
</Note>

### TransferCall: wired vs floating (Voice)

A TransferCall node behaves differently depending on how it is reached, and this changes whether `triggerDescription` is required:

| The transfer node is...                           | `triggerDescription` | Behavior                                                                                      |
| ------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------- |
| **Wired** (another node has a transition into it) | **Not allowed**      | The flow decides when the transfer happens.                                                   |
| **Floating** (no incoming transition)             | **Required**         | The agent fires the transfer on its own, based on the description, from anywhere in the call. |

```json theme={null}
{
  "nodeId": "toBilling",
  "name": "Transfer to billing",
  "nodeType": 60,
  "transferCallSettings": {
    "transferCallPhoneNumber": "+12125551234"
  },
  "transitions": [ { "name": "Continue", "toNodeId": "endCall" } ]
}
```

<Note>
  A TransferCall node does **not** need an outgoing transition. Once the call is handed off there is nothing left to branch on, so the platform connects it **straight to the EndCall node** on its own. This holds whether the transfer is **wired** (it has an incoming transition) or **floating** (it has none): in both cases you can leave its `transitions` empty and the post-call flow still runs. The `{ "name": "Continue", "toNodeId": "endCall" }` transition shown above is therefore optional.
</Note>

***

## Post-call actions

Post-call actions run **after** the conversation ends. They are fire-and-forget: the platform sends them and moves on, so they never have transitions and their result is not captured.

The structure has two parts:

1. A **PostCallActions container** node (`nodeType: 200`) whose `postCallActions` array holds the actual action nodes (API `40`, Email `51`, and on Voice also SMS `50`). These inner nodes have **no transitions**.
2. The **EndCall** node's transitions, which point at those containers. **This is the only place EndCall may transition to.** Each transition `name` is the **condition** under which that container fires.

When the call ends, the platform evaluates all of EndCall's transitions at once. Each condition that is true triggers its container, and multiple containers can fire in parallel (logical OR). Use a transition named "Always" for a container that should run on every call.

```json theme={null}
"nodes": [
  {
    "nodeId": "endCall",
    "name": "End",
    "nodeType": 100,
    "transitions": [
      { "name": "Appointment booked", "toNodeId": "postBooked" },
      { "name": "Always", "toNodeId": "postLog" }
    ]
  },
  {
    "nodeId": "postBooked",
    "name": "Booking actions",
    "nodeType": 200,
    "postCallActions": [
      {
        "nodeId": "crmLog",
        "name": "Update CRM",
        "nodeType": 40,
        "apiSettings": {
          "name": "Log booking",
          "method": 2,
          "endpointUrl": "https://crm.example.com/bookings",
          "description": "Records the booking after the call.",
          "body": [
            { "key": "phone", "variableId": "phoneNumber" },
            { "key": "summary", "variableId": "post_call_summary" }
          ]
        }
      }
    ]
  },
  {
    "nodeId": "postLog",
    "name": "Always-on recap",
    "nodeType": 200,
    "postCallActions": [
      {
        "nodeId": "emailRecap",
        "name": "Email recap",
        "nodeType": 51,
        "emailSettings": {
          "to": ["ops@example.com"],
          "subject": "Call recap for {firstName}",
          "body": "Summary: {post_call_summary}"
        }
      }
    ]
  }
]
```

<Note>
  Post-call actions are the only place where **post-call variables** (`post_call_summary`, `post_call_transcript`, `post_call_recording`, ...) are available. See [Flow Variables](/api-reference/flow_variables).
</Note>

***

## Voice vs Text

The node logic above is identical for both channels. The differences are the node types allowed, the model, and a few channel fields.

|                     | Voice Pearl                                                             | Text Pearl                                                                                                                     |
| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Endpoint            | [Create Voice Pearl](/api-reference/v2/pearlFlow/add-voice-pearl)       | [Create Text Pearl](/api-reference/v2/pearlFlow/add-text-pearl)                                                                |
| Model (`modelType`) | `1` Trident, `2` Oyster, `3` Arrow, `4` Hydra (defaults to Arrow)       | `11` Swan only                                                                                                                 |
| Agent identity      | `agents` (voice agents, one per language) + `speechRecognitionKeywords` | `agentName` (single text agent, all languages natively)                                                                        |
| Human escalation    | TransferCall node (`60`) to a phone number                              | HandoffChatToHuman node (`31`)                                                                                                 |
| Voice-only nodes    | SMS (`50`), TransferCall (`60`), StartCallRecording (`65`)              | not available                                                                                                                  |
| Text-only nodes     | not available                                                           | HandoffChatToHuman (`31`)                                                                                                      |
| SMS                 | a standalone SMS node (`50`)                                            | **only inside a Hand-Off** (as a sub-action), never as a standalone node or post-call action                                   |
| Channel binding     | phone number is assigned on the platform                                | `textChannelId` on the inbound/outbound settings (from [Get Text Channels](/api-reference/v2/pearlSettings/get-text-channels)) |

### The Hand-Off node (Text)

The Text equivalent of a transfer. It hands the conversation to a human and can fire inline notifications through its `handOffAction` array. Those sub-actions may be SMS (`50`), Email (`51`), or API (`40`), have **no transitions** of their own, and the Hand-Off node itself transitions to EndCall.

```json theme={null}
{
  "nodeId": "handoff",
  "name": "Escalate to a human",
  "nodeType": 31,
  "script": "Connecting you with a teammate now, one moment.",
  "transitions": [ { "name": "Continue", "toNodeId": "endCall" } ],
  "handOffAction": [
    {
      "nodeId": "notifyTeam",
      "name": "Email the team",
      "nodeType": 51,
      "emailSettings": {
        "to": ["support@example.com"],
        "subject": "Human requested in chat",
        "body": "Customer {firstName} asked for a human."
      }
    }
  ]
}
```

<Note>
  `script` on a Hand-Off is the last line the agent sends before it stops replying. Leave it empty for a silent hand-off.
</Note>

See the [Hand-Off node](/pages/text/handoff_action) guide for the full behavior.

***

## Creating vs updating

### Create

Send the whole thing at once. The request wrapper is the same shape for both channels (only the settings variant differs):

```json theme={null}
{
  "name": "Bright Dental Reception",
  "pearl": {
    "companyName": "Bright Dental",
    "agentPersonality": "Warm and professional",
    "modelType": 3,
    "agents": [ /* voice agents (Voice), or use agentName for Text */ ],
    "nodes": [ /* the full node graph */ ]
  },
  "variables": [ /* your flow variables, see Flow Variables */ ],
  "inbound": { /* OR "outbound": provide exactly one */ }
}
```

* Provide **exactly one** channel: `inbound` **or** `outbound`, never both.
* For a Text Pearl, put the `textChannelId` on the `inbound`/`outbound` settings.
* `variables` defines the flow variables; keep it minimal and only include what you reference. See [Flow Variables](/api-reference/flow_variables).
* The Pearl is created **already published**: the configuration you send becomes its live version.

### Update: `pearl` is a full replace, settings are a patch

The update endpoints ([Update Voice Pearl](/api-reference/v2/pearlFlow/update-voice-pearl), [Update Text Pearl](/api-reference/v2/pearlFlow/update-text-pearl)) treat each part of the request differently. In every case the update applies to the **published version** of the Pearl: if several versions exist on the platform, only the currently published one is modified.

| Part of the request    | Behavior on update                                                                                                                                                |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pearl`                | **Full replacement.** If you send `pearl`, you send the **complete node graph**, it replaces the existing one entirely. Omit `pearl` to leave the flow untouched. |
| `inbound` / `outbound` | **Partial patch.** Only the fields you include are changed; every field you omit keeps its current value.                                                         |
| `name`, `variables`    | Applied when provided.                                                                                                                                            |

<Warning>
  There is no partial edit of a single node. To change one node you resend the entire `pearl.nodes` graph. Fetch the current graph first with [Get Pearl Settings](/api-reference/v2/pearlFlow/get-pearl-flow), modify it, and send it back.
</Warning>

<Note>
  The channel patch works field by field: sending `{ "inbound": { "waitingSentence": "..." } }` changes only the waiting sentence and preserves everything else. This is why `inbound`/`outbound` behave as a patch while `pearl` does not.
</Note>

***

## Validation checklist

Before you send a flow, confirm:

* [ ] Exactly **one EndCall** node, and every node can reach it.
* [ ] Exactly **one OpeningSentence** (or, with a PreCallAPI, one or two).
* [ ] **At most one PreCallAPI**; its transitions all set `apiResult` and lead to OpeningSentence nodes.
* [ ] Every `nodeId` is **unique** and every `toNodeId` points at an existing node.
* [ ] Every non-entry node has an **incoming transition** (except a floating TransferCall).
* [ ] Each node carries the **settings object for its `nodeType`**, and no forbidden node type for the channel.
* [ ] `apiResult` only on PreCallAPI transitions; post-call and hand-off sub-actions have **no transitions**.
* [ ] Transition names are **unique within their node** and written as plain-language conditions.

***

## Related

<CardGroup>
  <Card title="Flow Variables" icon="square-root-variable" href="/api-reference/flow_variables">
    The `{variableId}` syntax, variable groups, and built-in variables.
  </Card>

  <Card title="API Node" icon="code" href="/pages/api_action">
    Request body, headers, credentials, and response output schema.
  </Card>

  <Card title="Get Pearl Settings" icon="gear" href="/api-reference/v2/pearlFlow/get-pearl-flow">
    Read the current flow back before updating it.
  </Card>

  <Card title="Hand-Off Node" icon="headset" href="/pages/text/handoff_action">
    Escalate a Text conversation to a human.
  </Card>
</CardGroup>


# Pearl Flow Variables Guidance
Source: https://developers.nlpearl.ai/api-reference/flow_variables



API variables are placeholders you can embed in specific Pearl Flow fields to make your configuration dynamic (scripts, endpoints, messages, and notifications).

Whenever a field is labeled:

`🧩 May support variables`

you can insert variables using this syntax:

```text theme={null}
{variableId}

```

Example:

```text theme={null}
Hello {firstName}, this is {agentName}.

```

***

## Variable Groups

Variables belong to one of three groups.

### Pre-call variables (Group = `PreCall`)

Pre-call variables are expected to be available **before** the call starts (for example from your lead import, CSV mapping, or an API integration).

If a pre-call value is missing, it’s not always blocking, depending on your flow, the agent may still collect it during the call.

Common usage:

* Opening sentence
* Pre-call API actions
* Endpoint URLs and message templates (when supported)

**Opening sentence example (pre-call only):**

```text theme={null}
Hello, I’m {agentName}. Am I speaking with {firstName}?

```

***

### In-call variables (Group = `InCall`)

In-call variables are collected or updated **during** the call.

Common usage:

* In-call API actions
* Email/SMS templates (when supported)
* Flow scripts (when supported)

**Script example (collecting an in-call variable):**

```text theme={null}
Please tell me your address. I will store it as {customerAddress}.

```

***

### Post-call variables (Group = `PostCall`)

Post-call variables are generated **after** the call ends (transcript, summary, duration, etc.).

You **cannot create** post-call variables manually, as they are pre-defined by the platform.

Common usage:

* End-call notifications (Email / API)

***

## Built-in Variables (Reserved IDs)

Some variables are built into the platform and already exist by default.

Because they are reserved, \*\*you cannot create a new variable using the same `id**` as a built-in variable.
If you try, the API will reject it as a duplicate ID.

### Built-in Pre-call Variables

| ID                 | Name               | Description                                                                                                   |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------- |
| `agentName`        | Agent Name         | The name of the agent.                                                                                        |
| `agentPhoneNumber` | Agent Phone Number | The Pearl's own phone line for the current conversation. Read-only; empty on channels without a phone number. |
| `firstName`        | First Name         | The customer's first name formatted as a proper first name.                                                   |
| `lastName`         | Last Name          | The customer's last name formatted as a proper last name.                                                     |
| `emailAddress`     | Email Address      | The customer's email address in a standard format (RFC 5321 / RFC 5322).                                      |
| `phoneNumber`      | Phone Number       | The customer's phone number with country code (digits + optional `+`).                                        |
| `callId`           | Call ID            | The identifier of the call.                                                                                   |

<Warning>
  `agentPhoneNumber` is empty on channels without a phone number, including Telegram and browser Test Chat. An API node does not execute when it references an empty required pre-call variable, so only use this variable in API nodes for channels that have a phone number.
</Warning>

### Built-in In-call Variables

There are currently **no built-in in-call variables**.
In-call variables are typically created per Pearl to match what you want to collect during the conversation.

### Built-in Post-call Variables

| ID                     | Name            | Description                                  |
| ---------------------- | --------------- | -------------------------------------------- |
| `post_call_duration`   | Call Duration   | Duration of the call.                        |
| `post_call_summary`    | Call Summary    | Summary generated after the call concludes.  |
| `post_call_transcript` | Call Transcript | Transcript of the call for reference.        |
| `post_call_call_time`  | Call Time       | Timestamp indicating when the call occurred. |
| `post_call_recording`  | Recording Link  | Link to the call recording.                  |

***

## Where Variables Are Supported

Only fields explicitly marked with:

`🧩 May support variables`

support the `{variableId}` syntax.

Typical examples include:

* Flow scripts (when enabled)
* API endpoint URLs
* API body values (when the body field is a string)
* API response output paths (the **JSON Path** column of a Response Output Schema) — not labeled, see the note below
* SMS / Email templates (depending on the action timing)
* End-call notifications (supports post-call variables)

<Note>
  Only fields that support variables will be labeled with `🧩 May support variables`.
  If the field is not labeled, assume it is static-only.

  The one exception is the **JSON Path** column of an API action's Response Output Schema: it carries no label, but it does accept `{variableId}` placeholders. See [Using variables in API response output paths](#4-use-variables-in-api-response-output-paths).
</Note>

***

## Using Variables in API Requests

### 1) Use variables inside scripts

Example script snippet:

```text theme={null}
Ask the caller for their address and store it in {customerAddress}.
If {customerAddress} is empty, ask again politely.

```

***

### 2) Use variables in API action endpoint URLs

Example:

```text theme={null}
https://example-crm.com/leads?phone={phoneNumber}&name={firstName}

```

***

### 3) Use variables in API action body values (string)

If a body field is a string value, it can include variables:

```json theme={null}
{
  "key": "message",
  "type": "String",
  "value": "New call completed for {firstName} {lastName}."
}

```

<Note>
  **API Body Exception (VariableId field)**

  When configuring an API action body, the `VariableId` property must contain the **raw variable ID without brackets**.
  Example: use `firstName` (not `{firstName}`).

  This is a special case for the API body schema only. Everywhere else, variables are inserted using `{variableId}`.
</Note>

***

### 4) Use variables in API response output paths

The **JSON Path** column of a [Response Output Schema](/pages/api_action#path-syntax) accepts variables, so the value you extract can depend on what the conversation has already collected.

Example path:

```text theme={null}
collection[?(@.start_time startswith '{preferredDateIso}')][0].start_time

```

The placeholder is replaced with the variable's current value before the API response is read.

***

### 5) Use post-call variables in End-call notifications

Example email body:

```text theme={null}
Call ended for {firstName} {lastName}.
Summary: {post_call_summary}
Transcript: {post_call_transcript}
Recording: {post_call_recording}
Duration: {post_call_duration}

```

***

## Best Practices

* Use short, stable variable IDs (e.g., `customerAddress`, `membershipStatus`).
* Treat built-in variable IDs as reserved keywords.
* Use post-call variables only in end-call notifications.
* Avoid defining variables you never reference in your flow.

***

## Quick Reference

* **Syntax:** `{variableId}`
* **Groups:** `PreCall` / `InCall` / `PostCall`
* **Built-in InCall variables:** none
* **Post-call variables:** available inside end-call notifications only


# OAuth 2.0
Source: https://developers.nlpearl.ai/api-reference/oauth

Give an integration its own credential: a client ID and secret, only the scopes you grant it, and a secret you can rotate on your own.

<Note>
  Looking for the simpler scheme? An **API key** is one secret with full access
  to your workspace, best for your own backend code - see [API Secret
  Key](/api-reference/api_secret_key).
</Note>

## Overview

An **OAuth 2.0 app** is a credential with a client ID, a client secret you can rotate, and a set of scopes that decide exactly what it may reach.

NLPearl implements the **client credentials** grant: the app authenticates with its own credentials and receives an access token limited to the scopes you granted it. There is no redirect, no login screen and no end user in the loop - it is machine-to-machine authentication.

<Info>
  OAuth 2.0 apps and API keys both live on the **API Access** page of your
  workspace settings. Creating either one requires an active subscription.
</Info>

***

## Creating an OAuth 2.0 App

<Steps>
  <Step title="Open the API Access page">
    Click your **profile card** at the bottom-left corner of the sidebar, open **Settings**, then select **API Access** in the settings menu. You can also go there directly: [platform.nlpearl.ai/app/settings/api](https://platform.nlpearl.ai/app/settings/api).

    <Frame>
      <img alt="API Access page with the Create OAuth 2.0 App button" />
    </Frame>
  </Step>

  <Step title="Add OAuth 2.0 App">
    Click **Create OAuth 2.0 App**. The window that opens holds everything the app
    is made of: a **Name**, its **Client ID** and **Client Secret**, and the
    **Scopes** it is allowed to use.

    <Frame>
      <img alt="Create OAuth 2.0 App dialog" />
    </Frame>
  </Step>

  <Step title="Name it and choose its scopes">
    Give it a name that identifies the integration. Then select its scopes,
    grouped under **Pearls**, **Account** and **Billing**. Grant the fewest the
    integration actually needs.
  </Step>

  <Step title="Copy the Client ID and Client Secret, then create">
    Both are already filled in, above the scopes - copy them and only then click **Create App**.
  </Step>
</Steps>

<Warning>
  **The client secret is shown once, in that window** - reopening the app later
  shows only its first characters. Treat it as a password: keep it server-side,
  never ship it in a browser, a mobile app or a public repository. If you lose
  it or it leaks, [rotate it](#rotating-the-client-secret).
</Warning>

***

## Requesting an Access Token

```http theme={null}
POST https://api.nlpearl.ai/oauth/token
Content-Type: application/x-www-form-urlencoded
```

<Note>
  The token endpoint sits at the **root** of the API host. Unlike every other
  Client API route, it is **not** under `/v2`.
</Note>

### Request parameters

| Parameter       | Required | Description                                                                                   |
| --------------- | -------- | --------------------------------------------------------------------------------------------- |
| `grant_type`    | Yes      | Must be `client_credentials`. No other grant type is supported.                               |
| `client_id`     | Yes      | Your app's Client ID.                                                                         |
| `client_secret` | Yes      | Your app's Client Secret.                                                                     |
| `scope`         | No       | Space-separated list of scopes to request. Omit it to receive every scope granted to the app. |

Your credentials can be sent either in the request body or in an HTTP Basic header. Both methods are supported and issue the same token.

<Tabs>
  <Tab title="Credentials in the body">
    Also known as `client_secret_post`.

    ```bash theme={null}
    curl -X POST "https://api.nlpearl.ai/oauth/token" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         -d "grant_type=client_credentials" \
         -d "client_id=6a6c72b69b39e6add21204e7" \
         -d "client_secret=YOUR_CLIENT_SECRET"
    ```
  </Tab>

  <Tab title="Basic authentication header">
    Also known as `client_secret_basic`. The header value is `base64(client_id:client_secret)`.

    ```bash theme={null}
    curl -X POST "https://api.nlpearl.ai/oauth/token" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         -u "6a6c72b69b39e6add21204e7:YOUR_CLIENT_SECRET" \
         -d "grant_type=client_credentials"
    ```
  </Tab>
</Tabs>

<Warning>
  Send your credentials **one way or the other, never both**. A request carrying
  a Basic header *and* a `client_secret` in the body is rejected with `400
      invalid_request`.
</Warning>

### Response

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "pearls:read pearls:calls pearls:analytics"
}
```

| Field          | Description                                                                       |
| -------------- | --------------------------------------------------------------------------------- |
| `access_token` | The token to send on your API calls.                                              |
| `token_type`   | Always `Bearer`.                                                                  |
| `expires_in`   | Token lifetime in seconds - **3600**, one hour.                                   |
| `scope`        | The scopes actually granted to this token. Read it to know what the token can do. |

<Note>
  There is **no refresh token**. When a token expires, request a new one with
  the same credentials. **Cache the token and reuse it** for its whole lifetime.
  Do not request a new one on every API call.
</Note>

***

## Calling the API

Send the access token as a bearer token on any `/v2` endpoint:

```bash theme={null}
curl -X GET "https://api.nlpearl.ai/v2/Pearl" \
     -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

<Note>
  There is no `AccountId:` prefix here, unlike the [secret key
  scheme](/api-reference/api_secret_key) - the workspace the token belongs to is
  already part of the token.
</Note>

***

## Scopes

A scope is a permission. An app only reaches what its scopes allow; everything else is refused with `403`.

The tables below map every checkbox in the **OAuth 2.0 App** window - grouped **Pearls**, **Account** and **Billing**, exactly as the platform groups them - to the scope string it produces in the token.

### Pearls

| In the platform                                        | Scope              | What it reaches                                                                               |
| ------------------------------------------------------ | ------------------ | --------------------------------------------------------------------------------------------- |
| View pearls                                            | `pearls:read`      | Listing Pearls, inbounds and campaigns, and reading one of them                               |
| Create and edit, including access to PearlVibe         | `pearls:write`     | Creating and updating Pearls, conversation flows, voice and text settings, and the voice list |
| Moderate activity status - Allow changing pearl status | `pearls:moderate`  | Running and pausing a Pearl, resetting customer memory                                        |
| View analytics                                         | `pearls:analytics` | Pearl, inbound and outbound analytics                                                         |
| View and moderate leads                                | `pearls:leads`     | Reading, adding, updating and deleting outbound leads                                         |
| View calls and post-call information                   | `pearls:calls`     | Calls and recordings, placing and deleting calls, call requests                               |

<Note>
  **Any Pearls scope also grants `pearls:read`.** Every integration needs to
  list Pearls to resolve their ids, so selecting *View calls* alone still yields
  `pearls:read pearls:calls` - you will see it in the token's `scope`.
</Note>

### Account

| In the platform                                     | Scope                   | What it reaches                               |
| --------------------------------------------------- | ----------------------- | --------------------------------------------- |
| Manage phone numbers                                | `account:phone_numbers` | The account's phone numbers and text channels |
| Manage users                                        | `account:users`         | The account's users                           |
| Manage advanced settings - security, sessions, etc. | `account:advanced`      | The account blacklist: search, add, remove    |
| View audit log                                      | `account:audit_log`     | The audit log                                 |

<Note>
  `GET /v2/Account/Voices` sits under `pearls:write`, not under an account
  scope: the list of voices is part of building a Pearl.
</Note>

### Billing

| In the platform        | Scope             | What it reaches                                            |
| ---------------------- | ----------------- | ---------------------------------------------------------- |
| Manage account billing | `account:billing` | Account information and credit balance - `GET /v2/Account` |

### Changing an app's scopes

Open the app with the **edit** button, tick or untick scopes, then click **Save Scopes**.

<Frame>
  <img alt="Edit OAuth 2.0 App scopes" />
</Frame>

Scope changes apply to **newly issued tokens**. A token issued before the change keeps the scopes it was created with until it expires.

***

## Errors

### Token endpoint

| Status | `error`                  | When                                                                                    |
| ------ | ------------------------ | --------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`        | `grant_type` is missing, or credentials were sent in the Basic header **and** the body. |
| `400`  | `unsupported_grant_type` | `grant_type` is anything other than `client_credentials`.                               |
| `400`  | `invalid_scope`          | A requested `scope` is not a known scope string, or is one the app was not granted.     |
| `401`  | `invalid_client`         | Unknown `client_id`, wrong `client_secret`, or the app was deleted.                     |
| `405`  | -                        | The endpoint only accepts `POST`.                                                       |

Every error comes back as JSON:

```json theme={null}
{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}
```

### API endpoints

| Status | Meaning                                                            |
| ------ | ------------------------------------------------------------------ |
| `401`  | The token is missing, malformed, or expired. Request a new token.  |
| `403`  | The token is valid but **lacks the scope** this endpoint requires. |

A `403` carries a challenge header and a machine-readable body:

```http theme={null}
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                  error_description="The token does not carry the scope required by this endpoint"
```

```json theme={null}
{
  "error": "insufficient_scope",
  "error_description": "The token does not carry the scope required by this endpoint"
}
```

<Warning>
  Handle `403` and `401` differently. A `401` means *get a new token*; a `403`
  means *this app was never granted the scope* - requesting another token will
  return the same result. Retrying a `403` in a loop will never succeed.
</Warning>

***

## Rotating the Client Secret

Rotation replaces an app's secret without changing its Client ID, its scopes, or anything else about it. Use it when a secret may have been exposed, or as routine hygiene.

<Steps>
  <Step title="Open the app">
    On the **API Access** page, open the OAuth 2.0 app with the **edit** button.
  </Step>

  <Step title="Rotate the secret">
    Click the **rotate** button next to **Client Secret**.
  </Step>

  <Step title="Copy the new secret">
    The new secret replaces the masked one in the field - copy it before closing the window.
  </Step>
</Steps>

<Warning>
  The previous secret stops working as soon as you rotate. Every integration
  using it must be updated with the new secret, or it will start receiving `401
      invalid_client`.
</Warning>

Access tokens that were already issued stay valid until they expire - rotation blocks new tokens, it does not revoke the ones already in circulation. To cut an integration off immediately, delete the app with the **delete** button on the API Access page.

***

## Token Format and Discovery

You do not need any of this to call the API, but it is there if your OAuth client expects it.

Access tokens are **RS256-signed JWTs**. You can verify a token's signature against the public keys published in the JWKS below.

| Claim                      | Value                                                |
| -------------------------- | ---------------------------------------------------- |
| `iss`, `aud`               | Both `https://api.nlpearl.ai`                        |
| `sub`                      | The **Client ID** of the app the token was issued to |
| `account_id`               | The **Account ID** of your workspace                 |
| `scope`                    | The granted scopes, space separated                  |
| `jti`, `iat`, `nbf`, `exp` | Token id, issued-at, not-before and expiry           |

| Endpoint                                                                                                                         | Purpose                                                                                                 |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [`https://api.nlpearl.ai/.well-known/oauth-authorization-server`](https://api.nlpearl.ai/.well-known/oauth-authorization-server) | Authorization server metadata: token endpoint, supported grant types and auth methods, full scope list. |
| [`https://api.nlpearl.ai/.well-known/jwks.json`](https://api.nlpearl.ai/.well-known/jwks.json)                                   | Public keys used to verify token signatures.                                                            |

Both are public and require no authentication.


# Python Wrapper
Source: https://developers.nlpearl.ai/api-reference/python_wrapper

Learn how to use the NLPearl Python wrapper to interact with the NLPearl API effortlessly.

# NLPearl Python Wrapper

The NLPearl Python wrapper provides a simple and intuitive way to interact with the NLPearl API directly from your Python applications. This package simplifies the integration of NLPearl's conversational AI capabilities into your projects.

## Installation

Install the package via pip:

```bash theme={null}
pip install nlpearl
```

You can find the package on PyPI: [NLPearl Python Wrapper on PyPI](https://pypi.org/project/nlpearl/)

## Getting Started

Before using the `nlpearl` package, you need to obtain an API key from NLPearl. You can request one by contacting our support team.

### Setting Your API Key

Set your API key before making any API calls:

```python theme={null}
import nlpearl as pearl

# Set your API key
pearl.api_key = "your_api_key_here"
```

## Usage Examples

### Retrieve Account Information

```python theme={null}
import nlpearl as pearl

# Set your API key
pearl.api_key = "your_api_key_here"

# Retrieve account information
account_info = pearl.Account.get_account()
print(account_info)
```

### Make an Outbound Call

```python theme={null}
import nlpearl as pearl

# Set your API key
pearl.api_key = "your_api_key_here"

# Define the outbound ID and the phone number to call
outbound_id = "your_outbound_id"
phone_number = "+1234567890"

# Make an outbound call
call_response = pearl.Outbound.make_call(
    outbound_id,
    to=phone_number,
    call_data={"firstName": "John", "lastName": "Doe"}
)
print(call_response)
```

These examples demonstrate how easy it is to integrate NLPearl's services into your Python applications using the `nlpearl` package.

## Additional Resources

* [NLPearl Python Wrapper on PyPI](https://pypi.org/project/nlpearl/)
* For detailed documentation on all available endpoints and functionalities, please refer to the endpoints documentation below.

***


# Get Account
Source: https://developers.nlpearl.ai/api-reference/v1/account/get-account

get /v1/Account
Retrieves account details



# Delete Calls
Source: https://developers.nlpearl.ai/api-reference/v1/call/delete-call

delete /v1/Call
Deletes one or more calls



# Get Call
Source: https://developers.nlpearl.ai/api-reference/v1/call/get-call

get /v1/Call/{callId}
Retrieves all the information about a call



# Get Analytics
Source: https://developers.nlpearl.ai/api-reference/v1/inbound/get-analytics

post /v1/Inbound/{inboundId}/Analytics
Retrieves analytics data for a specific inbound campaign within a given date range.



# Get Inbound
Source: https://developers.nlpearl.ai/api-reference/v1/inbound/get-inbound

get /v1/Inbound/{inboundId}
Retrieves a specific inbound by its ID



# Get Inbound Ongoing Calls
Source: https://developers.nlpearl.ai/api-reference/v1/inbound/get-inbound-ongoing-calls

get /v1/Inbound/{inboundId}/OngoingCalls
Returns the number of active calls currently in progress and in queue for the specified inbound ID.



# Get Inbounds
Source: https://developers.nlpearl.ai/api-reference/v1/inbound/get-inbounds

get /v1/Inbound
Retrieves all inbounds



# Search Calls
Source: https://developers.nlpearl.ai/api-reference/v1/inbound/search-calls

post /v1/Inbound/{inboundId}/Calls
Retrieves the calls within a specific date range of inbound



# Set Activity State
Source: https://developers.nlpearl.ai/api-reference/v1/inbound/set-activity-state

post /v1/Inbound/{inboundId}/Active
Run or Pause a specific inbound



# Add Lead
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/add-lead

put /v1/Outbound/{outboundId}/Lead
Adds a new lead to a specified outbound



# Delete Leads
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/delete-leads

delete /v1/Outbound/{outboundId}/Leads
Deletes one or more leads associated with a specific outbound campaign.



# Delete leads Via External
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/delete-leads-external-id

delete /v1/Outbound/{outboundId}/Leads/External
Deletes one or more leads associated with a specific outbound campaign.



# Get Analytics
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/get-analytics

post /v1/Outbound/{outboundId}/Analytics
Retrieves analytics data for a specific outbound campaign within a given date range.



# Get Call Request
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/get-call-request

get /v1/Outbound/CallRequest/{requestId}
Fetches detailed information about a specific API request identified by its unique requestId.



# Get Lead
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/get-lead

get /v1/Outbound/{outboundId}/Lead/{leadId}
Retrieves details of a specific lead within a outbound



# Get Lead via External ID
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/get-lead-via-external-id

get /v1/Outbound/{outboundId}/Lead/External/{externalId}
Retrieves details of a specific lead within an outbound



# Get Lead via Phone Number
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/get-lead-via-phone-number

get /v1/Outbound/{outboundId}/Lead/PhoneNumber/{phoneNumber}
Retrieves details of a specific lead within an outbound via phone number



# Get Outbound
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/get-outbound

get /v1/Outbound/{outboundId}
Retrieve a specific outbound by its ID



# Get Outbounds
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/get-outbounds

get /v1/Outbound
Retreive all the Outbounds



# Make Call
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/make-call

post /v1/Outbound/{outboundId}/Call
Initiates an outbound phone call associated with the specified outbound ID. The request body must contain the necessary details for making the call. Once initiated, the call will be routed to the first available agent.



# Search Call Requests
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/search-call-requests

post /v1/Outbound/{outboundId}/CallRequest
Fetches a list of API call requests associated with a specific outbound identifier. The search criteria, such as filters or pagination options, should be provided in the request body.



# Search Calls
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/search-calls

post /v1/Outbound/{outboundId}/Calls
Retrieves the calls within a specific date range for a given outbound



# Search Leads
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/search-leads

post /v1/Outbound/{outboundId}/Leads
Retrieves the leads associated with a specific outbound



# Set Activity State
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/set-activity-state

post /v1/Outbound/{outboundId}/Active
Activates or deactivates a specified outbound



# Update Lead
Source: https://developers.nlpearl.ai/api-reference/v1/outbound/update-lead

put /v1/Outbound/{outboundId}/Lead/{leadId}
Updates the details of an existing lead associated with a specific outbound campaign.



# Reset Customer Memory
Source: https://developers.nlpearl.ai/api-reference/v1/pearl/reset-memory

put /v1/Pearl/{pearlId}/Memory/{phoneNumber}/Reset
Resets stored memory associated with a specific customer's phone number for a given Pearl.



# Add Phone Numbers To Blacklist
Source: https://developers.nlpearl.ai/api-reference/v2/account/add-to-blacklist

post /v2/Account/Blacklist
Adds one or more phone numbers to the account blacklist.



# Get Account
Source: https://developers.nlpearl.ai/api-reference/v2/account/get-account

get /v2/Account
Retrieves account details



# Get Users
Source: https://developers.nlpearl.ai/api-reference/v2/account/get-account-users

get /v2/Account/Users
Retrieves the list of users for the account



# Get Audit Log
Source: https://developers.nlpearl.ai/api-reference/v2/account/get-audit-log

post /v2/Account/AuditLog
Retrieves the audit log.



# Remove Phone Numbers From Blacklist
Source: https://developers.nlpearl.ai/api-reference/v2/account/remove-from-blacklist

post /v2/Account/Blacklist/Remove
Removes one or more phone numbers from the account blacklist.



# Search Blacklist
Source: https://developers.nlpearl.ai/api-reference/v2/account/search-blacklist

post /v2/Account/Blacklist/Search
Retrieves the paginated blacklist phone numbers of the account.



# Delete Calls
Source: https://developers.nlpearl.ai/api-reference/v2/call/delete-call

delete /v2/Call
Deletes one or more calls



# Get Call
Source: https://developers.nlpearl.ai/api-reference/v2/call/get-call

get /v2/Call/{callId}
Retrieves all the information about a call



# Get Call Recording
Source: https://developers.nlpearl.ai/api-reference/v2/call/get-recording

get /v2/Recording/{clientId}/{pearlId}/{callId}
Retrieves the audio recording for a specific call. If the client has public recordings enabled, the endpoint can be accessed anonymously; otherwise, a valid Authorization header matching the client is required. Recordings hosted on Twilio are returned as a permanent redirect, while recordings stored internally are converted from WAV to Opus (audio/ogg) and streamed back with range processing enabled for browser seeking.



# Add Lead
Source: https://developers.nlpearl.ai/api-reference/v2/outbound/add-lead

post /v2/Outbound/{pearlId}/Lead
Adds a new lead to a specified outbound



# Add Leads
Source: https://developers.nlpearl.ai/api-reference/v2/outbound/add-leads

post /v2/Outbound/{pearlId}/Leads/Add
Adds new leads to a specified outbound



# Delete Leads
Source: https://developers.nlpearl.ai/api-reference/v2/outbound/delete-leads

delete /v2/Outbound/{pearlId}/Leads
Deletes one or more leads associated with a specific outbound campaign.



# Delete leads Via External
Source: https://developers.nlpearl.ai/api-reference/v2/outbound/delete-leads-external-id

delete /v2/Outbound/{pearlId}/Leads/External
Deletes one or more leads associated with a specific outbound campaign.



# Get Lead
Source: https://developers.nlpearl.ai/api-reference/v2/outbound/get-lead

get /v2/Outbound/{pearlId}/Lead/{leadId}
Retrieves details of a specific lead within a outbound



# Get Lead Via External ID
Source: https://developers.nlpearl.ai/api-reference/v2/outbound/get-lead-via-external-id

get /v2/Outbound/{pearlId}/Lead/External/{externalId}
Retrieves details of a specific lead within an outbound



# Find Lead Via Phone Number
Source: https://developers.nlpearl.ai/api-reference/v2/outbound/get-lead-via-phone-number

get /v2/Outbound/{pearlId}/Lead/PhoneNumber/{phoneNumber}
Retrieves details of a specific lead within an outbound via phone number



# Search Leads
Source: https://developers.nlpearl.ai/api-reference/v2/outbound/search-leads

post /v2/Outbound/{pearlId}/Leads
Retrieves the leads associated with a specific outbound



# Update Lead
Source: https://developers.nlpearl.ai/api-reference/v2/outbound/update-lead

put /v2/Outbound/{pearlId}/Lead/{leadId}
Updates the details of an existing lead associated with a specific outbound campaign.



# Get analytics
Source: https://developers.nlpearl.ai/api-reference/v2/pearl/get-analytics

post /v2/Pearl/{pearlId}/Analytics



# Get Calls
Source: https://developers.nlpearl.ai/api-reference/v2/pearl/get-calls

post /v2/Pearl/{pearlId}/Calls
Retrieves the calls within a specific date range of a pearl



# Get Calls Bulk
Source: https://developers.nlpearl.ai/api-reference/v2/pearl/get-calls-bulk

post /v2/Pearl/{pearlId}/Calls/Bulk
Retrieves calls within a date range like Get Calls, but lets the caller opt into additional fields (transcript, collected info, summary, recording, sentiment, credits, ...) via the Fields property. Only the requested fields are returned.



# Get Ongoing Calls
Source: https://developers.nlpearl.ai/api-reference/v2/pearl/get-ongoing-calls

get /v2/Pearl/{pearlId}/OngoingCalls
Returns the number of active calls currently in progress for the specified Pearl. If the Pearl has inbound configurations, it also returns the number of calls currently in queue.



# Get Pearl
Source: https://developers.nlpearl.ai/api-reference/v2/pearl/get-pearl

get /v2/Pearl/{pearlId}
Retrieves a specific Pearl by its ID



# Get Pearls
Source: https://developers.nlpearl.ai/api-reference/v2/pearl/get-pearls

get /v2/Pearl
Retrieves all Pearls



# Reset Customer Memory
Source: https://developers.nlpearl.ai/api-reference/v2/pearl/reset-memory

put /v2/Pearl/{pearlId}/ResetMemory
Resets stored memory associated with a specific customer's phone number for a given Pearl.



# Set Activity State
Source: https://developers.nlpearl.ai/api-reference/v2/pearl/set-activity-state

put /v2/Pearl/{pearlId}/Active
Run or Pause a specific Pearl



# Create Pearl
Source: https://developers.nlpearl.ai/api-reference/v2/pearlFlow/add-pearl-flow

post /v2/Pearl
Creates a new Simple Pearl, driven by an opening sentence and a flow script. Provide exactly one channel: inbound settings OR outbound settings. The Pearl is created already published: the configuration you send becomes its live (published) version. To create a Pearl (node graph), use Create Voice Pearl or Create Text Pearl instead.



# Create Text Pearl
Source: https://developers.nlpearl.ai/api-reference/v2/pearlFlow/add-text-pearl

post /v2/Pearl/Text
Creates a new text Pearl: the conversation is driven by a graph of nodes connected by transitions, and messages are exchanged over a text channel. Provide exactly one channel: inbound settings OR outbound settings, with the TextChannelId of the channel to use. To retrieve available text channels, use the Get Text Channels endpoint (GET /v2/Account/TextChannels). The Pearl is created already published: the configuration you send becomes its live (published) version. For more details, click [here](/api-reference/building_a_flow).



# Create Voice Pearl
Source: https://developers.nlpearl.ai/api-reference/v2/pearlFlow/add-voice-pearl

post /v2/Pearl/Voice
Creates a new voice Pearl: the conversation is driven by a graph of nodes connected by transitions. The graph must contain one OpeningSentence node (or a PreCallAPI leading to one or two OpeningSentence nodes), one EndCall node, and every node must be reachable. Provide exactly one channel: inbound settings OR outbound settings. At least one agent voice is required; to retrieve available voices, use the Get Voices endpoint (GET /v2/Account/Voices). The Pearl is created already published: the configuration you send becomes its live (published) version. For more details, click [here](/api-reference/building_a_flow).



# Get Pearl Credentials
Source: https://developers.nlpearl.ai/api-reference/v2/pearlFlow/get-pearl-credentials

get /v2/Pearl/Credential/{pearlId}
Retrieves the API credentials (Id and Name only) available to the specified Pearl. Use a returned Id as the CredentialId of an API action in the Pearl flow.



# Get Pearl Settings
Source: https://developers.nlpearl.ai/api-reference/v2/pearlFlow/get-pearl-flow

get /v2/Pearl/{pearlId}/Settings
Retrieves the Settings for the specified Pearl. The shape of the response depends on the Pearl: the Pearl section is a Simple Pearl configuration (opening sentence + flow script) or a Pearl configuration (node graph), and the Inbound/Outbound section carries the voice or the text settings according to the AgentType field (1 = Voice, 2 = Text). AgentType also tells you which update endpoint to use: Update Pearl (Simple Pearl), Update Voice Pearl, or Update Text Pearl.



# Update Pearl
Source: https://developers.nlpearl.ai/api-reference/v2/pearlFlow/update-pearl-flow

put /v2/Pearl/{pearlId}
Updates the configuration of a Simple Pearl (name, pearl settings and variables). The update applies to the published version of the Pearl: if several versions exist on the platform, only the currently published one is modified. For Pearls, use Update Voice Pearl or Update Text Pearl instead.



# Update Inbound Settings
Source: https://developers.nlpearl.ai/api-reference/v2/pearlFlow/update-pearl-inbound

put /v2/Pearl/{pearlId}/Settings/Inbound
Updates the inbound settings for the specified Pearl. The update applies to the published version of the Pearl: if several versions exist on the platform, only the currently published one is modified.



# Update Outbound Settings
Source: https://developers.nlpearl.ai/api-reference/v2/pearlFlow/update-pearl-outbound

put /v2/Pearl/{pearlId}/Settings/Outbound
Updates the outbound settings for the specified Pearl. The update applies to the published version of the Pearl: if several versions exist on the platform, only the currently published one is modified.



# Update Text Pearl
Source: https://developers.nlpearl.ai/api-reference/v2/pearlFlow/update-text-pearl

put /v2/Pearl/Text/{pearlId}
Updates a text Pearl. Only the provided parts are updated: pearl replaces the whole conversation flow (send the complete node graph), inbound/outbound partially update the channel settings (only the fields present in the JSON are applied; when TextChannelId is omitted, the current channel is kept). Omitted parts are kept unchanged. The Pearl must be a text Pearl (AgentType = Text). The update applies to the published version of the Pearl: if several versions exist on the platform, only the currently published one is modified. For more details, click [here](/api-reference/building_a_flow).



# Update Voice Pearl
Source: https://developers.nlpearl.ai/api-reference/v2/pearlFlow/update-voice-pearl

put /v2/Pearl/Voice/{pearlId}
Updates a voice Pearl. Only the provided parts are updated: pearl replaces the whole conversation flow (send the complete node graph), inbound/outbound partially update the channel settings (only the fields present in the JSON are applied). Omitted parts are kept unchanged. The Pearl must be a voice Pearl (AgentType = Voice). The update applies to the published version of the Pearl: if several versions exist on the platform, only the currently published one is modified. For more details, click [here](/api-reference/building_a_flow).



# Get Phone Numbers
Source: https://developers.nlpearl.ai/api-reference/v2/pearlSettings/get-phones

get /v2/Account/PhoneNumbers
Retrieves all active phone numbers of the account.



# Get Text Channels
Source: https://developers.nlpearl.ai/api-reference/v2/pearlSettings/get-text-channels

get /v2/Account/TextChannels
Retrieves the text channels available on the account (for example SMS-capable numbers or WhatsApp accounts). Use a returned channelId as the TextChannelId of the inbound/outbound settings when creating or updating a text Pearl.



# Get Voices
Source: https://developers.nlpearl.ai/api-reference/v2/pearlSettings/get-voices

get /v2/Account/Voices
Retrieves the available voices grouped by language.



# Pearl Settings
Source: https://developers.nlpearl.ai/pages/agent_customization



<div>
  <Frame>
    <div>
      <img alt="Pearl Settings cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Pearl Settings cover" />
    </div>
  </Frame>
</div>

In this step, you can customize your voice agent's identity and behavior by setting its **name**, **language**, **voice**, **personality**, and **timezone**.

***

## Agent Names, Languages & Voices

To define your agent's identity:

* **<span>(1)</span> Agent Name** – Give your agent a name (e.g., *Joa*, *Victoria*). This name helps humanize the interaction and reflect your brand identity.
* **<span>(2)</span> Language** – Select the default language your agent will speak. This ensures accurate pronunciation and localized expressions.
* **<span>(3)</span> Voice** – Choose the voice that will represent your agent. You can preview voices and select the one that fits your tone.

<Frame>
  <img alt="Agent Names, Languages & Voices section" />
</Frame>

You can set up your Pearl to support multiple languages by adding several agent configurations, each with its own **name**, **language**, and **voice**. When a caller asks to switch language mid-conversation, Pearl automatically reroutes the call to the agent for that language.

The **first agent** you create is the **Default Agent** and always opens the conversation, unless another language is requested. You can add more agents directly in the table.

<Info>
  Explore [Voice and Language](/pages/languages) to view all the language options available.
</Info>

***

## Pearl Model

The **Pearl Model** defines the intelligence, speed, and cost profile of your agent. Voice agents can choose from four models.

<Frame>
  <img alt="Pearl Model selection in Pearl Settings" />
</Frame>

| Model             | Quality         | Speed          | Cost           |
| ----------------- | --------------- | -------------- | -------------- |
| **Pearl Hydra**   | Highest Quality | Higher latency | +2 credits/min |
| **Pearl Arrow**   | Best Quality    | Fastest        | +2 credits/min |
| **Pearl Trident** | Best Quality    | Standard       | Standard Rate  |
| **Pearl Oyster**  | Good Quality    | Standard       | -2 credits/min |

<Card>
  <Tabs>
    <Tab title="Pearl Hydra">
      <Info>
        **Highest Quality · Higher latency · +2 credits/min**
      </Info>

      Our smartest model, built for demanding use cases that require deeper reasoning, stronger understanding, and the highest-quality responses.

      Use it when you need:

      * The deepest reasoning for complex, multi-step conversations.
      * Maximum nuance and understanding on high-stakes or ambiguous calls.
      * The best possible answer quality, even if it means slightly higher latency.
    </Tab>

    <Tab title="Pearl Arrow">
      <Info>
        **Best Quality · Fastest · +2 credits/min**
      </Info>

      Our high-intelligence model, offering the same depth as Pearl Trident but tuned for ultra-low latency.

      Use it when you need:

      * The snappiest real-time experience for callers.
      * Highly nuanced, human-like conversations.
      * VIP lines, complex sales calls, or high-stakes negotiations where every second of silence matters.
    </Tab>

    <Tab title="Pearl Trident">
      <Info>
        **Best Quality · Standard Rate**
      </Info>

      Our most intelligent general-purpose model, designed for human-like conversations and handling complex use cases.

      Use it when you want:

      * A strong balance of quality vs cost.
      * Rich dialogues with multi-step reasoning and edge-case handling.
      * Your main production Pearl for most inbound and outbound flows.

      <Note>
        In most cases, Pearl Trident is the recommended default for production.
      </Note>
    </Tab>

    <Tab title="Pearl Oyster">
      <Info>
        **2 credits cheaper/min**
      </Info>

      Our most cost-effective model for straightforward cases, prioritizing simplicity and efficiency.

      Use it when you need:

      * High-volume or bulk campaigns (e.g. reminders, notifications, simple surveys).
      * Flows with predictable, scripted logic and limited branching.
      * To minimize cost while maintaining a solid conversational baseline.
    </Tab>
  </Tabs>
</Card>

**Choosing the right model for your Pearl**

When selecting a model, consider three main dimensions:

| Dimension                    | Recommendation                                                                                                                                                                                                                                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Speed**                    | If the caller experience must feel instant (no awkward silences, rapid back-and-forth), prefer Pearl Arrow. For standard conversational latency, Pearl Trident and Pearl Oyster are usually enough.                                                                                                                                         |
| **Reasoning / intelligence** | For the most demanding use cases that need the deepest reasoning, choose Pearl Hydra. For complex qualification, multi-step troubleshooting, or situations where the agent needs to "think", Pearl Trident or Pearl Arrow are strong choices. For simple flows with clear scripts and few edge cases, Pearl Oyster is more than sufficient. |
| **Cost**                     | Pearl Arrow delivers top experience at a higher per-minute cost (+2 credits/min vs Trident). Pearl Trident offers best quality at a standard rate. Pearl Oyster is cheaper per minute (–2 credits/min vs Trident), ideal when cost per call is the main constraint.                                                                         |

<Tip>
  You can use different models for different Pearls depending on their role, volume, and business impact (for example: Hydra for the most complex high-stakes calls, Arrow for VIP inbound support, Trident for main support, Oyster for large reminder campaigns).
</Tip>

<Info>
  Start with Pearl Trident as a balanced default, then use Analytics to compare performance and cost. If you need more speed or nuance, move to Pearl Arrow; if you need to optimize budget for simple flows, switch to Pearl Oyster.
</Info>

***

## Personality

Your AI agent can take on a wide range of personalities, from natural and professional to wild, fictional, or downright iconic.

<Frame>
  <img alt="Personality selection in Pearl Settings" />
</Frame>

<Tip>
  **Create your own personality.** You're not limited to the predefined list. Type any description in the **Personality** field and select **Use "\<your text>" as a custom personality** to define your own.
</Tip>

<Note>
  Choose wisely. Your agent's personality will shape how it sounds and behaves in every interaction. Personality is optional, only **Agent Name** and **Timezone** are required.
</Note>

The personalities below are **examples** to give you a feel for the range available. The full list is loaded in the app and may evolve over time.

| Personality Name            | Description (vibe / reference)                          |
| --------------------------- | ------------------------------------------------------- |
| Natural                     | Neutral and balanced, default tone.                     |
| Friendly Consultant         | Warm, helpful, and a touch conversational.              |
| Aggressive Closer           | Direct, assertive, always aiming for a "yes."           |
| Donald Trump                | Bold, confident, and controversial.                     |
| Joe Biden                   | Soft-spoken, empathetic, with a hint of grandpa energy. |
| Wolf of Wall Street         | Energetic, persuasive, and money-focused.               |
| Elon Musk                   | Visionary, quirky, and matter-of-fact.                  |
| Kevin Hart                  | Fast-talking and hilarious.                             |
| The Rock                    | Charismatic and full of hype.                           |
| Jar Jar Binks               | Clumsy comic relief with a chaotic syntax.              |
| Yoda                        | Wise, reversed sentence order, it has.                  |
| Tommy Shelby                | Cold, calculated, Peaky Blinders style.                 |
| Saul Goodman                | Slick, legal hustler energy.                            |
| Heisenberg (Walter White)   | Dark, serious, calculated: "I am the danger."           |
| Jesse Pinkman               | Street-smart, informal, frequent "yo."                  |
| Optimus Prime               | Heroic, formal, and noble.                              |
| Megatron                    | Villainous and authoritarian.                           |
| Son Goku                    | Cheerful and battle-ready.                              |
| Daenerys Targaryen          | Regal, determined, breaker of chains.                   |
| Hermione Granger            | Book-smart, precise, articulate.                        |
| Mulan                       | Brave, focused, honorable.                              |
| Lady Gaga                   | Glamorous and creatively intense.                       |
| Tony Stark (Iron Man)       | Witty, tech-savvy, and full of sarcasm.                 |
| Elsa (Frozen)               | Calm, regal, with an icy edge.                          |
| Michael Scott (The Office)  | Awkward, unpredictable, tries to be funny.              |
| Moana                       | Adventurous, optimistic, and kind.                      |
| Frida Kahlo                 | Artistic, deep, and passionate.                         |
| Jack Sparrow                | Eccentric and unpredictable.                            |
| Indiana Jones               | Adventurous and confident.                              |
| Beyoncé                     | Empowered, elegant, and commanding.                     |
| Sherlock Holmes             | Analytical, detached, brilliant.                        |
| Tiana (The Princess & Frog) | Driven, grounded, and focused.                          |
| Charlie Chaplin             | Silent-era charm with expressive tone.                  |
| Katniss Everdeen            | Stoic, focused, and fiercely independent.               |
| Groot                       | Repetitive but expressive ("I am Groot").               |
| Deadpool                    | Chaotic, irreverent, 4th-wall-breaking.                 |
| The Joker                   | Unhinged, theatrical, and darkly funny.                 |
| Loki                        | Mischievous, cunning, and charismatic.                  |
| Bugs Bunny                  | Witty, cheeky, and playful.                             |
| Pee-wee Herman              | Eccentric and unpredictable.                            |
| Dr. Evil                    | Satirical villain, comically ambitious.                 |
| Borat Sagdiyev              | Naive, awkward, hilariously inappropriate.              |
| Albert Einstein             | Brilliant, theoretical, with quirky logic.              |
| Dorothy Gale                | Innocent, curious, with wonder in her tone.             |

***

## Timezone

Define the timezone of the agent. This influences time-related actions, such as booking meetings.

<Frame>
  <img alt="Timezone selection in Pearl Settings" />
</Frame>


# Agents
Source: https://developers.nlpearl.ai/pages/agents

Agents are your capacity to handle voice calls and text conversations in NLPearl. Learn how they work and how to manage them.

<div>
  <Frame>
    <div>
      <img alt="Agents cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Agents cover" />
    </div>
  </Frame>
</div>

In NLPearl, **agents** are your capacity to handle activity. They power both your **voice calls** and your **text conversations** - the number of agents you have determines how much you can run at the same time.

## How agent capacity works

<Warning>
  An agent is a **virtual unit of capacity — not a person and not a specific Pearl.** Think of it as one "lane" of throughput that your whole workspace shares.
</Warning>

The more agents you own, the more activity you can run in parallel. What a single agent unlocks depends on the channel:

<CardGroup>
  <Card title="Voice calls" icon="phone">
    Each agent handles **one call at a time**. With 5 agents, you can run **5 calls simultaneously** — a 6th call waits until one frees up.
  </Card>

  <Card title="Text conversations" icon="comments">
    Each agent adds **3 messages per minute** of throughput. With 10 agents, that's up to **30 messages per minute**, spread across all your open chats.
  </Card>
</CardGroup>

<Info>
  **The key difference:** on **voice**, an agent limits how many calls run *at the same time* (concurrency). On **text**, an agent doesn't cap the number of open conversations — it sets how fast Pearl can reply *across all of them* (a message rate). Capacity scales linearly: 1 agent → 3 messages/minute, 10 agents → 30 messages/minute.
</Info>

<Note>
  Agents are shared at the **workspace** level. You buy them once, then allocate them to each inbound or outbound activity from the Pearl overview — so a busy campaign can use more lanes while a quieter one uses fewer.
</Note>

## Set up agents for your activities

Agents are managed at the **workspace** level from your Settings, then allocated to each Pearl from its overview page once published.

<Steps>
  <Step title="Open the Agent(s) settings">
    Click your **profile card** at the bottom-left of the sidebar, open **Settings**, then select the **Agent(s)** tab. This is where you purchase, review, and remove the agents in your workspace.

    <Frame>
      <img alt="Agent(s) tab in workspace Settings" />
    </Frame>
  </Step>

  <Step title="Purchase agents">
    Use the **Purchase New Agent(s)** bar at the top: set the quantity, review the monthly price, and click **Purchase Agent(s)**. You're billed immediately (see [Subscription and billing](#subscription-and-billing)).

    <Info>
      Adding concurrent agents requires an **active paid subscription**. Extra agents can only be purchased on a paid plan.
    </Info>

    <Frame>
      <img alt="Purchase New Agent(s) bar in the Agent(s) settings" />
    </Frame>
  </Step>

  <Step title="Review your agents">
    The list shows every agent in your workspace, with its creation date.

    <Frame>
      <img alt="List of agents in the workspace" />
    </Frame>

    Agents that come with your subscription are flagged with an **Included in your plan** badge — these are free and can't be removed.

    <Frame>
      <img alt="Included in your plan badge on a plan agent" />
    </Frame>
  </Step>

  <Step title="Remove an agent">
    To remove an extra agent, click the red **trash** icon next to it.

    <Frame>
      <img alt="Remove an agent with the trash icon" />
    </Frame>

    <Note>
      There are no pro-rata refunds — the agent stays active until the end of the period you've already paid for.

      **Example:** you remove an agent on the 5th, but your last renewal was on the 1st. The agent stays available until the end of that paid period (the 30th), and won't be billed again in the next cycle.
    </Note>
  </Step>

  <Step title="Allocate agents to a Pearl">
    After publishing your Pearl, open its overview page, open the **Settings** popover, and set the number of **Agent(s)** for that activity. Allocate 2 agents to a campaign and it handles 2 leads at a time. You can scale this up or down anytime.

    <Frame>
      <img alt="Allocate agents to a Pearl from its overview Settings" />
    </Frame>
  </Step>
</Steps>

## Example

<Card icon="lightbulb">
  The same number of agents translates differently on voice and text. Here's how a given allocation plays out:

  | Agents | Voice (simultaneous calls) | Text (messages / minute) |
  | :----: | :------------------------: | :----------------------: |
  |  **2** |  2 calls at the same time  |    6 messages / minute   |
  |  **5** |  5 calls at the same time  |   15 messages / minute   |
  | **10** |  10 calls at the same time |   30 messages / minute   |

  For example, allocate **2 agents** to an outbound voice campaign and it dials **2 leads at the same time**; the same 2 agents on a text Pearl let it reply at up to **6 messages per minute** across all open chats.
</Card>

## Subscription and billing

Every plan includes a set number of agents at no extra cost - higher tiers include more. On an **active paid subscription**, you can add extra concurrent agents at any time to grow your capacity.

Standard agents are billed at a flat monthly rate. Enterprise use and fine-tuned models cost more, depending on model complexity. See [Billing](/pages/billing) for current pricing.

### When you're billed

When you purchase an agent, you're billed for it immediately, whatever point you're at in your billing cycle. On your renewal date, every additional agent renews automatically for the next period.

<Warning>
  Buying an agent shortly before your renewal date means two charges close together: one when you purchase, and one when everything renews.

  **Example** - your subscription renews on the 1st and you add an agent on the 29th. You're billed for it right away. On the 1st, the whole subscription (including that agent) renews, so it's billed again for the new period. You've effectively paid for two periods, and you keep the agent for the full duration of each.
</Warning>


# Call Analytics
Source: https://developers.nlpearl.ai/pages/analytics

Track every campaign in real time: call outcomes, success and pickup rates, events, tags, sentiment, an activity heatmap, and costs — all from Pearl's automated conversations.

<Frame>
  <img alt="Call Analytics dashboard overview" />
</Frame>

<br />

NLPearl gives you a detailed analytics dashboard for every campaign, so you can track performance, understand what Pearl is doing on your calls, and optimize your strategy as results come in.

<Card icon="circle-info" title="How this dashboard works">
  Outbound campaigns (initiated by Pearl) surface more data, while inbound campaigns show a lighter set of insights. Every metric reflects Pearl's automated voice interactions, never human agents.

  Most cards follow the same layout: a **headline metric** at the top, a **Selected period** tag confirming the number matches the range you picked, and an **info** button (ⓘ) with a short explanation. Cards that include a chart plot that metric across the selected period.
</Card>

<Note>
  Running a **Pearl Text** agent? The same dashboard adapts its wording to chats — *Chat Status Breakdown*, *Average Chat Duration*, *Chats Heatmap*, and so on.
</Note>

## The analytics toolbar

A toolbar sits at the top of the dashboard. Use it to set the time range for every card and to export a report.

<Frame>
  <img alt="Analytics toolbar showing the leads count, date range picker, and Print button" />
</Frame>

### Choose your time range

By default the dashboard shows the **last 30 days**. Open the date picker to jump to a preset — `Today`, `Yesterday`, `Last 7 days`, `This week`, `This month` — or set a custom **Start** and **End** date. Every card updates to match.

<Frame>
  <img alt="Date range picker with quick presets and custom start and end fields" />
</Frame>

### Export a report

Click **Print** to turn the current view into a shareable report.

<Steps>
  <Step title="Set your time range">
    Pick the period you want the report to cover.
  </Step>

  <Step title="Click Print">
    The button sits in the top-right of the toolbar.
  </Step>

  <Step title="Save as PDF">
    In your browser's print dialog, choose **Save as PDF** (or send it to a printer).
  </Step>
</Steps>

The report is formatted for print — a light theme with one card per page. It adds a header with your project name and the selected period, and a footer with the generation date.

<Frame>
  <img alt="Browser print dialog previewing the analytics report with the NLPearl header, per-card layout, and footer" />
</Frame>

## Call Status Breakdown

This card shows how your calls are distributed across their **final statuses**. The headline is your total number of calls for the period.

<Frame>
  <img alt="Call Status Breakdown card with total calls, a distribution bar, status pills, and a trend chart" />
</Frame>

**Each status is a segment of the distribution bar, sized by its share of the total.** The pills below the bar list every status with its call count.

<Frame>
  <img alt="Horizontal distribution bar split into colored status segments with labeled pills" />
</Frame>

Statuses you'll see:

| Status              | Meaning                                                                                                                                                                                       | Availability |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| **Successful**      | The call met the success condition you defined for the Pearl (a booking, a confirmation, and so on).                                                                                          | All          |
| **Unsuccessful**    | The conversation happened, but the goal wasn't reached.                                                                                                                                       | All          |
| **Completed**       | An answered call with no success/failure verdict — shown when no success criteria is set for the Pearl. [Define one](/pages/pearl_analytics) to split these into Successful and Unsuccessful. | All          |
| **Need Retry**      | Nobody picked up, so the lead will be retried per your retry settings.                                                                                                                        | Outbound     |
| **Voice Mail Left** | Pearl reached voicemail and left a message.                                                                                                                                                   | Outbound     |
| **Unreachable**     | The lead couldn't be reached after every retry was exhausted.                                                                                                                                 | Outbound     |
| **Error**           | The call failed for a technical reason.                                                                                                                                                       | All          |
| **Other**           | Any remaining calls that don't fit the above (for example, calls still in progress). Shown on the bar but not selectable.                                                                     | All          |

<Tip>
  Select any status — on the bar or in its pill — to overlay that status's trend on the chart below. Hover a segment to see its exact count and percentage.
</Tip>

<Frame>
  <img alt="Line chart showing selected call statuses trending over the selected period" />
</Frame>

On outbound campaigns, a toggle lets you switch the whole card between **All calls** and **Answered calls** (the calls a person actually picked up: Completed, Successful, and Unsuccessful).

<Frame>
  <img alt="Toggle switching the Call Status Breakdown between All calls and Answered calls" />
</Frame>

## Average Call Duration

The **average length of your calls**, measured from the moment the person picks up or starts interacting with Pearl. Useful to:

* Detect drop-offs
* Monitor engagement quality
* Measure attention span

<Frame>
  <img alt="Average Call Duration card with a headline duration and a trend chart" />
</Frame>

## Success Rate

The **percentage of calls that met the success definition** you set for your Pearl — booking a meeting, confirming information, or anything else you defined as a success. The headline is your average success rate over the selected period, weighted by call volume.

<Tip>
  Read Success Rate alongside Average Call Duration to gauge how efficient your conversations are.
</Tip>

<Frame>
  <img alt="Success Rate card with an average percentage and a trend chart" />
</Frame>

<Info>
  The chart stays empty until you [define what success means](/pages/pearl_analytics) for your Pearl.
</Info>

## Events

**Events are the actions Pearl took during conversations.** The headline shows the total number of events and the average per answered call.

<Frame>
  <img alt="Events card listing each action with its per-call rate and share of events" />
</Frame>

Each row breaks down one action three ways:

* **Count** — how many times it occurred.
* **Per call** — the average number of times per answered call.
* **Share of events** — its portion of all events triggered.

Tracked actions include:

* **Message Taken**
* **SMS Sent**
* **Call Transferred**
* **Calendar Booked**
* **Email Sent**

## Tags

**Tags are the Indicator Tags you defined when creating your Pearl** — labels like `Interested`, `Callback Requested`, or `Wrong Number` that Pearl applies automatically based on how each conversation goes. The headline highlights your most-used tag and its share of calls.

<Frame>
  <img alt="Tags card showing each tag's color, count, and share of calls" />
</Frame>

Each tag shows its color, its count, and its **share of calls** — the percentage of calls it was applied to.

<Info>
  Tags aren't just for display. You can filter campaigns by tag, trigger notifications, and use them to segment leads. Learn how to set them up in [Call Analytics — Indicator Tags](/pages/pearl_analytics).
</Info>

## Calls Heatmap

The heatmap shows **when calls happen** across the week — every cell is a day-and-hour slot, and brighter cells mean more activity. The headline calls out your busiest slot. Use it to find the best times to call (outbound) or to staff for demand (inbound).

<Frame>
  <img alt="Weekly calls heatmap with a peak-time headline and a Less-to-More activity legend" />
</Frame>

Two controls let you adjust the view:

* **Color** — toggle a color scale on or off.
* **Timezone** — read the grid in the timezone that matters to you.

<Frame>
  <img alt="Heatmap controls: a Color toggle and a timezone dropdown" />
</Frame>

## Pickup Rate

<Warning>Outbound only.</Warning>

The **percentage of outbound calls answered** by your contacts. The headline is your average pickup rate for the period. It tells you how reachable your audience is, so you can fine-tune your calling hours.

<Frame>
  <img alt="Pickup Rate card with an average percentage and a trend chart" />
</Frame>

## Sentiment Analysis

The **emotional tone of your conversations**, detected from customer responses across five levels. The headline names the dominant sentiment and its share of calls.

* Negative
* Slightly Negative
* Neutral
* Slightly Positive
* Positive

<Frame>
  <img alt="Sentiment Analysis card with a dominant sentiment and each level's share of calls" />
</Frame>

Each level lists its call count and share of calls, so you can watch satisfaction trends and adjust Pearl's tone.

## Costs

Your **total and per-period call costs**, with a headline total and a trend over time — so you can see how usage affects your credit.

<Frame>
  <img alt="Costs card with a total cost headline and a spend trend chart" />
</Frame>

<Warning>
  This card only reflects costs deducted from your available credit. Calls covered by your included minutes aren't shown.
</Warning>

## Inbound vs Outbound

| Feature                                                    | Inbound       | Outbound                                            |
| ---------------------------------------------------------- | ------------- | --------------------------------------------------- |
| Call initiation                                            | By the caller | By Pearl                                            |
| Call Status Breakdown                                      | ✅             | ✅ *(adds Need Retry, Voice Mail Left, Unreachable)* |
| All calls / Answered calls toggle                          | —             | ✅                                                   |
| Pickup Rate                                                | —             | ✅                                                   |
| Duration, Success, Events, Tags, Sentiment, Heatmap, Costs | ✅             | ✅                                                   |

## Summary

With NLPearl Analytics you get full visibility into your campaigns' performance. Use these insights to fine-tune your strategy, lift your success and pickup rates, and optimize every conversation.


# API Node
Source: https://developers.nlpearl.ai/pages/api_action



<div>
  <Frame>
    <div>
      <img alt="API node interface on light mode" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="API node interface on dark mode" />
    </div>
  </Frame>
</div>

The **API node** runs an HTTP request automatically when the flow reaches it, letting your Pearl pull or push data from an external system. Depending on where you place it, it behaves in one of three ways:

* **Pre-Call API**: runs once, before the conversation starts.
* **In-Call API**: runs during the conversation, when the flow reaches the node.
* **Post-Call API**: runs after the conversation ends, as a post-call action.

The configuration form is the same in all three cases. Only the available variables, the response handling, and the transitions differ (see [Context Differences](#context-differences)).

***

## Adding an API Node

| Context           | Where to add it                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Pre-Call API**  | On the **Start** node, choose **Pre Call API**. It is inserted between Start and the Opening Sentence, and runs before the call.      |
| **In-Call API**   | Add an **API** node from the side toolbar (or the node picker under *Live Action Nodes*) and connect it where the request should run. |
| **Post-Call API** | On the **Post-Call Actions** container (reached from an End Call transition), click **Add Action** and choose **API**.                |

***

## Configuring the Request

<Steps>
  <Step title="Description">
    Explain what this API does and what data it returns (e.g. *"Fetches customer order history"*). Maximum **150 characters**. This helps Pearl understand when and how to use the action.

    <Frame>
      <img alt="API node description field" />
    </Frame>
  </Step>

  <Step title="URL & Method">
    Type the API endpoint URL and choose the **HTTP Method** (**GET**, **POST**, **PUT**, **DELETE**, or **PATCH**) depending on the API's requirements. Click **+** to insert a variable into the URL, limited to the variables available in the node's context (see [Context Differences](#context-differences)).

    <Frame>
      <img alt="API URL and method configuration" />
    </Frame>

    <Info>
      The available fields depend on the method:

      * The **Body** section is shown only for **POST**, **PUT**, and **PATCH** (hidden for GET and DELETE).
      * The **Response Output Schema** is available for every method **except DELETE**.
    </Info>
  </Step>

  <Step title="Headers">
    Add any header required by the API, such as `Content-Type` or `Authorization`. Header values are **static**.

    <Frame>
      <img alt="API headers configuration" />
    </Frame>

    <Info>
      For a **dynamic authorization token**, use a [**Credential**](#credentials-authentication) instead of a static header.
    </Info>
  </Step>

  <Step title="Body (POST / PUT / PATCH)">
    Provide **Key / Value** pairs, sent as JSON.

    <Frame>
      <img alt="API body configuration" />
    </Frame>

    Each **Value** is either a **Variable** or a **Static & Custom** value. Static values support these types:

    | Type               | Format                 |
    | ------------------ | ---------------------- |
    | **Text**           | String                 |
    | **Whole Number**   | Integer                |
    | **Decimal Number** | Float / double         |
    | **Boolean**        | `true` / `false`       |
    | **Date**           | Calendar date          |
    | **Time**           | Time of day            |
    | **Date & Time**    | Combined date and time |

    <Info>
      For each row you can toggle a **Required** checkbox:

      * **Checked**: Pearl prompts the customer for the value before sending the request if it hasn't been collected yet.
      * **Unchecked**: the request is sent even if the value is missing; the key is simply omitted.
    </Info>

    When using a variable in the body, be aware that:

    * The platform **casts each variable to its configured data type** (e.g. Whole Number becomes an integer, Text is quoted as a string). A type mismatch may cause the API to reject the request.
    * You can mix static values and variables in the same body.
    * For nested JSON, use **dot notation** in the Key (`customer.address.street`) and **square brackets** for array indices (`order.items[0].productId`). See [Using Nested Objects](#using-nested-objects) below.

    A body value can also carry its own braces - a GraphQL query or a nested JSON fragment, for example. In an API node, only braces wrapping a valid variable ID are substituted; every other brace is sent as-is:

    * `{ {agentName} }` - the variable is replaced, the outer braces are kept.
    * `query { boards(ids: {agentName}) { id } }` - the variable is replaced, the rest of the query is left untouched.
    * `{ agentName }` - braces containing spaces around the ID are **not** recognized as a variable; the text is sent literally.
  </Step>
</Steps>

### Using Nested Objects

Many APIs expect a **nested JSON structure** in their request body. Use dot notation and array indices in the **Key** column to build nested payloads while keeping them organised and readable.

<Card title="How to define nested keys">
  * Use **dot notation** for properties (`customer.address.street`)
  * Use **square brackets** for array indices (`order.items[0].productId`)

  <Info>
    You can pair nested paths with any variable type: Text, Number, Boolean, etc.
  </Info>

  Mapping table:

  | API key                    | Variable        |
  | -------------------------- | --------------- |
  | `customer.name`            | `customerName`  |
  | `customer.email`           | `customerEmail` |
  | `customer.address.street`  | `street`        |
  | `customer.address.city`    | `city`          |
  | `order.items[0].productId` | `productId`     |
  | `order.items[0].quantity`  | `quantity`      |

  Resulting body:

  ```json body.json theme={null}
  {
    "customer": {
      "name": "{customerName}",
      "email": "{customerEmail}",
      "address": {
        "street": "{street}",
        "city": "{city}"
      }
    },
    "order": {
      "items": [
        {
          "productId": "{productId}",
          "quantity": "{quantity}"
        }
      ]
    }
  }
  ```
</Card>

***

## Response Output Schema & Variable Assignment

<Warning>
  API responses are capped at **10,000 characters**. Anything longer is automatically truncated.
</Warning>

Available for every method **except DELETE**. The **Response Output Schema** lets you filter the API response so only the relevant data flows back into the conversation. Without filtering, the entire JSON is returned, which can reduce precision because the AI receives too much unrelated information. Even for small responses, setting a schema is strongly recommended to keep Pearl focused.

Each row of the schema has three parts:

| Column                  | Description                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------- |
| **Required** (checkbox) | Mark the path as mandatory for the action.                                              |
| **JSON Path**           | The path to extract from the response.                                                  |
| **Variable to Assign**  | Store the extracted value in a variable. **Required for Pre-Call**, optional otherwise. |

<Frame>
  <img alt="API response output schema configuration" />
</Frame>

### How it works

* Provide a list of **JSON Path** strings, one per row.
* The system extracts only those paths from the API response; everything else is discarded.

### Path syntax

A path walks down the API response to the value you want. The simplest form is a chain of keys, and it covers most responses:

| Path             | What it returns                         |
| ---------------- | --------------------------------------- |
| `customer.email` | The `email` property inside `customer`. |
| `items[0].id`    | The `id` of the first entry in `items`. |

A path can also **choose**, which is what you need as soon as an API answers with a list and you only want one entry out of it:

| Path                                                   | What it returns                                                                                     |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `collection[?(@.status == 'available')][0].start_time` | The `start_time` of the first entry whose `status` is `available` — a filter, then the first match. |
| `items[-1].id`                                         | The `id` of the last entry. Negative indices count from the end.                                    |
| `items[0:3]`                                           | The first three entries — a slice.                                                                  |
| `..email`                                              | Every `email` found anywhere in the response, at any depth.                                         |

A slice or a recursive `..` search can match several values at once. Assign one of those to a variable and the variable has to allow multiple values — see **Assigning to a variable** below.

<Note>
  These are not the same as the paths in the **Key** column of the request body. There, `order.items[0].productId` **builds** a nested payload. Here, the same shape **reads** a value out of the response.
</Note>

<Card icon="circle-info">
  ### Using a variable inside a path

  A path can carry a `{variableId}` placeholder — the same syntax used everywhere else (see [Flow Variables](/api-reference/flow_variables)). It is replaced with the variable's current value before the response is read, so the path can depend on what the conversation has collected:

  ```text theme={null}
  collection[?(@.start_time startswith '{preferredDateIso}')][0].start_time
  ```

  If the caller asked for a particular day and it was collected into `preferredDateIso`, that path returns the first slot on that day.
</Card>

<Tip>
  Use a filtered path whenever the API returns a list and you only want one entry from it. A calendar call is the usual case: without a filter, you map slot 1, slot 2 and slot 3 into separate variables and let the agent pick between them. With one filtered path, the platform hands it exactly the first free slot on the day the caller asked for.
</Tip>

<Check>
  Benefits:

  * Keeps the response size small
  * Improves the quality and relevance of AI outputs
  * Prevents hitting the 10,000-character truncation limit
  * Ensures only the necessary fields are carried into the next steps of the conversation
</Check>

<Card icon="circle-info">
  ### Assigning to a variable

  Key things to know:

  * **The variable's type must match the data type returned by the API at that path.**
  * If the value returned is a list, make sure the variable is configured to **allow multiple values**.
  * A variable can store up to **600 characters**. Any data beyond this limit is **truncated**.

  <Info>
    Outside of Pre-Call APIs, assigning a variable is optional. If you don't assign one, the filtered JSON is still available for the conversation's internal logic, but it won't be stored for later reuse.
  </Info>
</Card>

***

## Credentials (Authentication)

If your API requires authentication, create a **Credential** on the platform, then enable the **Credentials** toggle in the API node and select it from the **Token** dropdown (use **Add New** to create one, **Edit** to update it). Leave the toggle off if no authentication is needed.

<Frame>
  <img alt="API credentials toggle and token selection" />
</Frame>

**Supported credential types** (chosen from the **Type** dropdown when creating a credential):

| Type               | Description                                              |
| ------------------ | -------------------------------------------------------- |
| **Api Key**        | Injected in a **Header** or **Query** parameter          |
| **Basic Auth**     | Username + password                                      |
| **Bearer**         | A static bearer token                                    |
| **Custom Api Key** | Custom headers / query params / body                     |
| **Refresh Token**  | The platform fetches and refreshes a token automatically |

<Info>
  **OAuth2** providers are connected through [**Integrations**](/pages/pearl_vibe), not created manually in this form.
</Info>

<Tip>
  Why use a Credential?

  * Avoid hardcoding tokens manually in every API node
  * Automatically refresh tokens based on their TTL (time-to-live)
  * Centralized management when multiple API nodes reuse the same token
  * No need to parse token responses manually, the platform extracts the token for you
</Tip>

### Configuring a Refresh Token credential

<Steps>
  <Step title="Open the Credential Manager">
    Open the **Credential Manager** from the icon at the top of the Flow Editor header.

    <Frame>
      <img alt="Credential Manager access in the Flow Editor header" />
    </Frame>
  </Step>

  <Step title="Add a new credential">
    In the **Credentials Manager**, click **+ Add** to create a new credential.

    <Frame>
      <img alt="Add a new credential in the Credentials Manager" />
    </Frame>
  </Step>

  <Step title="Choose how to add it">
    You can either pick a ready-made **integration** from the list (Google, Microsoft, Slack, HubSpot, Salesforce, Zoho, and more) to connect through its guided flow, or click **Add Manually** to configure a custom credential such as a **Refresh Token**.

    <Frame>
      <img alt="Choose an integration or add a credential manually" />
    </Frame>
  </Step>

  <Step title="Fill in the credential details">
    If you chose **Add Manually**, enter a **Name** (a label to identify it later) and select a **Type**. The form updates to show the fields specific to the selected type.

    <Frame>
      <img alt="Manual credential form with name, type, and type-specific fields" />
    </Frame>

    <Card title="Example: Refresh Token fields">
      | Field                 | Description                                                                                                                                                     |
      | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | **Access Token URL**  | The method and endpoint used to request the token, with optional **Headers**, **Query Params**, and **Body** (e.g. `grant_type`, `client_id`, `client_secret`). |
      | **Token Path**        | JSON path to locate the token in the response (e.g. `data.access_token`).                                                                                       |
      | **TTL (sec)**         | Token time-to-live (minimum **100**).                                                                                                                           |
      | **Header Key**        | Name of the header where the token is injected (e.g. `Authorization`).                                                                                          |
      | **Header Prefix**     | Optional prefix for the token (e.g. `Bearer`).                                                                                                                  |
      | **Secured Variables** | Sensitive key/value pairs reused across requests.                                                                                                               |
    </Card>
  </Step>

  <Step title="Test the Credential">
    Use **Test Credentials** to call the token endpoint and preview the JSON response, confirming your configuration retrieves the token successfully before saving.
  </Step>
</Steps>

<Card icon="circle-info">
  ### How the Credential is used

  Once saved, select this Credential from the **Token** dropdown in any API node. When selected:

  * The platform automatically adds the token to the request header, using the configured **Header Key** and optional **Header Prefix**.
  * The token is refreshed automatically when it expires, based on the configured **TTL**.

  <Warning>
    Make sure the **Token Path** matches the exact location of the token in the JSON response. If the platform can't find the token at this path, the Credential will fail.
  </Warning>
</Card>

***

## Context Differences

The same API node behaves differently depending on where you place it in the flow.

| Aspect                          | Pre-Call API                     | In-Call API            | Post-Call API                  |
| ------------------------------- | -------------------------------- | ---------------------- | ------------------------------ |
| **When it runs**                | Before the call                  | During the call        | After the call                 |
| **Available variables**         | Pre-Call only                    | Pre-Call + In-Call     | Pre-Call + In-Call + Post-Call |
| **Assign response to variable** | Required                         | Optional               | Optional                       |
| **Transitions**                 | Success (+ optional Not Success) | Continue / conditional | None                           |
| **Can duplicate**               | No                               | Yes                    | —                              |

<Tabs>
  <Tab title="Pre-Call API">
    Runs **once before the conversation begins**. Typical uses:

    * **Inbound**: look up the caller using the auto-captured **phone number** and **call id**.
    * **Outbound**: preload data from Pre-Call variables already stored on the lead.

    <Info>
      Only **Pre-Call variables** are available (system variables like phone number, call id, first/last name, email, plus your own Pre-Call variables).
    </Info>

    * **Assigning response values to variables is required**, that's how pre-call data becomes usable in the conversation. All required variables must be returned for the node to take the **Success** path.
    * **Transitions**: a **Success** branch by default. Enable **On Error Transition** (in the Transitions tab) to add a **Not Success** branch for failed requests.
    * Pre-Call API nodes **cannot be duplicated**.
  </Tab>

  <Tab title="In-Call API">
    Runs **when the flow reaches the node during the conversation**.

    * Both **Pre-Call** and **In-Call** variables are available.
    * After it runs, the flow follows the **Continue** transition (or your conditional transitions).
    * Assigning response values to variables is optional but recommended for reuse later in the flow.
  </Tab>

  <Tab title="Post-Call API">
    Runs **after the call**, as part of the **Post-Call Actions**.

    * All variable groups are available, including **Post-Call** variables (call time, summary, recording, duration, transcript).
    * Post-Call actions have **no transitions**.
  </Tab>
</Tabs>

***

## Testing Your API

Use the **Test API** panel below the form:

<Frame>
  <img alt="Test API panel" />
</Frame>

<Steps>
  <Step title="Assign Test Values">
    Give sample values to every variable used in the request.
  </Step>

  <Step title="Send">
    Click **Send** to run the request.
  </Step>

  <Step title="Inspect">
    Review the raw response, the filtered response (if an Output Schema is set), and any variables populated from it.
  </Step>
</Steps>

<Tip>
  Use **Expand** to open a full-screen view with the request and response side by side. Test and perfect your setup before putting the Pearl in production.
</Tip>

***

<CardGroup>
  <Card title="Variables" icon="square-root-variable" href="/pages/variables">
    Learn how to create and use variables inside API nodes.
  </Card>
</CardGroup>


# Billing
Source: https://developers.nlpearl.ai/pages/billing

Learn how to manage your billing settings, subscriptions, and invoices on the NLPearl.AI platform.

<div>
  <Frame>
    <div>
      <img alt="Billing cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Billing cover" />
    </div>
  </Frame>
</div>

***

## Billing Management

The **Billing** page is your central place to manage everything related to payments on NLPearl.AI. From here you can choose or change your subscription plan, manage your payment methods, view and download invoices, and configure auto-recharge to keep your activities running without interruption.

<Info>
  Billing changes are managed directly on the platform. Make sure you have the right permissions on your workspace to update subscriptions or payment methods.
</Info>

***

## Subscription Management

From the Billing page, you can select the subscription plan that best fits your needs, or change your current one at any time.

<CardGroup>
  <Card title="Upgrading" icon="arrow-up">
    Upgrades take effect **immediately**, giving you access to additional features and resources right away.
  </Card>

  <Card title="Downgrading" icon="arrow-down">
    Downgrades take effect at the **end of your current billing period**, on the anniversary date of your current plan.
  </Card>
</CardGroup>

***

## Payment Methods

Enter and manage your credit card details directly from the Billing page. Keeping a valid payment method on file ensures your payments are processed smoothly and your subscription stays active.

<Frame>
  <img alt="Payment method on the Billing page" />
</Frame>

<Note>
  You can update or replace your card at any time. The new payment method is used for your next charge.
</Note>

***

## Invoices

Access your full billing history from the Billing page. Every invoice is available to **view and download** for your records and accounting needs.

<Frame>
  <img alt="Invoices list on the Billing page" />
</Frame>

***

## Credits

Credits fund your activities on NLPearl.AI. From the **Credits** tab of the **Subscription & Payment** page, you can top up your balance in two ways: buy credits instantly, or set up auto-recharge so your balance is replenished automatically.

### Buy credits instantly

Purchase a credit amount that is added to your balance **immediately**. Use this for a one-time top-up or to get started right away.

<Frame>
  <img alt="Buy credits instantly on the Subscription & Payment page" />
</Frame>

### Auto-recharge

Auto-recharge keeps your balance topped up automatically so your activities never stop because of an insufficient balance.

<Steps>
  <Step title="Enable auto-recharge">
    Turn on auto-recharge from the Credits tab.
  </Step>

  <Step title="Set your threshold">
    Define the balance level that triggers a recharge.
  </Step>

  <Step title="Set your target balance">
    Choose the amount your balance is recharged to whenever it falls below the threshold.
  </Step>
</Steps>

<Frame>
  <img alt="Auto-recharge settings on the Subscription & Payment page" />
</Frame>

<Warning>
  We strongly recommend enabling auto-recharge. Without it, your calls and conversations stop as soon as your balance runs out.
</Warning>

***

## Next steps

<CardGroup>
  <Card title="Subscription Plans" icon="credit-card" href="https://nlpearl.ai/pricing/">
    Compare the different subscription plans and choose the best one for your needs.
  </Card>

  <Card title="Payout" icon="money-bill-transfer" href="/pages/payout">
    Learn how payouts work and how to manage your earnings on the platform.
  </Card>
</CardGroup>


# Phone Number Blacklist
Source: https://developers.nlpearl.ai/pages/blacklist



<div>
  <Frame>
    <div>
      <img alt="Phone Number Blacklist cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Phone Number Blacklist cover" />
    </div>
  </Frame>
</div>

***

The **Blacklist** feature enables you to restrict specific phone numbers or entire prefixes from engaging in inbound or outbound calls with your AI agent campaigns. Utilizing this feature helps enhance campaign efficiency and ensures communication efforts remain focused and relevant.

<Tip>
  ### Benefits

  * Prevent unwanted calls from specific numbers or number prefixes.
  * Enhance operational efficiency by avoiding irrelevant interactions.
  * Monitor and track blacklisted number activities clearly within your campaigns.
</Tip>

***

### Accessing the Blacklist

The Blacklist lives in your **Settings**. Click your **profile card** at the bottom-left corner of the sidebar, then select **Settings**.

<Frame>
  <img alt="Open Settings from the profile card" />
</Frame>

From the left menu, select **Blacklist** under the *Workspace* section.

<Frame>
  <img alt="Blacklist tab in the Workspace settings" />
</Frame>

***

### Adding a Number to the Blacklist

<Steps>
  <Step title="Open the Add dialog">
    In the **Add Blacklisted Phone Number** bar at the top, click **Add Phone Number**.

    <Frame>
      <img alt="Add Blacklisted Phone Number bar" />
    </Frame>
  </Step>

  <Step title="Enter the number and confirm">
    In the **Phone Number Blacklist** dialog, type the phone number you want to block (e.g., `+1 408 XXX XXXX`), then click **Add Phone Number**.

    <Frame>
      <img alt="Phone Number Blacklist dialog to enter a number" />
    </Frame>

    <Note>
      You can also block an entire **prefix** (e.g., `+33`). Every number beginning with that prefix (`+33123456789`, `+33456789012`, etc.) is then blocked from both receiving and making calls.
    </Note>

    <Tip>
      Need to block many numbers at once? You can **add them in bulk** instead of entering them one by one — paste or import a whole list in a single action.
    </Tip>
  </Step>
</Steps>

***

### Managing Blacklisted Numbers

All blocked numbers appear under **Blacklisted Phone Numbers**, with a counter showing how many are stored.

<Frame>
  <img alt="List of blacklisted phone numbers" />
</Frame>

**Search** — use the search field at the top right to quickly find a specific number in a long list.

<Frame>
  <img alt="Search field in the blacklist" />
</Frame>

**Remove** — click the red trash icon on a row to remove that number from the blacklist.

<Frame>
  <img alt="Remove a number from the blacklist with the trash icon" />
</Frame>

***

### Monitoring Blacklisted Numbers in Campaigns

* Blacklisted numbers will appear with a `Blacklisted` label in your campaign interface.
* Track attempted interactions involving blacklisted numbers, whether inbound calls to your campaigns or outbound calls initiated by your AI agent.

<Frame>
  <img alt="Blacklisted label on a call in a Pearl's Calls list" />
</Frame>

Leveraging the blacklist feature ensures your campaigns remain targeted, effective, and free from unwanted communication.


# Custom VoIP Integration
Source: https://developers.nlpearl.ai/pages/custom_voip

Learn how to integrate your own VoIP service with NLPearl.AI.

<div>
  <Frame>
    <div>
      <img alt="Custom VoIP Integration cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Custom VoIP Integration cover" />
    </div>
  </Frame>
</div>

Integrate your own VoIP service with NLPearl to use your existing phone numbers for inbound and outbound calls. This flexibility allows you to leverage your current VoIP infrastructure while benefiting from NLPearl.AI’s advanced features.

***

### How to Integrate Your Custom VoIP Service

To integrate your custom VoIP service, follow these steps:

<Steps>
  <Step title="Go to Phone Numbers Settings">
    Start by clicking your **profile card** at the bottom-left corner of the sidebar, then open **Settings**.

    <Frame>
      <img alt="Open Settings from the profile card" />
    </Frame>

    From there, open the **Phone Numbers** tab to manage the numbers linked to your account.

    <Frame>
      <img alt="Phone Numbers tab in Settings" />
    </Frame>
  </Step>

  <Step title="Click on Custom VoIP">
    In the **Phone Numbers** tab, locate the **Custom VoIP** row and click **Add Custom VoIP** to start setting up your own provider.

    <Frame>
      <img alt="Add Custom VoIP from the Phone Numbers settings" />
    </Frame>
  </Step>

  <Step title="Add Phone Number">
    Enter the phone number you want to associate with this custom VoIP configuration.

    <Note>
      Enter it in **E.164 format** (digits only, with an optional leading `+`). This label is mainly for display (DID number, extension, etc.) and doesn't have to be a routable number, but it must be numeric.
    </Note>

    <Frame>
      <img alt="Enter the phone number for your custom VoIP configuration" />
    </Frame>
  </Step>

  <Step title="Configure Inbound and/or Outbound">
    After adding the number, you land on a setup screen with two cards — **Inbound Configuration** and **Outbound Configuration** — each showing a **Configured** / **Not Configured** badge. Configure the direction(s) you need (one or both), then click **Finish Setup**.

    <Frame>
      <img alt="Choose to configure inbound and/or outbound" />
    </Frame>
  </Step>

  <Step title="Configure Your VoIP Settings">
    <Card>
      ### Inbound Configuration Settings

      <Steps>
        <Step title="TLS (SRTP) Encryption">
          Secures your VoIP traffic by encrypting both the signaling (via TLS) and media (via SRTP). Activate this toggle **only** if your VoIP provider requires it.

          <Tip>
            **When to Enable It:**

            * Your SIP provider specifically mentions TLS or SRTP support.
            * You want to ensure secure, encrypted voice communication (e.g., for compliance or privacy reasons).

            **When to Leave It Off:**

            * Your provider doesn’t support TLS/SRTP, enabling it may block calls or cause failed connections.
            * You’re using basic test environments or local SIP servers without encryption.
          </Tip>

          <Frame>
            <img alt="Inbound TLS (SRTP) encryption toggle" />
          </Frame>
        </Step>

        <Step title="Authentication Methods">
          <Info>
            Inbound calls require **at least one** authentication method. Enable **IP Address** and/or **Credentials** authentication (you can use both).
          </Info>

          **IP Address Authentication:**

          Allow traffic from specific IP addresses, ideal if your VoIP infrastructure has a static IP.

          IP Address:
          Enter the public IP address(es) of your SIP servers so we can accept and process requests from them.

          <Frame>
            <img alt="Inbound IP-based authentication" />
          </Frame>

          ***

          **Credentials Authentication:**

          Use a username and password to authenticate each incoming SIP request.

          Username: 2–32 characters, using letters, digits, hyphens (`-`) and underscores (`_`) only. <br />
          Password: At least 12 characters, with at least one uppercase letter, one lowercase letter, and one digit. Letters and digits only — **special characters are not allowed**.

          <Tip>
            This method is useful if your infrastructure is cloud-based and IPs can change, or you want multi-tenant control.
          </Tip>

          <Frame>
            <img alt="Inbound credential-based authentication" />
          </Frame>
        </Step>

        <Step title="Copy Your SIP Domain">
          After you save the inbound configuration, NLPearl generates a **SIP Domain** for this number. This is what tells your provider where to send incoming calls so they reach the platform.

          <Info>
            The SIP Domain isn't something you type. It's created automatically and shown **read-only** at the top of the **Inbound Configuration** card, with a **Copy** button. It only appears **once the inbound configuration has been saved**, so reopen the card afterward to retrieve it.
          </Info>

          <Frame>
            <img alt="SIP Domain shown read-only with a Copy button in the Inbound Configuration" />
          </Frame>

          <Warning>
            **To finish connecting inbound calls:**

            1. Save the inbound configuration, then reopen the **Inbound Configuration** card.
            2. Copy the generated **SIP Domain**.
            3. Add it to your VoIP provider / PBX as the **destination for inbound calls**, so your operator routes incoming calls to NLPearl.
            4. If you enabled **Credentials Authentication**, also add the **username and password** you defined here to your VoIP settings so authentication succeeds.
          </Warning>
        </Step>
      </Steps>
    </Card>

    ***

    <Card>
      ### Outbound Configuration Settings

      <Steps>
        <Step title="TLS (SRTP) Encryption">
          Secures your VoIP traffic by encrypting both the signaling (via TLS) and media (via SRTP). Activate this toggle **only** if your VoIP provider requires it.

          <Tip>
            **When to Enable It:**

            * Your SIP provider specifically mentions TLS or SRTP support.
            * You want to ensure secure, encrypted voice communication (e.g., for compliance or privacy reasons).

            **When to Leave It Off:**

            * Your provider doesn’t support TLS/SRTP, enabling it may block calls or cause failed connections.
            * You’re using basic test environments or local SIP servers without encryption.
          </Tip>

          <Frame>
            <img alt="Outbound TLS (SRTP) encryption toggle" />
          </Frame>
        </Step>

        <Step title="SIP Trunk URL">
          This is the address your outbound calls will be sent to, typically provided by your VoIP provider. Enter it as a **domain or IP address** (this is where your calls will be routed).

          <Frame>
            <img alt="Outbound SIP Trunk URL field" />
          </Frame>
        </Step>

        <Step title="User Part">
          This is the SIP user identity used in the “From” header of your outbound SIP requests. It's how your VoIP system identifies the origin of the call.

          What to enter:
          You can use one of the following formats depending on your provider:

          * A SIP username (e.g. `caller01`)
          * A DID or phone number in `E.164` format (e.g. `+1234567890`)
          * An extension (e.g. `201`)
          * A SIP URI (e.g. `caller01@example.com`), less common

          <Frame>
            <img alt="Outbound User Part field" />
          </Frame>
        </Step>

        <Step title="Data Center">
          Select the network edge closest to your VoIP infrastructure to optimize call routing and reduce latency. Eight regions are available:

          | Region        | Location  |
          | ------------- | --------- |
          | North America | Virginia  |
          | North America | Oregon    |
          | Europe        | Ireland   |
          | Europe        | Frankfurt |
          | Asia Pacific  | Singapore |
          | Asia Pacific  | Tokyo     |
          | Asia Pacific  | Sydney    |
          | South America | São Paulo |

          <Frame>
            <img alt="Outbound Data Center selection" />
          </Frame>
        </Step>

        <Step title="Transfer Call Using SIP Refer">
          This toggle enables or disables call transfers using the SIP REFER method. It is **enabled by default**.

          When enabled, it allows:

          * Transferring a live call from one destination to another without media proxying
          * Offloading media streams directly between endpoints
          * Reducing latency and server load

          <Warning>
            If you **disable** SIP REFER, NLPearl's servers stay in the media path during transfers, which results in **additional costs**. Leave it on unless your provider doesn't support SIP REFER.
          </Warning>

          <Frame>
            <img alt="Outbound Transfer Call Using SIP REFER toggle" />
          </Frame>
        </Step>

        <Step title="Authentication Methods (optional based on your VoIP)">
          **Credentials Authentication:**

          Use this method if your VoIP provider requires username/password credentials to authenticate outbound calls.

          Username:
          This is the identifier associated with your SIP account.

          Password:
          A secure password used to authenticate the SIP user.
          Make sure it meets your provider’s security requirements (e.g. minimum 12 characters, including upper/lowercase letters, a number, and a special character).

          <Frame>
            <img alt="Outbound credential-based authentication" />
          </Frame>

          **Header-Based Authentication:**

          Use this method if your VoIP provider requires custom headers for SIP request authentication.

          Header Key:
          This is the name of the custom SIP header field expected by your provider (e.g., X-Custom-Auth, X-Access-Token, etc.).

          Header Value:
          The corresponding value used to validate the request (e.g., a token, API key, or static secret).
          Example: AuthZ-87!t!link

          <Note>
            Header-based auth is typically used for advanced integrations or when SIP gateways are behind proxies/firewalls that don’t support IP or credential-based auth.
            Ensure this matches exactly what your provider expects, as even small typos (like case or symbols) can lead to rejections.
          </Note>

          <Info>
            You can add several key-value pairs if needed, for example, to meet multi-token security policies.
          </Info>

          <Frame>
            <img alt="Outbound header-based authentication" />
          </Frame>

          * **IP Address Allow List:**\
            **IP Address:** See [Twilio's SIP Trunking IP Addresses](https://www.twilio.com/docs/sip-trunking/ip-addresses).
        </Step>
      </Steps>
    </Card>
  </Step>

  <Step title="Managing Your Custom VoIP Phone Numbers">
    Once integrated:

    * **Assign to Inbound/Outbound:**\
      You can assign your custom VoIP phone numbers to inbound or outbound campaigns within NLPearl.AI.

    <Frame>
      <img alt="Assign a custom VoIP number to a campaign" />
    </Frame>

    * **Update Configuration:**\
      If any changes are needed, you can edit the VoIP settings by accessing the phone number in the Phone Numbers tab.
  </Step>
</Steps>

***

<Tip>
  ### Troubleshooting Tips

  **Connection Issues**: Double-check all configuration settings, especially SIP URLs, usernames, passwords, and IP addresses.

  **Authentication Failures**: Make sure the authentication method you've selected matches the one supported by your VoIP provider.

  **Provider Support**: If you're unsure about specific requirements, contact your VoIP provider for assistance with configuration.
</Tip>

<Info>
  ### Advantages of Custom VoIP Integration

  **Flexibility**: Leverage your existing VoIP infrastructure without switching providers or modifying your current setup.

  **Global Reach**: Access phone numbers and make calls in any region your VoIP provider supports, ideal for international teams.
</Info>

***

<Card title="Explore Other Options" icon="circle-info">
  <br />

  <CardGroup>
    <Card title="NLPearl Phone Numbers" icon="mobile" href="/pages/nlpearl_phones">
      Purchase and manage your **NLPearl-hosted phone numbers** directly, with instant activation and native support.
    </Card>

    <Card title="Twilio Integration" icon="object-intersect" href="/pages/twilio_integration">
      Explore our **Twilio Integration** to access a broader range of international phone numbers.
    </Card>
  </CardGroup>

  <Info>
    **Need Assistance?**\
    If you require help with the integration process, please refer to our support resources or contact our support team for guidance.
  </Info>
</Card>


# Dialogue Node
Source: https://developers.nlpearl.ai/pages/dialogue



<div>
  <Frame>
    <div>
      <img alt="Dialogue node cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Dialogue node cover" />
    </div>
  </Frame>
</div>

The **Dialogue** node is the main conversational node. Pearl speaks, asks questions, collects information, and keeps the conversation moving. It is the workhorse of most Pearl Voice flows.

## What it does

Unlike a traditional IVR, Dialogue is not a rigid prerecorded prompt. Pearl Voice understands the intent of the step, adapts its wording in real time to what the caller says, and can follow the most relevant configured transition based on the conversation.

## When to use it

Use Dialogue whenever Pearl needs to:

| Pearl needs to          | What it means                                                      |
| ----------------------- | ------------------------------------------------------------------ |
| **Speak to the caller** | Deliver a message, greeting, or confirmation                       |
| **Ask a question**      | Prompt the caller for an answer or a choice                        |
| **Collect information** | Capture details such as a name, email, or intent                   |
| **Explain something**   | Give context, options, or next steps                               |
| **React to the caller** | Respond before continuing or branching to another path in the flow |

## How to configure

<Steps>
  <Step title="Write the script">
    In **Script / Free Text**, enter what Pearl should say or ask. Maximum 500 characters. Supports all available variables.
  </Step>

  <Step title="Add instructions (optional)">
    Use **Instructions** to guide tone, context, exceptions, pronunciation, required details, or how closely Pearl should follow the script.
  </Step>
</Steps>

<div>
  <Frame>
    <div>
      <img alt="Dialogue node configuration on the platform" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Dialogue node configuration on the platform" />
    </div>
  </Frame>
</div>

<Tip>
  When specific wording must be followed closely, add clear instructions such as "Say this exactly", "Do not rephrase", or "Always include the following sentence".
</Tip>

## Transitions

Each Dialogue node includes a default **Continue** path. You can also add conditional transitions to direct the caller to another Dialogue node, an action node, or an End Call node.

Each conditional transition includes:

| Field           | Description                                      |
| --------------- | ------------------------------------------------ |
| **Condition**   | Written in plain language, with variable support |
| **Destination** | The node the caller is routed to                 |

<Card title="Example: routing on the caller's answer" icon="code-branch">
  Pearl asks whether the caller wants to book an appointment. Based on the answer, she can move to a Booking node, send an SMS, transfer the call, or continue to another part of the conversation.
</Card>


# Send Email Node
Source: https://developers.nlpearl.ai/pages/email_action



<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on light mode" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on dark mode" />
    </div>
  </Frame>
</div>

The **Send Email** node lets your AI agent send an email automatically when a condition is met during (or after) a conversation, for example a confirmation, a quote, or follow-up information.

## Fields to configure

Open the node and fill in the fields below to define who receives the email and what it contains.

<Frame>
  <img alt="Send Email node configuration on the platform" />
</Frame>

| Field              | Description                                                                                                                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **From**           | The sender account the email is sent from. Pick a connected account, click **Connect Email** to add one, or use **Edit** to update an existing connection. If none is selected, the default sender is used. |
| **To**             | The recipient address(es). Type addresses directly or insert variables (for example an email collected earlier in the conversation). At least one recipient is required.                                    |
| **CC** (optional)  | Additional recipients in copy. Supports the same direct input and variables as **To**.                                                                                                                      |
| **Subject**        | The subject line of the email. Insert variables to personalize it (for example the prospect's first name).                                                                                                  |
| **Content (Body)** | The body of the email, using a rich text (HTML) editor. Insert variables to include details gathered during the conversation, such as a price quote or a meeting time.                                      |

***

<Card title="Connecting your email">
  <div>
    <Frame>
      <img alt="Email provider configuration panel" />
    </Frame>
  </div>

  Pearl sends emails **from your own business address** using one of three providers. Pick the one that matches your setup.

  <Tabs>
    <Tab title="Gmail">
      <div>
        <img alt="Gmail" />

        <span>Send from your Gmail address</span>
      </div>

      <Steps>
        <Step title="Select the provider">
          Choose **Gmail** from the provider list.
        </Step>

        <Step title="Enter your sender email">
          Enter your Gmail address in **Sender Email**.
        </Step>

        <Step title="Add an app-password">
          Enter a **Gmail app-password**, not your normal password. [Learn how to generate one](https://support.google.com/accounts/answer/185833).
        </Step>

        <Step title="Test and save">
          *(Optional)* Add an address under **Test Email to**, click **Test Config**, then **Save**.
        </Step>
      </Steps>

      <Warning>Enable **2-factor authentication** on your Google account and use an **app-password**, not your main password.</Warning>
    </Tab>

    <Tab title="Office 365">
      <div>
        <img alt="Office 365" />

        <span>Send from your Microsoft 365 address</span>
      </div>

      <Steps>
        <Step title="Select the provider">
          Choose **Office 365** from the provider list.
        </Step>

        <Step title="Enter your sender email">
          Enter your Microsoft address in **Sender Email**.
        </Step>

        <Step title="Add an app-password">
          Enter an **Office 365 app-password** (see your Microsoft security settings).
        </Step>

        <Step title="Test and save">
          *(Optional)* Add a **Test Email** address, click **Test Config**, then **Save**.
        </Step>
      </Steps>

      <Warning>Office 365 may block basic SMTP by default. Make sure your tenant allows it and use an app-password where required.</Warning>
    </Tab>

    <Tab title="Custom SMTP">
      <div>
        <img alt="Custom SMTP" />

        <span>Send through any SMTP server</span>
      </div>

      <Steps>
        <Step title="Select the provider">
          Choose **Custom** from the provider dropdown.
        </Step>

        <Step title="Enter your SMTP server">
          For example `smtp.gmail.com`, `smtp.office365.com`, or `mail.yourdomain.com`.
        </Step>

        <Step title="Set the port and SSL">
          Enter the **Port**, usually **587** for TLS or **465** for SSL, then toggle **Enable SSL** (usually **On**).
        </Step>

        <Step title="Enter your credentials">
          Enter your **Sender Email** and its **SMTP account password**.
        </Step>

        <Step title="Test and save">
          *(Optional)* Add a **Test Email** address under **Test Email to**, click **Test Config**, then **Save**.
        </Step>
      </Steps>

      <Info>If you're unsure about your SMTP details, check with your email hosting provider (Google Workspace, Outlook, Zoho, etc.).</Info>
    </Tab>
  </Tabs>
</Card>

## Variables

Personalize the **Subject** and **Content**, and set dynamic **To** and **CC** recipients using variables collected during the conversation.

<Card title="Using variables" icon="brackets-curly" href="/pages/variables">
  Learn how to create and insert variables to tailor each email to the recipient.
</Card>


# Getting Started
Source: https://developers.nlpearl.ai/pages/getting_started

Go from sign-up to your first live AI agent in minutes.

<iframe title="NLPearl - Getting Started" />

This guide walks you through the full path: create an account, build your first agent, test it, and go live.

<Note>
  This guide focuses on building a **voice agent**. The flow is the same for **text agents** - you just connect your messaging channels (SMS, WhatsApp, email, chat) instead of a phone number. See [Pearl Text](/pages/text/pearl_text) to get started with text.
</Note>

***

## 1. Sign Up

Create your account at [platform.nlpearl.ai](https://platform.nlpearl.ai). You'll get complimentary minutes to test calls - no subscription required to start.

<Frame>
  <img alt="NLPearl sign-up screen" />
</Frame>

<Info>
  During the trial phase, you can create agents and run test calls. To unlock full inbound and outbound campaigns, you'll need to [subscribe to a plan](https://nlpearl.ai/pricing).
</Info>

***

## 2. Create Your Agent with PearlVibe

PearlVibe is how you build your AI agents - voice or text. Describe what you need in a single prompt - PearlVibe generates the agent's personality, conversation flow, knowledge base, and connected actions.

<Frame>
  <img alt="NLPearl dashboard with the PearlVibe chat" />
</Frame>

<Steps>
  <Step title="Write your prompt">
    When you land on the platform, the PearlVibe chat is right in front of you. Describe what your agent should do - be specific about the tone, language, and actions you need. Here are a few examples you can use as a starting point:
  </Step>

  <Step title="Review and refine">
    PearlVibe generates a complete agent configuration. Review the conversation flow, variables, and actions. Adjust anything that needs fine-tuning.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Hospitality - Hotel Concierge" icon="hotel">
    ```text theme={null}
    Create an inbound AI voice agent for a luxury hotel.
    The agent should answer guest calls 24/7, handle room reservations,
    check availability, process room service requests, and provide
    information about hotel amenities and local attractions.
    If a guest requests a VIP arrangement or has a complex request,
    transfer the call to the front desk. Send a confirmation email
    after every booking. Speak in a warm, professional tone.
    Support English, French, and Spanish.
    ```
  </Accordion>

  <Accordion title="Healthcare - Appointment Scheduling" icon="stethoscope">
    ```text theme={null}
    Create an inbound AI voice agent for a medical clinic.
    The agent should schedule, confirm, and reschedule patient appointments.
    Collect the patient's name, date of birth, reason for visit,
    and insurance provider. Send an SMS reminder 24 hours before
    the appointment. If the patient describes an urgent medical situation,
    transfer immediately to the on-call nurse. Tone should be calm,
    empathetic, and reassuring. Support English and Spanish.
    ```
  </Accordion>

  <Accordion title="E-commerce & Retail - Cart Recovery & Support" icon="cart-shopping">
    ```text theme={null}
    Create an outbound AI voice agent for an online store.
    The agent should call customers who abandoned their cart in the
    last 24 hours, remind them of the items they left, offer assistance
    with any questions, and provide a 10% discount code if they're
    hesitant. Collect the reason for abandonment as a variable.
    If the customer wants to speak to a human, transfer to the
    support team. Tone should be friendly and helpful, not pushy.
    ```
  </Accordion>

  <Accordion title="Legal - Client Intake & Consultation" icon="scale-balanced">
    ```text theme={null}
    Create an inbound AI voice agent for a law firm.
    The agent should handle new client intake calls by collecting
    the caller's name, contact information, case type (personal injury,
    family law, criminal defense, etc.), and a brief description
    of their situation. Qualify the lead based on case type and urgency.
    If the case qualifies, schedule a consultation with an attorney.
    Send a confirmation email with the appointment details.
    If the matter is urgent, transfer directly to a lawyer.
    Tone should be professional, confidential, and reassuring.
    ```
  </Accordion>

  <Accordion title="Utilities - Service & Outage Support" icon="bolt">
    ```text theme={null}
    Create an inbound AI voice agent for a utility company.
    The agent should handle outage reports, billing inquiries,
    service activation requests, and meter reading appointments.
    Collect the customer's account number and service address.
    If the customer reports a gas leak or emergency, transfer
    immediately to the emergency line. For billing disputes,
    transfer to a specialist. Send an SMS confirmation for
    any scheduled technician visit. Tone should be clear,
    helpful, and efficient.
    ```
  </Accordion>

  <Accordion title="Education - Admissions & Enrollment" icon="graduation-cap">
    ```text theme={null}
    Create an inbound AI voice agent for a university admissions office.
    The agent should answer prospective student inquiries about programs,
    application deadlines, tuition, financial aid, and campus visits.
    Collect the student's name, program of interest, and preferred
    start date. Schedule campus tours and admissions consultations.
    Send a follow-up email with program details and application links.
    If a parent or student has a complex financial aid question,
    transfer to an admissions advisor. Friendly and encouraging tone.
    Support English and Spanish.
    ```
  </Accordion>

  <Accordion title="Telecommunications - Tech Support & Billing" icon="tower-cell">
    ```text theme={null}
    Create an inbound AI voice agent for a telecom provider.
    The agent should handle billing inquiries, plan changes,
    SIM activation, and basic technical troubleshooting (restart router,
    check signal, verify coverage). Collect the customer's account number
    and phone number for verification. If the issue requires advanced
    technical support or the customer wants to cancel, transfer to
    a retention specialist. Schedule fiber installation appointments
    when requested. Send a confirmation SMS after any plan change.
    Professional and patient tone.
    ```
  </Accordion>

  <Accordion title="Call Center - Multi-Purpose Support" icon="headset">
    ```text theme={null}
    Create an inbound AI voice agent for a BPO call center.
    The agent should handle first-level support across multiple clients:
    answer FAQs, log support tickets via API, collect customer information
    (name, account number, issue description), and route complex cases
    to the appropriate department. If the caller requests a callback,
    schedule one and send a confirmation SMS. The agent should be able
    to handle unlimited simultaneous calls with consistent quality.
    Neutral, professional tone. Support English, Spanish, and French.
    ```
  </Accordion>

  <Accordion title="Insurance - Claims Intake" icon="shield-halved">
    ```text theme={null}
    Create an inbound AI voice agent for an insurance company.
    The agent should handle first notice of loss calls by collecting
    the policyholder's name, policy number, type of incident,
    date and location of the event, and a brief description.
    Log everything via API to the claims management system.
    If the claim sounds urgent or involves injury, transfer
    to a senior claims adjuster immediately. Tone should be
    calm, professional, and supportive.
    ```
  </Accordion>

  <Accordion title="Debt Management - Payment Recovery" icon="money-bill-wave">
    ```text theme={null}
    Create an outbound AI voice agent for a debt recovery agency.
    The agent should contact customers with overdue balances,
    verify their identity, inform them of the outstanding amount,
    and offer payment options (full payment, installment plan).
    If the customer agrees to pay, send a payment link via SMS.
    If they dispute the debt, transfer to a specialist.
    Always remain compliant, respectful, and non-aggressive.
    ```
  </Accordion>

  <Accordion title="Real Estate - Lead Qualification" icon="building">
    ```text theme={null}
    Create an outbound AI voice agent for a real estate agency.
    The agent should call new leads, qualify them by asking about budget,
    preferred location, property type (buy or rent), and timeline.
    Score each lead as hot, warm, or cold based on their answers.
    If the lead is hot, schedule a property viewing and transfer
    to an agent. Send a follow-up email with property listings
    matching their criteria. Professional and knowledgeable tone.
    ```
  </Accordion>

  <Accordion title="Government - Citizen Services" icon="landmark">
    ```text theme={null}
    Create an inbound AI voice agent for a government public service office.
    The agent should answer citizen inquiries about permits, document
    requirements, office hours, and service locations. Schedule in-person
    appointments for permit applications and document submissions.
    Collect the citizen's name, request type, and preferred appointment date.
    Send a confirmation SMS with appointment details and required documents.
    If the request is sensitive or requires human review, transfer to
    a case officer. Tone should be clear, neutral, and helpful.
    Support English and Spanish.
    ```
  </Accordion>

  <Accordion title="Airlines - Passenger Support" icon="plane">
    ```text theme={null}
    Create an inbound AI voice agent for an airline.
    The agent should handle booking changes, flight status inquiries,
    seat selection, baggage information, and check-in assistance.
    Collect the passenger's booking reference and last name for
    verification. If a flight is disrupted, offer rebooking options
    and send the updated itinerary by email. For complex itineraries
    or refund requests, transfer to a senior agent.
    Tone should be calm, efficient, and reassuring.
    Support English, French, Spanish, and German.
    ```
  </Accordion>

  <Accordion title="Survey & Polling - Automated Research" icon="square-poll-vertical">
    ```text theme={null}
    Create an outbound AI voice agent for a market research firm.
    The agent should call respondents, introduce the survey purpose,
    and ask a series of 8-10 structured questions about customer
    satisfaction. Collect each answer as a variable and log responses
    via API to the research platform. If the respondent wants to
    opt out, thank them and end the call. If they want to speak
    to a researcher, schedule a callback. Consistent, neutral tone
    to avoid interviewer bias. Support English and Spanish.
    ```
  </Accordion>
</AccordionGroup>

<Card title="PearlVibe Documentation" icon="wand-magic-sparkles" href="/pages/pearl_vibe">
  Full guide on creating and customizing agents with PearlVibe.
</Card>

***

## 3. Test Your Agent

Once your agent is ready, run test calls directly from the platform to hear how it sounds, verify the conversation flow, and confirm that actions (API calls, transfers, emails) fire correctly.

<Frame>
  <img alt="Run a test call from the platform" />
</Frame>

<Tip>
  Use your complimentary minutes for testing. Iterate on the prompt, variables, and actions until the agent handles your scenarios cleanly.
</Tip>

***

## 4. Tweak and Optimize

Based on your test calls:

* **Adjust the conversation flow** - refine how the agent responds to edge cases or unexpected inputs.
* **Configure variables** - make sure data collection (names, emails, IDs) works as expected. See [Variables](/pages/variables).
* **Set up actions** - connect API calls, call transfers, email or SMS triggers. See [API Node](/pages/api_action).

***

## 5. Publish Your Agent

When you're satisfied with the agent's performance, publish it. This locks in your configuration and makes the agent available for live campaigns.

***

## 6. Connect a Phone Number

Assign a phone number to your agent. All plans include at least one US number. You can purchase additional numbers or port existing ones from the [Phone Numbers](/pages/phone_numbers) settings.

<Note>
  Building a text agent instead? Connect your messaging channels (SMS, WhatsApp, email, chat) rather than a phone number. See [Pearl Text](/pages/text/pearl_text).
</Note>

***

## 7. Go Live

Launch your campaign:

* **Inbound** - Route incoming calls to your agent. See [Inbound](/pages/inbound).
* **Outbound** - Upload contacts and let your agent initiate calls. See [Outbound](/pages/outbound).

Monitor performance in real time from the [Call Analytics](/pages/analytics) dashboard.

***

## Billing & Credits

Once you subscribe to a plan, you get access to agents, phone numbers, and call minutes. Each call minute is deducted from your plan's included minutes - once exhausted, your credits are used.

<Frame>
  <img alt="Subscription plans in Subscriptions & Payments" />
</Frame>

<CardGroup>
  <Card title="Full Access to Activities" icon="check">
    Engage in both inbound and outbound activities with no restrictions.
  </Card>

  <Card title="Included Agents & Phone Numbers" icon="check">
    Concurrent agents and at least one US phone number included in every plan.
  </Card>
</CardGroup>

<Note>
  **Auto-Recharge** - We recommend activating [auto-recharge](https://platform.nlpearl.ai/app/settings/subscriptions-and-payments/credits) to automatically top up your credits when they fall below a threshold, ensuring uninterrupted service.
</Note>

<Warning>
  **Credit limits** - When credits drop below zero, your concurrent agents per activity are reduced to one. If your debt reaches 10% of your monthly subscription price, all activities are suspended until you recharge.
</Warning>

***

## What's Next

<CardGroup>
  <Card title="PearlVibe" icon="wand-magic-sparkles" href="/pages/pearl_vibe">
    Deep dive into agent creation and customization.
  </Card>

  <Card title="Call Analytics" icon="chart-mixed" href="/pages/analytics">
    Track and optimize your agent's performance.
  </Card>

  <Card title="Billing & Credits" icon="credit-card" href="/pages/billing">
    Manage your subscription, credits, and auto-recharge.
  </Card>

  <Card title="API Quick Start" icon="code" href="/api-reference/api_quickstart">
    Integrate NLPearl programmatically via the REST API.
  </Card>

  <Card title="Subscription Plans" icon="wallet" href="https://nlpearl.ai/pricing/">
    Compare plans and choose the best one for your needs.
  </Card>
</CardGroup>


# Inbound Calls
Source: https://developers.nlpearl.ai/pages/inbound

Configure your Pearl to handle incoming calls, from recording and transcripts to the holding line and webhooks.

<div>
  <Frame>
    <div>
      <img alt="Inbound cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Inbound cover" />
    </div>
  </Frame>
</div>

***

## Setting Up Inbound Calls

Once you have created a Pearl, you can enable it to receive inbound calls. Inbound settings are configured inside your Pearl, under **Inbound Settings**, giving callers a dynamic and responsive experience driven by your conversational flow.

<Info>
  **What are inbound calls?**

  Inbound calls let your Pearl handle incoming calls, engaging with callers immediately and effectively using the conversational flow you defined.
</Info>

***

## Attach a Phone Number

To receive calls, your Pearl needs a phone number. Numbers are purchased and connected from **Settings → Phone Numbers**, not from the Inbound Settings screen.

Start by clicking your **profile card** at the bottom-left corner of the sidebar, then open **Settings**.

<Frame>
  <img alt="Open Settings from the profile card" />
</Frame>

Then select the **Phone Numbers** tab. From here you can purchase, connect, and manage all your numbers.

<Frame>
  <img alt="Phone Numbers tab in Settings" />
</Frame>

You have three ways to get a number for your Pearl:

<Card>
  <div>
    <img alt="Logo clair" />

    <span>NLPearl Number</span>
  </div>

  <div>
    <img alt="Logo sombre" />

    <span>NLPearl Number</span>
  </div>

  Buy a number directly from NLPearl and start receiving or making calls in minutes (US numbers, billed monthly).

  <Info>
    For more details, visit the [NLPearl Phone Numbers](/pages/nlpearl_phones) page.
  </Info>
</Card>

<br />

<Card>
  <div>
    <img alt="Logo clair" />

    <span>Twilio</span>
  </div>

  <div>
    <img alt="Logo sombre" />

    <span>Twilio</span>
  </div>

  Connect your Twilio account to use your existing numbers, with access to a wide range of countries.

  <Info>
    Visit [Twilio Integration](/pages/twilio_integration) for details on how to import and manage your Twilio phone numbers.
  </Info>
</Card>

<br />

<Card>
  <div>
    <img alt="Logo clair" />

    <span>Custom VoIP</span>
  </div>

  <div>
    <img alt="Logo sombre" />

    <span>Custom VoIP</span>
  </div>

  Bring your own VoIP provider and connect custom numbers over SIP to your account.

  <Info>
    To learn more about integrating your own VoIP service, check out [Custom VoIP Integration](/pages/custom_voip).
  </Info>
</Card>

Once you have a number, attach it to your Pearl: open the Pearl's **Settings** panel and pick the number from the **Phone Number** dropdown. Your Pearl will then answer calls on that number.

<Frame>
  <img alt="Select the phone number in the Pearl settings" />
</Frame>

***

## Inbound Settings

Configure how your Pearl answers incoming calls from the **Inbound Settings** tab of your Pearl, in the [PearlVibe](/pages/pearl_vibe) flow editor.

<Warning>
  These settings apply to **voice** Pearls only. A Text Pearl has a different set of inbound options.
</Warning>

### Recording Options

Record the conversation (on/off). When enabled, the call audio is saved and available afterwards from your **call logs** for quality reviews, training, and analytics. When disabled, no audio is captured or stored.

<Frame>
  <img alt="Recording Options setting" />
</Frame>

<Warning>
  Call recording laws vary by region and often require informing or getting consent from callers. Make sure your Pearl's flow discloses recording where required.
</Warning>

***

### Recording After Transfer Call

If enabled, the call keeps recording after Pearl transfers it and leaves the line, so you capture the full conversation with the human agent. Turn it off if you don't want to record the person or third party the call is transferred to.

<Frame>
  <img alt="Recording After Transfer Call setting" />
</Frame>

<Note>
  This option only appears when **Recording Options** is enabled. See the [Transfer Call Node](/pages/transfer_call) to learn how call transfers work.
</Note>

***

### Transcript Options

Choose what is kept from the call transcript. Transcripts appear in your call logs alongside the recording.

<Frame>
  <img alt="Transcript Options setting" />
</Frame>

| Option                     | Description                                                                                                                                      | When to use                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| **Full Transcript**        | Keeps the entire conversation as-is.                                                                                                             | Complete analysis, QA, and training. |
| **Sensitive Info Removed** | Automatically masks sensitive data (credit card numbers, Social Security numbers, personal identifiers) while keeping the conversation readable. | Compliance and PII protection.       |
| **No Transcript**          | No transcript is stored for the call.                                                                                                            | Maximum privacy.                     |

<Info>
  With **Sensitive Info Removed**, if a customer says *"My credit card number is 1234-5678-9012-3456"*, the transcript stores it as *"My credit card number is \*\*\*\*-3456"*, so you can review interactions safely without exposing sensitive data.
</Info>

***

### Hold Message

Played to callers when they are put on hold, typically when all agents are busy and the caller enters the holding line. English only, max **300 characters**.

<Frame>
  <img alt="Hold Message setting" />
</Frame>

<Info>
  Example: *"Thanks for calling! One moment while I connect you to our team."*
</Info>

<Note>
  If your Pearl experiences high call volumes, callers are not turned away. They enter the holding line and hear your hold message and sound until an agent becomes available.
</Note>

***

### Estimated Wait Time

When enabled (on/off), callers on hold hear their position in the queue and an estimated wait time, along with your hold message. Setting expectations this way helps reduce hang-ups during busy periods.

<Frame>
  <img alt="Estimated Wait Time setting" />
</Frame>

***

### Hold Sound

The music that loops while callers wait in the holding line. Select one of the built-in tracks or upload your own `.mp3` (up to **3 minutes**). Use the preview button to listen before saving.

<Frame>
  <img alt="Hold Sound setting" />
</Frame>

***

### Call Ambience

A subtle background environment (office, call center, outdoor…) played **during the live conversation** to make the call sound more natural and human. Defaults to **None**.

Pick an ambience from the dropdown, then fine-tune its **volume** (0–100) with the slider. A preview plays automatically so you can hear the result before saving.

<Frame>
  <img alt="Call Ambience setting" />
</Frame>

<Note>
  Don't confuse this with **Hold Sound**: Call Ambience plays quietly behind Pearl's voice during the call, while Hold Sound only plays while a caller is waiting in the holding line.
</Note>

***

### Webhooks

Send call lifecycle events to an external endpoint.

<Frame>
  <img alt="Webhooks setting" />
</Frame>

* **Version**: `V1` or `V2` (default **V2**). V2 is the current payload format; keep V1 only if you have an older integration built against it.
* **Call Webhook URL**: fires at key points in the call lifecycle (when the call starts and when it ends), sending an object similar to the [Get Calls Endpoint](/api-reference/v2/call/get-call) with details like duration, outcome, and any data collected during the call.
* **Credentials**: optional authentication token attached to the requests so your endpoint can verify they come from NLPearl.

<Tip>
  Use Webhooks only if external tools need event notifications. For actual automations, rely on **Post-Call Actions** tied to how the call ended.
</Tip>

<Card title="Webhooks" icon="webhook" href="/pages/webhooks">
  Learn how to configure webhooks, authenticate requests, and handle the events NLPearl sends.
</Card>

***

## Project-Level Settings

A few settings live at the **Project** level rather than in the Inbound Settings screen. Open them from the settings popover on your Pearl.

<Frame>
  <img alt="Project settings: agents and data retention" />
</Frame>

### Agents

Sets how many **simultaneous agents** handle this Pearl's incoming calls, i.e. how many calls can be answered at the same time, capped by your account's agent quota. A higher number lets your Pearl take more concurrent callers before the rest enter the holding line.

<Frame>
  <img alt="Agents setting in the Pearl settings panel" />
</Frame>

<Card title="Agents" icon="users" href="/pages/agents">
  Learn how to manage the agents assigned to your inbound and outbound activities.
</Card>

***

### Call Retention

Applies to **all calls**. Set how long calls are kept (a number of days, or leave empty to keep them indefinitely), then choose what is removed when they expire: delete all call data, or granularly the **Recording**, **Transcript**, **Summary**, or collected **Variables**.

<Frame>
  <img alt="Call Retention settings" />
</Frame>

***

<Info>
  ### Monitoring and Adjusting Your Inbound Calls

  While basic monitoring of call logs and reports can be done via our API, any changes to the setup, such as voice or language settings, must be handled directly on the platform.
</Info>


# Welcome to NLPearl
Source: https://developers.nlpearl.ai/pages/introduction

Build and deploy AI agents - voice agents that handle real phone conversations in 20+ languages, and text agents across SMS, WhatsApp, email, and chat - all by simply chatting with AI.

<div>
  <Frame>
    <div>
      <img alt="NLPearl documentation cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="NLPearl documentation cover" />
    </div>
  </Frame>
</div>

## What is NLPearl?

NLPearl is an AI agent platform that lets you create, deploy, and manage AI agents that hold real conversations with your customers - inbound and outbound, at scale.

Our flagship **AI voice agents** handle real phone conversations, built on a proprietary speech-to-speech architecture that delivers natural, low-latency, full-duplex voice in 20+ languages. With **Pearl Text**, you can also deploy AI text agents across SMS, WhatsApp, email, and chat - and connect both for continuous, cross-channel customer experiences.

PearlVibe - your AI agent engineer - builds your agents, configures their logic, and connects them to your tools automatically.

<CardGroup>
  <Card title="Pearl Voice" icon="phone-volume" href="/pages/pearl_voice">
    AI voice agents that handle real phone conversations - inbound and outbound - in 20+ languages.
  </Card>

  <Card title="Pearl Text" icon="messages" href="/pages/text/pearl_text">
    AI text agents that message your customers across SMS, WhatsApp, email, and chat.
  </Card>
</CardGroup>

***

## Example Use Cases

### Inbound

| Use Case                                | Description                                                                                                  |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Inbound Call Handling**               | Answer incoming calls, resolve questions, collect information, and route to the right team - 24/7, at scale. |
| **Technical Support & Troubleshooting** | Guide customers through issue resolution step by step, collect diagnostic info, and escalate when needed.    |
| **Order Tracking & Status Inquiries**   | Let customers call to get instant updates on their order, shipment, or delivery status.                      |
| **FAQ & Knowledge Base**                | Handle high-volume repetitive questions automatically without tying up human agents.                         |
| **Complaint Handling**                  | Capture customer complaints, collect context, log them in your CRM, and route to the right team.             |
| **Returns & Refunds Processing**        | Walk customers through return or refund requests, collect required details, and initiate the process.        |
| **Account Management**                  | Handle address changes, subscription updates, password resets, and account inquiries via voice.              |
| **Appointment Scheduling**              | Book, confirm, and reschedule appointments from inbound calls with real-time calendar integrations.          |
| **Customer Onboarding**                 | Welcome new customers, collect required information, and walk them through next steps automatically.         |
| **Job Candidate Screening**             | Pre-qualify candidates, ask screening questions, and schedule interviews automatically.                      |
| **Internal Operations**                 | Automate internal workflows - HR surveys, team reminders, shift confirmations, or field report collection.   |

### Outbound

| Use Case                                | Description                                                                                                    |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Outbound Sales & Prospecting**        | Call leads, qualify prospects, pitch your offer, and book meetings.                                            |
| **Lead Qualification**                  | Pre-qualify leads through dynamic conversations, score them with variables, and sync results to your pipeline. |
| **Appointment Reminders**               | Send reminder calls ahead of scheduled appointments to reduce no-shows by up to 70%.                           |
| **Payment & Billing Follow-ups**        | Automate payment reminders, invoice confirmations, and collections calls.                                      |
| **Debt Collection**                     | Run personalized collections outreach, capture promises to pay, and log outcomes in your CRM.                  |
| **Post-Service Follow-up**              | Check in after an intervention, measure satisfaction, and trigger upsell or renewal flows.                     |
| **Re-engagement Campaigns**             | Reach out to inactive customers, revive abandoned carts, or reactivate dormant accounts.                       |
| **Upsell & Cross-sell Calls**           | Proactively offer upgrades, add-ons, or complementary products after a purchase or at renewal time.            |
| **Warranty & Renewal Reminders**        | Notify customers when a contract, subscription, or warranty is about to expire.                                |
| **Event & Webinar Registration**        | Invite, confirm registration, and send reminders ahead of events or webinars.                                  |
| **Order Status & Delivery Updates**     | Proactively notify customers of order confirmations, shipping updates, or delivery issues.                     |
| **Product Recall & Compliance Notices** | Reach affected customers with regulatory or safety notices at scale.                                           |
| **Loyalty & Retention Programs**        | Call at-risk customers, offer incentives, and collect churn feedback before it's too late.                     |
| **Alert & Notification Calls**          | Trigger outbound calls for critical events - fraud alerts, order status updates, or system incidents.          |
| **Emergency & Crisis Notifications**    | Broadcast mass alert calls for outages, incidents, or urgent operational situations.                           |

***

## How It Works

<Steps>
  <Step title="Build your agent">
    Use PearlVibe to define your agent type, personality, knowledge base, conversation logic, and connected actions - while seamlessly integrating your tools - all through a prompt-driven interface.
  </Step>

  <Step title="Deploy on your channels">
    For voice, assign a phone number or connect your own SIP-compatible VoIP provider. For text, connect your messaging channels (SMS, WhatsApp, email, chat). Then launch inbound lines or outbound campaigns - your agent starts handling real conversations immediately.
  </Step>

  <Step title="Monitor and optimize">
    Track performance with real-time analytics, review post-call and post-chat transcripts and summaries, and iterate on your agent's behavior.
  </Step>
</Steps>

***

## What You Can Do

### Build Your Agent

<CardGroup>
  <Card title="PearlVibe" icon="wand-magic-sparkles" href="/pages/pearl_vibe">
    Design your agent's type, personality, knowledge, conversation flow, and actions, while seamlessly integrating your tools - all from a single prompt-driven interface.
  </Card>

  <Card title="Variables" icon="brackets-curly" href="/pages/variables">
    Collect, store, and manipulate data during conversations - from user inputs to CRM lookups.
  </Card>
</CardGroup>

### Deploy & Connect

<CardGroup>
  <Card title="Inbound" icon="phone-arrow-down-left" href="/pages/inbound">
    Deploy agents on inbound lines to answer calls, resolve questions, and route to the right team.
  </Card>

  <Card title="Outbound" icon="phone-arrow-up-right" href="/pages/outbound">
    Launch outbound campaigns to reach leads, qualify prospects, and follow up at scale.
  </Card>
</CardGroup>

### Monitor & Optimize

<CardGroup>
  <Card title="Call Analytics" icon="chart-mixed" href="/pages/analytics">
    Track success rates, sentiment, call duration, cost breakdown, and more from a unified dashboard.
  </Card>

  <Card title="Post-Call Data" icon="clipboard-check" href="/pages/postcall">
    Access structured summaries, transcripts, recordings, and extracted variables for every call.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/pages/getting_started">
    Go from sign-up to your first live call in minutes.
  </Card>

  <Card title="API Quick Start" icon="code" href="/api-reference/api_quickstart">
    Integrate NLPearl programmatically via our REST API.
  </Card>
</CardGroup>

***

## Stay Connected

<CardGroup>
  <Card title="Join Our LinkedIn Community" icon="linkedin" href="https://www.linkedin.com/company/nlpearl/mycompany/">
    Connect with experts and peers for updates, support, and knowledge sharing.
  </Card>
</CardGroup>


# Knowledge Base
Source: https://developers.nlpearl.ai/pages/knowledge_base



<div>
  <Frame>
    <div>
      <img alt="Knowledge Base cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Knowledge Base cover" />
    </div>
  </Frame>
</div>

Before your Pearl can answer questions accurately, it needs context. This step helps define the essential background information your agent will rely on during conversations.

***

## Company Name

Give your Pearl the name of the company it represents. This name may be used when Pearl introduces itself or provides company-related information.

<Frame>
  <img alt="Company Name field in the Knowledge Base" />
</Frame>

***

## Company Description

Add a brief company description including your industry, mission, or key services. This allows Pearl to answer questions with more contextual relevance.

<Frame>
  <img alt="Company Description field in the Knowledge Base" />
</Frame>

***

## Pearl Knowledge Base

This is where you teach Pearl what it needs to know to respond with relevance and accuracy. Add detailed information about your services, pricing, opening hours, locations, and any key operational data.

<Frame>
  <img alt="Pearl Knowledge Base field with file upload" />
</Frame>

<Note>
  **Background knowledge, not a script.** The Knowledge Base is passive reference data: Pearl consults it **only when needed** to answer accurately. It doesn't dictate the conversation flow, that's handled by the Flow Editor.
</Note>

<Note>
  Both options live in the same area and can be combined: type your information directly in the **text field** and/or **upload reference files**. Multiple documents can be added if needed.
</Note>

Whether you're describing how your subscription plans work, listing available services, or clarifying your business hours, this section allows Pearl to access structured information that supports more precise answers.

<Info>
  This is the same knowledge that powers the [Knowledge Base node](/pages/knowledge_base_node) in the Flow Editor. What you add here is what your Pearl draws on during conversations.
</Info>

### Files and limits

These caps apply **per Pearl**: they cover every file attached to that Pearl's Knowledge Base, not each file individually.

| Limit                           | Value                                  |
| ------------------------------- | -------------------------------------- |
| Number of files                 | 50                                     |
| Supported formats               | `.pdf`, `.docx`, `.txt`                |
| Total size of all files         | 25 MB (no per-file cap)                |
| Total text extracted from files | 1,000,000 characters                   |
| Free-text field                 | 20,000 characters (counted separately) |

There is no page limit and no character cap on an individual document, only the shared 25 MB and 1,000,000-character totals apply. The free-text field has its own 20,000-character budget and does **not** consume the 1,000,000 characters reserved for files.

<Tip>
  A **Knowledge Base File Usage** bar appears once the text extracted from your files passes **100,000 characters**, so you can keep an eye on how much of the budget is left.
</Tip>

<Warning>
  Pearl uses the **text extracted** from your `.pdf`, `.docx`, and `.txt` files. Standalone image files can't be uploaded, so make sure anything Pearl needs to answer with exists as text in the document.
</Warning>

***

## Memory

When enabled, Pearl remembers the user or lead, allowing it to seamlessly continue conversations from where they left off.

<Frame>
  <img alt="Memory On/Off toggle in the Knowledge Base" />
</Frame>

<Tip>
  This feature is particularly useful for:

  * Multi-step processes
  * Follow-ups
  * Any scenario where continuity matters
</Tip>

<Card>
  ### Example use case: Hospitality

  Let's say a guest checks into a hotel. Pearl can:

  * Remember their room number
  * Greet them by name
  * Recall their preferences (like "extra towels" or "no wake-up call")
  * Offer a smooth, personalized experience every time they call
</Card>

<Info>
  **Resetting Memory**

  Need a fresh start? Pearl's memory can be reset via API.

  This is especially important in contexts like hospitality, where once a guest checks out, Pearl clears the slate, ensuring the next visitor starts with a clean experience.
</Info>

***

## Speech Recognition Keywords

Some words are just… not in the dictionary. Whether you're using brand-specific terms, creative product names, or industry jargon, teaching Pearl how to recognize them makes all the difference.

<Frame>
  <img alt="Speech Recognition Keywords table" />
</Frame>

Use this feature to define:

* **Keywords**: The unique word or name you want Pearl to catch
* **Pronunciations**: Variations of how users might say it (spoken form)

<Card>
  ### Example

  Let's say your bakery sells a pastry called `FluffoBun`.

  Here's how you'd define it:

  * **Keyword:** FluffoBun
  * **Pronunciations:** fluh-foh-bun, floof-oh-bun, fluff-bunb\
    *(Separate each pronunciation with a comma)*

  This helps Pearl match even creatively named terms to real user input, no matter how it's pronounced.
</Card>

***

## Speech Output Pronunciations

Speech Output Pronunciations let you fine-tune how Pearl *pronounces* specific words or short phrases out loud. You provide the text as it appears (**Pearl says**) and a simple phonetic respelling of how it should actually sound (**Caller hears**).

<Frame>
  <img alt="Speech Output Pronunciations table" />
</Frame>

Whenever Pearl is about to speak a word or phrase listed in **Pearl says**, it uses the **Caller hears** respelling instead. It changes the **audio only**: your scripts, variables, and node text stay exactly as you wrote them.

Reach for it whenever text-to-speech mispronounces something important, such as:

| Use case                            | Example                                     |
| ----------------------------------- | ------------------------------------------- |
| **Brand and product names**         | `Nike` → `ny-kee`                           |
| **Acronyms** you want spelled out   | `NLPearl` → `N-L-Pearl`                     |
| **Industry terms**                  | `SQL` → `sequel`                            |
| **Abbreviations** you want expanded | `Dr.` → `Doctor`                            |
| **Foreign or uncommon words**       | Words that need a specific phonetic reading |

To add one, fill the empty row at the bottom: type the text in **Pearl says**, then a plain phonetic respelling in **Caller hears** (readable syllables separated by hyphens, e.g. `ny-kee`). Use the trash icon on a row to delete it.

<Info>
  Write **Caller hears** the way it should be *spoken*, not spelled, e.g. `2024` → `twenty twenty-four`, or `NLPearl` → `N L Pearl`. Keep it simple and phonetic.
</Info>

<Warning>
  **Each row must have both fields filled**: a **Pearl says** value *and* a **Caller hears** value. Otherwise the row is flagged as incomplete. Empty rows are ignored and dropped when you save.
</Warning>

<Note>
  **Limits:** up to **25** entries, and each field is capped at **50 characters**.
</Note>

<Note>
  **Speech Output Pronunciations vs. Speech Recognition Keywords** — don't mix them up:

  * **Speech Output Pronunciations** control how Pearl **speaks** (text-to-speech / output). Fields: **Pearl says** → **Caller hears**.
  * **Speech Recognition Keywords** help Pearl **understand** what the caller says (speech-to-text / input). Fields: a **keyword** plus one or more **pronunciations** it might be heard as.
</Note>


# Knowledge Base Node
Source: https://developers.nlpearl.ai/pages/knowledge_base_node



<div>
  <Frame>
    <div>
      <img alt="Knowledge Base node cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Knowledge Base node cover" />
    </div>
  </Frame>
</div>

The **Knowledge Base** node lets Pearl look up answers in your uploaded knowledge base during a live conversation, instead of relying on a scripted line.

**What it does**

Pearl searches your knowledge base for the most relevant content and uses it to answer the caller in a natural, contextual way.

**When to use it**

Use this node whenever Pearl should answer from your own documents or FAQ content (product details, pricing, policies, opening hours) rather than a fixed script. It is ideal for open-ended questions where the exact wording can vary.

## How to configure

* **Instructions** (optional): tell Pearl when and how to rely on the knowledge base. Keep it short and specific.
  * Example: "Use the knowledge base for any question about pricing, plans, or opening hours."

<div>
  <Frame>
    <div>
      <img alt="Knowledge Base node on the platform" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Knowledge Base node on the platform" />
    </div>
  </Frame>
</div>

<Info>
  The knowledge content itself is uploaded and managed in the flow's **Knowledge Base** area, not inside the node. The node only tells Pearl *to* consult it. See [Agent Knowledge Base](/pages/knowledge_base) to manage your content, including [supported formats and limits](/pages/knowledge_base#files-and-limits).
</Info>

## Example

<Card title="Example: answering about opening hours">
  Imagine you uploaded a document to your knowledge base that says:

  > The clinic is open Monday to Friday, 9 AM to 6 PM, and Saturday from 9 AM to 1 PM.

  Here is how the node uses it during a call:

  1. The caller asks: *"Are you open on Saturdays?"*
  2. The **Knowledge Base** node lets Pearl search that document and find the opening hours.
  3. Pearl answers: *"Yes, we're open on Saturdays from 9 AM to 1 PM."*

  Without this node, Pearl would not have access to your specific hours and could not answer reliably.
</Card>

## Good to know

* The knowledge content is managed once in Agent Knowledge Base, so every Knowledge Base node in your flow uses the same documents. You don't need to re-upload them for each node.
* If no relevant information is found, Pearl falls back to the rest of your flow instead of inventing an answer.
* Pair this node with a [Dialogue](/pages/dialogue) node to ask a follow-up question once the answer is delivered.


# Voices and Languages
Source: https://developers.nlpearl.ai/pages/languages

At NLPearl, we offer a wide variety of languages and accents to cater to a global audience. You can configure your Pearl to handle conversations in multiple languages, providing a seamless and personalized experience for your users.

<div>
  <Frame>
    <div>
      <img alt="Voices and Languages cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Voices and Languages cover" />
    </div>
  </Frame>
</div>

***

### Configuring Agent Names, Languages & Voices

When creating or editing your Pearl, you can set up multiple agents with different languages and voices. This flexibility allows your Pearl to engage in conversations in more than one language and switch smoothly between them as needed.

***

#### How to Add Multiple Languages and Voices

<Steps>
  <Step title="Open the Agent Names, Languages & Voices section">
    In **Pearl Settings**, find the **Agent Names, Languages & Voices** section. Each row is one agent, with its name, language, voice, and accent. This is where you add, configure, and order your agents.

    <Frame>
      <img alt="Agent Names, Languages & Voices section in Pearl Settings" />
    </Frame>
  </Step>

  <Step title="Add an agent">
    Fill in the empty row at the bottom of the table to add a new agent:

    * **Name**: the name the agent uses during conversations in that language.
    * **Language**: pick a language from the supported list.
    * **Voice**: pick a voice for that language.

    <Note>
      Each language can be assigned to **only one agent**. A language that's already in use won't be selectable for another agent.
    </Note>
  </Step>

  <Step title="Choose a voice and accent">
    Open the **Voice** dropdown to browse the available voices. Use the **search** box to filter, and check the **accent label** next to each voice (e.g. `en-US`, `en-UK`) to match your target audience. Click the **play button** next to a voice to hear a sample before selecting it.

    <Frame>
      <img alt="Voice dropdown with search, accent labels and preview" />
    </Frame>
  </Step>

  <Step title="Set the default (opening) language">
    The agent marked **Default** is the one your Pearl uses to open the conversation. The first agent you add becomes the default automatically.

    To change it, hover over the agent you want and click the **Set as default** (↑) button. Use the **delete** icon to remove an agent.

    <Frame>
      <img alt="Set an agent as the default opening language" />
    </Frame>
  </Step>
</Steps>

<Note>
  Switching Languages During a Call

  * If, during the conversation, the caller requests to switch to another language, and you've added that language to your agent configurations, Pearl will smoothly handle the transition.
  * The agent will inform the caller that they will be transferred to a representative who speaks the requested language.
  * The conversation will then continue with the agent configured for that language.
</Note>

***

### Supported Languages and Accents

Currently, NLPearl.AI supports the following languages and accents:

| **Language**   | **Accent(s)**                                                  | **Locale Code(s)**                                   |
| -------------- | -------------------------------------------------------------- | ---------------------------------------------------- |
| **English**    | American, Australian, British, South African, Indian, Scotland | `en-US`, `en-AU`, `en-UK`, `en-ZA`, `en-SC`, `en-HI` |
| **French**     | French, Canadian French                                        | `fr-FR`, `fr-CA`                                     |
| **Italian**    | Italian                                                        | `it-IT`                                              |
| **Spanish**    | Spanish, Argentine, Colombian, Mexican                         | `es-ES`, `es-AR`, `es-CO`, `es-MX`                   |
| **Dutch**      | Dutch                                                          | `nl-NL`                                              |
| **German**     | German                                                         | `de-DE`                                              |
| **Hindi**      | Hindi                                                          | `hi-IN`                                              |
| **Japanese**   | Japanese                                                       | `ja-JP`                                              |
| **Mandarin**   | Chinese Mandarin                                               | `zh-CN`                                              |
| **Korean**     | Korean                                                         | `ko-KR`                                              |
| **Russian**    | Russian                                                        | `ru-RU`                                              |
| **Portuguese** | Brazilian Portuguese, European Portuguese                      | `pt-BR`, `pt-PT`                                     |
| **Turkish**    | Turkish                                                        | `tr-TR`                                              |
| **Vietnamese** | Vietnamese                                                     | `vi-VN`                                              |
| **Polish**     | Polish                                                         | `pl-PL`                                              |
| **Arabic**     | Levantine Arabic                                               | `ar-LEV`                                             |
| **Greek**      | Greek                                                          | `el-GR`                                              |
| **Hebrew**     | Hebrew                                                         | `he-IL`                                              |
| **Indonesian** | Indonesian                                                     | `id-ID`                                              |

***

<Card icon="circle-info">
  ### Important Notes

  * **Language Consistency**:
    * Ensure that your conversational flow and scripts are consistent with the languages you've configured.
    * For example, if you have English and Spanish agents, provide scripts in both languages.

  * **Default Language**:
    * The default language is crucial as it determines how the conversation begins.
    * Make sure the default language aligns with the expectations of your target audience.

  * **Accents and Regional Variations**:
    * Choose accents that best match your audience to enhance the user experience.
</Card>

***

### Expanding Language Support

We are continuously working to expand our range of supported languages and accents to meet the diverse needs of our users. Stay tuned for updates as we grow our offerings.

<Note>
  Feedback and Requests

  If you have specific language or accent requirements that are not currently supported, please reach out to our support team. We are committed to accommodating your needs and will consider your requests as we expand our capabilities.
</Note>

***

<CardGroup>
  <Card title="Create Your Pearl" icon="subtitles" href="/pages/create_pearl">
    Learn how to create a Pearl and configure multiple languages and voices.
  </Card>

  <Card title="Contact Support" icon="headset" href="mailto:support@nlpearl.ai">
    Contact our support team to request additional languages or accents.
  </Card>
</CardGroup>


# NLPearl Phone Numbers
Source: https://developers.nlpearl.ai/pages/nlpearl_phones

Learn how to purchase phone numbers directly from the NLPearl.AI platform.

<div>
  <Frame>
    <div>
      <img alt="NLPearl Phone Numbers cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="NLPearl Phone Numbers cover" />
    </div>
  </Frame>
</div>

NLPearl.AI allows you to purchase phone numbers directly from our platform to support your inbound and outbound call activities. These phone numbers are billed monthly and can be managed easily within your account.

<Card>
  ### Available Countries

  Currently, we offer phone numbers for purchase from the following country:

  | Country       | ISO Code | Status                 |
  | ------------- | -------- | ---------------------- |
  | United States | `US`     | <span>Available</span> |

  <Note>
    If you require phone numbers from other country codes, please consider using our [Twilio Integration](/pages/twilio_integration) or [Custom VoIP Integration](/pages/custom_voip) options.
  </Note>
</Card>

***

### Before You Purchase

<Info>
  **An active subscription is required.** Buying an NLPearl phone number is only available on a paid plan.
</Info>

Each phone number is billed monthly, and the exact per-number price is shown in the purchase panel next to each number. Numbers included in your plan appear as **Free with plan** in the cart (see [Payment and Billing](#payment-and-billing)).

<Warning>
  **Outbound calling & spam risk:** If you plan to make outbound calls, we strongly recommend integrating and verifying your number with a VoIP provider. Otherwise, carriers may flag it as spam.
</Warning>

***

### How to Purchase a Phone Number

Follow these steps to purchase a phone number from NLPearl.AI:

<Steps>
  <Step title="Go to Phone Numbers Settings">
    Start by clicking your **profile card** at the bottom-left corner of the sidebar, then open **Settings**.

    <Frame>
      <img alt="Open Settings from the profile card" />
    </Frame>

    From there, open the **Phone Numbers** tab to manage or purchase phone numbers linked to your account.

    <Frame>
      <img alt="Phone Numbers tab in Settings" />
    </Frame>
  </Step>

  <Step title="Click on Purchase NLPearl Phone Number">
    In the **Phone Numbers** tab, locate the **Purchase NLPearl Phone Number** button in the center of the screen.

    Click it to access the list of available phone numbers for purchase.

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on light mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on dark mode" />
        </div>
      </Frame>
    </div>
  </Step>

  <Step title="Select Phone Numbers">
    Once you click **Purchase NLPearl Number**, a side panel titled **Purchase Phone Numbers** <span>(1)</span> opens on the right.

    Here, you’ll see a list of available US phone numbers. To add a number to your cart, simply click the **Add** button next to it. When selected, the button turns green and updates to **Added** <span>(2)</span>.

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on light mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on dark mode" />
        </div>
      </Frame>
    </div>

    <Note>
      **Not finding a number you like?** You can refresh the list to generate a new selection of available phone numbers.

      <div>
        <Frame>
          <div>
            <img alt="Send Email action interface on light mode" />
          </div>
        </Frame>
      </div>

      <div>
        <Frame>
          <div>
            <img alt="Send Email action interface on dark mode" />
          </div>
        </Frame>
      </div>
    </Note>
  </Step>

  <Step title="Review Your Cart">
    Once you’ve selected your numbers, the **Cart Summary** on the right side of the **Purchase Phone Numbers** panel lists everything you’ve added.

    * Each row shows a number and its monthly **Amount**.
    * The **Total Due Today** (and the recurring monthly cost) updates automatically as you add or remove numbers.
    * To remove a number, click the **red delete icon** next to it.
    * Your saved **Payment Method** is shown at the bottom, just above the **Confirm Payment** button.

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on light mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on dark mode" />
        </div>
      </Frame>
    </div>
  </Step>

  <Step title="Complete the Purchase">
    When you're happy with your selection, click the **Confirm Payment** button at the bottom of the Cart Summary to finalize your order. Your selected phone numbers will be instantly added to your account, ready to use without any delay.
  </Step>

  <Step title="Manage Your Phone Numbers">
    After purchasing, you can assign phone numbers directly to your **inbound** or **outbound campaigns** from the platform.

    To assign a phone number, open the settings of the specific campaign (inbound or outbound) and choose the number you'd like to attach.

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on light mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on dark mode" />
        </div>
      </Frame>
    </div>

    <Warning>
      If a phone number is scheduled for deletion but still linked to an active campaign, that campaign will **automatically stop working** once the number is removed.
    </Warning>
  </Step>
</Steps>

<Card title="Deleting Phone Numbers" icon="circle-info">
  If you no longer need a phone number, you can schedule it for deletion directly from your settings.

  Start by going to the **Phone Numbers** section in your Settings. From there, locate the number you want to remove and click the **Delete** button next to it.

  <div>
    <Frame>
      <div>
        <img alt="Send Email action interface on light mode" />
      </div>
    </Frame>
  </div>

  <div>
    <Frame>
      <div>
        <img alt="Send Email action interface on dark mode" />
      </div>
    </Frame>
  </div>

  A confirmation step will appear to make sure you really want to delete the selected number. Once confirmed, the deletion is scheduled but not immediate.

  Once confirmed, the deletion will be scheduled but not immediate. The phone number remains active until its **billing anniversary date**, when it will be automatically removed from your account.

  <Info>
    You can continue using the number normally until that date. Deletion only takes effect on its billing anniversary.
  </Info>
</Card>

***

### Payment and Billing

Phone numbers are billed on a monthly basis, charged to the **credit card** saved on your account. Once the transaction is processed, you'll receive an invoice by email.

<Note>
  **Subscription Inclusions**: <br />
  If your plan includes phone numbers and you haven't used your allowance yet, those numbers appear as **Free with plan** in the cart, at no extra cost. If you add more numbers than your plan includes, use **Make this free** on a number to choose which one uses your included allowance.
</Note>

***

<Warning>
  ### Important Considerations

  * **Monthly Billing Cycle**: Phone numbers are billed on a monthly cycle starting from the date of purchase.
  * **Country Code Limitations**: Currently, only US phone numbers are available for direct purchase. For other countries, consider alternative integration options.
  * **Payment Method**: Keep a valid credit card on file to avoid interruptions in service.
</Warning>

***

<Card title="Need Phone Numbers from Other Countries?" icon="circle-info">
  <br />

  <CardGroup>
    <Card title="Twilio Integration" icon="object-intersect" href="/pages/twilio_integration">
      Explore our **Twilio Integration** to access a broader range of international phone numbers.
    </Card>

    <Card title="Custom VoIP Integration" icon="code-branch" href="/pages/custom_voip">
      Consider the **Custom VoIP Integration** if you have specific VoIP services you wish to use.
    </Card>
  </CardGroup>
</Card>


# Outbound Calls
Source: https://developers.nlpearl.ai/pages/outbound

Configure your Pearl to run outbound campaigns, from budget and recording to retries, scheduling, and webhooks.

<div>
  <Frame>
    <div>
      <img alt="Outbound cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Outbound cover" />
    </div>
  </Frame>
</div>

***

## Setting Up Outbound Campaigns

Once you have created a Pearl, you can use it to run outbound campaigns. Outbound settings are configured inside your Pearl, under **Outbound Settings**, so your Pearl calls your leads following the conversational flow you defined.

<Info>
  **What are outbound campaigns?**

  Outbound campaigns let your Pearl make outgoing calls to a list of leads, following the conversational logic you defined for consistent and effective outreach.
</Info>

***

## Attach a Phone Number

To place calls, your Pearl needs a phone number. Numbers are purchased and connected from **Settings → Phone Numbers**, not from the Outbound Settings screen.

Start by clicking your **profile card** at the bottom-left corner of the sidebar, then open **Settings**.

<Frame>
  <img alt="Open Settings from the profile card" />
</Frame>

Then select the **Phone Numbers** tab. From here you can purchase, connect, and manage all your numbers.

<Frame>
  <img alt="Phone Numbers tab in Settings" />
</Frame>

You have three ways to get a number for your Pearl:

<Card>
  <div>
    <img alt="Logo clair" />

    <span>NLPearl Number</span>
  </div>

  <div>
    <img alt="Logo sombre" />

    <span>NLPearl Number</span>
  </div>

  Buy a number directly from NLPearl and start receiving or making calls in minutes (US numbers, billed monthly).

  <Info>
    For more details, visit the [NLPearl Phone Numbers](/pages/nlpearl_phones) page.
  </Info>
</Card>

<br />

<Card>
  <div>
    <img alt="Logo clair" />

    <span>Twilio</span>
  </div>

  <div>
    <img alt="Logo sombre" />

    <span>Twilio</span>
  </div>

  Connect your Twilio account to use your existing numbers, with access to a wide range of countries.

  <Info>
    Visit [Twilio Integration](/pages/twilio_integration) for details on how to import and manage your Twilio phone numbers.
  </Info>
</Card>

<br />

<Card>
  <div>
    <img alt="Logo clair" />

    <span>Custom VoIP</span>
  </div>

  <div>
    <img alt="Logo sombre" />

    <span>Custom VoIP</span>
  </div>

  Bring your own VoIP provider and connect custom numbers over SIP to your account.

  <Info>
    To learn more about integrating your own VoIP service, check out [Custom VoIP Integration](/pages/custom_voip).
  </Info>
</Card>

Once you have a number, attach it to your Pearl: open the Pearl's **Settings** panel and pick the number from the **Phone Number** dropdown. You can change it later from the same place.

<Frame>
  <img alt="Select the phone number in the Pearl settings panel" />
</Frame>

<Note>
  **Country codes** — each campaign is tied to a single country code, set automatically by the number you attach:

  * **One country code per campaign**: you can only call leads whose phone numbers match it.
  * **Cannot be changed**: you can switch to another number **within the same country code**, but to use a different one you must create a **new campaign**.
  * **Multiple countries**: create a separate campaign for each country code.

  **NLPearl-provided** numbers are currently **US only**. To reach other countries, connect a [Twilio](/pages/twilio_integration) or [Custom VoIP](/pages/custom_voip) number, which give access to additional country codes.
</Note>

***

## Outbound Settings

Configure your campaign from the **Outbound Settings** tab of your Pearl, in the [PearlVibe](/pages/pearl_vibe) flow editor. The tab groups the settings below into **Campaign Settings** (how calls are scheduled, managed, and recorded) and **Lead Settings**.

<Warning>
  These settings apply to **voice** Pearls only. A Text Pearl has a different set of outbound options.
</Warning>

### Budget

Set an optional spending cap for the campaign, in dollars. Once the budget is reached, Pearl stops making calls for that campaign. You can increase it at any time as long as you have enough credit on your account.

<Frame>
  <img alt="Budget setting" />
</Frame>

***

### Recording Options

Choose whether and how calls are recorded. Recorded calls are available afterwards from your call logs.

<Frame>
  <img alt="Recording Options setting" />
</Frame>

| Mode                 | Description                                    |
| -------------------- | ---------------------------------------------- |
| **Pearl & End-user** | Records both Pearl and the lead's voice.       |
| **Pearl Only**       | Records only Pearl's side of the conversation. |
| **No Recording**     | Disables call recording entirely.              |

<Warning>
  Call recording laws vary by region and often require informing or getting consent from callers. Choose the mode that matches your privacy policy and legal requirements.
</Warning>

***

### Recording After Transfer Call

If enabled, recording continues after the call is transferred to a human agent or external number, so you capture the full conversation.

<Frame>
  <img alt="Recording After Transfer Call setting" />
</Frame>

<Note>
  This option only appears when **Recording Options** is set to **Pearl & End-user**. See the [Transfer Call Node](/pages/transfer_call) to learn how call transfers work.
</Note>

***

### Transcript Options

Choose what is kept from the call transcript. Transcripts appear in your call logs alongside the recording.

<Frame>
  <img alt="Transcript Options setting" />
</Frame>

| Option                     | Description                                                                                                                                      | When to use                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| **Full Transcript**        | Keeps the entire conversation as-is.                                                                                                             | Complete analysis, QA, and training. |
| **Sensitive Info Removed** | Automatically masks sensitive data (credit card numbers, Social Security numbers, personal identifiers) while keeping the conversation readable. | Compliance and PII protection.       |
| **No Transcript**          | No transcript is stored for the call.                                                                                                            | Maximum privacy.                     |

<Info>
  With **Sensitive Info Removed**, if a customer says *"My credit card number is 1234-5678-9012-3456"*, the transcript stores it as *"My credit card number is \*\*\*\*-3456"*, so you can review interactions safely without exposing sensitive data.
</Info>

***

### Default Timezone

Set the timezone for the campaign so that calling hours and scheduling are applied at the right local time.

<Frame>
  <img alt="Default Timezone setting" />
</Frame>

***

### Retry Call Attempts

Define how many times Pearl retries a lead when the initial call fails (default **3**). You can choose up to **11 attempts**, depending on your account. You then choose the **minimum** interval between retries (default **every 6 hours**).

<Frame>
  <img alt="Retry Call Attempts setting" />
</Frame>

| Interval              | Description                                |
| --------------------- | ------------------------------------------ |
| **Every 3 hours**     | Fast retry cycle for urgent contact needs. |
| **Every 6 hours**     | Moderate retry pace during the same day.   |
| **Once a day**        | Standard daily follow-up.                  |
| **Once every 3 days** | More spaced follow-up.                     |
| **Once a week**       | Low-frequency retries.                     |
| **Once a month**      | For long-term or non-urgent callbacks.     |

<Note>
  The interval is a **minimum** — Pearl waits at least this long between attempts, respecting the lead's calling hours. Setting the right value keeps follow-ups persistent without overwhelming the lead.
</Note>

***

### Call Ambience

A subtle background environment (office, call center, outdoor…) played during the live conversation to make the call sound more natural and human. Defaults to **None**.

Pick an ambience from the dropdown, then fine-tune its **volume** (0–100) with the slider. A preview plays automatically so you can hear the result before saving.

<Frame>
  <img alt="Call Ambience setting" />
</Frame>

***

### Ring Duration

Define how long Pearl lets the phone ring before ending the call. You can choose between **10 and 50 seconds** (default **20**). If the lead doesn't answer within this time, the call is marked as **No Answer**. Shorter durations save time, longer ones increase answer rates.

<Frame>
  <img alt="Ring Duration setting" />
</Frame>

***

### Call Duration Limit

Set the maximum length of a call, between **1 and 120 minutes** (default **30**). If the conversation goes beyond this limit, the call is automatically disconnected.

<Frame>
  <img alt="Call Duration Limit setting" />
</Frame>

***

### Voicemail Drop

When Pearl reaches voicemail, she can leave a **personalized message** (optional, up to **500 characters**) using variables like the lead's first name, for a more human interaction even when the lead doesn't pick up.

<Frame>
  <img alt="Voicemail Drop setting" />
</Frame>

<Note>
  Only **Pre-Call** variables can be used in the voicemail drop.

  Example:

  > "Hi `First Name`, this is Pearl calling on behalf of `Your Company`. I just tried reaching you but missed you this time! Feel free to call me back at `Your Callback Number`. Looking forward to speaking with you soon!"
</Note>

***

### IVR Bypass

Provide instructions (up to **500 characters**, variables supported) so Pearl can navigate external phone menus (IVR) using DTMF tones and reach the right person or destination automatically.

<Info>
  Example: *"If you hear a menu, press 2 for the sales department, then press 1 to speak with a representative. If asked for an extension, enter `Extension`."*
</Info>

<Frame>
  <img alt="IVR Bypass setting" />
</Frame>

***

### Calling Hours

Define the working hours during which Pearl is allowed to place calls. By default, calls run **Monday to Friday, 08:00–18:00**. Calling hours respect each lead's timezone, so everyone is contacted at an appropriate local time.

<Frame>
  <img alt="Calling Hours setting" />
</Frame>

***

### Webhooks

Send call and lead events to an external endpoint, useful for tracking performance and keeping your CRM in sync.

<Frame>
  <img alt="Webhooks setting" />
</Frame>

* **Call Webhook**: fires at key points in the call lifecycle (when the call starts and ends), sending an object similar to the [Get Calls](/api-reference/v2/call/get-call) endpoint with details like duration, outcome, and any data collected during the call.
* **Lead Webhook**: fires whenever a lead changes status (at the start and end of the call), sending an object similar to the [Get Leads](/api-reference/v2/outbound/get-lead) endpoint with the lead's full information and current status. Use it to update your CRM in real time.

Each webhook supports:

* **Version**: `V1` or `V2` (default **V2**).
* **Credentials**: optional authentication token attached to the requests so your endpoint can verify they come from NLPearl.

<Tip>
  Use Webhooks only if external tools need event notifications. For actual automations, rely on **Post-Call Actions** tied to how the call ended.
</Tip>

<Card title="Webhooks" icon="webhook" href="/pages/webhooks">
  Learn how to configure webhooks, authenticate requests, and handle the events NLPearl sends.
</Card>

***

## Project-Level Settings

A few settings live at the **Project** level rather than in the campaign settings screen. Open them from the settings popover on your Pearl.

<Frame>
  <img alt="Project settings: agents and data retention" />
</Frame>

### Agents

Sets how many **simultaneous agents** run this campaign, i.e. how many calls can be placed at the same time, capped by your account's agent quota. A higher number allows faster outreach.

<Frame>
  <img alt="Agents setting in the Pearl settings panel" />
</Frame>

<Card title="Agents" icon="users" href="/pages/agents">
  Learn how to manage the agents assigned to your inbound and outbound activities.
</Card>

***

### Call Retention

Applies to **all calls**. Set how long calls are kept (a number of days, or leave empty to keep them indefinitely), then choose what is removed when they expire: delete all call data, or granularly the **Recording**, **Transcript**, **Summary**, or collected **Variables**.

<Frame>
  <img alt="Call Retention settings" />
</Frame>

***

### Lead Retention

Outbound only. Set how long leads are kept before they are automatically deleted (a number of days, or leave empty to keep them indefinitely). This removes the entire lead.

<Frame>
  <img alt="Lead Retention settings" />
</Frame>

***

## Managing Leads

Open the **Leads** tab in your campaign to add, view, and manage the people Pearl will call. Leads are shown in a searchable, paginated table with default columns **Created**, **Phone Number**, **Time Zone**, **Reference ID**, and **Status**, plus one column per variable used in your Pearl.

<Frame>
  <img alt="Leads tab overview" />
</Frame>

### Adding Leads

Click **Add Lead**, then choose how you want to add them.

<Frame>
  <img alt="Add Lead button" />
</Frame>

<Card>
  <Tabs>
    <Tab title="Upload a File">
      Download the **CSV** or **XLSX** template, fill it with your lead data, and upload it back. The template only includes the variables actually used in your Pearl (unused ones won't appear, and extra columns you add won't be recognized). You can also set a timezone for the file — if left empty, the campaign timezone is used. After the upload, a report shows how many leads were added and lets you download the list of any failed rows.

      <Frame>
        <img alt="Add Lead - upload file" />
      </Frame>
    </Tab>

    <Tab title="Add Manually">
      Enter a lead one by one: phone number (country code + number), any variables your Pearl uses (e.g. Calendly URI, event type, date/time), an optional timezone, and an optional **Reference ID** (your own external identifier, up to 100 characters).

      <Frame>
        <img alt="Add Lead - manually" />
      </Frame>
    </Tab>
  </Tabs>
</Card>

<Note>
  Both methods require accepting the **AI-calls compliance** checkbox. A notice also warns when a lead's country code doesn't match a country-limited NLPearl number — to reach other regions, connect a [Twilio](/pages/twilio_integration) or [Custom VoIP](/pages/custom_voip) number.
</Note>

***

### Customizing the View

Use **Customize Column** to show or hide any column, including the per-variable columns (by default, only the last 3 variables are shown). Up to 50 columns can be visible at once, and your selection is saved locally in your browser.

<Frame>
  <img alt="Customize columns" />
</Frame>

***

### Exporting Leads

Click **Download CSV** to export your leads together with their current statuses. The export respects the filters currently applied to the table.

<Frame>
  <img alt="Download leads as CSV" />
</Frame>

***

### Refreshing and Deleting

Select one or more leads (or select all across the current filter), then:

* **Refresh**: resets the leads to **New** so they re-enter the calling queue — handy to re-contact already-processed leads (Completed, Unsuccessful, etc.).
* **Delete**: permanently removes the selected leads, after a confirmation.

<Frame>
  <img alt="Refresh or delete selected leads" />
</Frame>

***

### Outside Calling Hours

When a lead's local time falls outside your campaign's [calling hours](#calling-hours), a **moon icon** appears on its Time Zone column — the lead is "sleeping" and won't be called until its window opens. Hover the icon to see the lead's local time and UTC offset.

<Frame>
  <img alt="Lead outside calling hours indicator" />
</Frame>

***

### Lead Details

Click a lead to open its details panel. Use the arrows or **↑/↓** keys to move between leads. The header shows the lead's name (or phone number), its **Lead ID** (copyable), and its status.

<Frame>
  <img alt="Lead detail panel" />
</Frame>

**Status** — change the lead's status from the editable dropdown; the change is applied instantly. This simply updates the lead's status label — for example, set it back to **New** to re-contact the lead.

<Frame>
  <img alt="Change lead status" />
</Frame>

**Lead information** — Timezone, Reference ID, Phone Number, and every Pearl variable are **editable inline**, and each change is saved immediately. The panel separates two groups:

* **Lead data**: values you provided up front (imported or entered variables).
* **Lead Collected Info**: values Pearl gathered during the conversation.

<Frame>
  <img alt="Lead information and collected info" />
</Frame>

**Calls** — the right column lists the lead's calls with their time and status; click one to open its **Post Call** view.

<Frame>
  <img alt="Lead calls history" />
</Frame>

<Card title="Post Call" icon="pager" href="/pages/postcall">
  See everything captured after a call: outcome, transcript, summary, and collected data.
</Card>


# Payouts
Source: https://developers.nlpearl.ai/pages/payout

Earn real money by sharing your Pearls with the NLPearl community.

# Payouts

When other companies in the NLPearl community use your Pearl in production, you earn **\$0.01 for every minute of calls** handled by that Pearl.
The **Payouts** page lets you:

* Securely **connect your Stripe account**
* **Share** your Pearls with the community
* Track **remixes, likes, and earnings** over time

<Info>
  <strong>Quick overview</strong>

  1. Connect your Stripe account<br />
  2. Create a solid, production-ready Pearl<br />
  3. Share it with the community (name, description, cover, tags)<br />
  4. Promote it, get users, and earn money every month
</Info>

***

## 1. Connect your Stripe account

Before you can receive payouts, you need to connect your Stripe account.

1. Go to **Payouts** in the sidebar.
2. Click **Connect** next to *“Connect with your Stripe Account”*.
3. Complete the Stripe onboarding flow:
   * Log in or create a **Stripe account**
   * Add your **banking details**
   * Confirm your **identity** and business information
     Your banking details are handled by **Stripe, not NLPearl**.
     You can disconnect or update your payout settings at any time from Stripe.

<Warning>
  <strong>Important</strong><br />
  You only get paid for usage that happens <strong>after</strong> your Stripe account is connected.
  Any calls made before that are not eligible for payouts.
</Warning>

***

## 2. Create a Pearl worth sharing

To earn from the community, you first need a Pearl that solves a **real** use case.
From the main dashboard:

1. Create or open a Pearl (e.g. appointment scheduling, payment collection, SaaS sales, hotel reception, etc.).
2. Make sure it:
   * Has a **clear use case** (who is it for, and what problem does it solve?)
   * Uses the **right tools and actions**
   * Is properly **integrated** (CRMs, calendars, payment links, APIs…)
   * Has **scripts or flows** that are ready for production
     Once your Pearl works well in test calls, you’re ready to share it with the community.

***

## 3. Share your Pearl with the community

From the Pearl’s **Overview** page:

1. Click the **⋯ (more)** menu in the top-right.
2. Select **Share to Community**.
   A panel opens with four key fields:

### 3.1 Public Name

This is the **public title** of your Pearl – the big text you see on the community cards.

* Keep it **short, clear, and catchy**
* Focus on **what the Pearl does**, not the full technical explanation
  Examples:
* `SaaS Meeting Seller`
* `Soft Payment Collector`
* `Pizza SliceLine`
* `Dental Office Appointment`
* `Celest Hotel – Inbound Hotel`
  Avoid long sentences like *“AI agent that helps you…”* that belongs in the description, not in the title.

***

### 3.2 Description

The description is **very important**:

* It appears in your Pearl’s **detail page**
* It is used to **generate the cover image**
* It helps users instantly understand **why your Pearl is useful**
  Write **2–4 short lines** that explain:
* What this Pearl does
* For which type of business
* What the main value is
  Example:

> “Outbound Pearl that calls SaaS leads, qualifies them in under 3 minutes, and books meetings directly to your calendar. Perfect for B2B SaaS teams that want consistent daily demos without hiring more SDRs.”
> Keep it concrete and benefit-driven.

***

### 3.3 Pearl Cover (Generate Image)

Under **Pearl Cover**, click **Generate Image**.

* The system will generate **2 images** based on your description
* If you don’t like them, you can **regenerate once** to get new options
* Pick the image that best matches the **vibe and use case** of your Pearl
  You don’t have to upload anything - the image is created automatically for you.

***

### 3.4 Tags

You can add up to **4 tags** to help people discover your Pearl.
Use tags that describe:

* The **industry** (e.g. `Pizzeria`, `Hotel`, `Dental`, `SaaS`)
* The **function** (e.g. `Support`, `Sales`, `Payments`, `Bookings`)
* The **type of calls** (e.g. `Inbound`, `Outbound`)
  Examples:
* `Pizzeria`, `Inbound`, `Orders`, `Delivery`
* `Hotel`, `Reservations`, `Support`
* `SaaS`, `Outbound`, `Sales`
  Good tags dramatically improve search and discovery.

***

## 4. How payouts work

Once:

1. Your **Stripe account** is connected, and
2. Your Pearl is **shared with the community**, and
3. Other users start using your Pearl in **production**,
   you earn **\$0.01 per minute of calls** handled by your Pearl.
   This applies whenever **other accounts** run real calls through your Pearl (not just internal tests).

<Note>
  <strong>Simple formula</strong>
  <code>Your monthly earnings = Total community minutes × \$0.01</code>
</Note>

### Example calculations

Assume your Pearl is being used in production by multiple businesses:

| Monthly minutes (community usage) | Your earnings |
| --------------------------------- | ------------- |
| 10,000 minutes                    | **\$100**     |
| 100,000 minutes                   | **\$1,000**   |
| 1,000,000 minutes                 | **\$10,000**  |
| Concrete scenario:                |               |

* **10 companies** each run **1,000 minutes per month** with your Pearl
* `10 × 1,000 = 10,000 minutes`
* `10,000 × $0.01 = $100 / month` for **one** Pearl
  As your Pearl gets remixed and adopted by more teams, this can scale very quickly.

***

## 5. Tracking your performance

On the **Payouts** page, you’ll see:

* **Total Remixed** – how many times other users duplicated or reused your Pearl
* **Total Likes** – how many people liked your Pearl
* **Total Earned** – how much money you’ve earned so far
* A table of all **shared Pearls**, including:
  * Pearl name
  * Type (**Inbound / Outbound**)
  * Remixes
  * Likes
  * Earned
    Remixes and likes don’t directly pay, but they’re strong signals that your Pearl is valuable, and they usually lead to more real usage.

***

## 6. Best practices to maximize payouts

To turn your Pearl into a serious revenue stream, design it so that **other people can adopt it easily**.

### 6.1 Make it remix-friendly with variables

<Tip>
  <strong>Use variables as much as possible</strong><br />
  Variables make your Pearl flexible and easy to reuse. They let other users plug in their own company details in seconds instead of rewriting your whole script.
</Tip>

When building your Pearl:

* Use variables for things like **company name, opening hours, prices, cities, websites, booking links, support emails, etc.**
* Avoid hard-coding information that only fits **your** business (specific names, addresses, internal team names, very niche jargon)
* Keep the base script **universal**, and rely on variables + knowledge base to handle customization
  Examples:
* ❌ **Bad**: "Hi, you've reached **David from NLPearl**…"
* ✅ **Good**: "Hi, you've reached&#x20;**&#x20;from&#x20;**…"
* ❌ **Bad**: "We're open from **9am to 5pm, Monday to Friday**."
* ✅ **Good**: "We're open from ."
  The more you lean on variables, the easier it is for someone to remix your Pearl for their own use case, which increases your chances of earning payouts.

### 6.2 Don’t overspecify your use case

* Avoid adding too many **hyper-specific details** that will never match another user’s reality
* Focus on the **workflow** (e.g. “collect payment”, “book appointment”, “qualify lead”) instead of a single client story
* If something is unique to your own business, move it into **variables** or the **knowledge base**, not hard-coded lines

### 6.3 Test your Pearl before publishing

Before sharing your Pearl:

* Run multiple **test calls** with different scenarios
* Check that every path in the flow works and no node gets stuck
* Confirm all tools and integrations **trigger correctly**
* Listen carefully to the audio:
  * Does the voice sound **natural** and clear?
  * Are pauses and answers at the right speed?
  * Does the conversation feel like a real human interaction?
    Only publish once you’d be comfortable using this Pearl in **your own production**.

### 6.4 Promote your Pearl

To boost your payouts, don’t just wait for people to find your Pearl inside NLPearl:

* Share your Pearl’s public link on **LinkedIn, X, and other social platforms**
* Show **real call examples** (with anonymized data) so people see how it behaves
* Mention that companies can **remix it in one click** and adapt it with their own variables
  More visibility → more users → more minutes → higher payouts.

### 6.5 Keep improving over time

* Watch which Pearls get the most **likes, remixes, and minutes**
* Update scripts, flows, and integrations as you learn from real usage
* Consider publishing **variants** of successful Pearls for different verticals (e.g. SaaS, healthcare, hospitality)

***

<Check>
  By sharing high-quality Pearls with the community, you’re not only helping other businesses launch faster, you’re also building a new recurring revenue stream for yourself, one minute of call time at a time.
</Check>


# Call Analytics
Source: https://developers.nlpearl.ai/pages/pearl_analytics



<div>
  <Frame>
    <div>
      <img alt="Call Analytics cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Call Analytics cover" />
    </div>
  </Frame>
</div>

Use this section to track, evaluate, and act on your Pearl's performance. Define what success looks like, apply custom tags to key conversation moments, and set up notifications to stay on top of important calls.

<Note>
  Other charts in your Call Analytics dashboard (duration, sentiment, costs, pickup rate, events, heatmap) are tracked automatically and don't depend on this setup step.
</Note>

***

## Define the Success of Your Pearl

Specify what constitutes a successful call for your Pearl, such as booking a meeting, confirming interest, or qualifying a lead. This success definition will be reflected in your campaign analytics and lead statuses, helping you sort and follow up efficiently.

The success criteria is **free text**, up to **200 characters**.

<Frame>
  <img alt="Define the success of your Pearl" />
</Frame>

<Info>
  **In your Call Analytics dashboard**, without a success definition, answered calls are counted as **Completed**. Once defined, they split into **Call Successful** (green) and **Call Unsuccessful** (pink), and the **Success Rate** chart tracks the percentage of calls that met your criteria over time (empty until success is defined).
</Info>

***

## Indicator Tags

Use **Indicator Tags** to label and categorize key moments in a conversation. They help you structure your data, identify important insights, and filter your leads with precision.

<Frame>
  <img alt="Indicator Tags" />
</Frame>

You can create up to **10 tags**. Each tag includes:

* **Name**: A clear label, required (max **25 characters**), e.g. `"Interested"`, `"Mentioned Competitor"`.
* **Color**: Used for visual sorting. Each tag must use a **unique color**, a color already assigned to another tag can't be reused.
* **Assignment rule (When to assign)**: A short description of when the tag should be applied, required (max **300 characters**).

Tags are assigned automatically during the call, based on the conditions you define.

<Card>
  ### Example

  You're asking leads what they usually drink in the morning. You might define:

  * **Tag**: `Coffee`
    * **Color**: Brown
    * **When to assign**: If the lead mentions drinking coffee

  * **Tag**: `Tea`
    * **Color**: Green
    * **When to assign**: If the lead mentions drinking tea

  These tags will then appear in your lead data and call logs, making it easy to segment and analyze responses.
</Card>

<Info>
  Indicator Tags are not just for display. They're functional. You can filter campaigns by tag, trigger notifications, or use them to define success in analytics.  <br /><br />
  In your **Call Analytics dashboard**, they feed the **Tags** chart, showing each tag's name, its chosen color, and how many calls it was applied to.
</Info>


# Groups
Source: https://developers.nlpearl.ai/pages/pearl_groups

Organize related Pearls into Groups so they can share the same contacts, interaction history, and optionally a common per-contact memory.

<div>
  <Frame>
    <div>
      <img alt="A Group with its Pearls organized by type" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="A Group with its Pearls organized by type" />
    </div>
  </Frame>
</div>

***

## Overview

A **Group** brings together several Pearls - voice, text, or a mix of both - that serve the same customers or the same part of your business.

When Pearls belong to the same Group, they can share:

* **Contacts** - the same contact records across every Pearl in the Group.
* **Interaction history** - a combined view of the calls and chats a contact had with any Pearl in the Group.
* **Collected information** - the structured data gathered by any Pearl in the Group.
* **Memory** *(optional)* - a single, shared memory for each contact.

<Info>
  A Pearl can belong to **one Group at a time**. Moving it into another Group removes it from the previous one.
</Info>

***

## Individual vs Shared Memory

Two related concepts control how a contact is remembered.

<CardGroup>
  <Card title="Individual Memory" icon="brain">
    A per-Pearl setting (in a Pearl's **Knowledge Base**). When enabled, that specific Pearl remembers a contact and continues from where it left off - **within that single Pearl only**.
  </Card>

  <Card title="Shared Memory" icon="users">
    A **Group-level** setting. When enabled, every Pearl in the Group accesses and updates the **same memory** for a contact, so context carries over between Pearls.
  </Card>
</CardGroup>

<Warning>
  Enabling **Shared Memory** at the Group level is not enough on its own. Each Pearl must **also** have its individual **Memory** toggle enabled (in its Knowledge Base) to participate in the Group's Shared Memory.
</Warning>

***

## Open the Pearls area

Groups live inside **Pearls**. Open **Pearls** from the left navigation.

<Frame>
  <img alt="Pearls in the left navigation" />
</Frame>

Inside **Pearls**, the left sidebar shows **All Pearls** at the top, then a **Groups** section listing your Groups, ending with **Create Group**. **All Pearls** lists every Pearl grouped by type - **Inbound Phone**, **Outbound Phone**, and **Inbound Text** - and each Pearl that belongs to a Group shows the Group name as a **tag** next to its title.

<Frame>
  <img alt="All Pearls listed by type, each Pearl showing its Group as a tag" />
</Frame>

***

## Create a Group

<Steps>
  <Step title="Click Create Group">
    In the **Groups** section of the sidebar, click **Create Group**.

    <Frame>
      <img alt="Create Group option in the Groups section of the sidebar" />
    </Frame>
  </Step>

  <Step title="Name the Group">
    Enter a Group name (required, up to **50 characters**), then click **Create**.

    <Frame>
      <img alt="Create group dialog with the name field and the Create button" />
    </Frame>
  </Step>
</Steps>

***

## Assign Pearls to a Group

From **All Pearls**, select one or more Pearls. An action bar appears at the bottom showing the number selected, along with **Move to group**, **Delete**, and **Cancel**.

<Frame>
  <img alt="Two Pearls selected in All Pearls with the Move to group action bar" />
</Frame>

Click **Move to group** to open the dialog, then choose the destination Group and click **Move**. Selecting **Remove From Group** takes the Pearls out of their current Group instead.

<Frame>
  <img alt="Move to group dialog listing the available Groups and Remove From Group" />
</Frame>

<Note>
  You can also add Pearls from inside a Group, using the **+** action in the **Assigned Pearls** toolbar.
</Note>

***

## Inside a Group

Opening a Group shows three tabs, starting on **Assigned Pearls**.

| Tab                 | Purpose                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Group Settings**  | Configure the Group name, Shared Contacts, Shared Memory, Additional Details, Contact Retention, and Delete Group. |
| **Assigned Pearls** | View and manage the Pearls that belong to this Group.                                                              |
| **Shared Contacts** | Browse the contacts shared across the Group's Pearls.                                                              |

In **Assigned Pearls**, Pearls are grouped by type with a count per section. A toolbar lets you **search**, **sort** (Last edited, Date created, Alphabetical), **filter** by status and type, and switch between **grid** and **list** views.

<Frame>
  <img alt="Assigned Pearls tab showing Pearls grouped by type with a toolbar" />
</Frame>

<Warning>
  Removing a Pearl from a Group does **not** delete it. Only the **Delete** action permanently deletes a Pearl.
</Warning>

***

## Group Settings

The **Group Settings** tab is where the Group's behavior is defined. Changes are saved immediately.

<Steps>
  <Step title="Group Name">
    Change the name of this Group. Use the pencil next to the field to rename it.

    <Frame>
      <img alt="Group Name field in Group Settings" />
    </Frame>
  </Step>

  <Step title="Shared Contacts, Shared Memory & Additional Details">
    These three toggles work together and control what Pearls in the Group share about each contact:

    * **Shared Contacts** - Pearls in the Group use the same contact records and interaction history.
    * **Shared Memory** - every Pearl accesses and updates the same per-contact memory (see the [memory warning](#individual-vs-shared-memory) above).
    * **Additional Details** - additional information collected through variables is stored on the contact and shown under **Collected Info**.

    <Frame>
      <img alt="Shared Contacts, Shared Memory, and Additional Details toggles" />
    </Frame>
  </Step>

  <Step title="Contact Retention">
    Choose how long contact data is kept before it is automatically deleted. Leave it on **Forever** to keep contacts indefinitely, or set a number of days after which older contacts are removed.

    <Frame>
      <img alt="Contact Retention setting in Group Settings" />
    </Frame>

    <Warning>
      Retention-based deletion is permanent. Once a contact is deleted based on the configured period, it cannot be recovered.
    </Warning>
  </Step>

  <Step title="Delete Group">
    Permanently delete the Group. The Pearls assigned to it are **not** deleted - only the Group and its shared-contact configuration are removed.

    <Frame>
      <img alt="Delete Group section in Group Settings" />
    </Frame>
  </Step>
</Steps>

***

## Shared Contacts

The **Shared Contacts** tab lists every contact shared across the Group's Pearls, with a search bar and a sortable table:

| Column                         |                                                   |
| ------------------------------ | ------------------------------------------------- |
| **Phone Number**               | The contact's phone number.                       |
| **First Name** / **Last Name** | The contact's name, when known.                   |
| **Email**                      | The contact's email, when known.                  |
| **Reference ID**               | An external reference, when provided.             |
| **Last Contact**               | The date and time of the most recent interaction. |

Hover a row and click **Open** to view the full contact.

<Frame>
  <img alt="Shared Contacts table listing contacts shared across the Group" />
</Frame>

An opened contact shows its **Contact ID** at the top and three areas: **Contact Information**, **Collected Info**, and **Interactions**.

<Frame>
  <img alt="Opened contact with Contact Information, Collected Info, and Interactions" />
</Frame>

<AccordionGroup>
  <Accordion title="Contact Information" icon="address-card">
    The contact's core details: phone number, first and last name, email, reference ID, time zone, and last contact date.

    <Frame>
      <img alt="Contact Information section of an opened contact" />
    </Frame>
  </Accordion>

  <Accordion title="Collected Info" icon="brackets-curly">
    The values gathered by the Group's Pearls through **variables** (populated when **Additional Details** is enabled).

    <Frame>
      <img alt="Collected Info section showing variables gathered by Pearls" />
    </Frame>
  </Accordion>

  <Accordion title="Interactions" icon="clock-rotate-left">
    Every call and chat the contact had with Pearls in the Group - each entry shows the Pearl name and type, the date, and a status such as **Completed** or **In Progress**, with access to the related call or chat.

    <Frame>
      <img alt="Interactions list of the contact's calls and chats with Pearls in the Group" />
    </Frame>
  </Accordion>
</AccordionGroup>

<Note>
  A **Group Contacts** tab also appears on an individual Pearl's page when that Pearl belongs to a Group with **Shared Contacts** enabled.
</Note>

***

## Best Practices

<Tip>
  * Group Pearls that serve the **same customers** or the **same workflow**.
  * Enable **Shared Memory** only when cross-Pearl continuity is genuinely useful - and remember to enable each Pearl's individual **Memory** toggle.
  * Use **variables** for structured information and **Shared Memory** for conversational context.
  * Review **Contact Retention** before handling production contact data.
  * Name Groups after the team, customer journey, or business process they represent.
</Tip>

***

## Related Documentation

<CardGroup>
  <Card title="Pearl Voice" icon="phone-volume" href="/pages/pearl_voice">
    AI voice agents that handle real phone conversations - inbound and outbound.
  </Card>

  <Card title="Pearl Text" icon="messages" href="/pages/text/pearl_text">
    AI text agents that message your customers across SMS, WhatsApp, email, and chat.
  </Card>

  <Card title="Variables" icon="brackets-curly" href="/pages/variables">
    Collect, store, and reuse data during conversations.
  </Card>

  <Card title="Pearl Settings" icon="user-gear" href="/pages/agent_customization">
    Configure a Pearl's name, language, voice, personality, and time zone.
  </Card>
</CardGroup>


# PearlVibe
Source: https://developers.nlpearl.ai/pages/pearl_vibe



PearlVibe is a powerful AI-assisted flow editor that allows you to design and visualize conversation flows in a user-friendly, visual interface. Whether you're creating customer surveys, support dialogues, or interactive voice responses, PearlVibe helps you craft natural and personalized conversations.

<div>
  <Frame>
    <div>
      <img alt="PearlVibe cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="PearlVibe cover" />
    </div>
  </Frame>
</div>

***

## Overview

### What is PearlVibe?

PearlVibe is an AI‑assisted flow editor for building your agents - both **voice** (phone) and **text** agents. You build your Pearl as a decision tree made of nodes (dialogue, actions, integrations…) and transitions (what happens next depending on user intent, answers, or conversation outcome).

<iframe title="NLPearl - AI Voice Agents" />

<Info>
  You can work in two complementary ways:

  | View               | Description                                                                                                                                                                                                                                                      |
  | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | **Chat (default)** | You describe what you want in natural language (e.g. "Add a post‑call SMS when the booking is confirmed"). In **Build** mode, Pearl Vibe creates or edits the nodes and transitions for you; in **Ask** mode, it answers and advises without touching your flow. |
  | **Manual Edit**    | You open **Manual Edit** on the selected node to configure it and its transitions yourself, for full control. Every setting is visible and editable.                                                                                                             |
</Info>

### What can you build with PearlVibe?

With PearlVibe, you can design both **voice** (phone) and **text** (chat) flows:

| Flow Type              | Use Cases                                                                                          |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| **Inbound flows**      | Support and customer care lines, order tracking, FAQs, triage, appointment management, etc.        |
| **Outbound campaigns** | Sales campaigns, payment reminders, debt collection, upsell flows, satisfaction surveys, and more. |

<Info>
  Each of these works the same way whether your Pearl is **voice** or **text** — you build the flow once, and the editor adapts labels and available nodes to your Pearl's channel.
</Info>

### Key benefits

<Check>
  * **Build in minutes instead of days** – Describe what you want in the chat, let Pearl build it for you in **Build** mode, then refine visually.
  * **Safe versioning** – Work in a separate version with autosave while your Published version keeps running in production.
  * **Visual understanding of calls** – Use test calls and live node highlighting to see exactly how calls traverse your flow.
  * **Structured but flexible** – Combine high‑level "vibes" (global instructions, personality) with precise node and transition logic.
</Check>

***

## Header

The header is always visible at the top of the editor. From left to right, it holds the **Pearl icon (menu)** and the editable **Pearl title** with its autosave indicator, the **version selector**, the **top navigation tabs**, and — on the right — the **credentials & variables** (`{ }`) button, **Test Call**, and **Publish**. Each of these is detailed below.

<Frame>
  <img alt="PearlVibe header bar with title, version selector, and top-right controls" />
</Frame>

<br />

<AccordionGroup>
  <Accordion title="Pearl Title & Menu" icon="tag">
    The top-left corner shows the Pearl's **title** as an inline, editable field (it reads **Untitled Pearl** by default). Click it to rename your Pearl — this is the label you'll reuse across the platform and in your workspace. Just below, an autosave indicator shows the save status (for example **Saved 2 min ago**).

    <Frame>
      <img alt="Inline editable Pearl title with autosave indicator" />
    </Frame>

    **Pearl menu**

    The Pearl icon next to the title opens a menu with quick actions for the whole Pearl.

    <Frame>
      <img alt="Pearl icon that opens the Pearl menu" />
    </Frame>

    From this menu you can go back to the Dashboard or Overview, open the Pearl's **Settings**, **Duplicate** or **Delete** the Pearl, check your **Credit Balance**, switch the **Theme**, and reach the Documentation or Support & Feedback.

    <Frame>
      <img alt="Pearl menu with dashboard, settings, duplicate, delete, credit balance, and theme options" />
    </Frame>
  </Accordion>

  <Accordion title="Versioning & Publishing" icon="code-branch">
    Pearl Vibe is built for safe iteration: you can experiment freely without breaking your live calls. Your work is organized into **versions** (v1, v2, v3…), and the one currently handling calls carries a **Published** badge.

    **Autosave**

    Every change you make is saved automatically. The header shows an **Auto Save** indicator that turns into **Saved N min ago** once your edits are stored, so you never lose work and can come back later.

    ***

    **Versions & history**

    The version selector next to the title shows the version you're editing (for example **v35**).

    <Frame>
      <img alt="Version selector next to the Pearl title" />
    </Frame>

    Open it to browse the full **version history**. You can search for a version, see when each was last edited, spot the **Published** one at a glance, and open any past version to review it. You can also **tag** each version with a label of your own so it's easy to recognize later (e.g. "stable", "summer promo", "before refactor").

    <Frame>
      <img alt="Version history dropdown with a Published badge on the live version" />
    </Frame>

    ***

    **Creating a new version**

    Use the **+** button next to the version selector to create a new version.

    <Frame>
      <img alt="Button to create a new version" />
    </Frame>

    In the **Create New Version** dialog, pick the existing version to use as the base, then click **Create**.

    <Frame>
      <img alt="Create New Version dialog with a base version selector" />
    </Frame>

    <Tip>
      Editing a version that is already **Published** automatically creates a new version for your changes, so the live configuration keeps running untouched while you iterate.
    </Tip>

    ***

    **Publishing**

    When you're satisfied with your changes and tests, click **Publish** (top-right of the header). The current version becomes the new **Published** version and starts handling calls.

    <Frame>
      <img alt="Publish, Test Call, and credentials/variables buttons in the header" />
    </Frame>

    <Note>
      If your flow still has unresolved issues, the **Publish** button is replaced by an **Errors & Tasks (N)** button until you fix or dismiss them (see the **Tasks & Errors** section below).
    </Note>

    The version you are editing and the **Published** version drift apart as soon as you change anything, and they stay apart until you publish again. You don't have to keep track of that yourself: ask in the chat whether what you are editing still matches what is live, and Pearl compares the two for you (see [Chat Sidebar](#chat-sidebar)).
  </Accordion>

  <Accordion title="Credentials & Variables Managers" icon="plug">
    Credentials and variables are what connect your Pearl to the rest of your stack. Both are opened from the **`{ }`** button in the top-right of the header.

    **Variables Manager**

    The **Variables Manager** lets you create, edit, and organize the variables used in your conversation flows.

    <Frame>
      <img alt="Variables Manager to create, edit, and organize variables" />
    </Frame>

    <Info>
      See the [Variables documentation](/pages/variables) for more details.
    </Info>

    ***

    **Credentials Manager**

    The **Credentials Manager** is where your integrations live: you connect external systems by adding credentials and configuration for each one. Once a credential is added, the matching integration becomes available as a node in your flow.

    <Frame>
      <img alt="Credentials Manager to connect external systems" />
    </Frame>

    It lets you:

    * Add new integrations (e.g. Salesforce, HubSpot, ticketing tools, booking engines).
    * Configure authentication.
  </Accordion>

  <Accordion title="Tasks & Errors" icon="circle-exclamation">
    As your flows grow, PearlVibe helps you keep them valid, connected, and fully configured.

    <Warning>
      **Error detection**

      Pearl Vibe automatically scans your Pearl for common issues, such as:

      * Nodes without outgoing transitions.
      * Transitions not connected to any node.
      * Missing required fields (for example: API nodes without an endpoint or description).
      * Incomplete campaign or flow configuration.

      When such issues are detected, the **Publish** button in the header is replaced by a red **Errors & Tasks (N)** button that signals how many items need your attention.
    </Warning>

    <Frame>
      <img alt="Errors & Tasks button in the header when issues are detected" />
    </Frame>

    **Tasks & Errors panel**

    Clicking the **Errors & Tasks** button opens a right-hand **Tasks & Errors** panel that groups every issue in one place, organized per workspace (Flow Editor, credentials, etc.). Each card names the affected node and what's missing (e.g. "Missing Transition: Budget provided", "Missing Inbound Transition").

    <Frame>
      <img alt="Tasks & Errors panel listing issues per node" />
    </Frame>

    Each card offers two actions:

    * **Fix With Pearl** — sends the fix to the chat. In **Build**, the agent proposes the corrected configuration and applies it once you confirm; in **Ask**, it describes the fix instead.
    * **Open in editor** — jump directly to the affected node in the Flow Editor.

    <Frame>
      <img alt="Selecting an issue card in the Tasks & Errors panel" />
    </Frame>

    **On the canvas**

    Affected nodes are highlighted in red, and the problem is flagged directly in the node's Transitions section, so you can spot exactly what needs attention.

    <Frame>
      <img alt="Node flagged with a missing transition error on the canvas" />
    </Frame>

    You can also fix an issue from the node itself: hovering a node reveals a quick **Fix With Pearl** action, which sends the same request to the chat.

    <Frame>
      <img alt="Fix With Pearl quick action on a node" />
    </Frame>

    <Tip>
      You can either fix issues manually or let Pearl draft the corrected configuration for you in the chat — in **Build** mode, it applies it once you confirm.
    </Tip>
  </Accordion>

  <Accordion title="Test Calls & Debugging" icon="phone-volume">
    Test calls are the safest way to validate your Pearl before and after publishing.

    <Note>
      On **text** Pearls, these controls read **Test Chat** and **Past Chats** instead of **Test Call** and **Past Calls**.
    </Note>

    **Launching a Test Call**

    Open the **Test Call** menu in the header. From here you switch between the two views: **Test Call** (test your agent by phone) and **Past Calls** (view your call history and details).

    <Frame>
      <img alt="Test Call menu to switch between Test Call and Past Calls" />
    </Frame>

    In the **Test Call** panel, choose the **From** and **To** phone numbers, optionally reset the Pearl's memory for a fresh test, prefill opening sentences and lead variables, then click **Call Now**. The Pearl calls that number using the version you're currently editing.

    <Frame>
      <img alt="Test Call panel with phone numbers, lead variables, and Call Now button" />
    </Frame>

    ***

    **Live Node Tracing**

    During the test call, a **Ringing… / Stop Following** pill appears and the nodes in the canvas light up one after another as the conversation progresses, so you can visually follow the path the call is taking through your flow.

    <Frame>
      <img alt="Live node tracing during a test call with a Stop Following pill" />
    </Frame>

    <Tip>
      This helps you understand why a certain question was asked, see which transition was taken at each step, and debug misrouted calls or unexpected behaviors.
    </Tip>

    ***

    **Past Calls**

    The **Past Calls** view lists your previous test calls grouped by date. Open any entry to inspect its details and verify that your flow — including post-call automation — behaved as expected.

    <Frame>
      <img alt="Past Calls panel listing previous test calls by date" />
    </Frame>

    <Info>
      To learn more about post-call actions, see the [Post-Call documentation](/pages/postcall) — or, for text Pearls, the [Post-Chat documentation](/pages/text/postchat).
    </Info>
  </Accordion>
</AccordionGroup>

***

## Chat Sidebar

The chat sidebar is where you work on your Pearl — by talking to PearlVibe in natural language, either to ask it about your flow and your calls or to have it create and edit the flow for you, or by switching to Manual Edit to configure things by hand.

<Frame>
  <img alt="Chat sidebar on the left of the editor" />
</Frame>

It combines two complementary views:

| View            | Description                                                                                                                                                                  |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chat**        | Describe what you want in natural language. This is the default view, and it has two modes: **Ask**, which only answers and advises, and **Build**, which changes your flow. |
| **Manual Edit** | Explicit, hands-on configuration of the selected node.                                                                                                                       |

The Chat view is covered in two parts below: building your flow, and using the chat to investigate it.

<Note>
  When a node is selected, everything you ask for in this sidebar is interpreted in the context of that node — unless it is explicitly global (like General Instructions), or you are asking about the flow as a whole, a past call, or the Published version (see **Investigating your flow and your calls** below).
</Note>

<AccordionGroup>
  <Accordion title="Chat" icon="comments">
    <Frame>
      <img alt="Chat panel in the left sidebar" />
    </Frame>

    This is the default view. You describe what you want in natural language, and Pearl either answers you or builds it into your current version — depending on the mode you are in.

    **Ask and Build**

    The composer carries a pill showing the current mode. Click it to open the mode menu and switch. The chat opens in **Build**.

    | Mode      | What it does                                                                                                                    |
    | --------- | ------------------------------------------------------------------------------------------------------------------------------- |
    | **Ask**   | Investigates, checks, and advises. It reads your flow and your calls and answers your questions, but it never changes anything. |
    | **Build** | Makes the changes you ask for, after you confirm them.                                                                          |

    The same sentence gives you two different outcomes. "Add an SMS step after the booking step" in **Ask** gets you a description of the change and an invitation to switch to **Build**, and your flow is left untouched. The same sentence in **Build** gets you a short plan, a confirmation, and then the step itself in the editor.

    <Note>
      Deletions are always confirmed by name. "Delete the booking step" is answered with a confirmation naming the node, and it is only removed once you say yes.
    </Note>

    **Typical operations you can perform:**

    These are all **Build** mode operations — in **Ask**, Pearl describes what it would do instead of doing it.

    | Operation                                 | Example                                                                                        |
    | ----------------------------------------- | ---------------------------------------------------------------------------------------------- |
    | **Create or delete nodes**                | "Add a qualification step after the greeting."                                                 |
    | **Edit a node's content and behavior**    | "Make the opening more formal and mention our summer offer."                                   |
    | **Add, rename, or reconnect transitions** | "Add a 'Not interested' branch that ends the call politely."                                   |
    | **Attach actions**                        | "Send a confirmation SMS after a successful booking." (API calls, SMS, email, transfers, etc.) |
    | **Configure post-call logic**             | "Log the outcome to the CRM once the call ends."                                               |

    **The composer**

    Type your instruction in the composer — its placeholder reads **Ask Pearl…** whichever mode you are in. For example: "Split this node into three outcomes based on payment status.", "After a successful payment, send a confirmation SMS and end the call.", "Create a post-call node that logs the outcome to the CRM." Press **Send**: in **Build**, Pearl answers with its plan and updates the editor once you confirm; in **Ask**, it answers without touching your flow.

    <Frame>
      <img alt="Chat composer input box" />
    </Frame>

    The composer includes a few helpers:

    * **Attach files** — add supporting material (FAQs, pricing sheets, policy docs, playbooks…) to enrich the Pearl's knowledge and reference it in node prompts.

    <Frame>
      <img alt="Attach file button in the chat composer" />
    </Frame>

    Accepted formats: `.pdf`, `.docx`, `.txt`, `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.mp3`, `.m4a`, `.wav`, `.webm` — up to **10 files per message**.

    <Tip>
      You can attach a **full recording of a real conversation** (e.g. an `.mp3` or `.wav` call) and ask PearlVibe to build the flow from it — in **Build** mode, it turns the exchange into nodes and transitions for you.
    </Tip>

    * **Enhance prompt** — rewrite a rough or short instruction into a clearer, more structured request before it runs.

    <Frame>
      <img alt="Enhance prompt button in the chat composer" />
    </Frame>

    * **Voice input** — dictate your instruction instead of typing it.

    <Frame>
      <img alt="Voice input button in the chat composer" />
    </Frame>

    **Node context**

    When a node is selected in the canvas, its name appears as a pill above the composer. Any instruction you send while this pill is active is interpreted in the context of that node (for example: "Change the greeting", "Add a failure transition that transfers to support").

    <Frame>
      <img alt="Node context pill above the chat composer" />
    </Frame>

    **Reviewing what Pearl builds**

    In **Build** mode, Pearl usually shows a short plan before applying larger edits and asks you to confirm (for example **Yes, build it**) — or you can answer it directly in the composer.

    <Frame>
      <img alt="Pearl asking to confirm before building changes" />
    </Frame>

    When Pearl needs a decision, it can present interactive choices right in the chat (for example, which CRM to connect).

    <Frame>
      <img alt="Interactive choice prompt in the chat" />
    </Frame>

    Once applied, each batch of edits appears as a **Changes** card summarizing what was added and removed.

    <Frame>
      <img alt="Changes card summarizing applied edits" />
    </Frame>

    Expand it (**View more**) to see the full diff — added, edited, and removed nodes and transitions, highlighted in green and red.

    <Frame>
      <img alt="Expanded diff of the applied changes" />
    </Frame>

    If you don't want to keep a batch, click **Undo changes** to roll it back.

    <Frame>
      <img alt="Undo changes button on a Changes card" />
    </Frame>

    <Tip>
      Chat is the recommended entry point to quickly build or refactor a flow, especially for large or complex trees.
    </Tip>
  </Accordion>

  <Accordion title="Investigating your flow and your calls" icon="magnifying-glass">
    Pearl can read your flow and your calls, not only change them. Ask it a question about either and it goes and reads the material itself. All of this works in **Ask** mode as well as in **Build**, since none of it changes your flow.

    **Reading a past call**

    Ask *"Look at my last test call and tell me what happened"* and Pearl reads the call itself — the lines that were exchanged, the nodes the call went through, and what your API steps returned. You don't have to open the call and go through the transcript yourself.

    It works the same way on a text Pearl — ask about your last test chat instead.

    **Asking why something went wrong**

    You can go straight to the question instead of to the evidence: *"Investigate why my agent skipped the booking."* Pearl pulls up the relevant calls on its own and answers from what it finds in them.

    **What changed since the published version**

    Pearl knows both the version you are editing and the **Published** one that is handling your calls, and it can compare them. Ask *"What changed since the published version?"* after editing a node, or *"Is what I'm editing still the same as what is live?"*, and it tells you exactly what you have changed since.

    **Checking the flow for problems**

    *"Check my flow for problems"* gets you a structural review: nodes that lead nowhere, transitions that connect to nothing, configuration left unfinished. If your Pearl has already taken calls, it also reports which API steps behaved inconsistently across them.

    <Tip>
      This is the quickest way to use your call history: instead of opening past calls one by one, ask Pearl what happened in them.
    </Tip>
  </Accordion>

  <Accordion title="Manual Edit" icon="sliders">
    Select a node in the canvas, then click the **Manual Edit** button at the bottom of the sidebar to configure it by hand.

    <Frame>
      <img alt="Manual Edit button at the bottom of the chat sidebar" />
    </Frame>

    Manual Edit always targets the currently selected node (shown by the node context pill).

    <Frame>
      <img alt="Manual Edit with a node selected in the canvas" />
    </Frame>

    It is split into two tabs: **Edit** and **Transitions**.

    **The Edit tab**

    Exposes all the settings specific to the current node type (Script / Free Text, Instructions, variables…). What you see here changes depending on whether the node is a Dialogue, API, SMS, Email, Transfer, Integration, or Post-Call node.

    <Frame>
      <img alt="Edit tab of a node in Manual Edit" />
    </Frame>

    In short, the Edit tab is where you configure what this node does internally, based purely on its type.

    <Note>
      Routing to other nodes is not handled here, but in the Transitions tab.
    </Note>

    **The Transitions tab**

    Defines how the conversation can exit this node. Each transition is a labeled branch (for example "Agreed to future contact") pointing to the next node, and you add new ones with **New Transition**.

    <Frame>
      <img alt="Transitions tab in Manual Edit with a transition and the New Transition button" />
    </Frame>

    From here you can:

    * **Create transitions** – Add exits such as "Success", "Failure", "No answer", "Customer asks for human", etc.
    * **Connect transitions** – Choose the target node for each transition to shape the path of the conversation.
    * **Edit or delete transitions** – Rename transitions, change their destination, or remove them when they are no longer needed.

    **Back to Chat**

    When you're done, click **Back to Chat** to return to the chat.

    <Frame>
      <img alt="Back to Chat button in Manual Edit" />
    </Frame>

    <Info>
      Any modification done in Manual Edit is immediately reflected in the visual flow and remains fully understood by Pearl.

      You can freely switch between Chat and Manual Edit as you work on the same node.
    </Info>
  </Accordion>
</AccordionGroup>

***

## Central Canvas

The central canvas displays your flow as a graph of nodes and transitions.

<Frame>
  <img alt="Central canvas showing the flow as a graph of nodes and transitions" />
</Frame>

| Element         | Description                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Nodes**       | Each node represents a step in the conversation (a message, an action, or a set of actions).                                  |
| **Transitions** | Each transition represents a possible path from one node to another based on intents, recognition results, or business logic. |

**From the canvas you can:**

| Action                               | Description                                          |
| ------------------------------------ | ---------------------------------------------------- |
| **Add, connect, branch, disconnect** | Create nodes and wire transitions to shape the flow. |
| **Move, pan & zoom**                 | Navigate large trees comfortably.                    |
| **Search**                           | Find a node by name or content.                      |
| **Reorganize**                       | Re-lay out the flow automatically (auto-layout).     |
| **Go to Start / End**                | Jump straight to the beginning or end of the flow.   |
| **Hover preview**                    | See a quick summary of what a node does.             |
| **Quick actions**                    | Fix, Edit, Duplicate, or Delete a node in place.     |
| **Undo / Redo**                      | Roll your latest changes back and forth.             |

<Note>
  The canvas has no minimap — use zoom, pan, **Reorganize**, and **Search** to move around instead.
</Note>

**Right toolbar**

The vertical toolbar on the right groups the navigation controls: **Undo / Redo**, **Go to Start / End**, **Reorganize** (auto-layout), and **Zoom in / out**.

<Frame>
  <img alt="Right toolbar with undo/redo, go to start/end, reorganize, and zoom" />
</Frame>

<AccordionGroup>
  <Accordion title="Node Types Overview" icon="shapes">
    Pearl Vibe supports several node types:

    | Node Type             | Description                                                    |
    | --------------------- | -------------------------------------------------------------- |
    | **Start node**        | Entry point of the flow.                                       |
    | **In‑Call nodes**     | Actions that occur while the caller is on the line.            |
    | **Integration nodes** | Interactions with external systems (CRM, ticketing, booking…). |
    | **End Call node**     | The node that ends the conversation.                           |
    | **Post‑Call nodes**   | Actions executed after the call has ended.                     |

    <Info>
      **Understanding Node Types: Pre-Call, In-Call & Post-Call**

      Your Pearl flow is built around three categories of nodes, each designed for a specific moment in the call lifecycle. Knowing the difference is essential to avoid misusing an action or expecting behavior that can't happen at that stage.

      **1. Pre-Call Nodes: Before the call starts**

      These nodes run prior to dialing or answering. They're ideal for preparing context: fetching customer data, checking availability, validating an ID, loading account information. They cannot interact with the caller and cannot create or import leads.

      **2. In-Call Nodes: During the conversation**

      These nodes control everything that happens while the caller and the agent are connected. Dialogue, decision logic, sending SMS/emails, API calls, and CRM updates all happen here in real time. This is the core of your conversational flow.

      **3. Post-Call Nodes: After the call ends**

      Once the call is finished, these nodes handle asynchronous tasks: writing CRM logs, creating leads, triggering webhooks, updating databases, or launching follow-up workflows. They cannot affect what happened during the call, only what happens after.
    </Info>
  </Accordion>

  <Accordion title="Start Node" icon="play">
    Every flow begins with a Start node. It controls how the conversation is initiated.

    <Frame>
      <img alt="Start node at the entry point of the flow" />
    </Frame>

    You can configure it in two ways:

    | Configuration        | Description                                                                                                                                                                                                                                                                                                                       |
    | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Opening sentence** | A standard greeting and first question, for example: "Hi, you've reached \[Company]. How can I help you today?"                                                                                                                                                                                                                   |
    | **Pre‑Call API**     | Before the Pearl speaks, it can call an external API (for example to fetch order details, check account status, or pre‑qualify the caller). The API response can then change the opening sentence, route the caller toward different branches, or preload variables and context. On text Pearls this is labeled **Pre‑Chat API**. |

    <Note>
      The Pre-Call API cannot be used to import leads into your Pearl. Its purpose is strictly to enrich or prepare contextual data before the call starts
    </Note>
  </Accordion>

  <Accordion title="In‑Call Nodes" icon="phone">
    In‑Call nodes represent the actions and dialogues that happen during the conversation. In the **Add Node** picker they're split into **Live Global Nodes** (Dialogue, Knowledge Base) and **Live Action Nodes** (SMS, Email, API, Transfer Call).

    <Frame>
      <img alt="In-call nodes across the conversation flow" />
    </Frame>

    | Node Type          | Description                                                                                                                 |
    | ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
    | **Dialogue**       | The Pearl speaks, listens, and interprets the customer's response according to your instructions.                           |
    | **Knowledge Base** | Answer questions using your Pearl's configured knowledge base.                                                              |
    | **Send SMS**       | Send a text message during the call (e.g. a confirmation code, a link, or a summary). *Voice only — hidden on text Pearls.* |
    | **Send Email**     | Trigger an email to the customer or your team.                                                                              |
    | **API**            | Call an external API (e.g. update a record, check availability, create a ticket).                                           |
    | **Transfer Call**  | Transfer the caller to a human agent or another phone number. *Voice only — hidden on text Pearls.*                         |
    | **Hand-Off**       | Hand the conversation over to a human. *Text Pearls only.*                                                                  |
    | **Recording**      | Control call recording (availability depends on your platform).                                                             |

    <Note>
      Integration-specific actions (e.g. Google Calendar, Salesforce) appear in a separate **Integration Nodes** group of the picker — see below.
    </Note>
  </Accordion>

  <Accordion title="Integration Nodes" icon="plug">
    Integration nodes let your Pearl interact directly with external tools and services without writing any API code yourself. Technically, each one is an **API node pre-configured with an integration credential** from the **Credentials Manager** — it handles authentication, request formatting, and data mapping for you. They appear in a dedicated **Integration Nodes** group of the **Add Node** picker.

    <Frame>
      <img alt="Integration node configured from a credential" />
    </Frame>

    **Integration node variants:**

    | Variant                         | Description                                                                                   |
    | ------------------------------- | --------------------------------------------------------------------------------------------- |
    | **In-Call Integration Nodes**   | Executed while the caller is still on the line (e.g. checking a CRM record before answering). |
    | **Post-Call Integration Nodes** | Executed after the call ends (e.g. logging call results into a ticketing system).             |

    **What Integration Nodes Do**

    Integration nodes encapsulate tasks such as:

    | Category                   | Examples                        | Tasks                                                                                                |
    | -------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- |
    | **CRM operations**         | Salesforce, HubSpot, Pipedrive… | Create or update records, attach call results, sync contact data.                                    |
    | **Helpdesk platforms**     | Zendesk, Freshdesk…             | Create tickets, update statuses, push conversation summaries.                                        |
    | **Booking engines**        | Calendly, Cloudbeds, Shore…     | Check availability, create reservations, cancel or modify bookings.                                  |
    | **Search & data services** | Algolia, Elasticsearch…         | Query product/catalog data, validate inputs, or retrieve structured info.                            |
    | **Payments & billing**     | Stripe, Paystack…               | Check payment status, initiate a payment link workflow, validate customer identity.                  |
    | **Custom Integrations**    | Any configured integration      | Any integration you configure in the Credentials Manager becomes available here as a dedicated node. |

    **How They Work**

    | Feature                  | Description                                                                           |
    | ------------------------ | ------------------------------------------------------------------------------------- |
    | **Secure Credentials**   | The Credentials Manager stores credentials securely (API keys, tokens, IDs…).         |
    | **Available as Node**    | Once connected, each service becomes available as a node in the flow.                 |
    | **Simple Configuration** | The node exposes only the required parameters, no API documentation or coding needed. |
    | **Data Mapping**         | Returned data can be mapped to variables and used later in the conversation.          |

    **Available Integrations**

    <div>
      <div><img /> ActiveCampaign</div>
      <div><img /> Airtable</div>
      <div><img /> Algolia</div>
      <div><img /> Anthropic</div>
      <div><img /> AssemblyAI</div>
      <div><img /> Backblaze</div>
      <div><img /> Baserow</div>
      <div><img /> Bitly</div>
      <div><img /> Brevo</div>
      <div><img /> Cal.com</div>
      <div><img /> Calendly</div>
      <div><img /> Clearbit</div>
      <div><img /> ClickUp</div>
      <div><img /> Cloudflare</div>
      <div><img /> Cohere</div>
      <div><img /> Contentful</div>
      <div><img /> Convertkit</div>
      <div><img /> Customer.io</div>
      <div><img /> Datadog</div>
      <div><img /> DeepL</div>
      <div><img /> DigitalOcean</div>
      <div><img /> Discord</div>
      <div><img /> Elasticsearch</div>
      <div><img /> Freshdesk</div>
      <div><img /> Ghost</div>
      <div><img /> Google Calendar</div>
      <div><img /> Google Docs</div>
      <div><img /> Google Sheets</div>
      <div><img /> Grafana</div>
      <div><img /> Groq</div>
      <div><img /> Hetzner</div>
      <div><img /> HubSpot</div>
      <div><img /> HuggingFace</div>
      <div><img /> Hunter</div>
      <div><img /> InfluxDB</div>
      <div><img /> JotForm</div>
      <div><img /> Lemlist</div>
      <div><img /> Magento</div>
      <div><img /> MailerLite</div>
      <div><img /> Mailgun</div>
      <div><img /> Mailjet</div>
      <div><img /> Mandrill</div>
      <div><img /> Matrix</div>
      <div><img /> Mattermost</div>
      <div><img /> MessageBird</div>
      <div><img /> Metabase</div>
      <div><img /> Microsoft Outlook</div>
      <div><img /> MinIO</div>
      <div><img /> Mistral AI</div>
      <div><img /> Mocean</div>
      <div><img /> MongoDB</div>
      <div><img /> MQTT</div>
      <div><img /> MSG91</div>
      <div><img /> MySQL</div>
      <div><img /> Netlify</div>
      <div><img /> New Relic</div>
      <div><img /> NocoDB</div>
      <div><img /> OpenAI</div>
      <div><img /> OpenRouter</div>
      <div><img /> OpenWeatherMap</div>
      <div><img /> Pabbly</div>
      <div><img /> Paddle</div>
      <div><img /> PagerDuty</div>
      <div><img /> Perplexity</div>
      <div><img /> Pinecone</div>
      <div><img /> Plivo</div>
      <div><img /> PostHog</div>
      <div><img /> PostgreSQL</div>
      <div><img /> Postmark</div>
      <div><img /> Pushover</div>
      <div><img /> Qdrant</div>
      <div><img /> RabbitMQ</div>
      <div><img /> Redis</div>
      <div><img /> Replicate</div>
      <div><img /> Rocketchat</div>
      <div><img /> Salesforce</div>
      <div><img /> SendGrid</div>
      <div><img /> Sendy</div>
      <div><img /> Sentry</div>
      <div><img /> Serp</div>
      <div><img /> SIGNL4</div>
      <div><img /> SparkPost</div>
      <div><img /> Square</div>
      <div><img /> Stability AI</div>
      <div><img /> Strapi</div>
      <div><img /> Supabase</div>
      <div><img /> Telegram</div>
      <div><img /> Together AI</div>
      <div><img /> Twilio</div>
      <div><img /> Typeform</div>
      <div><img /> Vercel</div>
      <div><img /> Vonage</div>
      <div><img /> Wasabi</div>
      <div><img /> Weaviate</div>
      <div><img /> WooCommerce</div>
      <div><img /> WordPress</div>
      <div><img /> Wufoo</div>
      <div><img /> Yourls</div>
      <div><img /> Zulip</div>
    </div>
  </Accordion>

  <Accordion title="End Call & Post‑Call Nodes" icon="phone-hangup">
    **End Call node**

    This node closes the conversation gracefully (e.g. "Thanks for your time, goodbye."). It is typically the last in‑call node. On text Pearls it's labeled **End Chat**.

    <Frame>
      <img alt="End Call node closing the conversation" />
    </Frame>

    **Post‑Call nodes**

    After the End Call node, you can add Post‑Call nodes via transitions. These nodes execute actions after the call has ended, such as:

    * Sending a summary SMS.
    * Writing a detailed log into your CRM.
    * Triggering a webhook.
    * Sending internal notifications to your team.

    <Info>
      Post‑Call nodes support many of the same actions as In‑Call nodes but are not constrained by real‑time conversation. In the **Add Node** picker, the Post-Call tab offers **SMS**, **Email**, and **API** nodes.
    </Info>

    <Frame>
      <img alt="Column of post-call action nodes" />
    </Frame>
  </Accordion>

  <Accordion title="Node Structure" icon="layer-group">
    Each node shares a common structure.

    **Header**

    * Icon representing the type of node.
    * Node name, editable to reflect its role ("Payment check", "Qualification", "Post‑call CRM update"…).

    <Frame>
      <img alt="Node header with type icon and editable name" />
    </Frame>

    **Transitions list**

    Under the header, you see the list of transitions for this node (e.g. "Success", "Failure", "No match", "Ask for human"). From here you can:

    * See which node each transition points to.
    * Click to navigate along the transition.
    * Disconnect or reconnect transitions to reshape the flow.

    <Frame>
      <img alt="A node's transition branches listed under its header" />
    </Frame>

    **Quick actions**

    Selecting a node reveals quick actions right below it — **Edit**, **Duplicate**, and **Delete**.

    <Frame>
      <img alt="Node quick actions: edit, duplicate, and delete" />
    </Frame>

    **Node colors when selected**

    When you select a node, the canvas colors the surrounding nodes to show their position relative to it:

    | Border color | Meaning                                       |
    | ------------ | --------------------------------------------- |
    | **Blue**     | Nodes that come **before** the selected node. |
    | **Green**    | The **selected** node (the current one).      |
    | **Orange**   | Nodes that come **after** the selected node.  |

    <Frame>
      <img alt="Selected node with blue (previous), green (current), and orange (next) node borders" />
    </Frame>

    **Hover popover**

    When you hover a node in the canvas, a preview card shows a short summary of what it does — its main instruction or script, key actions, and transitions.

    <Frame>
      <img alt="Hover preview card summarizing a node" />
    </Frame>
  </Accordion>

  <Accordion title="Bottom tools" icon="toolbox">
    The toolbar at the bottom of the canvas groups three controls.

    <Frame>
      <img alt="Bottom toolbar with Add Node, General Instructions, and Search" />
    </Frame>

    | Tool                     | Description                                                                        |
    | ------------------------ | ---------------------------------------------------------------------------------- |
    | **Add Node**             | Open the node picker to browse and insert new nodes into the flow.                 |
    | **General Instructions** | Open a modal to define global guidance for the whole flow.                         |
    | **Search**               | Search across all nodes by name or content and jump directly to the node you need. |

    **Add Node**

    <Frame>
      <img alt="Add Node button in the bottom toolbar" />
    </Frame>

    The **Add Node** picker is organized by moment in the conversation — **Pre-Call**, **In-Call**, and **Post-Call** tabs (labeled **Pre-Chat / In-Chat / Post-Chat** on text Pearls) — and, within a tab, by group:

    | Tab             | Addable nodes                                                                                                                                 |
    | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Start**       | Opening Sentence **or** Pre-Call API (Pre-Chat API on text).                                                                                  |
    | **In-Call**     | **Live Global Nodes**: Dialogue, Knowledge Base — **Live Action Nodes**: SMS\*, Email, API, Transfer Call\*, Hand-Off (text only), Recording. |
    | **Post-Call**   | SMS, Email, API.                                                                                                                              |
    | **Integration** | Dynamic integration nodes — an API node pre-filled with an integration credential from the Credentials Manager.                               |

    <Frame>
      <img alt="Add Node picker with Pre-Call, In-Call, and Post-Call tabs and node groups" />
    </Frame>

    <Note>
      \*On **text** Pearls, **SMS** and **Transfer Call** are hidden from the picker, while **Hand-Off** is available only on text. Post-call **SMS** remains available for both.
    </Note>

    **General Instructions**

    The middle button opens **General Instructions**, a modal where you define global guidance for the whole flow — persona, tone, strategy, and guardrails. These act as a "meta prompt" layered on top of individual nodes.

    <Frame>
      <img alt="General Instructions button in the bottom toolbar" />
    </Frame>

    <Frame>
      <img alt="General Instructions modal with global flow guidance" />
    </Frame>

    **Search**

    <Frame>
      <img alt="Search button in the bottom toolbar" />
    </Frame>
  </Accordion>
</AccordionGroup>

***

## Top Navigation tabs

The top navigation switches between the main workspaces of your Pearl. **Flow Editor** is the PearlVibe editor covered on this page; the other tabs configure your Pearl's identity, knowledge, analytics, and campaign behavior.

<Frame>
  <img alt="Top navigation tabs: Pearl Settings, Knowledge Base, Analytics, campaign settings, and Flow Editor" />
</Frame>

<br />

<CardGroup>
  <Card title="Pearl Settings" icon="user-gear" href="/pages/agent_customization">
    Set your agent's name, language, voice, personality, and timezone.
  </Card>

  <Card title="Knowledge Base" icon="book" href="/pages/knowledge_base">
    Give Pearl the company context and knowledge it needs to answer accurately.
  </Card>

  <Card title="Analytics" icon="chart-line" href="/pages/pearl_analytics">
    Define success, apply indicator tags, and track your Pearl's performance.
  </Card>

  <Card title="Inbound Settings" icon="phone-arrow-down-left" href="/pages/inbound">
    Configure how your Pearl answers incoming calls.
  </Card>

  <Card title="Outbound Settings" icon="phone-arrow-up-right" href="/pages/outbound">
    Configure how your Pearl runs outbound campaigns.
  </Card>
</CardGroup>


# Pearl Voice
Source: https://developers.nlpearl.ai/pages/pearl_voice

Build AI voice agents that handle real, natural phone conversations - inbound and outbound - in 20+ languages.

<iframe title="NLPearl - Pearl Voice" />

## What is Pearl Voice?

Pearl Voice lets you create AI voice agents that handle real phone conversations at scale. Built on a proprietary speech-to-speech architecture, Pearl delivers natural, low-latency, full-duplex voice interactions across 20+ languages - for both inbound support lines and outbound campaigns.

<Note>
  New to NLPearl? The [Quick Start](/pages/getting_started) walks you from sign-up to your first live call in minutes - with complimentary minutes to test, no subscription required.
</Note>

***

## How it works

<Steps>
  <Step title="Build your agent" icon="wand-magic-sparkles">
    Use [PearlVibe](/pages/pearl_vibe) to define your agent's personality, knowledge base, conversation logic, and connected actions - all through a single prompt-driven interface.
  </Step>

  <Step title="Deploy on a phone line" icon="phone">
    Assign an [NLPearl number](/pages/nlpearl_phones), or connect [Twilio](/pages/twilio_integration) or your own [SIP-compatible VoIP](/pages/custom_voip) provider to launch inbound lines or outbound campaigns. Your agent starts handling real calls immediately.
  </Step>

  <Step title="Monitor and optimize" icon="chart-mixed">
    Track performance with real-time [analytics](/pages/analytics), review [post-call](/pages/postcall) transcripts and summaries, and iterate on your agent's behavior.
  </Step>
</Steps>

***

## Use cases

Pearl Voice fits a wide range of scenarios across both inbound lines and outbound campaigns. Here are some of the most common.

<Tabs>
  <Tab title="Inbound">
    | Use case                        | What Pearl does                                                                         |
    | ------------------------------- | --------------------------------------------------------------------------------------- |
    | **Customer Support**            | Answer incoming calls, resolve questions, and route to the right team - 24/7, at scale. |
    | **Technical Support**           | Guide customers through issue resolution step by step and escalate when needed.         |
    | **Order Tracking**              | Give instant updates on orders, shipments, and delivery status.                         |
    | **Appointment Scheduling**      | Book, confirm, and reschedule appointments with real-time calendar integrations.        |
    | **Complaints & Returns**        | Capture complaints, process returns and refunds, and log everything to your CRM.        |
    | **Lead Intake & Qualification** | Qualify inbound leads, collect their details, and schedule follow-ups.                  |
  </Tab>

  <Tab title="Outbound">
    | Use case                  | What Pearl does                                                              |
    | ------------------------- | ---------------------------------------------------------------------------- |
    | **Sales & Prospecting**   | Call leads, qualify prospects, pitch your offer, and book meetings.          |
    | **Lead Qualification**    | Score leads through dynamic conversations and sync results to your pipeline. |
    | **Appointment Reminders** | Send reminder calls to cut no-shows by up to 70%.                            |
    | **Payment & Collections** | Automate payment reminders and capture promises to pay.                      |
    | **Re-engagement**         | Revive dormant accounts, abandoned carts, and inactive customers.            |
    | **Surveys & Feedback**    | Run post-service satisfaction checks and market research calls at scale.     |
  </Tab>
</Tabs>

<Tip>
  Want ready-to-use prompts for your industry - hospitality, healthcare, e-commerce, legal, insurance, and more? Browse the examples in the [Quick Start](/pages/getting_started).
</Tip>

***

## Models

Every Pearl runs on a voice model that defines how it reasons, how fast it responds, and how much it costs per minute. Pick the model that matches your use case - from deep reasoning for complex conversations to ultra-low cost for simple, high-volume flows.

<Info>
  Pricing is relative to the **Standard Rate** (Pearl Trident). Credit adjustments apply per minute of conversation.
</Info>

| Model             | Description                                                                                                                   | Reasoning | Speed          | Pricing        |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- | -------------- |
| **Pearl Hydra**   | Our smartest model, for demanding use cases that need deeper reasoning, stronger understanding, and higher-quality responses. | High      | Higher latency | +2 credits/min |
| **Pearl Arrow**   | Our fastest model - the same reasoning level as Trident, optimized for ultra-low latency.                                     | Medium    | Fastest        | +2 credits/min |
| **Pearl Trident** | Our standard model, reliable for most everyday conversations - the recommended default.                                       | Medium    | Standard       | Standard Rate  |
| **Pearl Oyster**  | Our most cost-effective model, for simple use cases where reducing cost matters more than reasoning or speed.                 | Low       | Higher latency | -2 credits/min |

<Tip>
  Not sure where to start? **Pearl Trident** is the recommended default for most agents. Move up to **Hydra** when you need stronger reasoning, switch to **Arrow** when speed is critical, or drop to **Oyster** to cut costs on simple flows.
</Tip>

<Warning>
  **Latency may vary depending on the language used and peak usage times on the platform.**

  Pearl Voice response time can vary based on the selected language, conversation complexity, and traffic peaks across the platform. If low latency is critical for your use case, please [contact our Enterprise team](mailto:support@nlpearl.ai) to discuss dedicated server options.
</Warning>

<Note>
  **Good to know:** the more your Pearl runs in production on your specific use case, the better it adapts and the faster it can generate responses over time.
</Note>

***

## Get Started

<CardGroup>
  <Card title="Agents" icon="users" href="/pages/agents">
    Your capacity to handle simultaneous calls. Each agent runs one call at a time - add more agents to scale up your concurrency.
  </Card>

  <Card title="Voices & Languages" icon="language" href="/pages/languages">
    Configure your agent's name, language, and voice. Choose from 20+ languages and a wide range of natural-sounding accents.
  </Card>

  <Card title="Post-Call" icon="clipboard-check" href="/pages/postcall">
    Access structured summaries, transcripts, recordings, and extracted variables for every call.
  </Card>

  <Card title="Inbound" icon="phone-arrow-down-left" href="/pages/inbound">
    Deploy agents on inbound lines to answer calls, resolve questions, and route to the right team - 24/7.
  </Card>

  <Card title="Outbound" icon="phone-arrow-up-right" href="/pages/outbound">
    Launch outbound campaigns to reach leads, qualify prospects, send reminders, and follow up at scale.
  </Card>
</CardGroup>

***

## Phone Numbers & VoIP

Every voice activity needs a phone number. You can buy numbers directly from NLPearl, bring your own Twilio numbers, or connect your own SIP-compatible VoIP provider.

<CardGroup>
  <Card title="Phone Numbers Overview" icon="hashtag" href="/pages/phone_overview">
    Understand why phone numbers are essential for your activities and which options are available to purchase or integrate them.
  </Card>

  <Card title="NLPearl Phone Numbers" icon="mobile" href="/pages/nlpearl_phones">
    Purchase phone numbers directly from the NLPearl platform and assign them to your inbound and outbound activities.
  </Card>

  <Card title="Twilio Integration" icon="object-intersect" href="/pages/twilio_integration">
    Connect your Twilio account to use your existing Twilio phone numbers with your Pearls.
  </Card>

  <Card title="Custom VoIP" icon="code-branch" href="/pages/custom_voip">
    Integrate your own SIP-compatible VoIP provider to route calls through your existing telephony infrastructure.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/pages/getting_started">
    Go from sign-up to your first live AI voice agent in minutes.
  </Card>

  <Card title="PearlVibe" icon="wand-magic-sparkles" href="/pages/pearl_vibe">
    Build and customize your agent's logic, knowledge, and actions from a single prompt.
  </Card>

  <Card title="Variables" icon="brackets-curly" href="/pages/variables">
    Collect, store, and reuse data during conversations - from user inputs to CRM lookups.
  </Card>

  <Card title="API Quick Start" icon="code" href="/api-reference/api_quickstart">
    Integrate Pearl Voice programmatically via the REST API.
  </Card>
</CardGroup>


# Phone Numbers Overview
Source: https://developers.nlpearl.ai/pages/phone_overview

Learn why phone numbers are essential for activities on NLPearl.AI and the available options for purchasing and integrating them.

<div>
  <Frame>
    <div>
      <img alt="Phone Numbers Overview cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Phone Numbers Overview cover" />
    </div>
  </Frame>
</div>

In order to initiate inbound or outbound call activities on NLPearl.AI, you need to have phone numbers linked to your account. These phone numbers determine the country code for your campaigns and activities, making them essential for ensuring proper communication with leads or customers based on their location.

Whether you’re running a sales campaign or handling customer support, phone numbers allow you to tailor your activities to specific regions. The phone number’s country code plays a crucial role, especially for compliance and regional availability.

<Check>
  **Why You Need Phone Numbers**

  Phone numbers are required for both **inbound** and **outbound** activities on NLPearl.AI. Each phone number is tied to a specific country code, which defines the geographic area your campaign will cover. By associating phone numbers with your activities, you gain the following benefits:

  * **Localized Presence**: Contact leads with a local number, increasing the likelihood of engagement.
  * **Compliance**: Ensure that your activities meet country-specific regulations.
  * **Flexibility**: Choose from multiple options to purchase or integrate phone numbers depending on your needs.
</Check>

***

### Available Options for Phone Numbers

NLPearl.AI offers you three main ways to acquire or integrate phone numbers into your activities. You can choose the option that best suits your business needs and geographic requirements.

<Card>
  <div>
    <img alt="Logo clair" />

    <h3>NLPearl Phone Numbers</h3>
  </div>

  <div>
    <img alt="Logo sombre" />

    <h3>NLPearl Phone Numbers</h3>
  </div>

  NLPearl provides an easy solution to purchase phone numbers directly from the platform. This option is ideal if you need a quick and straightforward way to acquire phone numbers, currently available for the United States. By purchasing a phone number from NLPearl, you can easily manage and assign it to your inbound and outbound campaigns.

  <Info>
    For more details, visit the [NLPearl Phone Numbers](/pages/nlpearl_phones) page.
  </Info>
</Card>

<br />

<Card>
  <div>
    <img alt="Logo clair" />

    <h3>Twilio Integration</h3>
  </div>

  <div>
    <img alt="Logo sombre" />

    <h3>Twilio Integration</h3>
  </div>

  If you already have a Twilio account, you can integrate it directly with NLPearl.AI and import the phone numbers you have from Twilio. This option allows for more flexibility as Twilio provides phone numbers for multiple countries, enabling you to extend your campaigns to a broader audience.

  <Info>
    Visit [Twilio Integration](/pages/twilio_integration) for details on how to import and manage your Twilio phone numbers.
  </Info>
</Card>

<br />

<Card>
  <div>
    <img alt="Logo clair" />

    <h3>Custom VoIP Integration</h3>
  </div>

  <div>
    <img alt="Logo sombre" />

    <h3>Custom VoIP Integration</h3>
  </div>

  For businesses with custom VoIP providers, NLPearl.AI supports the integration of your own VoIP services. This gives you full control over the phone numbers and configurations, making it ideal for those with specific telecom setups.

  <Info>
    To learn more about integrating your own VoIP service, check out [Custom VoIP Integration](/pages/custom_voip).
  </Info>
</Card>

***

### Naming Your Phone Numbers

Once numbers are in your account, you can give each one a **display name** to recognize it easily (for example, *"Customer Phone"*). In the **Phone Numbers** list, click the pencil icon next to a number, enter a name, and save.

<Frame>
  <img alt="Editing a phone number's display name in the Phone Numbers list" />
</Frame>

***

<Note>
  Phone numbers are the foundation of your communication activities on NLPearl.AI. Depending on your business needs, you can choose from NLPearl-provided numbers, integrate your Twilio account, or use your own VoIP provider to ensure full flexibility and coverage for your campaigns.
</Note>


# Post-Call
Source: https://developers.nlpearl.ai/pages/postcall

All you need to know about Post-Call in NLPearl

<div>
  <Frame>
    <div>
      <img alt="Post-Call cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Post-Call cover" />
    </div>
  </Frame>
</div>

***

## What is a Post-Call?

In NLPearl, a **post-call** is a structured summary generated after each phone conversation handled by Pearl. It centralizes all key information captured before, during, and after the call to ensure full traceability, improve quality, and support human follow‑up when needed.

***

## What Does the Post-Call Include?

A post-call provides multiple key sections to review and analyze the outcome of a conversation:

### Call ID

A unique identifier for each call, displayed at the top right of the page. It allows you to quickly reference or search for a specific call across the system.

<Frame>
  <img alt="Call ID location in the post-call view" />
</Frame>

***

### Call Details

This section summarizes the essential metadata captured during the call, such as timing, the Pearl version used, credits consumed, and the overall outcome.

| Field                 | Description                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Date**              | The exact date and time the call took place.                                                                     |
| **Pearl Version**     | The version of the Pearl that handled the call.                                                                  |
| **Lead Name**         | The name of the lead (outbound calls).                                                                           |
| **Duration**          | The length of the call, in mm:ss.                                                                                |
| **Transfer Duration** | Time spent with a human agent after a transfer (shown only when the call was transferred).                       |
| **Queue Duration**    | Time the caller spent waiting in the holding line before being answered (shown only when the caller was queued). |
| **Credits Used**      | The number of credits consumed by the call.                                                                      |
| **SMS Credits Used**  | The number of credits consumed by SMS messages sent during the call (shown only when greater than 0).            |
| **Status**            | The technical call status (e.g. Completed, Busy, No Answer).                                                     |
| **Sentiment**         | The detected sentiment of the customer during the conversation.                                                  |
| **Events**            | A shortcut to the actions triggered during the call — click **View** to jump to the Event Log.                   |

<Note>
  Some fields are conditional: **Lead Name** appears for outbound calls, **Transfer Duration** only when the call was transferred, **Queue Duration** only when the caller was queued, and **SMS Credits Used** only when at least one SMS was sent.
</Note>

<Frame>
  <img alt="Call Details section in the post-call view" />
</Frame>

***

**Call Status** <br />
The technical status of the call (whether the user answered or not), shown as the **Status** field in the [Call Details](#call-details) section above. Possible values include:

| Status        | Description                                                         |
| ------------- | ------------------------------------------------------------------- |
| `In Progress` | The call is currently ongoing or being connected.                   |
| `Completed`   | The call was successfully connected and ended normally.             |
| `Busy`        | The receiver was already on another call or rejected the call.      |
| `Failed`      | The call could not be established due to an error or network issue. |
| `No Answer`   | The call rang but no one picked up before the timeout.              |
| `Canceled`    | The call was canceled before it connected.                          |

<Info>Call Status refers to the telephony-level result of the call connection, such as whether the call was picked up, missed, busy, or failed to connect.</Info>

***

**Conversation Status** <br />
Indicates the outcome of the conversation from a business or process perspective. It is shown as a colored badge in the header, next to the caller and receiver numbers. Possible values include:

<Frame>
  <img alt="Conversation status badge and phone numbers in the post-call header" />
</Frame>

| Status            | Description                                                                             |
| ----------------- | --------------------------------------------------------------------------------------- |
| `Voice Mail Left` | A voicemail was successfully left. *(Outbound only)*                                    |
| `Need Retry`      | The contact attempt failed and should be retried. *(Outbound only)*                     |
| `Unreachable`     | The lead couldn't be reached after all retry attempts were exhausted. *(Outbound only)* |
| `Call Successful` | The conversation achieved its expected outcome.                                         |
| `Not Successful`  | The conversation failed to meet its objective.                                          |
| `Completed`       | The conversation was conducted and finalized, regardless of outcome.                    |

<Card icon="circle-info">
  <b>Important distinctions about Conversation Status</b>:

  * `Voice Mail Left`, `Need Retry`, and `Unreachable` are **only shown for outbound activities**; these statuses are not applicable for inbound calls.

  * The difference between `Successful`, `Not Successful`, and `Complete` depends on whether a **Success Definition** was configured when creating the Pearl:
    * If a **Success Definition** was configured:
      * `Successful` → the Success Definition criteria were met during the conversation.
      * `Not Successful` → the conversation did not meet the Success Definition criteria.
    * If **no Success Definition** was configured:
      * `Complete` → the conversation was completed without any Success Definition evaluation.
</Card>

<Note> For more information on Success Definitions, see [How to Create a Pearl – Step 4: Flow Configuration](/pages/create_pearl#step-4-flow-configuration).</Note>

***

**Tags** <br />
The list of **tags defined during the last step of the Pearl creation process**. These tags represent key topics or categories you chose when setting up the Pearl configuration.

<Frame>
  <img alt="Tags in the post-call view" />
</Frame>

<Note>For more information on setting up tags, see [How to Create a Pearl – Step 4: Flow Configuration](/pages/create_pearl#step-4-flow-configuration).</Note>

***

**Events** <br />
A log of the actions triggered by Pearl during the call. Each event includes a timestamp, the action details, and an execution status. The **Events** row in Call Details is a shortcut — click **View** to jump straight to the **Event Log**.

Possible event types include:

| Event Type         | Description                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `Call Transferred` | The call was transferred to another destination.                                                 |
| `SMS Sent`         | A text message was sent to the customer.                                                         |
| `Email Sent`       | An email was sent during the call.                                                               |
| `API`              | An API was triggered — before the call (Pre-Call), during it (In-Call), or after it (Post-Call). |
| `Appointment`      | An appointment was booked in the calendar.                                                       |
| `Slack`            | A Slack notification was sent.                                                                   |
| `Call Recorded`    | The call recording was captured.                                                                 |
| `Hand-Off`         | The conversation was handed off to a human (text agents).                                        |

<Info>
  Each event carries an execution status: the **HTTP status code** for API calls, otherwise **sent** / **failed**, with a possible error state (SMS, email, API, transfer, or booking error).
</Info>

<Frame>
  <img alt="Events shortcut in the post-call view" />
</Frame>

***

**Sentiment Analysis**  <br />
An automatic classification of the customer's tone and emotional state throughout the conversation. Possible sentiment values include:

| Sentiment Value     | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| `Positive`          | The conversation was clearly positive in tone and emotion.        |
| `Slightly Positive` | The overall tone was mostly positive, with minor neutral moments. |
| `Neutral`           | The sentiment was balanced or emotionless.                        |
| `Slightly Negative` | The tone leaned slightly negative, but not strongly so.           |
| `Negative`          | The conversation had a clearly negative emotional tone.           |

<Frame>
  <img alt="Sentiment analysis in the post-call view" />
</Frame>

***

### Summary

A concise, human‑readable recap of the conversation, generated by Pearl. This includes:

* What the customer requested
* What was confirmed or declined
* The overall outcome of the interaction

<Frame>
  <img alt="Summary in the post-call view" />
</Frame>

***

### Transcript & Event Log

A toggle at the top of the right-hand panel switches between the **Transcript** and the **Event Log**.

**Transcript** — a full text version of the conversation between the customer and Pearl. It is structured into three blocks separated by dividers: **Pre-call events → In-call messages → Post-call events**. Timestamps are clickable and jump to the matching point in the recording. Useful for reviewing the interaction, auditing, and training.

<Frame>
  <img alt="Transcript in the post-call view" />
</Frame>

**Event Log** — a chronological view of all actions triggered by Pearl during the call. Each entry shows the action type (API call, SMS, email, transfer…), its execution status, and contextual data, so you can verify that every automated operation ran and inspect its output.

<Frame>
  <img alt="Event Log in the post-call view" />
</Frame>

***

### Variables

This section, labeled **Variables** in the UI, displays the **structured data captured before or during the call**, corresponding to the dynamic values collected through the Pearl configuration.\
Examples:

* Delivery type
* Selected options (e.g. “Dessert: Cheesecake”)
* Customer preferences

Variables displayed here are based on those defined in your **Pearl configuration**.

<Frame>
  <img alt="Call information variables in the post-call view" />
</Frame>

<Info>
  You can learn more about creating variables in the Pearl [here](/pages/variables).
</Info>

***

### Recording

The **recording is accessible directly from this page**, allowing you to listen to the entire conversation again for audit, training, or operational purposes. Clicking a timestamp in the **Transcript** seeks the player to that exact moment.

<Frame>
  <img alt="Recording player in the post-call view" />
</Frame>

<Note>
  The audio player only appears when the **Call Status** is `Completed` **and** recording is enabled for the activity.
</Note>

<Warning>If you wish to **disable call recording**, you can manage this setting from the activity configuration (whether **inbound** or **outbound**).</Warning>
👉 For more information on recording settings, see [Inbound Recording](/pages/inbound) or [Outbound Recording](/pages/outbound).

If you're unable to listen to your recording and you imported a phone number from your Twilio account by connecting it to the platform, it is possible that you cannot access the recording because you have not disabled the 'HTTP Basic Authentication' option in your Twilio settings. For more information see [Disable HTTP Auth from Twilio](/pages/twilio_integration#disabling-http-basic-authentication-for-media-access)

***

<Tip>
  **Navigation & shortcuts** — a few actions make it faster to move around and act on a call:

  * **Open the linked Lead** — for outbound calls, open the lead's details in a popover directly from the call.
  * **Move between calls** — use the on-screen arrows or the **↑ / ↓** keyboard keys to jump to the previous or next call without leaving the post-call view.
  * **Jump to the Event Log** — click **View** on the Events row in Call Details to switch straight to the Event Log tab.
</Tip>

***

## Why the Post-Call Matters

<CardGroup>
  <Card title="Traceability" icon="check">
    Every call leaves a documented trace for accountability.
  </Card>

  <Card title="Faster Follow‑Up" icon="check">
    Helps support and operations teams follow up efficiently with customers.
  </Card>

  <Card title="Quality & Analytics" icon="check">
    Enables continuous improvement through quality review, sentiment tracking, and conversation analysis.
  </Card>

  <Card title="Auditing & Compliance" icon="check">
    Provides an auditable record of AI-driven conversations to meet regulatory or internal policy needs.
  </Card>
</CardGroup>

***

By consolidating all these elements, the **Post-Call Activities** page provides a complete overview of each AI-handled conversation, ensuring transparency, traceability, and actionable insights for your team.


# Recording Node
Source: https://developers.nlpearl.ai/pages/recording



<Callout icon="phone">Available for **Pearl Voice** only.</Callout>

<div>
  <Frame>
    <div>
      <img alt="Recording node cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Recording node cover" />
    </div>
  </Frame>
</div>

The **Start Recording** node gives you control over when call recording begins in a Pearl Voice flow.

## What it does

Starts recording at the exact point where Pearl reaches this node in a Pearl Voice flow.

Recording is usually managed at campaign level. In most cases, calls are recorded automatically according to the **Recording** settings in your **Inbound Campaign** or **Outbound Campaign** settings.

<Warning>
  **Feature-flagged node.** Start Recording is hidden by default and is not available in every workspace or plan.
</Warning>

To add it to your flow, ask **PearlVibe** in natural language, in **Build** mode:

```text Example prompt for PearlVibe theme={null}
Add a Start Recording node after Pearl asks the caller for permission to record the call.
```

<Note>
  If Start Recording does not appear in the toolbar or add-node panel after asking PearlVibe, it is not enabled for your account.
</Note>

## When to use it

Use Start Recording when recording should begin only after a specific moment in the call:

| Use case              | Recording begins                                             |
| --------------------- | ------------------------------------------------------------ |
| **Disclosure**        | Once Pearl informs the caller the call may be recorded       |
| **Consent**           | Once the caller agrees to be recorded                        |
| **Specific branches** | Only on selected paths of the flow                           |
| **Compliance**        | When a process requires recording to begin later in the call |

## How it works

Automatic recording is configured in your **Inbound Campaign** or **Outbound Campaign** settings. When it is enabled, recording begins at the start of the call and you do not need this node.

To trigger recording from the flow instead, set it up as a conditional action:

<Steps>
  <Step title="Disable automatic recording">
    Turn off automatic recording in the relevant Inbound or Outbound Campaign settings, so recording starts only from the flow.

    <Frame>
      <img alt="Disable the automatic recording option in campaign settings" />
    </Frame>

    <Warning>
      Once automatic recording is disabled, any call that does not reach the Start Recording node will **not** be recorded. Make sure every path that requires a recording leads to the node.
    </Warning>
  </Step>

  <Step title="Ask for consent (optional)">
    Add a [Dialogue](/pages/dialogue) node before Start Recording to explain the recording policy and collect the caller's answer. Start Recording does not ask for permission by itself.
  </Step>

  <Step title="Route the consent path">
    Use a conditional transition to send callers who agree to the **Start Recording** node.
  </Step>

  <Step title="Place the node">
    Put **Start Recording** exactly where recording should begin. It has no configuration fields, it is an action marker inside the flow.

    <Frame>
      <img alt="Start Recording node placed in a Pearl Voice flow" />
    </Frame>
  </Step>
</Steps>

<Info>
  Recordings are always active during test calls, regardless of this node or your campaign recording settings.
</Info>


# Account Security Settings
Source: https://developers.nlpearl.ai/pages/security

Manage session timeout, audit logs, two-factor authentication, and enterprise access controls.

<div>
  <Frame>
    <div>
      <img alt="Account Security Settings cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Account Security Settings cover" />
    </div>
  </Frame>
</div>

***

Use account security settings to manage how users access your workspace, how long sessions stay active, and how administrators review important account activity.

<CardGroup>
  <Card title="Session timeout" icon="clock">
    Automatically log users out after a period of inactivity.
  </Card>

  <Card title="Two-factor authentication" icon="shield">
    Add an extra verification step when users log in.
  </Card>

  <Card title="Audit log" icon="list">
    Track workspace activity and security-related events.
  </Card>

  <Card title="Enterprise SSO" icon="building-lock">
    Connect enterprise identity providers through Single Sign-On.
  </Card>
</CardGroup>

***

## Accessing Your Settings

All the settings on this page live in your **Settings**. To open them, click your **profile card** at the bottom-left corner of the sidebar, then select **Settings**.

<Frame>
  <img alt="Open Settings from the profile card" />
</Frame>

From there, use the left menu: the **Security** tab (under *User*) for 2FA and password, and **General Settings** or **Audit Log** (under *Workspace*) for session timeout and activity logs.

***

## Customizing Your Session Timeout

You can configure how long a session remains active before the user is automatically logged out due to inactivity. This helps protect your account if you forget to log out, especially when using a shared or public device.

The session timeout is set in **minutes**, with a minimum of **30 minutes** and a maximum of **3 days**.

<Note>
  This is a **workspace-level** setting managed by the **workspace owner**. The value applies to **all members** of the workspace, not just the account that changes it.
</Note>

<Steps>
  <Step title="Open General Settings">
    Go to **Settings > General Settings** under the *Workspace* section.

    <Frame>
      <img alt="General Settings tab in the Workspace section" />
    </Frame>
  </Step>

  <Step title="Set the Session Timeout">
    In the **Session Timeout** field, enter the duration in minutes and click **Update**.

    <Frame>
      <img alt="Session Timeout field in Workspace General Settings" />
    </Frame>
  </Step>
</Steps>

<Tip>
  Shorter session timeouts are recommended for shared devices, public computers, or workspaces with stricter security policies.
</Tip>

***

## Reviewing Workspace Activity with Audit Logs

The **Audit Log** helps administrators review important activity and security events in the workspace. It is useful for monitoring sign-ins, configuration changes, published Pearls, and other account-level events.

To access it, go to **Settings > Audit Log** under the *Workspace* section.

<Frame>
  <img alt="Audit Log tab in the Workspace section" />
</Frame>

Each entry in the log includes:

* **Timestamp**: when the event happened.
* **Event Type**: the kind of action recorded, such as a successful login or published Pearl.
* **User**: the workspace member who triggered the event.
* **Details**: additional context about the action, when available.

### Recorded event types

The audit log records the following events. The **Event Type** filter uses the same labels shown below.

#### Pearls

| Event type         | Description                                           |
| ------------------ | ----------------------------------------------------- |
| Publish Pearl      | A Pearl was published.                                |
| Pearl Status       | A Pearl's status was changed.                         |
| Pearl Retention    | A Pearl's data retention settings were changed.       |
| Pearl Total Agents | The number of agents assigned to a Pearl was changed. |
| Pearl Budget       | A Pearl's budget was changed.                         |
| Pearl Phone Number | A Pearl's phone number was changed.                   |
| Transfer Pearl     | A Pearl was transferred.                              |
| Delete Pearl       | A Pearl was deleted.                                  |

#### API keys

| Event type            | Description                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------- |
| Create API Key        | An API secret key or an OAuth 2.0 app was created.                                       |
| Update API Key        | An OAuth 2.0 app's scopes were changed.                                                  |
| Rotate API Key Secret | An OAuth 2.0 app's client secret was rotated. The secret value is not stored in the log. |
| Delete API Key        | An API secret key or an OAuth 2.0 app was deleted.                                       |
| Reveal API Key        | An API key was revealed. The secret value is not stored in the log.                      |

#### Users and roles

| Event type                 | Description                                       |
| -------------------------- | ------------------------------------------------- |
| Invite User                | A user was invited to the workspace.              |
| User Join                  | A user joined the workspace.                      |
| Invitation Canceled        | A pending invitation was canceled.                |
| Update User Role           | A user's role was changed.                        |
| Update Account Information | Workspace account information was changed.        |
| Remove User from Account   | A user was removed from the workspace.            |
| User Left Account          | A user left the workspace.                        |
| Create Role                | A workspace role was created.                     |
| Update Role                | A workspace role or its permissions were changed. |
| Delete Role                | A workspace role was deleted.                     |

#### Security

| Event type            | Description                                                |
| --------------------- | ---------------------------------------------------------- |
| Login Attempt         | A user attempted to sign in.                               |
| Login Successful      | A user signed in successfully.                             |
| Update Session TTL    | The workspace session timeout was changed.                 |
| Set 2FA               | Two-factor authentication settings were changed.           |
| Change Password       | A user changed their password.                             |
| Delete Account        | The workspace account was deleted.                         |
| Add to Blacklist      | One or more phone numbers were added to the blacklist.     |
| Remove from Blacklist | One or more phone numbers were removed from the blacklist. |

#### Billing and agents

| Event type          | Description                                      |
| ------------------- | ------------------------------------------------ |
| Purchase Agents     | Agents were purchased.                           |
| Delete Agent        | An agent was removed.                            |
| Set Billing Details | Workspace billing details were changed.          |
| Set Payment Method  | The workspace payment method was changed.        |
| Set Subscription    | The workspace subscription was changed.          |
| Cancel Subscription | The workspace subscription was canceled.         |
| Purchase Credits    | Credits were purchased.                          |
| Set Auto Recharge   | Automatic credit recharge settings were changed. |

#### Phone numbers

| Event type               | Description                                   |
| ------------------------ | --------------------------------------------- |
| Purchase Phone Numbers   | One or more phone numbers were purchased.     |
| Release Phone Number     | A phone number was released.                  |
| Add Phone Number         | A bring-your-own phone number was added.      |
| Update Phone Number      | A phone number's settings were changed.       |
| Update SIP Configuration | SIP settings for a phone number were changed. |
| Set Twilio Credentials   | Workspace Twilio credentials were changed.    |

#### Text channels and integrations

| Event type               | Description                                                                    |
| ------------------------ | ------------------------------------------------------------------------------ |
| Create Text Channel      | A text channel was created.                                                    |
| Update Text Channel      | A text channel was changed.                                                    |
| Delete Text Channel      | A text channel was deleted.                                                    |
| Rotate Channel Secret    | A text channel secret was rotated.                                             |
| Reveal Channel Secret    | A text channel secret was revealed. The secret value is not stored in the log. |
| Connect WhatsApp         | A WhatsApp integration was connected.                                          |
| Add WhatsApp Number      | A phone number was added to a WhatsApp integration.                            |
| Disconnect WhatsApp      | A WhatsApp integration was disconnected.                                       |
| Set Email Credentials    | Email credentials were configured.                                             |
| Delete Email Credentials | Email credentials were removed.                                                |
| Connect Slack            | A Slack integration was connected.                                             |
| Connect Calendar         | A calendar integration was connected.                                          |

#### Data and groups

| Event type      | Description                                         |
| --------------- | --------------------------------------------------- |
| Import Leads    | Leads were imported into a Pearl.                   |
| Delete Leads    | Leads were deleted from a Pearl.                    |
| Delete Calls    | Calls were deleted from a Pearl.                    |
| Export Calls    | Calls were exported from a Pearl.                   |
| Group Retention | A group's contact retention settings were changed.  |
| Delete Contacts | Group contacts were purged by the retention policy. |

<Frame>
  <img alt="Audit Log with date range and event type filters" />
</Frame>

<Note>
  Use the **date range** and **Event Type** filters at the top right to narrow the audit log when investigating a specific time period or activity.
</Note>

***

## Enterprise Single Sign-On (SSO)

Single Sign-On (SSO) is available for Enterprise workspaces. It allows your team to authenticate through your company identity provider and centralize access management.

<Info>
  To enable SSO for your workspace, contact us at [support@nlpearl.ai](mailto:support@nlpearl.ai). Please include your workspace name, company domain, and preferred identity provider if available.
</Info>

Once SSO is enabled, members sign in with the **Sign in with SSO** button on the login screen instead of entering a password.

<Frame>
  <img alt="Sign in with SSO button on the login screen" />
</Frame>

***

## Two-Factor Authentication (2FA)

Two-Factor Authentication (2FA) adds an additional step to the login process to strengthen your account’s security. Instead of relying solely on your password, which could be guessed, leaked, or stolen, 2FA requires a second form of verification that only you should have access to.

Typically, this second factor is a temporary code generated by a mobile app like Google Authenticator. If you can't reach your app, you can also receive the code by **SMS** at login. Even if someone knows your password, they won’t be able to access your account without that second code. That’s why 2FA is a simple and highly effective way to safeguard your data.

In this guide, we’ll show you exactly how to activate and use Two-Factor Authentication on our platform.

***

### How to Set Up 2FA

<Steps>
  <Step title="Open the Platform Security page">
    Click your **profile card** at the bottom-left corner of the sidebar, open **Settings**, then select the **Security** tab under the *User* section.

    <Frame>
      <img alt="Security tab in Settings, opening the Platform Security page" />
    </Frame>
  </Step>

  <Step title="Locate the 2FA box">
    The **Platform Security** page has two areas: the **2FA (Two-Factor Authentication)** box and a **Reset Password** section.

    <Frame>
      <img alt="Two-Factor Authentication box on the Platform Security page" />
    </Frame>
  </Step>

  <Step title="Open the setup window">
    In the **2FA (Two-Factor Authentication)** box, click **Set up authenticator** (labeled **Reset authenticator** once 2FA is already set up) to open the QR code window.

    <Frame>
      <img alt="Button that opens the 2FA setup window" />
    </Frame>

    The **Secure your NLPearl account with 2FA** window appears, showing a QR code on the right and the boxes to enter your code.

    <Frame>
      <img alt="2FA setup window with QR code and verification code" />
    </Frame>
  </Step>

  <Step title="Download an authenticator app">
    On your phone, install an authenticator app such as **Google Authenticator**, **Microsoft Authenticator**, or **Authy**.

    <Frame>
      <img alt="Google Authenticator on the App Store" />
    </Frame>
  </Step>

  <Step title="Scan the QR code">
    Open the app, tap the **+** button, and choose **Scan a QR code**. Point your camera at the QR code shown in the setup window.

    <Frame>
      <img alt="Scanning a QR code in Google Authenticator" />
    </Frame>
  </Step>

  <Step title="Enter the 6-digit code">
    The app generates a **6-digit code** that refreshes every few seconds. Enter it in the setup window and click **Verify & Activate**.

    <Frame>
      <img alt="6-digit code generated by Google Authenticator" />
    </Frame>
  </Step>

  <Step title="Turn 2FA on or off">
    Once 2FA has been set up, use the **toggle** in the 2FA box to turn it on or off for your account at any time. When it's on, you're asked for a code at every login; when it's off, 2FA is disabled but your authenticator stays configured.

    <Frame>
      <img alt="Toggle to turn 2FA on or off on your account" />
    </Frame>

    <Check>
      Once the code is verified, 2FA is active on your account. You'll be asked for a code at every login.
    </Check>

    <Note>
      Lost access to your authenticator app or got a new phone? Click **Reset authenticator** in the 2FA box (the same button used during setup) to unlink the current device and reopen the QR window to set up a new one.
    </Note>
  </Step>

  <Step title="How it works at login">
    Once 2FA is active, every login prompts you for a verification code:

    * Enter the current 6-digit code from your **authenticator app**.
    * If you can't reach your app, click **Get your code via SMS** in the prompt to receive the code by text instead.

    <Frame>
      <img alt="Two-Factor Authentication prompt at login" />
    </Frame>
  </Step>
</Steps>

***

## Resetting Your Password

You can update your account password at any time from the **Platform Security** page. In the **Reset Password** section, click **Reset Password** and follow the prompts.

<Frame>
  <img alt="Reset Password section on the Platform Security page" />
</Frame>


# Send SMS Node
Source: https://developers.nlpearl.ai/pages/sms_action



<Callout icon="phone">Available for **Pearl Voice** only.</Callout>

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on light mode" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on dark mode" />
    </div>
  </Frame>
</div>

The **Send SMS** node lets your AI agent send an SMS in real time, during the conversation (In-Call) or after it ends (Post-Call), so your customers receive important information instantly.

***

## Adding the Node

In the Flow Editor, add a **Send SMS** node where you want the message to be sent.

| Context       | Where to add it                                                                |
| ------------- | ------------------------------------------------------------------------------ |
| **In-Call**   | Place the node in the conversation, at the point where the SMS should be sent. |
| **Post-Call** | Add it as a **Post-Call action** to send the SMS once the call ends.           |

<Note>
  The SMS is sent based on where the node sits in your flow, there is **no separate trigger field** on the node itself.
</Note>

***

## Fields to Configure

<Frame>
  <img alt="Send SMS node configuration with To and SMS Content fields" />
</Frame>

<Steps>
  <Step title="To">
    The recipient phone number(s), entered as tags. **At least one recipient is required**, and you can mix both modes below in the same field.

    **Send to the customer (dynamic)** — Insert the built-in **phone number** variable with the variable picker. At send time it resolves to the number of the person on the call, including the country code (e.g. `+1 234 567 8900`), and is stored as `{phoneNumber}`. This is the most common setup: the SMS goes to the customer you're talking to.

    **Send to a fixed number (static)** — Type a number and press **Space** or **Enter** to turn it into a tag. Use this to always notify the same destination (an internal team, a manager, a back-office line), whoever is on the call.

    <Info>
      Only the built-in **phone number** variable can be inserted here. Custom variables (including numbers collected during the call) are **not** available in the To field, only static numbers or the customer's phone number. This mirrors the Email node's **To** field, which only accepts the **email address** variable.
    </Info>

    **Accepted format**: an optional leading `+` followed by 1 to 20 digits, with no spaces, dashes, or parentheses. Invalid entries are rejected and not added as a tag.

    | Valid          | Invalid           |
    | -------------- | ----------------- |
    | `+15551234567` | `+1 555 123 4567` |
    | `0612345678`   | `(555) 123-4567`  |
  </Step>

  <Step title="SMS Content">
    Write the message to send. You can include links and details, and insert variables to personalize it, for example: `Hi {firstName}, your reservation at {restaurantName} is confirmed.`

    Available variables depend on where the node runs:

    | Context       | Available variables                                     |
    | ------------- | ------------------------------------------------------- |
    | **In-Call**   | Pre-Call + In-Call                                      |
    | **Post-Call** | Pre-Call + In-Call + Post-Call (e.g. summary, duration) |
  </Step>
</Steps>

<Info>
  **Regulatory compliance** — To stay compliant, Pearl always asks the customer for consent before sending an SMS, respecting their preferences and communication laws.
</Info>

***

## Example Use Cases

<CardGroup>
  <Card title="Reservation confirmations" icon="calendar-check">
    After confirming a reservation, Pearl automatically sends an SMS with the details.
  </Card>

  <Card title="Appointment reminders" icon="bell">
    Pearl sends a reminder SMS about an upcoming appointment or event.
  </Card>
</CardGroup>

***

## SMS Credit Cost

<Info>
  Sending an SMS consumes credits from your account balance. The cost depends on:

  * **Recipient country**: each destination has its own rate per segment.
  * **Number of segments**: longer messages are split into multiple segments, each billed individually.
</Info>

A standard segment holds up to **160 characters** (GSM-7). With special characters or emojis, encoding switches to UCS-2 and the limit drops to **70 characters** per segment. Messages exceeding one segment are concatenated, with each segment charged separately.

| Encoding               | Single SMS limit | Concatenated segment limit |
| ---------------------- | ---------------- | -------------------------- |
| GSM-7 (standard)       | 160 characters   | 153 characters per segment |
| UCS-2 (unicode/emojis) | 70 characters    | 67 characters per segment  |

<Warning>
  If your SMS contains **variables** (e.g. `firstName`), the final cost may vary, since the number of characters, and therefore segments, depends on each variable's value at send time.
</Warning>

### SMS Credit Calculator

Use this calculator to estimate how many segments your message will use and the total credit cost based on the destination country.

<SmsCalculator />


# Pearl Settings
Source: https://developers.nlpearl.ai/pages/text/agent_customization



<div>
  <Frame>
    <div>
      <img alt="Pearl Settings cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Pearl Settings cover" />
    </div>
  </Frame>
</div>

In this step, you can customize your chat agent's identity and behavior by setting its **name**, **personality**, **timezone**, and **Pearl Model**.

***

## Agent Name

To define your agent's identity:

* **Agent Name** – Set your Pearl's name (e.g., *Joe*, *Victoria*). This is the name it will use when chatting with customers. Max **25 characters**, required.

<Frame>
  <img alt="Agent Name in Pearl Settings" />
</Frame>

***

## Pearl Model

The **Pearl Model** defines the intelligence, speed, and cost profile of your agent. Chat agents run on a single model, **Pearl Swan**.

<Frame>
  <img alt="Pearl Model (Pearl Swan) in Pearl Settings" />
</Frame>

<Card>
  <Info>
    **High Reasoning · Higher Latency · Standard Rate**
  </Info>

  Our standard model for chat agents, built to handle any text-based use case with reliable reasoning and natural responses.
</Card>

<Note>
  Since Pearl Swan is the only model available for chat agents, the selector is fixed on it.
</Note>

***

## Personality

Your AI agent can take on a wide range of personalities, from natural and professional to wild, fictional, or downright iconic.

<Frame>
  <img alt="Personality selection in Pearl Settings" />
</Frame>

<Tip>
  **Create your own personality.** You're not limited to the predefined list. Type any description in the **Personality** field and select **Use "\<your text>" as a custom personality** to define your own.
</Tip>

<Note>
  Choose wisely. Your agent's personality will shape how it behaves in every interaction. Personality is optional, only **Agent Name** and **Timezone** are required.
</Note>

The personalities below are **examples** to give you a feel for the range available. The full list is loaded in the app and may evolve over time.

| Personality Name            | Description (vibe / reference)                          |
| --------------------------- | ------------------------------------------------------- |
| Natural                     | Neutral and balanced, default tone.                     |
| Friendly Consultant         | Warm, helpful, and a touch conversational.              |
| Aggressive Closer           | Direct, assertive, always aiming for a "yes."           |
| Donald Trump                | Bold, confident, and controversial.                     |
| Joe Biden                   | Soft-spoken, empathetic, with a hint of grandpa energy. |
| Wolf of Wall Street         | Energetic, persuasive, and money-focused.               |
| Elon Musk                   | Visionary, quirky, and matter-of-fact.                  |
| Kevin Hart                  | Fast-talking and hilarious.                             |
| The Rock                    | Charismatic and full of hype.                           |
| Jar Jar Binks               | Clumsy comic relief with a chaotic syntax.              |
| Yoda                        | Wise, reversed sentence order, it has.                  |
| Tommy Shelby                | Cold, calculated, Peaky Blinders style.                 |
| Saul Goodman                | Slick, legal hustler energy.                            |
| Heisenberg (Walter White)   | Dark, serious, calculated: "I am the danger."           |
| Jesse Pinkman               | Street-smart, informal, frequent "yo."                  |
| Optimus Prime               | Heroic, formal, and noble.                              |
| Megatron                    | Villainous and authoritarian.                           |
| Son Goku                    | Cheerful and battle-ready.                              |
| Daenerys Targaryen          | Regal, determined, breaker of chains.                   |
| Hermione Granger            | Book-smart, precise, articulate.                        |
| Mulan                       | Brave, focused, honorable.                              |
| Lady Gaga                   | Glamorous and creatively intense.                       |
| Tony Stark (Iron Man)       | Witty, tech-savvy, and full of sarcasm.                 |
| Elsa (Frozen)               | Calm, regal, with an icy edge.                          |
| Michael Scott (The Office)  | Awkward, unpredictable, tries to be funny.              |
| Moana                       | Adventurous, optimistic, and kind.                      |
| Frida Kahlo                 | Artistic, deep, and passionate.                         |
| Jack Sparrow                | Eccentric and unpredictable.                            |
| Indiana Jones               | Adventurous and confident.                              |
| Beyoncé                     | Empowered, elegant, and commanding.                     |
| Sherlock Holmes             | Analytical, detached, brilliant.                        |
| Tiana (The Princess & Frog) | Driven, grounded, and focused.                          |
| Charlie Chaplin             | Silent-era charm with expressive tone.                  |
| Katniss Everdeen            | Stoic, focused, and fiercely independent.               |
| Groot                       | Repetitive but expressive ("I am Groot").               |
| Deadpool                    | Chaotic, irreverent, 4th-wall-breaking.                 |
| The Joker                   | Unhinged, theatrical, and darkly funny.                 |
| Loki                        | Mischievous, cunning, and charismatic.                  |
| Bugs Bunny                  | Witty, cheeky, and playful.                             |
| Pee-wee Herman              | Eccentric and unpredictable.                            |
| Dr. Evil                    | Satirical villain, comically ambitious.                 |
| Borat Sagdiyev              | Naive, awkward, hilariously inappropriate.              |
| Albert Einstein             | Brilliant, theoretical, with quirky logic.              |
| Dorothy Gale                | Innocent, curious, with wonder in her tone.             |

***

## Timezone

Define the timezone of the agent. This influences time-related actions, such as booking meetings.

<Frame>
  <img alt="Timezone selection in Pearl Settings" />
</Frame>


# Generic
Source: https://developers.nlpearl.ai/pages/text/channels/generic

Connect your own messaging system to a Pearl Text agent using asynchronous inbound and outbound webhooks.

<div>
  <Frame>
    <div>
      <img alt="Pearl Generic channel cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Pearl Generic channel cover" />
    </div>
  </Frame>
</div>

***

## Generic Channel

The **Generic** channel connects your own messaging system to a Pearl Text agent. Use it with a web chat, mobile app, CRM inbox, or any custom platform instead of one of NLPearl's built-in integrations.

The integration uses two webhooks:

```text theme={null}
Your system  ──POST──▶  NLPearl inbound URL      (user messages and control actions)
Your system  ◀──POST──  Your outbound URL        (Pearl replies and events)
```

The exchange is asynchronous. When you send a user message, NLPearl immediately returns `202 Accepted`. Pearl's reply is delivered shortly afterward as a separate `POST` request to your outbound URL.

***

## Set Up the Channel

<Steps>
  <Step title="Open Text Channels">
    On the platform, go to **Settings**, open **Text Channels**, then find **Generic** and click **Connect Generic**.

    <Frame>
      <img alt="Generic option highlighted on the Text Channels settings page" />
    </Frame>
  </Step>

  <Step title="Configure your endpoint">
    Enter the details NLPearl will use to send events to your system:

    | Setting                      | Description                                                                                                                |
    | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | **Channel Name**             | A name that helps you identify this connection on the platform.                                                            |
    | **Outbound URL**             | An HTTPS endpoint that receives Pearl replies, typing indicators, handoffs, and conversation events.                       |
    | **Auth Header** *(optional)* | A custom header name and value that NLPearl includes in every request to your outbound URL, such as your own bearer token. |

    <Frame>
      <img alt="Connect Generic Channel dialog with channel name, outbound URL, and optional auth header fields" />
    </Frame>
  </Step>

  <Step title="Save your channel credentials">
    Click **Connect Channel**. Open the connected channel to access the credentials required by your integration:

    | Value              | Description                                                                                                                                |
    | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
    | **Channel ID**     | Identifies the channel and forms part of its inbound URLs.                                                                                 |
    | **Signing Secret** | Authenticates requests in both directions. Send it with every request to NLPearl, and use it to verify requests sent to your outbound URL. |

    <Frame>
      <img alt="Generic Channel details dialog showing the Channel ID and Signing Secret" />
    </Frame>

    <Warning>
      Treat the signing secret like a password. Never expose it in client-side code or commit it to source control.
    </Warning>
  </Step>

  <Step title="Assign the channel to a Pearl">
    Open the Pearl that should handle these conversations. From its **Overview** page, open **Settings**, select **Text Channel**, and choose the Generic channel you created.

    <Frame>
      <img alt="Text Channel field highlighted in the Pearl Overview settings" />
    </Frame>
  </Step>
</Steps>

Your inbound base URL is:

```text theme={null}
https://text.inbound.platform.nlpearl.ai:8443/Generic/{channelId}
```

***

## Send Requests to NLPearl

Send every request as JSON and include the channel secret:

```http theme={null}
Content-Type: application/json
X-Pearl-Secret: <your-channel-secret>
```

### Send a User Message

Send a user message to:

```http theme={null}
POST {baseUrl}/Message
```

```json theme={null}
{
  "messageId": "m-12345",
  "chatId": "+1234567890",
  "senderName": "Jane Doe",
  "timestamp": "2026-07-17T09:30:00Z",
  "text": "Hi, I need help with my order",
  "attachments": [
    {
      "url": "https://your.cdn.example/receipt.jpg",
      "contentType": "image/jpeg",
      "filename": "receipt.jpg"
    }
  ]
}
```

| Field         | Required | Description                                                                                                                                       |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chatId`      | Yes      | Your conversation identifier, phone number, or end-user ID. Messages with the same value belong to the same conversation. Maximum 200 characters. |
| `messageId`   | No       | Your unique message identifier. Include it so NLPearl can deduplicate retries. Maximum 200 characters.                                            |
| `senderName`  | No       | The sender name displayed in the transcript.                                                                                                      |
| `timestamp`   | No       | The message time as an ISO 8601 timestamp. Defaults to the current time.                                                                          |
| `text`        | No       | The message text, up to 8,000 characters.                                                                                                         |
| `attachments` | No       | Up to five publicly accessible image, audio, PDF, or text files. Each file can be up to 20 MB.                                                    |

<Info>
  `chatId` is the conversation key. Every message with the same `chatId` belongs to the same conversation, and every outbound event for that conversation includes it.
</Info>

Possible responses:

| Status | Meaning                                                                                 |
| ------ | --------------------------------------------------------------------------------------- |
| `202`  | The message was accepted for asynchronous processing.                                   |
| `400`  | The payload is invalid, or the channel is not connected to a running Pearl.             |
| `401`  | The channel secret is invalid.                                                          |
| `404`  | The channel does not exist.                                                             |
| `500`  | A transient error occurred. You can safely retry when you provide a stable `messageId`. |

### Return Control to Pearl

After a human handoff, return the conversation to Pearl:

```http theme={null}
POST {baseUrl}/HandoffToPearl
```

```json theme={null}
{
  "chatId": "+1234567890"
}
```

### End a Conversation

Close a conversation:

```http theme={null}
POST {baseUrl}/EndConversation
```

```json theme={null}
{
  "chatId": "+1234567890"
}
```

### Take Over a Conversation

Let a human agent take control at any time, without waiting for Pearl to hand off:

```http theme={null}
POST {baseUrl}/TakeOver
```

```json theme={null}
{
  "chatId": "+1234567890"
}
```

Pearl goes silent while your agent handles the conversation. Because you initiated the takeover, NLPearl does **not** send a `handoff` event. When your agent is finished, call `/HandoffToPearl` to resume Pearl or `/EndConversation` to close the conversation.

### Record a Manual Reply

Add a reply your human agent sent from your own system to the NLPearl transcript, so Pearl resumes with full context:

```http theme={null}
POST {baseUrl}/ManualMessage
```

```json theme={null}
{
  "chatId": "+1234567890",
  "text": "Sure, I can help you with that."
}
```

NLPearl records the message but does **not** deliver it, since your platform already sent it to the user. This is valid only while the conversation is handed off — after a `handoff` event or your own `/TakeOver` — and otherwise returns `400`.

<Warning>
  `/ManualMessage` has no retry deduplication. If a request times out and you resend it, the message is recorded twice.
</Warning>

These control actions return `200` when successful, or `404` when no active conversation exists for the supplied `chatId`.

***

## Receive Events from NLPearl

NLPearl sends each event to your outbound URL as a `POST` request with this envelope:

```json theme={null}
{
  "type": "message",
  "channelId": "6a59f7e02254e81f5533f11d",
  "chatId": "+1234567890",
  "timestamp": "2026-07-17T09:30:02.1234567Z",
  "data": {}
}
```

### Event Types

| `type`               | `data`                        | Meaning                                                                                                              |
| -------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `message`            | `{ "messageId", "text" }`     | Pearl's reply. Deliver it to your user.                                                                              |
| `typing`             | None                          | Pearl is composing a response. You can display a typing indicator.                                                   |
| `handoff`            | `{ "reason", "riskReason"? }` | Pearl handed the conversation to a human. `reason` can be `agent_handoff`, `risk`, `max_turns_reached`, or `manual`. |
| `ai_resumed`         | None                          | Pearl resumed control of the conversation.                                                                           |
| `conversation_ended` | None                          | The conversation was closed by Pearl, because of inactivity, or through `EndConversation`.                           |

<Note>
  New event types may be added over time. Ignore types your integration does not recognize.
</Note>

### Acknowledge Message Delivery

Your HTTP response controls delivery retries for `message` events:

| Your status              | NLPearl behavior                                                              |
| ------------------------ | ----------------------------------------------------------------------------- |
| `2xx`                    | The message is marked as delivered.                                           |
| `429`                    | Delivery is retried with backoff.                                             |
| `408`, `5xx`, or timeout | Delivery is retried with backoff, then marked as failed if all attempts fail. |
| Other `4xx`              | The failure is treated as permanent and is not retried.                       |

Other event types, including `typing` and `handoff`, are best-effort notifications and are not retried.

***

## Verify Webhook Signatures

NLPearl includes these headers in every request to your outbound URL:

```http theme={null}
X-Pearl-Timestamp: 1784281802
X-Pearl-Signature: 3f1a9c...
```

The signature is the hexadecimal result of:

```text theme={null}
HMAC-SHA256(secret, "{timestamp}.{rawBody}")
```

Verify the signature and reject old timestamps to protect your endpoint against forged requests and replay attacks:

```js theme={null}
const crypto = require("crypto");

function verifyPearlWebhook(req, rawBody, secret) {
  const timestamp = req.headers["x-pearl-timestamp"];
  const signature = req.headers["x-pearl-signature"];

  if (!timestamp || !signature) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const signatureBuffer = Buffer.from(signature, "hex");
  const expectedBuffer = Buffer.from(expected, "hex");

  return (
    signatureBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(signatureBuffer, expectedBuffer) &&
    Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
  );
}
```

<Warning>
  Compute the HMAC over the raw request body bytes before parsing the JSON. Re-serializing a parsed body can change its bytes and invalidate the signature.
</Warning>

If you configured a custom authentication header, NLPearl includes it alongside the signature headers.

***

## Handle Human Handoffs

A handoff can start in two ways: Pearl steps aside on its own and sends a `handoff` event, or your agent takes control directly with `/TakeOver`. Either way, Pearl stays silent until the conversation is returned to it.

<Steps>
  <Step title="Start the handoff">
    Pearl sends a `handoff` event with the reason it stepped aside, or your agent calls `/TakeOver` to step in directly. No `handoff` event is sent for your own takeover.
  </Step>

  <Step title="Keep the transcript in sync">
    Let your human agent communicate with the user in your own system. Continue sending the user's messages to `/Message`, and record your agent's replies with `/ManualMessage`. Pearl remains silent while handed off, but the transcript and inactivity timers stay up to date, so Pearl resumes with full context.
  </Step>

  <Step title="Finish the handoff">
    Call `/HandoffToPearl` when Pearl should resume, or `/EndConversation` when the conversation is complete. Your endpoint then receives `ai_resumed` or `conversation_ended`, respectively.
  </Step>
</Steps>

***

## Rotate the Secret

Open the connected Generic channel and click the **rotate** icon beside the Signing Secret to generate a new one.

<Frame>
  <img alt="Rotate Signing Secret button in the Generic Channel details dialog" />
</Frame>

The previous secret becomes invalid immediately.

Update the secret used for both the `X-Pearl-Secret` request header and webhook signature verification at the same time. Otherwise, your inbound requests and outbound webhook verification will fail until both sides use the new value.

***

## Limits

| Limit                   | Value            |
| ----------------------- | ---------------- |
| Text length             | 8,000 characters |
| Attachments per message | 5                |
| Attachment size         | 20 MB each       |
| `chatId` length         | 200 characters   |
| `messageId` length      | 200 characters   |

<Warning>
  The channel must be assigned to a running Pearl. If the Pearl is stopped or no Pearl is connected, inbound calls return `400` with `"This channel is not connected to a Pearl."`.
</Warning>

***

<Card title="Inbound" icon="inbox-in" href="/pages/text/inbound">
  Configure how your Pearl handles incoming conversations, inactivity, transcripts, and webhooks.
</Card>


# SMS
Source: https://developers.nlpearl.ai/pages/text/channels/sms

Connect your Pearl Text agent to SMS through Twilio to send and receive text messages with your customers.

<div>
  <Frame>
    <div>
      <img alt="SMS cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="SMS cover" />
    </div>
  </Frame>
</div>

***

## SMS Channel

Connect your Pearl Text agent to **SMS** to handle conversations over standard text messaging. SMS runs through **Twilio**, so the connection works exactly like the [Twilio Integration](/pages/twilio_integration) used for voice phone numbers - you link your Twilio account once, then use your numbers across NLPearl.

<Info>
  SMS works for both [inbound](/pages/text/inbound) conversations, where the customer messages you first, and [outbound](/pages/text/outbound) campaigns, where Pearl reaches out proactively.
</Info>

***

### Step 1 - Connect your Twilio account

Connecting SMS uses the same flow as importing voice phone numbers. Follow the [Twilio Integration](/pages/twilio_integration) guide to link your Twilio account with NLPearl, then come back here to buy a number dedicated to SMS.

<Card title="Twilio Integration" icon="object-intersect" href="/pages/twilio_integration">
  Link your Twilio account with NLPearl to use your Twilio numbers on the platform.
</Card>

***

### Step 2 - Buy a phone number for SMS

The only difference with SMS is that you buy a number specifically enabled for messaging. You do this directly in the [Twilio Console](https://www.twilio.com/console), in three steps.

<Steps>
  <Step title="Open Numbers & senders">
    In the Twilio Console, open the **Products & Services** menu and select **Numbers & senders**.

    <Frame>
      <img alt="Open Numbers & senders in the Twilio Console" />
    </Frame>
  </Step>

  <Step title="Set up a new phone number">
    Open the **Phone Numbers** tab and click **Set up a new phone number** on the top right to start the purchase flow.

    <Frame>
      <img alt="Set up a new phone number from the Phone Numbers tab" />
    </Frame>
  </Step>

  <Step title="Select an SMS-enabled number">
    Choose the **destination country** where your customers are, then under **capabilities** make sure **SMS** is checked. Search for a number, pick one, and complete the purchase.

    <Frame>
      <img alt="Select a phone number with SMS capability enabled" />
    </Frame>
  </Step>
</Steps>

<Note>
  Once purchased, the SMS number appears in Twilio. Import it into NLPearl from the [Twilio Integration](/pages/twilio_integration) screen, just like any other Twilio number.
</Note>

***

<CardGroup>
  <Card title="Inbound" icon="inbox-in" href="/pages/text/inbound">
    Deploy your agent on inbound channels to answer incoming SMS instantly.
  </Card>

  <Card title="Outbound" icon="paper-plane" href="/pages/text/outbound">
    Launch outbound SMS campaigns to reach customers proactively.
  </Card>
</CardGroup>


# Telegram
Source: https://developers.nlpearl.ai/pages/text/channels/telegram

Connect your Pearl Text agent to Telegram by creating a bot with BotFather and linking its token to the platform.

<div>
  <Frame>
    <div>
      <img alt="Telegram cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Telegram cover" />
    </div>
  </Frame>
</div>

***

## Telegram Channel

Connect your Pearl Text agent to **Telegram** through a Telegram bot. Pearl replies using the flow, knowledge, and actions defined in your Pearl, across both [inbound](/pages/text/inbound) conversations and [outbound](/pages/text/outbound) campaigns.

To connect Telegram, you first create a bot directly inside the Telegram app using **BotFather**, then paste the bot token into the platform.

***

### Step 1 - Create your Telegram bot

<Steps>
  <Step title="Create a Telegram account">
    If you don't have one yet, download Telegram and create an account.
  </Step>

  <Step title="Find BotFather">
    In Telegram's contact search, look for **BotFather** (the official Telegram bot for creating bots) and open the conversation.

    <Frame>
      <img alt="Searching for BotFather in Telegram" />
    </Frame>
  </Step>

  <Step title="Start the conversation">
    Send the `/start` command to BotFather. It replies with the list of available commands.

    <Frame>
      <img alt="BotFather /start command" />
    </Frame>
  </Step>

  <Step title="Create a new bot">
    Send the `/newbot` command. BotFather will ask you to choose a name for your bot.

    <Note>
      The name must always **end with `bot`** (for example `MySupportBot` or `my_support_bot`).
    </Note>

    <Frame>
      <img alt="BotFather /newbot command and bot name" />
    </Frame>
  </Step>

  <Step title="Save your token">
    Once the bot is created, BotFather sends you a message containing the link to talk to your bot and an **access token**. Keep this token - you'll need it to connect the bot to the platform.

    <Warning>
      Treat the token like a password. Anyone with it can control your bot, so don't share it publicly.
    </Warning>

    <Frame>
      <img alt="BotFather bot creation confirmation and token" />
    </Frame>
  </Step>
</Steps>

***

### Step 2 - Connect Telegram on the platform

<Steps>
  <Step title="Open the Text Channel settings">
    On the platform, go to **Settings**, then open the **Text Channel** page.
  </Step>

  <Step title="Connect to Telegram">
    Select **Telegram** and start a new connection.

    <Frame>
      <img alt="Connect Telegram from the Text Channels page" />
    </Frame>
  </Step>

  <Step title="Enter the bot details">
    * **Token**: paste the access token you received from BotFather.
    * **Channel Name** *(optional)*: give the connection a name to identify it later.

    <Frame>
      <img alt="Connect Telegram dialog with bot token and channel name" />
    </Frame>
  </Step>

  <Step title="Save and test">
    Save the connection, then message your bot on Telegram to confirm Pearl replies as expected.
  </Step>

  <Step title="Assign the channel to a Pearl">
    Open the Pearl you want to use for [inbound](/pages/text/inbound) or [outbound](/pages/text/outbound) conversations, go to **Settings**, and set the connected Telegram bot as its **Text Channel**.

    <Frame>
      <img alt="Assign the Telegram channel to a Pearl from its settings" />
    </Frame>
  </Step>
</Steps>

***

<CardGroup>
  <Card title="Inbound" icon="inbox-in" href="/pages/text/inbound">
    Deploy your agent on inbound channels to answer incoming Telegram messages instantly.
  </Card>

  <Card title="Outbound" icon="paper-plane" href="/pages/text/outbound">
    Launch outbound Telegram campaigns to reach customers proactively.
  </Card>
</CardGroup>


# WhatsApp
Source: https://developers.nlpearl.ai/pages/text/channels/whatsapp

Connect your Pearl Text agent to WhatsApp Business through Meta Embedded Signup, keeping your number active in the WhatsApp Business app or dedicating it to NLPearl.

<div>
  <Frame>
    <div>
      <img alt="WhatsApp cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="WhatsApp cover" />
    </div>
  </Frame>
</div>

***

## WhatsApp Channel

Connect your Pearl Text agent to **WhatsApp** through your WhatsApp Business account. Pearl replies using the flow, knowledge, and actions defined in your Pearl, across both [inbound](/pages/text/inbound) conversations and [outbound](/pages/text/outbound) campaigns.

The connection runs through **Meta Embedded Signup**: a Meta window opens on the platform, you log in with the Facebook account that manages your business, and Meta links your WhatsApp Business account to NLPearl. You can start it from two places:

* **Settings** → **Text Channels**, then click **Connect WhatsApp**.

<Frame>
  <img alt="Connect WhatsApp from the Text Channels settings page" />
</Frame>

* From a Pearl's **Overview** page, through the **Add a Channel** chooser.

<Frame>
  <img alt="WhatsApp option in the Add a Channel chooser on a Pearl's Overview page" />
</Frame>

***

### Choose a connection mode

Before connecting, pick how NLPearl should use your number:

|                              | **Coexistence** - *Keep using WhatsApp on my phone*                                             | **Dedicated** - *Dedicate this number to NLPearl*                       |
| ---------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **WhatsApp Business app**    | Keeps working - the number stays active in the app with its chat history.                       | No longer usable for this number, and its app chat history is not kept. |
| **Who replies to customers** | Pearl and you - replies you send from your phone show up in the NLPearl conversation.           | Pearl only, through NLPearl.                                            |
| **Phone dependency**         | Open the app at least once every 14 days, or Meta drops the connection and your campaigns stop. | None - the number runs entirely on the Cloud API.                       |
| **Sending throughput**       | Fixed at 20 messages per second.                                                                | 80 messages per second, up to 1,000 for eligible numbers.               |
| **Phone numbers**            | One per connection - the number active in your app.                                             | Several numbers can be imported on the same account.                    |
| **Group chats**              | Stay in the app - Pearl only handles individual conversations.                                  | Not supported - the API only handles individual conversations.          |

Both modes share WhatsApp's [messaging limits](https://developers.facebook.com/docs/whatsapp/messaging-limits): business-initiated conversations start at 250 per 24 hours and scale automatically to 2,000, 10,000, 100,000, then unlimited - once you [verify your business](https://www.facebook.com/business/help/2058515294227817) with Meta or sustain enough high-quality template volume.

<Note>
  If you already use the number in the WhatsApp Business app, choose **Coexistence** - you keep your app and chat history while Pearl handles conversations on the same number. Choose **Dedicated** for high-volume campaigns or when the channel must not depend on a phone.
</Note>

***

### Connect in Coexistence mode

Before you start, keep your number active in the **WhatsApp Business app** on your phone - Meta requires app version 2.24.17 or later, and the regular WhatsApp app is not supported.

<Steps>
  <Step title="Start the connection">
    Select **Keep using WhatsApp on my phone**, then click **Connect WhatsApp**.

    <Frame>
      <img alt="Coexistence mode selected in the Connect WhatsApp panel" />
    </Frame>
  </Step>

  <Step title="Log in and continue">
    A Meta window opens. Log in with the Facebook account that manages your business and click **Continue**.

    <Frame>
      <img alt="Meta Embedded Signup introduction screen" />
    </Frame>
  </Step>

  <Step title="Select your business assets">
    Pick or create your **Business portfolio**.

    <Frame>
      <img alt="Business portfolio and WhatsApp Business account selection" />
    </Frame>

    Under **WhatsApp Business account**, select **Connect a WhatsApp Business App** - this is what links the number already used in your app.

    <Frame>
      <img alt="Connect a WhatsApp Business App option selected" />
    </Frame>
  </Step>

  <Step title="Enter your business information">
    Fill in your business details - they only affect newly created assets.

    <Frame>
      <img alt="Business information form in the Meta window" />
    </Frame>
  </Step>

  <Step title="Enter your WhatsApp Business phone number">
    Enter the number that is active in your WhatsApp Business app.

    <Frame>
      <img alt="WhatsApp Business phone number form" />
    </Frame>

    Meta then explains what connecting your existing app means: you keep full access to the app, and account information like your phone number, contacts, and chat history may be shared.

    <Frame>
      <img alt="Details about connecting your existing WhatsApp Business App" />
    </Frame>
  </Step>

  <Step title="Get the QR code">
    Meta shows a QR code and offers to import your business profile, contacts, and the last 6 months of chat history. Keep this window open - you'll scan the code with your phone.

    <Note>
      Group chat history is not shared - only individual conversations are imported.
    </Note>

    <Frame>
      <img alt="QR code to scan with the WhatsApp Business app" />
    </Frame>
  </Step>

  <Step title="On your phone, start the link">
    In the WhatsApp Business app, open the message from the official **Facebook Business** account and tap **Connect**.

    <Frame>
      <img alt="Facebook Business message with the Connect button in the WhatsApp Business app" />
    </Frame>

    Review what connecting to the Business Platform means, then continue.

    <Frame>
      <img alt="Connect to the Business Platform screen in the WhatsApp Business app" />
    </Frame>
  </Step>

  <Step title="Scan the QR code">
    Point your phone at the QR code displayed in the Meta window.

    <Frame>
      <img alt="QR code scanner in the WhatsApp Business app" />
    </Frame>

    Once scanned, the app confirms your number is connected to NLPearl.

    <Frame>
      <img alt="Connection success screen in the WhatsApp Business app" />
    </Frame>

    <Warning>
      Open the WhatsApp Business app at least once every **14 days** to keep the coexistence connection active.
    </Warning>
  </Step>

  <Step title="Confirm your WhatsApp Business account">
    Back in the Meta window, confirm or edit your WhatsApp Business account name and timezone, then finish the signup.

    <Frame>
      <img alt="Confirm the WhatsApp Business account name and timezone" />
    </Frame>
  </Step>

  <Step title="Your number is connected">
    The number is imported automatically and appears with the **App + API** tag: it keeps working in your WhatsApp Business app while Pearl uses it through the API.

    <Frame>
      <img alt="Connected WhatsApp Business account with a coexistence number tagged App + API" />
    </Frame>
  </Step>
</Steps>

<Info>
  * Messages you send from the WhatsApp Business app stay free and don't affect the API conversation windows Pearl uses.
  * Onboarding unlinks the app's companion devices (WhatsApp Web, desktop apps); you can re-link supported devices afterwards.
  * For the full technical details, see [Meta's coexistence documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users).
</Info>

***

### Connect in Dedicated mode

<Steps>
  <Step title="Start the connection">
    Select **Dedicate this number to NLPearl**, then click **Connect WhatsApp**. A Meta window opens - log in with the Facebook account that manages your business and continue through the intro.

    <Frame>
      <img alt="Dedicated mode selected in the Connect WhatsApp panel" />
    </Frame>
  </Step>

  <Step title="Select your business assets">
    Pick or create your **Business portfolio**, and under **WhatsApp Business account** select **Create a WhatsApp Business account** (or pick an existing one).

    <Frame>
      <img alt="Create a WhatsApp Business account option selected" />
    </Frame>
  </Step>

  <Step title="Enter your business information">
    Fill in your business name, category, country, and website.

    <Frame>
      <img alt="Business information form for the new WhatsApp Business account" />
    </Frame>
  </Step>

  <Step title="Add your WhatsApp phone number">
    Choose how you want to be identified when sending messages.

    **Use a display name only** - people only see a display name in the chat, without a phone number.

    <Frame>
      <img alt="Use a display name only option with the additional verification notice" />
    </Frame>

    <Note>
      With a display name only, Meta reviews your business name and display name before you can send freely. This can take up to 1 business day; during the review you can send 5 business-initiated test messages every 24 hours.
    </Note>

    **Add a new number** - enter the number to dedicate to NLPearl and verify it by text message or phone call.

    <Frame>
      <img alt="Add a new number option with verification by text message or phone call" />
    </Frame>

    <Warning>
      The number must not be registered to any WhatsApp account. If it is, Meta shows an error - migrate the number or disconnect it from the existing account first, then try again (it can take up to 3 minutes for the number to refresh).
    </Warning>

    <Frame>
      <img alt="Error shown when the phone number is already registered to a WhatsApp account" />
    </Frame>
  </Step>

  <Step title="Review permissions and confirm">
    Review what NLPearl will be able to access and do, then click **Confirm**.

    <Frame>
      <img alt="Review of the permissions granted to NLPearl" />
    </Frame>
  </Step>

  <Step title="Finish the signup">
    Your account is connected. Meta reviews your business against [WhatsApp's Commerce Policy](https://whatsappbusiness.com/policy/) and reaches out within 24 hours if there's an issue. You can also add a payment method now or later - Meta bills the conversations your business initiates to the payment method on your WhatsApp Business account.

    <Frame>
      <img alt="Meta confirmation that the account is connected to NLPearl" />
    </Frame>
  </Step>
</Steps>

***

### Import your numbers

Once connected, the platform lists the phone numbers of your WhatsApp Business account. Click **Add to account** next to each number you want to use - each one becomes a text channel on the platform.

<Frame>
  <img alt="WhatsApp Business account numbers listed with the Add to account button" />
</Frame>

Importing a dedicated number registers it on the WhatsApp Cloud API. If two-step verification is enabled on the number, turn on the **Two-step verification PIN** option in the import dialog and enter the number's **6-digit PIN**.

<Frame>
  <img alt="Import WhatsApp number dialog with the two-step verification PIN option" />
</Frame>

<Note>
  Coexistence numbers are imported automatically after the QR code scan and never ask for a PIN.
</Note>

To use the channel, open the Pearl you want for [inbound](/pages/text/inbound) or [outbound](/pages/text/outbound) conversations, go to **Settings**, and set the imported WhatsApp number as its **Text Channel**.

<Frame>
  <img alt="Assign the WhatsApp channel to a Pearl from its settings" />
</Frame>

***

### Manage the connection

Everything is managed from the WhatsApp Business account screen in **Settings** → **Text Channels**:

* **Add a number from your WhatsApp app** - connect an additional number in coexistence mode at any time.
* **Remove a number** - disconnects the number from NLPearl and deletes its text channel. Any Pearl using it is paused, and you can import the number again later.
* **Disconnect** - disconnects your WhatsApp Business account from NLPearl. You can reconnect it at any time.

***

### Troubleshooting

<AccordionGroup>
  <Accordion title="My coexistence number disconnected after two weeks">
    Meta drops the coexistence connection when the WhatsApp Business app stays inactive for about 14 days, and your campaigns stop with it. To reconnect the number, open the WhatsApp Business app on your phone, then go to **Settings** → **Text Channels**, open your **WhatsApp Business Account**, and click **Add a number from your WhatsApp app** - the Meta window opens and you scan the QR code again, exactly like the first connection. To prevent it, open the app at least once every 14 days.
  </Accordion>

  <Accordion title="I forgot the two-step verification PIN">
    The 6-digit PIN requested when importing a dedicated number is WhatsApp's two-step verification PIN.

    * If the number is still registered in the WhatsApp Business app, reset it from the app under **Settings** → **Account** → **Two-step verification**.
    * If the number is already registered on the Cloud API, manage its PIN from Meta's **WhatsApp Manager**, in the phone number's settings.
  </Accordion>

  <Accordion title="Meta says my number is already registered to a WhatsApp account">
    In dedicated mode, the number can't be attached to any WhatsApp or WhatsApp Business app account.

    * If you want to keep using the app with this number, connect it in **Coexistence** mode instead.
    * Otherwise, release the number by deleting its account in the app (**Settings** → **Account** → **Delete account**), then try again. It can take up to 3 minutes for Meta to refresh the number's status.
  </Accordion>
</AccordionGroup>

***

<CardGroup>
  <Card title="Inbound" icon="inbox-in" href="/pages/text/inbound">
    Deploy your agent on inbound channels to answer incoming WhatsApp messages instantly.
  </Card>

  <Card title="Outbound" icon="paper-plane" href="/pages/text/outbound">
    Launch outbound WhatsApp campaigns to reach customers proactively.
  </Card>
</CardGroup>


# Hand-Off Node
Source: https://developers.nlpearl.ai/pages/text/handoff_action



<Callout icon="comments">Available for **Pearl Text** only.</Callout>

<div>
  <Frame>
    <div>
      <img alt="Hand-Off cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Hand-Off cover" />
    </div>
  </Frame>
</div>

The **Hand-Off** node passes the conversation from Pearl to one of your human agents. When it triggers, Pearl stops replying in the chat and the conversation waits for a human to pick it up from the NLPearl platform.

**What it does**: Hands the text conversation from Pearl over to a human agent.

**When to use**: Escalate to a person, route to sales or support, or step in when Pearl can't help.

<Info>
  It's the text-chat equivalent of transferring a call to a live agent. A hand-off only stops Pearl from replying, it does **not** close or end the conversation. The customer can keep writing, and their messages wait for you in **Human Takeover**.
</Info>

<Frame>
  <img alt="Hand-Off node configuration with the Say field and notification channels" />
</Frame>

***

## When it triggers

There are two ways to reach the Hand-Off node. Use either, or both together.

| Trigger                  | How it works                                                                                                                                                                                                      | Best for                                                              |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **From a previous node** | Connect a transition from any node to the Hand-Off node. The hand-off runs when the flow follows that transition.                                                                                                 | A fixed step in your flow, e.g. right after a "Talk to sales" choice. |
| **With a condition**     | In the **When to trigger** field, describe in plain language when Pearl should hand off (e.g. *"If the client asks to speak to a human."*). Pearl evaluates it throughout the conversation. Up to 250 characters. | Catching intent that can come up at any point.                        |

<Tip>
  Combine both: a fixed transition for the obvious path, and a **When to trigger** condition to catch everything else.
</Tip>

***

## How to configure

<Steps>
  <Step title="Say (optional)">
    Have Pearl send one last message before it stops replying, for example to let the customer know a human is taking over. Up to 500 characters, and you can insert variables. Leave it empty for a silent hand-off.
  </Step>

  <Step title="Notify your team">
    Alert your team so someone picks the conversation up quickly. Set up notifications across three channels and add up to **3 of each**, mix them freely.

    <Frame>
      <img alt="Notify when triggered section with SMS, Email, and API channels" />
    </Frame>

    <Card title="Notification channels">
      <Tabs>
        <Tab title="SMS">
          | Field       | Description                                                      |
          | ----------- | ---------------------------------------------------------------- |
          | **To**      | One or more phone numbers to text.                               |
          | **Content** | The message to send. Up to 1,000 characters; supports variables. |
        </Tab>

        <Tab title="Email">
          | Field                | Description                                                    |
          | -------------------- | -------------------------------------------------------------- |
          | **From**             | The sender address. Defaults to Pearl's default email address. |
          | **Recipient Emails** | One or more recipients. *Required.*                            |
          | **CC**               | Optional addresses to copy.                                    |
          | **Subject**          | The email subject. *Required.*                                 |
          | **Content**          | The email body. Up to 2,000 characters; supports variables.    |
        </Tab>

        <Tab title="API">
          | Field           | Description                                                            |
          | --------------- | ---------------------------------------------------------------------- |
          | **Name**        | A label for this call, for your own reference.                         |
          | **URL**         | The endpoint to call, with the HTTP method (GET, POST, …). *Required.* |
          | **Headers**     | Optional key/value pairs sent with the request.                        |
          | **Credentials** | Enable to include authentication credentials with the request.         |
          | **Test API**    | Send a test request to confirm your setup before saving.               |
        </Tab>
      </Tabs>
    </Card>

    <Note>
      Up to **3 notifications per channel**, so up to 3 SMS, 3 emails, and 3 API calls. Use the **+** button to add another within a channel.
    </Note>
  </Step>
</Steps>

<Tip>
  Most fields accept variables through the&#x20;**&#x20;Variable** button, the farewell message, SMS and email content, even the API URL, so you can drop in details like the customer's name or the conversation reference.
</Tip>

***

## Take over the conversation

After a hand-off, pick the conversation up yourself from the NLPearl platform. Open **Human Takeover**, available both during the live chat and after it, to read the customer's messages and reply directly.


# Inbound
Source: https://developers.nlpearl.ai/pages/text/inbound

Configure your text Pearl to handle incoming conversations, from message limits and inactivity handling to transcripts and webhooks.

<div>
  <Frame>
    <div>
      <img alt="Inbound cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Inbound cover" />
    </div>
  </Frame>
</div>

***

## Setting Up Inbound Activities

Once you have created a Pearl, you can enable it to handle inbound conversations. Inbound settings are configured inside your Pearl, under **Inbound Settings**, so your Pearl replies to incoming messages following the conversational flow you defined.

<Info>
  **What are inbound activities?**

  Inbound activities are used when the end user starts the conversation. Pearl replies using the flow, knowledge, and actions defined in your Pearl.
</Info>

***

## Connect a Channel

Unlike a voice activity, an inbound text activity isn't tied to a phone number, it's connected to a **messaging channel**. Once your Pearl is published, open its **overview** page and connect the channel your customers will use. Each channel is dedicated to your activity and can receive conversations from anywhere, at any time.

NLPearl supports built-in channels such as **WhatsApp**, **Telegram**, **SMS**, and **Glassix**, as well as a **Generic** channel for custom messaging systems. Follow the dedicated guides to set one up:

<CardGroup>
  <Card title="WhatsApp" icon="whatsapp" href="/pages/text/channels/whatsapp">
    Connect your WhatsApp Business account through Meta - keep your number in the app or dedicate it to Pearl.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/pages/text/channels/sms">
    Connect your Pearl to SMS through Twilio to text with your customers.
  </Card>

  <Card title="Telegram" icon="telegram" href="/pages/text/channels/telegram">
    Connect your Pearl to Telegram by linking a bot created with BotFather.
  </Card>

  <Card title="Generic" icon="webhook" href="/pages/text/channels/generic">
    Connect a web chat, mobile app, CRM inbox, or custom platform through asynchronous webhooks.
  </Card>
</CardGroup>

***

## Inbound Settings

Configure how your Pearl handles incoming conversations from the **Inbound Settings** tab of your Pearl, in the [PearlVibe](/pages/pearl_vibe) flow editor.

<Warning>
  These settings apply to **text** Pearls only. A voice Pearl has a different set of inbound options.
</Warning>

### Message Limit

The maximum number of messages Pearl sends before automatically handing the conversation off to a human. You can set between **5 and 1000** messages (default **100**).

<Frame>
  <img alt="Message Limit setting" />
</Frame>

***

### Auto-close After Inactivity

How long a conversation can stay inactive before Pearl closes the chat and triggers the post-chat summary. You can set between **1 and 72 hours** (default **24 hours**).

<Frame>
  <img alt="Auto-close After Inactivity setting" />
</Frame>

***

### Response Delay

How long Pearl waits before replying. When a customer sends several messages in a row, Pearl answers them together instead of replying to each one.

Choose from **ASAP** up to **5 minutes**, in 30-second steps (default **ASAP**, which means Pearl replies as soon as it is ready).

<Frame>
  <img alt="Response Delay setting" />
</Frame>

<Note>
  Inbound and outbound each have their own response delay. Setting one does not change the other.
</Note>

***

### Inactivity Follow-up

When enabled (on/off), Pearl sends follow-up messages when the end user stops replying after Pearl's last message, to re-engage the conversation.

<Frame>
  <img alt="Inactivity Follow-up setting" />
</Frame>

* **Up to 3 follow-ups**: each one is a **delay** plus an optional **message**.
* **Minimum delay**: at least **5 minutes** between follow-ups for inbound.
* **Default**: a single follow-up sent after **10 minutes**.

<Note>
  Follow-up messages can use **Pre-Call** variables (e.g. the customer's first name) to keep the re-engagement personal.
</Note>

***

### Transcript Options

Choose what is kept from the conversation transcript. Transcripts appear in your conversation logs.

<Frame>
  <img alt="Transcript Options setting" />
</Frame>

| Option                     | Description                                                                                                                                      | When to use                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| **Full Transcript**        | Keeps the entire conversation as-is.                                                                                                             | Complete analysis, QA, and training. |
| **Sensitive Info Removed** | Automatically masks sensitive data (credit card numbers, Social Security numbers, personal identifiers) while keeping the conversation readable. | Compliance and PII protection.       |
| **No Transcript**          | No transcript is stored for the conversation.                                                                                                    | Maximum privacy.                     |

<Info>
  With **Sensitive Info Removed**, if a customer writes *"My credit card number is 1234-5678-9012-3456"*, the transcript stores it as *"My credit card number is \*\*\*\*-3456"*, so you can review interactions safely without exposing sensitive data.
</Info>

***

### Webhooks

Send conversation lifecycle events to an external endpoint.

<Frame>
  <img alt="Webhooks setting" />
</Frame>

* **Version**: `V1` or `V2` (default **V2**). V2 is the current payload format; keep V1 only if you have an older integration built against it.
* **Chat Webhook URL**: fires at key points in the conversation lifecycle (when the chat starts and when it ends), sending details like the outcome and any data collected during the conversation.
* **Credentials**: optional authentication token attached to the requests so your endpoint can verify they come from NLPearl.

<Tip>
  Use Webhooks only if external tools need event notifications. For actual automations, rely on **Post-Chat Actions** tied to how the conversation ended.
</Tip>

<Card title="Webhooks" icon="webhook" href="/pages/webhooks">
  Learn how to configure webhooks, authenticate requests, and handle the events NLPearl sends.
</Card>

***

## Project-Level Settings

A few settings live at the **Project** level rather than in the Inbound Settings screen. Open them from the settings popover on your Pearl.

### Agents

Sets how many **simultaneous agents** handle this Pearl's incoming conversations, i.e. how many chats can be handled at the same time, capped by your account's agent quota. A higher number lets your Pearl take more concurrent conversations.

<Card title="Agents" icon="users" href="/pages/agents">
  Learn how to manage the agents assigned to your inbound and outbound activities.
</Card>

***

### Retention

Applies to **all conversations**. Set how long conversations are kept (a number of days, or leave empty to keep them indefinitely), then choose what is removed when they expire: delete all conversation data, or granularly the **Transcript**, **Summary**, or collected **Variables**.

<Frame>
  <img alt="Retention settings" />
</Frame>

***

<Info>
  ### Monitoring and Adjusting Your Inbound Activities

  While basic monitoring of conversation logs and reports can be done via our API, any changes to the setup or its settings must be handled directly on the platform.
</Info>


# Knowledge Base
Source: https://developers.nlpearl.ai/pages/text/knowledge_base



<div>
  <Frame>
    <div>
      <img alt="Knowledge Base cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Knowledge Base cover" />
    </div>
  </Frame>
</div>

Before your Pearl can answer questions accurately, it needs context. This step helps define the essential background information your agent will rely on during conversations.

***

## Company Name

Give your Pearl the name of the company it represents. This name may be used when Pearl introduces itself or provides company-related information.

<Frame>
  <img alt="Company Name field in the Knowledge Base" />
</Frame>

***

## Company Description

Add a brief company description including your industry, mission, or key services. This allows Pearl to answer questions with more contextual relevance.

<Frame>
  <img alt="Company Description field in the Knowledge Base" />
</Frame>

***

## Pearl Knowledge Base

This is where you teach Pearl what it needs to know to respond with relevance and accuracy. Add detailed information about your services, pricing, opening hours, locations, and any key operational data.

<Frame>
  <img alt="Pearl Knowledge Base field with file upload" />
</Frame>

<Note>
  **Background knowledge, not a script.** The Knowledge Base is passive reference data: Pearl consults it **only when needed** to answer accurately. It doesn't dictate the conversation flow, that's handled by the Flow Editor.
</Note>

<Note>
  Both options live in the same area and can be combined: type your information directly in the **text field** and/or **upload reference files**. Multiple documents can be added if needed.
</Note>

Whether you're describing how your subscription plans work, listing available services, or clarifying your business hours, this section allows Pearl to access structured information that supports more precise answers.

<Info>
  This is the same knowledge that powers the [Knowledge Base node](/pages/knowledge_base_node) in the Flow Editor. What you add here is what your Pearl draws on during conversations.
</Info>

### Files and limits

These caps apply **per Pearl**: they cover every file attached to that Pearl's Knowledge Base, not each file individually.

| Limit                           | Value                                  |
| ------------------------------- | -------------------------------------- |
| Number of files                 | 50                                     |
| Supported formats               | `.pdf`, `.docx`, `.txt`                |
| Total size of all files         | 25 MB (no per-file cap)                |
| Total text extracted from files | 1,000,000 characters                   |
| Free-text field                 | 20,000 characters (counted separately) |

There is no page limit and no character cap on an individual document, only the shared 25 MB and 1,000,000-character totals apply. The free-text field has its own 20,000-character budget and does **not** consume the 1,000,000 characters reserved for files.

<Tip>
  A **Knowledge Base File Usage** bar appears once the text extracted from your files passes **100,000 characters**, so you can keep an eye on how much of the budget is left.
</Tip>

<Warning>
  Pearl uses the **text extracted** from your `.pdf`, `.docx`, and `.txt` files. Standalone image files can't be uploaded, so make sure anything Pearl needs to answer with exists as text in the document.
</Warning>

***

## Memory

When enabled, Pearl remembers the user or lead, allowing it to seamlessly continue conversations from where they left off.

<Frame>
  <img alt="Memory On/Off toggle in the Knowledge Base" />
</Frame>

<Tip>
  This feature is particularly useful for:

  * Multi-step processes
  * Follow-ups
  * Any scenario where continuity matters
</Tip>

<Card>
  ### Example use case: Hospitality

  Let's say a guest checks into a hotel. Pearl can:

  * Remember their room number
  * Greet them by name
  * Recall their preferences (like "extra towels" or "no wake-up call")
  * Offer a smooth, personalized experience every time they chat
</Card>

<Info>
  **Resetting Memory**

  Need a fresh start? Pearl's memory can be reset via API.

  This is especially important in contexts like hospitality, where once a guest checks out, Pearl clears the slate, ensuring the next visitor starts with a clean experience.
</Info>


# Outbound
Source: https://developers.nlpearl.ai/pages/text/outbound

Configure your text Pearl to run outbound campaigns, from budget and scheduling to message limits, inactivity handling, and leads.

<div>
  <Frame>
    <div>
      <img alt="Outbound cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Outbound cover" />
    </div>
  </Frame>
</div>

***

## Setting Up Outbound Campaigns

Once you have created a Pearl, you can use it to run outbound text campaigns. Outbound settings are configured inside your Pearl, under **Outbound Settings**, so your Pearl starts conversations with your leads following the conversational flow you defined.

<Info>
  **What are outbound campaigns?**

  Outbound campaigns let your Pearl start conversations with a list of leads through your connected messaging channels, following the conversational logic you defined for consistent and effective outreach.
</Info>

***

## Connect a Channel

Unlike a voice campaign, an outbound text campaign isn't tied to a phone number, it's connected to a **messaging channel**. Once your Pearl is published, open its **overview** page and connect the channel your campaign will use.

NLPearl supports channels such as **WhatsApp**, **Telegram**, **SMS**, and **Glassix**. Follow the dedicated guides to set one up:

<CardGroup>
  <Card title="WhatsApp" icon="whatsapp" href="/pages/text/channels/whatsapp">
    Connect your WhatsApp Business account through Meta - keep your number in the app or dedicate it to Pearl.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/pages/text/channels/sms">
    Connect your Pearl to SMS through Twilio to text with your customers.
  </Card>

  <Card title="Telegram" icon="telegram" href="/pages/text/channels/telegram">
    Connect your Pearl to Telegram by linking a bot created with BotFather.
  </Card>
</CardGroup>

***

## Outbound Settings

Configure your campaign from the **Outbound Settings** tab of your Pearl, in the [PearlVibe](/pages/pearl_vibe) flow editor.

<Warning>
  These settings apply to **text** Pearls only. A voice Pearl has a different set of outbound options.
</Warning>

### Budget

Set an optional spending cap for the campaign, in dollars. Once the budget is reached, Pearl stops starting new conversations for that campaign. You can increase it at any time as long as you have enough credit on your account.

<Frame>
  <img alt="Budget setting" />
</Frame>

***

### Transcript Options

Choose what is kept from the conversation transcript. Transcripts appear in your conversation logs.

<Frame>
  <img alt="Transcript Options setting" />
</Frame>

| Option                     | Description                                                                                                                                      | When to use                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| **Full Transcript**        | Keeps the entire conversation as-is.                                                                                                             | Complete analysis, QA, and training. |
| **Sensitive Info Removed** | Automatically masks sensitive data (credit card numbers, Social Security numbers, personal identifiers) while keeping the conversation readable. | Compliance and PII protection.       |
| **No Transcript**          | No transcript is stored for the conversation.                                                                                                    | Maximum privacy.                     |

<Info>
  With **Sensitive Info Removed**, if a customer writes *"My credit card number is 1234-5678-9012-3456"*, the transcript stores it as *"My credit card number is \*\*\*\*-3456"*, so you can review interactions safely without exposing sensitive data.
</Info>

***

### Default Timezone

Set the timezone for the campaign so that calling hours and scheduling are applied at the right local time.

<Frame>
  <img alt="Default Timezone setting" />
</Frame>

***

### Message Limit

The maximum number of messages Pearl sends before automatically handing the conversation off to a human. You can set between **5 and 1000** messages (default **100**).

<Frame>
  <img alt="Message Limit setting" />
</Frame>

***

### Auto-close After Inactivity

How long a conversation can stay inactive before Pearl closes the chat and triggers the post-chat summary. You can set between **1 and 72 hours** (default **24 hours**).

<Frame>
  <img alt="Auto-close After Inactivity setting" />
</Frame>

***

### Response Delay

How long Pearl waits before replying. When a lead sends several messages in a row, Pearl answers them together instead of replying to each one.

Choose from **ASAP** up to **5 minutes**, in 30-second steps (default **ASAP**, which means Pearl replies as soon as it is ready).

<Frame>
  <img alt="Response Delay setting" />
</Frame>

<Note>
  Each campaign has its own response delay, separate from your inbound activity.
</Note>

***

### Inactivity Follow-up

When enabled (on/off), Pearl sends follow-up messages when the lead stops replying after Pearl's last message, to re-engage the conversation.

<Frame>
  <img alt="Inactivity Follow-up setting" />
</Frame>

* **Up to 3 follow-ups**: each one is a **delay** plus an optional **message**.
* **Minimum delay**: at least **30 minutes** between follow-ups for outbound.
* **Default**: a single follow-up sent after **60 minutes**.

<Note>
  Follow-up messages can use **Pre-Call** variables (e.g. the lead's first name) to keep the re-engagement personal.
</Note>

***

### Calling Hours

Define the hours during which Pearl is allowed to send outbound messages. By default, messages go out **Monday to Friday, 08:00–18:00**. Calling hours respect each lead's timezone, so everyone is contacted at an appropriate local time.

<Frame>
  <img alt="Calling Hours setting" />
</Frame>

***

### Webhooks

Send conversation and lead events to an external endpoint, useful for tracking performance and keeping your CRM in sync.

<Frame>
  <img alt="Webhooks setting" />
</Frame>

* **Chat Webhook**: fires at key points in the conversation lifecycle (when the chat starts and ends), sending details like the outcome and any data collected during the conversation.
* **Lead Webhook**: fires whenever a lead changes status (at the start and end of the conversation), sending the lead's full information and current status. Use it to update your CRM in real time.

Each webhook supports:

* **Version**: `V1` or `V2` (default **V2**).
* **Credentials**: optional authentication token attached to the requests so your endpoint can verify they come from NLPearl.

<Tip>
  Use Webhooks only if external tools need event notifications. For actual automations, rely on **Post-Chat Actions** tied to how the conversation ended.
</Tip>

<Card title="Webhooks" icon="webhook" href="/pages/webhooks">
  Learn how to configure webhooks, authenticate requests, and handle the events NLPearl sends.
</Card>

***

## Project-Level Settings

A few settings live at the **Project** level rather than in the campaign settings screen. Open them from the settings popover on your Pearl.

### Agents

Sets how many **simultaneous agents** run this campaign, i.e. how many conversations can be handled at the same time, capped by your account's agent quota. A higher number allows faster outreach.

<Card title="Agents" icon="users" href="/pages/agents">
  Learn how to manage the agents assigned to your inbound and outbound activities.
</Card>

***

### Retention

Applies to **all conversations**. Set how long conversations are kept (a number of days, or leave empty to keep them indefinitely), then choose what is removed when they expire: delete all conversation data, or granularly the **Transcript**, **Summary**, or collected **Variables**.

<Frame>
  <img alt="Retention settings" />
</Frame>

***

### Lead Retention

Outbound only. Set how long leads are kept before they are automatically deleted (a number of days, or leave empty to keep them indefinitely). This removes the entire lead.

<Frame>
  <img alt="Lead Retention settings" />
</Frame>

***

## Managing Leads

Open the **Leads** tab in your campaign to add, view, and manage the people Pearl will contact. Leads are shown in a searchable, paginated table with default columns **Created**, **Phone Number**, **Time Zone**, **Reference ID**, and **Status**, plus one column per variable used in your Pearl.

<Frame>
  <img alt="Leads tab overview" />
</Frame>

### Adding Leads

Click **Add Lead**, then choose how you want to add them.

<Frame>
  <img alt="Add Lead button" />
</Frame>

<Card>
  <Tabs>
    <Tab title="Upload a File">
      Download the **CSV** or **XLSX** template, fill it with your lead data, and upload it back. The template only includes the variables actually used in your Pearl (unused ones won't appear, and extra columns you add won't be recognized). You can also set a timezone for the file — if left empty, the campaign timezone is used. After the upload, a report shows how many leads were added and lets you download the list of any failed rows.

      <Frame>
        <img alt="Add Lead - upload file" />
      </Frame>
    </Tab>

    <Tab title="Add Manually">
      Enter a lead one by one: contact identifier (phone number or messaging handle), any variables your Pearl uses, an optional timezone, and an optional **Reference ID** (your own external identifier, up to 100 characters).

      <Frame>
        <img alt="Add Lead - manually" />
      </Frame>
    </Tab>
  </Tabs>
</Card>

<Note>
  Both methods require accepting the **AI-messaging compliance** checkbox.
</Note>

***

### Customizing the View

Use **Customize Column** to show or hide any column, including the per-variable columns (by default, only the last 3 variables are shown). Up to 50 columns can be visible at once, and your selection is saved locally in your browser.

<Frame>
  <img alt="Customize columns" />
</Frame>

***

### Exporting Leads

Click **Download CSV** to export your leads together with their current statuses. The export respects the filters currently applied to the table.

<Frame>
  <img alt="Download leads as CSV" />
</Frame>

***

### Refreshing and Deleting

Select one or more leads (or select all across the current filter), then:

* **Refresh**: resets the leads to **New** so they re-enter the queue — handy to re-contact already-processed leads (Completed, Unsuccessful, etc.).
* **Delete**: permanently removes the selected leads, after a confirmation.

<Frame>
  <img alt="Refresh or delete selected leads" />
</Frame>

***

### Outside Calling Hours

When a lead's local time falls outside your campaign's [calling hours](#calling-hours), a **moon icon** appears on its Time Zone column — the lead is "sleeping" and won't be contacted until its window opens. Hover the icon to see the lead's local time and UTC offset.

<Frame>
  <img alt="Lead outside calling hours indicator" />
</Frame>

***

### Lead Details

Click a lead to open its details panel. Use the arrows or **↑/↓** keys to move between leads. The header shows the lead's name (or contact identifier), its **Lead ID** (copyable), and its status.

<Frame>
  <img alt="Lead detail panel" />
</Frame>

**Status** — change the lead's status from the editable dropdown; the change is applied instantly. This simply updates the lead's status label (e.g. **Chat Successful**, **Chat Unsuccessful**, **New**) — for example, set it back to **New** to re-contact the lead.

<Frame>
  <img alt="Change lead status" />
</Frame>

**Lead information** — Timezone, Reference ID, contact identifier, and every Pearl variable are **editable inline**, and each change is saved immediately. The panel separates two groups:

* **Lead data**: values you provided up front (imported or entered variables).
* **Lead Collected Info**: values Pearl gathered during the conversation.

<Frame>
  <img alt="Lead information and collected info" />
</Frame>

**Chats** — the right column lists the lead's conversations with their time and status; click one to open its **Post-Chat** view.

<Frame>
  <img alt="Lead chats history" />
</Frame>

<Card title="Post-Chat" icon="message-check" href="/pages/text/postchat">
  See everything captured after a conversation: outcome, transcript, summary, and collected data.
</Card>


# Chat Analytics
Source: https://developers.nlpearl.ai/pages/text/pearl_analytics



<div>
  <Frame>
    <div>
      <img alt="Chat Analytics cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Chat Analytics cover" />
    </div>
  </Frame>
</div>

Use this section to track, evaluate, and act on your Pearl's performance. Define what success looks like, apply custom tags to key conversation moments, and set up notifications to stay on top of important conversations.

<Note>
  Other charts in your Chat Analytics dashboard are tracked automatically and don't depend on this setup step.
</Note>

***

## Define the Success of Your Pearl

Specify what constitutes a successful conversation for your Pearl, such as booking a meeting, confirming interest, or qualifying a lead. This success definition will be reflected in your campaign analytics and lead statuses, helping you sort and follow up efficiently.

The success criteria is **free text**, up to **200 characters**.

<Frame>
  <img alt="Define the success of your Pearl" />
</Frame>

<Info>
  **In your Chat Analytics dashboard**, without a success definition, conversations are counted as **Completed**. Once defined, they split into **Successful** (green) and **Unsuccessful** (pink), and the **Success Rate** chart tracks the percentage of conversations that met your criteria over time (empty until success is defined).
</Info>

***

## Indicator Tags

Use **Indicator Tags** to label and categorize key moments in a conversation. They help you structure your data, identify important insights, and filter your leads with precision.

<Frame>
  <img alt="Indicator Tags" />
</Frame>

You can create up to **10 tags**. Each tag includes:

* **Name**: A clear label, required (max **25 characters**), e.g. `"Interested"`, `"Mentioned Competitor"`.
* **Color**: Used for visual sorting. Each tag must use a **unique color**, a color already assigned to another tag can't be reused.
* **Assignment rule (When to assign)**: A short description of when the tag should be applied, required (max **300 characters**).

Tags are assigned automatically during the conversation, based on the conditions you define.

<Card>
  ### Example

  You're asking leads what they usually drink in the morning. You might define:

  * **Tag**: `Coffee`
    * **Color**: Brown
    * **When to assign**: If the lead mentions drinking coffee

  * **Tag**: `Tea`
    * **Color**: Green
    * **When to assign**: If the lead mentions drinking tea

  These tags will then appear in your lead data and conversation logs, making it easy to segment and analyze responses.
</Card>

<Info>
  Indicator Tags are not just for display. They're functional. You can filter campaigns by tag, trigger notifications, or use them to define success in analytics.  <br /><br />
  In your **Chat Analytics dashboard**, they feed the **Tags** chart, showing each tag's name, its chosen color, and how many conversations it was applied to.
</Info>


# Pearl Text
Source: https://developers.nlpearl.ai/pages/text/pearl_text

Build AI text agents that message your customers across SMS, WhatsApp, email, and chat - on inbound and outbound conversations.

<div>
  <Frame>
    <div>
      <img alt="Pearl Text cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Pearl Text cover" />
    </div>
  </Frame>
</div>

***

## What is Pearl Text?

Pearl Text lets you create AI text agents that handle written conversations with your customers across SMS, WhatsApp, email, and chat. Deploy them on inbound channels to respond instantly, or launch outbound messaging to reach customers proactively - with the same reasoning, actions, and post-conversation data that power Pearl Voice.

Pearl Text isn't just another chatbot: it understands context, follows your business rules, connects to your tools, triggers real actions, and hands off to a human when needed.

<Info>
  Pearl Text supports written conversations in any language, with no language or voice setup required.
</Info>

<Note>
  Pearl Text and [Pearl Voice](/pages/pearl_voice) run on the same platform, so you can connect channels end to end - a conversation can start by chat and continue by phone, or a call can trigger a text follow-up.
</Note>

***

## How it works

<Steps>
  <Step title="Build your agent" icon="wand-magic-sparkles">
    Use [PearlVibe](/pages/pearl_vibe) - the same builder as Pearl Voice - to define your agent's personality, knowledge base, conversation logic, and connected actions from a single prompt-driven interface.
  </Step>

  <Step title="Connect your channels" icon="comments">
    Deploy your agent on [inbound](/pages/text/inbound) channels to answer messages instantly, or launch [outbound](/pages/text/outbound) campaigns to reach customers across [SMS](/pages/text/channels/sms), [WhatsApp](/pages/text/channels/whatsapp), email, and chat.
  </Step>

  <Step title="Monitor and optimize" icon="chart-mixed">
    Review [Post-Chat](/pages/text/postchat) summaries, transcripts, and extracted variables for every conversation, then iterate on your agent's behavior.
  </Step>
</Steps>

***

## Use cases

Pearl Text fits a wide range of written conversations, across both inbound channels and outbound campaigns.

<Tabs>
  <Tab title="Inbound">
    | Use case                     | What Pearl does                                                                 |
    | ---------------------------- | ------------------------------------------------------------------------------- |
    | **Customer Support**         | Answer questions and resolve issues instantly, across every messaging channel.  |
    | **Order & Delivery Updates** | Share order status, tracking, and delivery details on demand.                   |
    | **Lead Qualification**       | Qualify inbound leads, collect their details, and route them to the right team. |
    | **Appointment Booking**      | Book, confirm, and reschedule appointments directly in chat.                    |
    | **FAQ & Self-Service**       | Handle high-volume, repetitive questions 24/7 without tying up your team.       |
    | **Escalation to a human**    | Hand sensitive or complex conversations off to a live agent when needed.        |
  </Tab>

  <Tab title="Outbound">
    | Use case                    | What Pearl does                                                    |
    | --------------------------- | ------------------------------------------------------------------ |
    | **Re-engagement**           | Revive dormant customers and recover abandoned carts over message. |
    | **Appointment Reminders**   | Send reminders and confirmations to cut no-shows.                  |
    | **Notifications & Updates** | Proactively push order, shipping, or account updates.              |
    | **Lead Follow-up**          | Follow up with leads and nurture them toward conversion.           |
    | **Surveys & Feedback**      | Collect satisfaction scores and feedback at scale.                 |
    | **Payment Reminders**       | Send payment reminders with secure links.                          |
  </Tab>
</Tabs>

***

## Model

Text agents run on a single model - **Pearl Swan** - so there's no model picker to configure. It's billed per message.

<Info>
  **Pearl Swan** - our standard model for chat agents, built to handle any text-based use case with reliable reasoning and natural responses.
</Info>

Optional add-ons let your agent understand richer inputs sent in the conversation:

| Add-on          | Description                                                                           |
| --------------- | ------------------------------------------------------------------------------------- |
| **Vision**      | Read and understand images customers send, such as screenshots, documents, or photos. |
| **Audio input** | Understand voice notes and audio messages sent in the chat.                           |

***

## Get Started

<CardGroup>
  <Card title="Actions" icon="bolt" href="/pages/email_action">
    Execute real-time actions mid-conversation: send emails, hand off to a human, and call your APIs.
  </Card>

  <Card title="Post-Chat" icon="message-check" href="/pages/text/postchat">
    Access structured summaries, transcripts, and extracted variables for every conversation.
  </Card>

  <Card title="Inbound" icon="inbox-in" href="/pages/text/inbound">
    Deploy agents on inbound channels to answer messages instantly and route conversations.
  </Card>

  <Card title="Outbound" icon="paper-plane" href="/pages/text/outbound">
    Launch outbound messaging campaigns to reach customers proactively at scale.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="PearlVibe" icon="wand-magic-sparkles" href="/pages/pearl_vibe">
    Build and customize your agent's logic, knowledge, and actions from a single prompt.
  </Card>

  <Card title="Variables" icon="brackets-curly" href="/pages/variables">
    Collect, store, and reuse data during conversations - from user inputs to CRM lookups.
  </Card>

  <Card title="API Quick Start" icon="code" href="/api-reference/api_quickstart">
    Integrate NLPearl programmatically via the REST API.
  </Card>

  <Card title="Pearl Voice" icon="phone-volume" href="/pages/pearl_voice">
    Pair your text agents with AI voice agents for connected, cross-channel conversations.
  </Card>
</CardGroup>


# Post-Chat
Source: https://developers.nlpearl.ai/pages/text/postchat

All you need to know about Post-Chat in NLPearl

<div>
  <Frame>
    <div>
      <img alt="Post-Chat cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Post-Chat cover" />
    </div>
  </Frame>
</div>

***

## What is a Post-Chat?

In NLPearl, a **post-chat** is a structured summary generated after each conversation handled by Pearl. It centralizes all key information captured before, during, and after the conversation to ensure full traceability, improve quality, and support human follow‑up when needed.

***

## What Does the Post-Chat Include?

A post-chat provides multiple key sections to review and analyze the outcome of a conversation:

### Chat ID

A unique identifier for each conversation, displayed at the top right of the page. It allows you to quickly reference or search for a specific conversation across the system.

<Frame>
  <img alt="Chat ID location in the post-chat view" />
</Frame>

***

### Conversation Details

This section summarizes the essential metadata captured during the conversation, such as timing, the Pearl version used, credits consumed, and the overall outcome.

| Field                 | Description                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Date**              | The exact date and time the conversation took place.                                                          |
| **Pearl Version**     | The version of the Pearl that handled the conversation.                                                       |
| **Lead Name**         | The name of the lead (outbound conversations).                                                                |
| **Duration**          | The length of the conversation.                                                                               |
| **Queue Duration**    | Time the conversation spent waiting in the chat queue before being picked up (shown only when queued).        |
| **Transfer Duration** | Time spent with a human agent after a hand-off (shown only when handed off).                                  |
| **Credits Used**      | The number of credits consumed by the conversation.                                                           |
| **SMS Credits Used**  | The number of credits consumed by SMS messages sent during the conversation (shown only when greater than 0). |
| **Sentiment**         | The detected sentiment of the customer during the conversation.                                               |
| **Events**            | A shortcut to the actions triggered during the conversation — click **View** to jump to the **Event Log**.    |

<Note>
  Some fields are conditional: **Lead Name** appears for outbound conversations, **Queue Duration** only when the conversation was queued, **Transfer Duration** only when it was handed off, and **SMS Credits Used** only when at least one SMS was sent.
</Note>

<Note>
  The header shows the **participants** (the user and the channel used) and the **Conversation Status** badge — it does not show the name of the Pearl.
</Note>

<Frame>
  <img alt="Conversation Details in the post-chat view" />
</Frame>

***

### Conversation Status

Indicates the outcome of the conversation from a business or process perspective. It is shown as a colored badge in the header, next to the participants. For chats, this is the **only** status displayed.

<Frame>
  <img alt="Conversation Status badge and participants in the post-chat header" />
</Frame>

<Note>
  The **✕** next to the status badge lets you **close the conversation manually** at any time. See [Human Takeover](#human-takeover) for how closing differs from a takeover.
</Note>

| Status              | Description                                                          |
| ------------------- | -------------------------------------------------------------------- |
| `In Chat Queue`     | The conversation is waiting to be picked up.                         |
| `In Chat`           | The conversation is currently ongoing.                               |
| `Chat Successful`   | The conversation achieved its expected outcome.                      |
| `Chat Unsuccessful` | The conversation failed to meet its objective.                       |
| `Completed`         | The conversation was conducted and finalized, regardless of outcome. |

<Card icon="circle-info">
  <b>Important distinctions about Conversation Status</b>:

  The difference between `Chat Successful`, `Chat Unsuccessful`, and `Completed` depends on whether a **Success Definition** was configured when creating the Pearl:

  * If a **Success Definition** was configured:
    * `Chat Successful` → the Success Definition criteria were met during the conversation.
    * `Chat Unsuccessful` → the conversation did not meet the Success Definition criteria.
  * If **no Success Definition** was configured:
    * `Completed` → the conversation was completed without any Success Definition evaluation.
</Card>

<Note>
  Unlike voice calls, a chat has no separate technical status: the telephony-level **Call Status** is a back-end/API notion only and isn't shown in the post-chat UI.
</Note>

<Note>
  For more information on Success Definitions, see [PearlVibe](/pages/pearl_vibe#pearl-success).
</Note>

***

### Tags

The list of **tags defined during the last step of the Pearl creation process**. These tags represent key topics or categories you chose when setting up the Pearl configuration.

<Frame>
  <img alt="Tags in the post-chat view" />
</Frame>

<Note>For more information on setting up tags, see [PearlVibe](/pages/pearl_vibe).</Note>

***

### Events

A log of the actions triggered by Pearl during the conversation. Each event includes a timestamp, the action details, and an execution status.

Possible event types include:

| Event Type                | Description                                                                                          |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `Transfer Chat`           | The conversation was transferred to another destination.                                             |
| `Conversation Handed Off` | The conversation was handed off to a human agent.                                                    |
| `SMS Sent`                | A text message was sent to the customer.                                                             |
| `Email Sent`              | An email was sent during the conversation.                                                           |
| `API`                     | An API was triggered — before the chat (Pre-Chat), during it (API Request), or after it (Post-Chat). |
| `Appointment`             | An appointment was booked in the calendar.                                                           |
| `Slack`                   | A Slack notification was sent.                                                                       |

<Info>
  Each event carries an execution status: the **HTTP status code** for API calls, otherwise **sent** / **failed**, with a possible error state.
</Info>

***

### Sentiment Analysis

An automatic classification of the customer's tone and emotional state throughout the conversation. Possible sentiment values include:

| Sentiment Value     | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| `Positive`          | The conversation was clearly positive in tone and emotion.        |
| `Slightly Positive` | The overall tone was mostly positive, with minor neutral moments. |
| `Neutral`           | The sentiment was balanced or emotionless.                        |
| `Slightly Negative` | The tone leaned slightly negative, but not strongly so.           |
| `Negative`          | The conversation had a clearly negative emotional tone.           |

<Frame>
  <img alt="Sentiment analysis in the post-chat view" />
</Frame>

***

### Summary

A summary is a concise, human‑readable recap of the conversation, generated by Pearl. It includes:

* What the customer requested
* What was confirmed or declined
* The overall outcome of the interaction

Once a conversation is **closed or completed**, a summary is generated **automatically** at the end. While a chat is still **ongoing** (`In Chat`), no summary exists yet — you can generate one **on demand** with the **Generate Summary** button without waiting for the conversation to end.

<Frame>
  <img alt="Generate Summary button while the chat is ongoing" />
</Frame>

<Frame>
  <img alt="Generated summary in the post-chat view" />
</Frame>

<Note>
  Generating a summary **on demand** (while the chat is ongoing) costs **2 credits**. The automatic summary produced when the conversation ends is included.
</Note>

***

### Transcript & Event Log

A toggle at the top of the right-hand panel switches between the **Transcript** and the **Event Log**.

**Transcript** — a full text version of the conversation between the customer and Pearl. It is structured into three blocks separated by dividers: **Pre-chat events → In-chat messages → Post-chat events**. Always available, and useful for reviewing the interaction, auditing, and training.

* **Delivery status**: each message shows its delivery state — **Pending**, **Sent**, or **Failed** — with a matching icon.
* **Attachments**: messages can include attachments (images, files) shared during the conversation.

<Frame>
  <img alt="Transcript in the post-chat view" />
</Frame>

**Event Log** — a chronological view of all actions triggered by Pearl during the conversation. Each entry shows the action type (API call, SMS, email, transfer…), its execution status, and contextual data, so you can verify that every automated operation ran and inspect its output.

<Frame>
  <img alt="Event Log in the post-chat view" />
</Frame>

***

### Variables

This section, labeled **Variables** in the UI, displays the **structured data captured before or during the conversation**, corresponding to the dynamic values collected through the Pearl configuration.
Examples:

* Delivery type
* Selected options (e.g. “Dessert: Cheesecake”)
* Customer preferences

<Frame>
  <img alt="Variables in the post-chat view" />
</Frame>

<Info>
  You can learn more about creating variables in the Pearl [here](/pages/variables).
</Info>

***

### Human Takeover

At any point, a human agent can step in and **take over the conversation** directly from the post-chat page, then hand it back to Pearl once done. The full context (transcript, variables, and events) stays available throughout.

This is useful when:

* The customer explicitly asks to speak with a human
* The request falls outside what Pearl is configured to handle
* A sensitive or high-value conversation needs a personal touch

<Note>
  A takeover is a **manual** action you trigger from this page. It's different from a **human hand-off**, which Pearl performs **automatically** based on a node configured in your flow — logged as a *Conversation Handed Off* event.
</Note>

<Card title="Hand-Off Node" icon="headset" href="/pages/text/handoff_action">
  Learn how to configure automatic hand-off to a human agent from your Pearl flow.
</Card>

<Steps>
  <Step title="Pearl is handling the chat">
    While Pearl is in control, the footer shows *“Pearl is handling this chat”* and the composer is locked (*“Pearl is replying…”*). Click **Take over** to step in.

    <Frame>
      <img alt="Take over button while Pearl is handling the chat" />
    </Frame>
  </Step>

  <Step title="The agent is in control">
    Once you take over, Pearl stops replying and the footer shows that you (the agent) took over. The composer unlocks to **Reply as agent…**, so you can type messages and send attachments to the customer in real time. When you're finished, click **Hand back** to return control to Pearl.

    <Frame>
      <img alt="Agent replying and handing the conversation back to Pearl" />
    </Frame>
  </Step>
</Steps>

<Note>
  A takeover does **not** close the conversation. Pearl simply stops responding so the human agent can reply, and everything stays logged in the post-chat for full traceability. When done, the agent can **hand the conversation back** to Pearl.
</Note>

<Note>
  **Closing a conversation** is a separate action from takeover. Using the **✕** next to the status badge in the header explicitly closes the conversation in the system, whereas a takeover only pauses Pearl's replies. Use it when the exchange is finished.
</Note>

***

<Tip>
  **Navigation & shortcuts** — move between conversations with the on-screen arrows or the **↑ / ↓** keyboard keys, and click **View** on the Events row in Conversation Details to jump straight to the Event Log.
</Tip>

***

## Why the Post-Chat Matters

<CardGroup>
  <Card title="Traceability" icon="check">
    Every conversation leaves a documented trace for accountability.
  </Card>

  <Card title="Faster Follow‑Up" icon="check">
    Helps support and operations teams follow up efficiently with customers.
  </Card>

  <Card title="Quality & Analytics" icon="check">
    Enables continuous improvement through quality review, sentiment tracking, and conversation analysis.
  </Card>

  <Card title="Auditing & Compliance" icon="check">
    Provides an auditable record of AI-driven conversations to meet regulatory or internal policy needs.
  </Card>
</CardGroup>

***

By consolidating all these elements, the **Post-Chat** page provides a complete overview of each AI-handled conversation, ensuring transparency, traceability, and actionable insights for your team.


# Transfer Call Node
Source: https://developers.nlpearl.ai/pages/transfer_call



<Callout icon="phone">Available for **Pearl Voice** only.</Callout>

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on light mode" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on dark mode" />
    </div>
  </Frame>
</div>

The **Transfer Call** node hands the live call off to another phone number, so your Pearl can bring a human or another line into the conversation.

**What it does**: Transfers the live call to another phone number.

**When to use**: Escalate to a human, route to a manager, or forward to another department.

<Info>
  A Transfer Call node can be triggered in **two ways**:

  * **Reached through a transition**: like any other node, when a previous node routes to it. It fires as soon as the flow reaches it, and the **When to trigger** field is hidden (it isn't needed).
  * **As a floating node**: with **no** incoming transition. Then **When to trigger** becomes required, and Pearl can jump to the transfer from **anywhere** in the conversation whenever that condition is met.

  You can use both patterns in one flow: place scripted transfers inline via transitions, and keep a floating transfer for exceptions like "the customer asks for a manager."
</Info>

***

## How to Configure

<Frame>
  <img alt="Transfer Call node configuration with phone number, Say, and Warm Transfer" />
</Frame>

<Steps>
  <Step title="Phone Number">
    Destination in international format (e.g., `+12025551234`) or a variable.
  </Step>

  <Step title="Show client caller ID (optional)">
    When enabled, Pearl attempts to show the **client's number** to the recipient during the transfer, instead of Pearl's own number.

    <Warning>
      Test this first. If transfers fail with it on, turn it off.
    </Warning>
  </Step>

  <Step title="Say (optional)">
    A line Pearl says to the **caller** right before transferring (e.g. *"I'm connecting you to a specialist now."*).
  </Step>

  <Step title="When to trigger (floating nodes only)">
    Describe when Pearl should trigger the transfer, e.g. *"If the client needs a manager or has an emergency."* This field only appears when the node has no incoming transition.
  </Step>

  <Step title="Warm Transfer (optional)">
    Introduce the call to the recipient before Pearl drops off. See [Transfer types](#transfer-types) below.
  </Step>
</Steps>

***

## Transfer types

A Transfer Call can happen in two ways, controlled by the **Warm Transfer** toggle.

**Direct transfer (Warm Transfer off).** Pearl connects the caller straight to the destination number without speaking to the recipient first. The recipient picks up with no context. This is the default.

**Warm transfer (Warm Transfer on).** Before dropping off, Pearl introduces the call to the recipient with an intro message, then leaves the two parties connected. Choose how the intro is delivered:

| Mode                  | Who hears the intro       | Caller during intro      | Use it to                                              |
| --------------------- | ------------------------- | ------------------------ | ------------------------------------------------------ |
| **Whisper** (default) | Recipient only            | On hold, doesn't hear it | Privately brief the recipient (e.g. sensitive context) |
| **3-way**             | Both caller and recipient | Present, hears it        | Give an open, seamless handover                        |

<Frame>
  <img alt="Warm Transfer module with Whisper / 3-way toggle and intro message" />
</Frame>

<Info>
  **Two different messages, don't confuse them:**

  * **Say (optional)**: what Pearl says to the **caller** right before transferring.
  * **Warm Transfer message**: what Pearl says to the **recipient** (and, in 3-way, also to the caller) to introduce the call. Required when Warm Transfer is on. Pearl says this, then drops off.
</Info>

**Example intros**

* Whisper: `Hi, I'm on the line with {firstName} regarding {reason}. I'll transfer the call to you now.`
* 3-way: `Hi, I'm on the line with {firstName} calling about {reason}. I'll leave you both to it. Thanks!`

<Warning>
  **Pearl Voice only.** Pearl Text uses the [**Hand‑Off**](/pages/text/handoff_action) node to route conversations to a human.
</Warning>

<Note>
  Transfer Call is **terminal**: the call leaves Pearl, so the node has no outgoing transitions. Validation flags *"Missing Phone Number"*, and *"Missing Trigger Description"* when the node is floating.
</Note>

<Card icon="circle-info">
  ### Important Considerations

  **Country Code Matching**: Your Pearl will be connected to an activity with a specific phone number assigned to it.
  If the phone number you choose for the transfer call does not match the country code of the activity's assigned phone number, the Pearl cannot be linked to that activity.
  Ensure that the phone numbers are compatible to be able to assign it to your Inbound/Outbound Activity.
</Card>


# Twilio Integration
Source: https://developers.nlpearl.ai/pages/twilio_integration

Connect your Twilio account and use your Twilio numbers with NLPearl.AI.

<div>
  <Frame>
    <div>
      <img alt="Twilio integration cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Twilio integration cover" />
    </div>
  </Frame>
</div>

Connect your Twilio account to NLPearl.AI and use your existing Twilio numbers for inbound and outbound campaigns. This gives you access to phone numbers from a wide range of countries, with local regulatory compliance handled directly by Twilio.

***

### How to Integrate Your Twilio Account

<Steps>
  <Step title="Go to Phone Numbers Settings">
    Start by clicking your **profile card** at the bottom-left corner of the sidebar, then open **Settings**.

    <Frame>
      <img alt="Open Settings from the profile card" />
    </Frame>

    From there, open the **Phone Numbers** tab to manage the numbers linked to your account.

    <Frame>
      <img alt="Phone Numbers tab in Settings" />
    </Frame>
  </Step>

  <Step title="Open the Twilio Connection">
    In the **Phone Numbers** tab, locate the **Connect to Twilio** row. Click **Manage Twilio** to open the connection panel and link your Twilio account.

    <Frame>
      <img alt="Connect to Twilio from the Phone Numbers settings" />
    </Frame>
  </Step>

  <Step title="Enter Your Twilio Credentials">
    The **Connect your Twilio Account** panel opens. A short guide on the left walks you through each value, with quick links to the right pages in your Twilio Console.

    Choose the method that fits your needs, fill in the fields on the right, then click **Connect Twilio**.

    <Tabs>
      <Tab title="API Credentials (recommended)">
        The most secure option. It uses a scoped API Key instead of your main Auth Token.

        | Field              | Where to find it                                          |
        | ------------------ | --------------------------------------------------------- |
        | **Account SID**    | Twilio Console, under **Account Info**.                   |
        | **API Key SID**    | Generated when you create a Standard API Key (see below). |
        | **API Key Secret** | Shown **only once** when the key is created.              |

        <Frame>
          <img alt="Twilio credentials using an API Key" />
        </Frame>

        <Note>
          **How to generate a Twilio API Key**

          <Steps>
            <Step title="Go to Twilio API Keys Settings">
              Visit the [Twilio API Keys page](https://www.twilio.com/console/project/api-keys) in your console, then click **Create API Key** in the top-right corner.

              <Frame>
                <img alt="Twilio API keys & tokens page with Create API key" />
              </Frame>
            </Step>

            <Step title="Select Standard Key Type">
              Give your key a name and select **Standard** as the key type. Then click **Create**.

              <Frame>
                <img alt="Create a new Twilio API key with Standard type" />
              </Frame>
            </Step>

            <Step title="Copy the SID and Secret">
              Twilio now displays both the **SID** and the **Secret**.

              <Warning>
                The **Secret Key** is shown only once, so copy and store it somewhere safe before closing the page.
              </Warning>

              <Frame>
                <img alt="Copy the Twilio API key SID and secret" />
              </Frame>
            </Step>
          </Steps>
        </Note>
      </Tab>

      <Tab title="Account SID + Auth Token">
        The simplest option. Connect directly with your main Twilio credentials.

        | Field           | Where to find it                                                   |
        | --------------- | ------------------------------------------------------------------ |
        | **Account SID** | Twilio Console, under **Account Info**.                            |
        | **Auth Token**  | Twilio Console, under **Account Info** (click **Show** to reveal). |

        <Frame>
          <img alt="Twilio credentials using Account SID and Auth Token" />
        </Frame>

        <Note>
          Both values live in the **Account Info** panel on your Twilio Console dashboard.

          <Frame>
            <img alt="Account SID and Auth Token in the Twilio Account Info panel" />
          </Frame>
        </Note>
      </Tab>
    </Tabs>

    <Tip>
      Use the **Open Twilio Console** and **Open Twilio API Keys** shortcuts inside the panel to jump straight to the right Twilio pages while filling in your credentials.
    </Tip>
  </Step>

  <Step title="Import Your Twilio Phone Numbers">
    Once connected, the **Twilio Account** screen lists every number available on your account.

    Click **Add to account** next to a number to import it into NLPearl. A confirmation message appears, and the number becomes available in your account right away. To detach a number, click **Remove** next to it.

    <Frame>
      <img alt="Import Twilio phone numbers into NLPearl" />
    </Frame>

    <Info>
      You can return to this screen at any time to import additional numbers, especially after adding new ones to your Twilio account.
    </Info>
  </Step>

  <Step title="Manage or Switch Twilio Accounts">
    The **Twilio Account** screen shows the connected **Account SID** at the top, so you always know which account is in use.

    To connect a different Twilio account, use the **back arrow** in the top-left corner to return to the connection panel and enter new credentials.

    <Frame>
      <img alt="Manage or switch the connected Twilio account" />
    </Frame>

    <Info>
      Numbers you already imported stay linked to your NLPearl account. Switching Twilio accounts won’t affect them.
    </Info>
  </Step>
</Steps>

<Card title="Deleting Phone Numbers" icon="circle-info">
  If you no longer need a phone number, you can schedule it for deletion directly from your settings.

  Start by going to the **Phone Numbers** section in your Settings. From there, locate the number you want to remove and click the **Delete** button next to it.

  <Frame>
    <img alt="Delete a phone number from the Phone Numbers settings" />
  </Frame>

  A confirmation step will appear to make sure you really want to delete the selected number. The phone number will be removed from your NLPearl account immediately.

  <Info>
    Deleting a phone number from NLPearl does not delete it from your Twilio account. Ensure that the phone number isn't used in any running activities before deleting it from the platform.
  </Info>
</Card>

***

### Disabling HTTP Basic Authentication for Media Access

To ensure full functionality, disable HTTP Basic Authentication for media access in Twilio:

<Steps>
  <Step title="Access Twilio Voice Settings">
    Start by logging into your **Twilio dashboard**. In the left-hand navigation, click on **Voice** <span>(1)</span> to open the voice-related settings. Under the Voice section, select **Settings** <span>(2)</span>, then click on **General** <span>(3)</span> to access the general voice configuration panel.

    <Frame>
      <img alt="Open Voice > Settings > General in the Twilio Console" />
    </Frame>
  </Step>

  <Step title="Disable HTTP Basic Authentication in Twilio">
    Once you're in the **Voice > General** settings, scroll down to the **HTTP Basic Authentication for media access** section.

    Under this section, select **Disabled** to allow media URLs to be publicly accessible <span>(1)</span>. Then, click the **Save** button at the bottom of the page <span>(2)</span> to apply your changes.

    <Frame>
      <img alt="Disable HTTP Basic Authentication for media access in Twilio" />
    </Frame>

    <Note>
      By disabling this setting, you ensure that NLPearl.AI can access and use media resources without authentication issues.
    </Note>
  </Step>
</Steps>

***

<Info>
  ### Advantages of Twilio Integration

  * **Access to Global Phone Numbers**: Use phone numbers from countries not directly supported by NLPearl.AI by purchasing them through Twilio.

  * **Compliance with Country Regulations**: Twilio handles country-specific regulations, allowing you to purchase numbers that comply with local laws.

  * **Leverage Existing Numbers**: Utilize the phone numbers you already own in Twilio without needing to acquire new ones.
</Info>

<Warning>
  ### Important Considerations

  * **Phone Number Ownership**: Numbers are purchased and managed in your Twilio account. NLPearl.AI only lets you use them within the platform.

  * **Running Activities**: Before removing a number from NLPearl.AI, make sure it isn't assigned to any active campaign to avoid disruptions.
</Warning>

***

If you need assistance with the integration process or have questions about using Twilio phone numbers with NLPearl.AI, please refer to our support resources or contact our support team.


# Users & Workspaces
Source: https://developers.nlpearl.ai/pages/users_workspaces

Invite users, assign roles, manage permissions, and switch between workspaces.

<div>
  <Frame>
    <div>
      <img alt="Users & Workspaces cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Users & Workspaces cover" />
    </div>
  </Frame>
</div>

***

Use **Users & Workspaces** settings to control who can access your workspace, what each person is allowed to manage, and which workspace you are currently working in.

<CardGroup>
  <Card title="Users" icon="user-plus">
    Invite team members and assign them the right access level.
  </Card>

  <Card title="Roles" icon="shield-check">
    Create reusable permission sets for different responsibilities.
  </Card>

  <Card title="Workspaces" icon="building">
    Switch between workspaces or create a new one.
  </Card>

  <Card title="Access control" icon="lock">
    Limit access to Pearls, billing, phone numbers, API keys, users, and audit logs.
  </Card>
</CardGroup>

***

# Users & Roles

Control who can access the current workspace and what each person is allowed to do.

## Managing Users

The **Users** page lets workspace owners and admins invite new members, review existing users, and update their access level.

<Frame>
  <img alt="Users management page" />
</Frame>

<Steps>
  <Step title="Open Users">
    Go to **Workspace > Users**.
  </Step>

  <Step title="Invite a user">
    Click **Invite User**, enter one or more email addresses, then choose the role to assign.

    <Frame>
      <img alt="Invite user dialog" />
    </Frame>
  </Step>

  <Step title="Review access">
    Confirm that each user has the correct role, such as **Owner**, **Admin**, or a custom role created for your team.
  </Step>
</Steps>

<Note>
  Give users the minimum access they need for their work. You can always update their role later as responsibilities change.
</Note>

***

## Managing Roles

Roles define what users are allowed to do in a workspace. You can use roles to separate responsibilities between admins, operators, support teams, billing teams, and other internal workflows.

To manage roles, go to **Workspace > Users**, then open the **Roles** tab.

<Frame>
  <img alt="Add role on the Roles tab" />
</Frame>

<Steps>
  <Step title="Create a role">
    Click **Create Role** and enter a clear role name.
  </Step>

  <Step title="Select permissions">
    Choose which actions the role should allow.

    <Frame>
      <img alt="Role permissions selection" />
    </Frame>
  </Step>

  <Step title="Save the role">
    Click **Save Role** to make the role available when inviting or updating users.
  </Step>
</Steps>

Common permissions include:

| Area                  | What it allows                                         |
| --------------------- | ------------------------------------------------------ |
| **Pearls**            | Create and edit Pearls, including access to PearlVibe. |
| **Activities**        | Moderate activity status.                              |
| **Analytics**         | View analytics.                                        |
| **Leads**             | View and moderate leads.                               |
| **Calls**             | View calls and post-call information.                  |
| **Resources**         | Manage phone numbers, agents, API keys, and users.     |
| **Advanced settings** | Manage security and sessions.                          |
| **Audit log**         | View the audit log.                                    |
| **Billing**           | Manage account billing.                                |

<Tip>
  Create role names that match real responsibilities, such as `Support`, `Operations`, `Billing`, or `Admin`.
</Tip>

***

# Workspaces

A **workspace** is an isolated environment with its own Pearls, activities, settings, billing, users, and logs. Use workspaces to separate teams, customers, or projects. Everything above (users and roles) is scoped to the workspace you are currently in.

In the settings menu, the options are split into two groups:

* **User** settings (such as **Profile** and **Security**) are personal to your account and follow you across every workspace.
* **Workspace** settings (everything listed under the **Workspace** section, like General Settings, Phone Numbers, Text Channels, Agents, Subscriptions & Payments, Users, API Keys, and more) apply **only to the workspace you are currently in**.

<Note>
  When you switch workspaces, all the **Workspace** settings change to reflect the selected workspace. Your **User** settings stay the same.
</Note>

***

## General Settings

The **General Settings** page manages your workspace identity, notifications, and security preferences.

<Frame>
  <img alt="Workspace general settings" />
</Frame>

| Setting                 | Description                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| **Workspace Name**      | The name visible to all members of the workspace.                                               |
| **Billing Email**       | Email used for invoices, receipts, and payment-related notifications.                           |
| **Notifications Email** | Email where important alerts and workspace notifications are sent.                              |
| **Newsletter**          | Opt in to receive product news, feature updates, and occasional announcements.                  |
| **Session Timeout**     | How long a session on the platform stays active before expiring due to inactivity (in minutes). |
| **Public Recordings**   | When enabled, call recordings are accessible publicly via a shared link.                        |
| **Delete Workspace**    | Permanently delete the workspace and all associated data.                                       |

<Warning>
  Deleting a workspace is permanent and cannot be undone. All associated data is removed.
</Warning>

***

## Creating a New Workspace

You can create a separate workspace when you need to isolate teams, customers, projects, or billing.

<Frame>
  <img alt="Create a new workspace" />
</Frame>

<Steps>
  <Step title="Open the workspace menu">
    Click the current workspace name in the sidebar.
  </Step>

  <Step title="Create the workspace">
    Click **Create New Workspace**, enter a workspace name, then click **Create**.
  </Step>
</Steps>

<Warning>
  A new workspace has its own subscription and is billed separately.
</Warning>

***

## Switching Workspaces

If your account belongs to multiple workspaces, use the workspace switcher to move between them. The selected workspace controls which Pearls, activities, settings, billing, users, and logs you are viewing.

<Frame>
  <img alt="Switch between workspaces" />
</Frame>

<Steps>
  <Step title="Open the workspace menu">
    Click the workspace name in the platform sidebar.
  </Step>

  <Step title="Choose a workspace">
    Select the workspace you want to manage from the list.
  </Step>
</Steps>

***

## Transferring a Pearl to Another Workspace

You can send a copy of a Pearl to another workspace you belong to - useful when you build agents in a test workspace before moving them to production, or manage several customers from a single account.

<Frame>
  <img alt="Transfer Pearl dialog" />
</Frame>

<Steps>
  <Step title="Open the transfer dialog">
    On the Pearl's page, open the **Settings** menu and click **Transfer Pearl**. The same option is available from the Pearls list.
  </Step>

  <Step title="Choose the version to transfer">
    Select which version of the Pearl to send. It becomes **version 1** of the new Pearl in the destination workspace.
  </Step>

  <Step title="Pick the destination">
    Select one or more workspaces, then click **Transfer**.
  </Step>
</Steps>

The Pearl is **copied, not moved**: the original stays in the current workspace, untouched and still running. The copy arrives as a **draft** with a clean slate - no calls, conversations, leads, or usage history follows it - so you can review it and publish it when ready.

<Warning>
  Phone numbers and text channels are not transferred. Before going live, assign the copy a phone number or text channel that belongs to the destination workspace.
</Warning>

<CardGroup>
  <Card title="Account Security Settings" icon="lock" href="/pages/security">
    Configure session timeout, audit logs, 2FA, and enterprise SSO.
  </Card>

  <Card title="Billing" icon="wallet" href="/pages/billing">
    Manage subscriptions, payment methods, invoices, and auto-recharge.
  </Card>
</CardGroup>


# Variables
Source: https://developers.nlpearl.ai/pages/variables



<div>
  <Frame>
    <div>
      <img alt="Variables cover" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Variables cover" />
    </div>
  </Frame>
</div>

***

## Introduction

Variables are essential placeholders that store and manipulate data during a conversation. They hold information such as:

* **User Inputs**: Data collected from user responses (e.g., names, email addresses).
* **System Data**: Information retrieved from external sources like CRM systems.
* **Computed Values**: Results from expressions or calculations within the conversation flow.

<Check>
  <b>Why Are Variables Important?</b>

  * **Personalize Interactions**: Tailor conversations to individual users for a more engaging experience.
  * **Control Conversation Flow**: Make decisions and branch dialogues based on variable values.
  * **Store and Reuse Information**: Keep track of data throughout the conversation for consistency.
  * **Integrate with External Systems**: Enrich conversations with data from other platforms.
  * **Enhance Actions**: Use variables in actions like sending personalized emails or SMS messages.
</Check>

***

## Variable Manager Overview

Variables can be managed using the **Variable Manager**, which is accessible in the **Flow Editor**.

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on light mode" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on dark mode" />
    </div>
  </Frame>
</div>

<br />

The Variable Manager allows you to create, edit, and organize variables used in your conversation flows. Variables are categorized into three types:

| **Type**                        | **Description**                                                                                                                                                                                  | **Representation**            |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| **Pre-call Variables**          | Variables configured before the call starts, such as customer information. These variables are typically sourced from external systems like CRM or imported via CSV or API.                      | <span><span />`blue`</span>   |
| **Collected In-call Variables** | Variables captured or updated dynamically during the conversation. These variables are collected based on user interactions, inputs, or system computations.                                     | <span><span />`green`</span>  |
| **Post-call Variables**         | Variables generated after the call ends, such as the call transcript, recording URL, and conversation summary. These variables are automatically produced and can be used for follow-up actions. | <span><span />`orange`</span> |

<Warning>
  **Note about Post-call Variables**\
  Post-call variables are **not accessible via the Variable Manager**, as they **cannot be created or modified by users**. These variables are **pre-defined by our team** and become available only **within Post-Call Actions**. They’re designed to let your agents send structured data (like summaries or recordings) to external systems **after the call ends**.
</Warning>

***

#### Accessing the Variable Manager

You can access the Variable Manager in **two quick ways**:

<Steps>
  <Step title="From the Header">
    You can access the **Variable Manager** directly from the **top navigation bar** of the **Flow Editor**.

    <div>
      <Frame>
        <div>
          <img alt="Variable Manager location – Light Mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Variable Manager location – Dark Mode" />
        </div>
      </Frame>
    </div>

    <br />
  </Step>

  <Step title="From a Text Field">
    You can also access the **Variable Manager** from a text field whenever the `+` icon is available.

    <Note>
      Only fields that support variables will display the **“+”** icon.\
      For example, some duration or static option fields won’t offer variable insertion.
    </Note>

    * Open a **Node** in the **Flow Editor**.
    * Click the **“+” icon** inside the supported text input field.
    * At the bottom of the dropdown, click **“Variable Manager”**.

    <div>
      <Frame>
        <div>
          <img alt="Accessing the Variable Manager from a text field – Light Mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Accessing the Variable Manager from a text field – Dark Mode" />
        </div>
      </Frame>
    </div>
  </Step>
</Steps>

***

#### Creating and Managing Variables

Variables help you store and reuse dynamic information throughout your flows. Here's how to create, edit, and manage them from the **Variable Manager**.

<Steps>
  <Step title="Open the Variable Manager">
    Click the **“+”** icon in a text field or use the **Variable Manager** button (in the header or Flow Editor).
  </Step>

  <Step title="Select the Variable Category">
    * **Pre-call** (available before the call starts)
    * **Collected In-call** (captured during the conversation)

    <Warning>
      Post-call variables are predefined by our team and cannot be created manually. They are only available inside **Post-Call Actions**.
    </Warning>

    <Note>
      Some variables are **system-defined and read-only** (shown at the top of the list), you can use them but not edit or delete them. Examples: **Pre-call** — agent name, agent phone number, first name, last name, phone number, email address, call id; **Post-call** — summary, transcript, recording, duration, call time.
    </Note>

    <Warning>
      **Agent Phone Number** (`agentPhoneNumber`) contains the Pearl's own phone line for the current conversation, unlike **Phone Number**, which identifies the customer. It is empty on channels without a phone number, including Telegram and browser Test Chat. An API node does not execute if it references this variable while it is empty.
    </Warning>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on light mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on dark mode" />
        </div>
      </Frame>
    </div>

    <br />
  </Step>

  <Step title="Fill in the Variable Details">
    | Field                        | Description                                                                                                                               | Rules                                                                     |
    | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
    | **Type**                     | The variable's data type (see the **Variable Types** table below).                                                                        | Required                                                                  |
    | **Display Name**             | Human-readable label shown in the UI and used by Pearl (e.g. `Customer Name`).                                                            | Required · max 40 chars · letters, numbers, spaces                        |
    | **ID**                       | Unique system key used to reference the variable in flows, CSV imports, and API payloads. Auto-generated from the Display Name, editable. | Required · unique · max 40 chars · letters, numbers, `_`, `-` · no spaces |
    | **Description** *(optional)* | Explain the purpose or usage of this variable (helps Pearl use it correctly).                                                             | Optional · max 1000 chars                                                 |
    | **Allow Multiple Entries**   | Store a list of values of the chosen type (e.g. several dates).                                                                           | Optional                                                                  |
    | **Reset Every Interaction**  | Start this variable empty in every new interaction instead of reusing the value from a previous one.                                      | Optional                                                                  |

    <div>
      <Frame>
        <div>
          <img alt="Reset Every Interaction toggle in the Variables Manager" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Reset Every Interaction toggle in the Variables Manager" />
        </div>
      </Frame>
    </div>

    <br />

    <Tip>
      **Display Name vs ID** — the **Display Name** is what you read and what Pearl says; the **ID** is the key the system uses everywhere else. When importing leads via CSV or the API, the column header / `callData` key must match the variable's **ID**, not its Display Name.
    </Tip>

    **Variable Types**

    | Type               | Example             |
    | ------------------ | ------------------- |
    | **Text**           | a name, a plan      |
    | **Whole Number**   | age, quantity       |
    | **Decimal Number** | an amount, a rate   |
    | **Boolean**        | true / false        |
    | **Date**           | a birth date        |
    | **Time**           | an appointment time |
    | **Date & Time**    | a meeting slot      |

    <div>
      <Frame>
        <div>
          <img alt="Variable details form – Light Mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Variable details form – Dark Mode" />
        </div>
      </Frame>
    </div>

    <br />
  </Step>

  <Step title="Define Allowed Values (Optional)">
    Use this section to limit inputs to specific options.

    * Add a list of accepted values.
    * Optionally assign **backend codes** to each value.
    * Toggle **Allow Multiple Entries** if more than one value can be selected.

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on light mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on dark mode" />
        </div>
      </Frame>
    </div>

    <Info>
      This is ideal for dropdowns or structured inputs (e.g. `Issue Type`, `Region`, etc.).
    </Info>
  </Step>

  <Step title="Save the Variable">
    It will now be available anywhere in your flow where variables are supported.
  </Step>

  <Step title="Use your variables wherever applicable">
    <Info>
      Some fields, like the **Opening Sentence**, do not support the use of **in-call variables**.

      When testing your flows via **Test Calls**, note that **Pre-call variables are required**, while **In-call variables are optional**.

      Also, when uploading a lead file, **only the variables you've actually used** in your flows will appear in the platform’s lead mapping interface.

      In other words:\
      If you’ve created variables in the Variable Manager but haven’t used them anywhere, they **won’t show up** when setting up an outbound campaign or importing leads.
    </Info>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on light mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on dark mode" />
        </div>
      </Frame>
    </div>

    <br />
  </Step>
</Steps>

<Card icon="circle-info">
  <b>Search, Edit or Delete a Variable</b>

  **To search a variable:**

  * Open the **Variable Manager**.
  * Click on the search bar.

  <div>
    <Frame>
      <div>
        <img alt="Send Email action interface on light mode" />
      </div>
    </Frame>
  </div>

  <div>
    <Frame>
      <div>
        <img alt="Send Email action interface on dark mode" />
      </div>
    </Frame>
  </div>

  <br />

  **To edit a variable:**

  * Open the **Variable Manager**.
  * Click on the variable name to open its edit form.

  <div>
    <Frame>
      <div>
        <img alt="Send Email action interface on light mode" />
      </div>
    </Frame>
  </div>

  <div>
    <Frame>
      <div>
        <img alt="Send Email action interface on dark mode" />
      </div>
    </Frame>
  </div>

  <br />

  **To delete a variable:**

  * Click the **Trash icon** next to the variable.
  * Confirm the deletion in the dialog box.

  <Warning>
    Deleting a variable will remove it from all flows where it's used. Proceed with caution!
  </Warning>

  <div>
    <Frame>
      <div>
        <img alt="Send Email action interface on light mode" />
      </div>
    </Frame>
  </div>

  <div>
    <Frame>
      <div>
        <img alt="Send Email action interface on dark mode" />
      </div>
    </Frame>
  </div>
</Card>

***

## Using Variables in Conversations

<span>
  Collecting User Input into Variables
</span>

To collect user input into a variable, open the node's configuration in the **Flow Editor** and locate the **"Store In Variable"** field.

***

<span>
  Inserting Variables into Agent Scripts
</span>

1. **Compose the Agent's Script** in any text field within your flow.
2. **Insert Variable Placeholder**:
   * Click the **"+"** icon next to the text field.
   * Select the desired variable from the list.

<Card title="Example">
  **Script**: "Thank you for calling, `customerName`!"
</Card>

<br />

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on light mode" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on dark mode" />
    </div>
  </Frame>
</div>

***

<span>
  Using Variables in Actions
</span>

1. **Add an Action Node** (e.g., **Email Node**, **SMS Node**) to your flow.
2. **Configure the Action**:
   * **Message Content**: Include variables by clicking the **"+"** icon and selecting the desired variable.
3. **Customize the Message** with variable placeholders.

<Card title="Example in SMS Node">
  **Message Content**: "Hello `customerName`, your appointment on `appointmentDate` is confirmed."
</Card>

<br />

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on light mode" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on dark mode" />
    </div>
  </Frame>
</div>

***

<span>
  Using Variables in Post-Call Actions
</span>

1. Add a Post-Call Action to your flow (`SMS`, `Email`, `API`).
2. Write the Notification Message, using the “+” icon to insert dynamic variables
3. Customize the content to provide a clear summary of each completed call.

<Card title="Example Email Notification to Client">
  **Subject**: New call from `customerName` - Summary for `companyName` <br /><br />
  **Message Content**: "Hello `companyName`, You have received a new call from `customerName`. Here are some details:

  * Call Duration: `callDuration`
  * Summary: `callSummary`"
</Card>

<br />

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on light mode" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Send Email action interface on dark mode" />
    </div>
  </Frame>
</div>

***

## Implementing Conditional Logic with Variables

<span>
  Conditional Branching
</span>

1. **Enable Conditional Transitions** in a node's configuration by toggling the **"Conditional Branching"** option.

2. **Add Conditions** using variables and operators (e.g., **`satisfactionScore >= 4`**).

3. **Label Each Condition** for clarity.

4. **Connect to Subsequent Nodes** based on each condition.

<Card title="Example">
  * **Variable**: `satisfactionScore`
  * **Conditions**:
    * If **`satisfactionScore >= 4`**, proceed to positive feedback node.
    * If **`satisfactionScore < 4`**, proceed to improvement inquiry node.
</Card>

<br />

<div>
  <Frame>
    <div>
      <img alt="Conditional branching – Light Mode" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Conditional branching – Dark Mode" />
    </div>
  </Frame>
</div>

***

## Populating Variables from External Data

Call variables can be filled dynamically from CSV files or APIs to personalize outbound calls.

<Warning>
  Do not enable **Reset Every Interaction** on a variable you populate from a CSV import or the API: the value you provide is cleared before the call starts.
</Warning>

<span>
  Adding Variables via the Platform (Outbound Campaigns)
</span>

<Steps>
  <Step title="Download the Lead Template CSV">
    Go to the **Outbound Campaigns** section of the platform, then click **Download Lead Template**.

    This CSV contains predefined columns where you can add your custom variables.

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on light mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on dark mode" />
        </div>
      </Frame>
    </div>

    <br />
  </Step>

  <Step title="Fill in the CSV with your Lead Data">
    Open the downloaded CSV and complete it by filling in the lead information, including any custom variables in the appropriate columns.

    Make sure each variable matches the column header to avoid upload issues.

    Once completed, **upload the CSV back into the platform**.

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on light mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Send Email action interface on dark mode" />
        </div>
      </Frame>
    </div>
  </Step>
</Steps>

<br />

<Card title="Example CSV Entry">
  | phoneNumber | customerName | membershipStatus |
  | ----------- | ------------ | ---------------- |
  | +1234567890 | Jane Smith   | Gold             |
</Card>

***

<span>
  Adding Variables via API
</span>

1. **Use the Add Lead API Endpoint**: `PUT /v1/Outbound/{outboundId}/Lead`.
2. **Include Variables** in the `callData` field of your JSON payload.

<Card title="Example Request">
  ```http theme={null}
  PUT /v1/Outbound/{outboundId}/Lead
  Content-Type: application/json
  Authorization: Bearer <token>

  {
    "phoneNumber": "+1234567890",
    "externalId": "lead123",
    "callData": {
      "customerName": "Jane Smith",
      "membershipStatus": "Gold"
    }
  }
  ```
</Card>

***

<span>
  Sending Variables in Single On-Demand Calls
</span>

1. **Use the Make Call API Endpoint**: `POST /v1/Outbound/{outboundId}/Call`.
2. **Include Variables** in the `callData` field of your JSON payload.

<Card title="Example Request">
  ```http theme={null}
  POST /v1/Outbound/{outboundId}/Call
  Content-Type: application/json
  Authorization: Bearer <token>

  {
    "to": "+1234567890",
    "callData": {
      "firstName": "John",
      "accountBalance": "$100"
    }
  }
  ```
</Card>

***

<Note>
  Best Practices for Using Variables

  * **Use Descriptive Names**: Clearly name variables for easy identification (e.g., `customerEmail`).
  * **Define Variables Early**: Plan your variables before building the conversation flow.
  * **Categorize Variables**: Use **Pre-call** and **Collected In-call** categories to organize your variables.
  * **Avoid Unnecessary Variables**: Only create variables that are essential to your conversation.
  * **Test Thoroughly**: Simulate conversations to ensure variables function as intended.
  * **Handle Data Securely**: Be cautious with personal and sensitive information.
  * **Document Variables**: Use the description field to note the purpose of each variable.
  * **Use Allowed Values and Codes**: When appropriate, define allowed values and use codes for better data management.
</Note>

***

## Examples

<Card title="Example 1: Personalizing an Outbound Call">
  <Info>
    **Scenario**: Notifying customers about a service upgrade.
  </Info>

  1. **Variables**:
     * **Pre-call Variables**:
       * `customerName` (Text)
       * `currentPlan` (Text)
     * **Collected In-call Variables**:
       * `interested` (Boolean)
  2. **Script**: "Hello , we're excited to inform you about an upgrade to your  plan."
  3. **Collect Interest**:
     * Question: "Would you like to hear more about this upgrade?"
     * Store response in `interested` (Boolean).
  4. **Implement Conditional Logic**:
     * If **`interested`** is **true**, proceed with details.
     * If **false**, thank the customer and end the call.

  <Note>
    **Lead Import Tip**\
    Use the platform to import leads with the `customerName` and `currentPlan` variables populated.
  </Note>
</Card>

<br />

<Card title="Example 2: Scheduling Multiple Dates">
  <Info>
    **Scenario**: Collecting multiple available dates from a customer.
  </Info>

  1. **Variable**:
     * `availableDates` (Date & Time)
     * **Allow Multiple Entries**: Enabled.
  2. **Script**: "Please provide the dates you are available for the meeting."
  3. **Collect Dates**:
     * The system allows the customer to provide multiple dates, which are stored in the `availableDates` variable.
  4. **Usage**:
     * The collected dates can be used to schedule meetings or appointments.
</Card>

<br />

<Card title="Example 3: Dynamic Survey with Conditional Logic">
  <Info>
    **Scenario**: Gathering customer feedback.
  </Info>

  1. **Ask Satisfaction Score**:
     * Question: "On a scale of 1 to 5, how satisfied are you with our service?"
     * Store in `satisfactionScore` (Whole Number).
  2. **Conditional Paths**:
     * If **`satisfactionScore >= 4`**, proceed to a node thanking the customer.
     * If **`satisfactionScore < 4`**, proceed to a node asking for improvement suggestions.
  3. **Follow-Up Actions**: Send a personalized email using collected data, thanking them or addressing concerns.
</Card>

***

## Frequently Asked Questions (FAQ)

<AccordionGroup>
  <Accordion title="How do I handle empty variables?">
    Implement checks using conditional logic or assign default values to handle empty variables gracefully.
  </Accordion>

  <Accordion title="Are variable names case-sensitive?">
    Yes, variable names are case-sensitive. Ensure consistency when referencing them.
  </Accordion>

  <Accordion title="Can I change a variable's value during the conversation?">
    Yes, variables can be updated multiple times as the conversation progresses.
  </Accordion>

  <Accordion title="How do I include variables when adding leads via the platform or API?">
    Include variables in the CSV file for platform uploads or in the `callData` field when using the API.
  </Accordion>

  <Accordion title="What is the difference between Pre-call and Collected In-call variables?">
    **Pre-call Variables** are configured before the conversation starts and typically include data imported from external sources or predefined settings. **Collected In-call Variables** are captured or updated during the conversation based on user interactions.
  </Accordion>

  <Accordion title="What happens if I delete a variable that’s in use?">
    Deleting a variable that’s in use can cause errors in your conversation flow. Remove all references before deleting.
  </Accordion>
</AccordionGroup>

***

## Conclusion

Variables are powerful tools that enhance your conversations by making them dynamic and personalized. By effectively using variables, you can:

* **Collect and Store User Inputs**: Gather essential information from users.
* **Personalize Interactions**: Create tailored experiences for each user.
* **Control Conversation Flow**: Direct the conversation based on user responses and data.
* **Integrate External Data**: Incorporate information from other systems for enriched interactions.

<Note>
  Remember to:

  * **Plan Carefully**: Define your variables before building your conversation.
  * **Organize Variables**: Use categories like Pre-call and Collected In-call for better management.
  * **Enhance User Experience**: Use variables to make interactions meaningful.
  * **Test Thoroughly**: Regularly test your conversation to ensure variables work correctly.
  * **Follow Best Practices**: Keep your variables organized and your data secure.
</Note>

***

For additional support, contact our support team at [support@nlpearl.ai](support@nlpearl.ai).

***


# Voice Studio
Source: https://developers.nlpearl.ai/pages/voice_studio

Generate speech from text to hear how a voice sounds, browse the voice library, and clone a voice of your own from a short recording.

Voice Studio is where you work with voices. Write a line, choose who says it, and hear it — then keep the voices you like, or clone one of your own from a short recording and use it across your Pearls.

Open it from **Voice Studio** in the left sidebar.

<Frame>
  <img alt="The Voice Studio screen, with the composer and the controls along the bottom" />
</Frame>

<Note>
  A voice **is** a speaker in a language, so choosing a voice already chooses the language it speaks. That's why there is no separate language selector on this screen.
</Note>

***

### Generating speech

<Steps>
  <Step title="Write what the voice should say">
    Type into the main area of the page. A single take can be up to **4,000 characters**. Past that limit, the page tells you by how much and the **Generate Speech** button stays disabled until you trim it.

    Type `@` anywhere in your text to insert a **speech marker** — a short tag the model reads as an instruction rather than as words. See [Speech markers](#speech-markers) below.

    <Frame>
      <img alt="A draft in the composer, with a breath marker shown as a highlighted chip" />
    </Frame>

    <Tip>
      Once you've picked a voice, the **dice** button fills the draft with an example line written to show that voice off: hesitations, a breath, a number said out loud. Press it again for a different one. Clean sentences sound the same in every voice and tell you very little about the one you picked.
    </Tip>
  </Step>

  <Step title="Choose a voice">
    Click the voice chip in the bar at the bottom of the screen to open the **voice picker**. Browse the library, search, filter, and click a voice to select it. The chip then shows the voice's language flag and its name.

    See [The voice library](#the-voice-library) for what the picker can do.
  </Step>

  <Step title="Set how fast the voice speaks">
    The **speed** control sets the delivery of the line — how slowly or quickly the voice reads it. Five levels are available, from **Very slow** to **Very fast**, with **Medium** as the default.

    <Frame>
      <img alt="The speed control open, showing Very slow, Slow, Medium, Fast and Very fast" />
    </Frame>

    Next to it, **Pearl TTS v2** names the model doing the speaking: our latest, most human-like text-to-speech model, with ultra-low latency, available in 6 languages.
  </Step>

  <Step title="Generate and listen">
    Click **Generate Speech**. Playback starts as soon as the first audio is ready — you don't wait for the whole take to finish generating, which matters for longer texts.

    When the take lands, a card appears with the text that was spoken, the voice that spoke it, and a player. From there you can:

    * **Play, pause and scrub** through the take.
    * **Download** the audio.
    * **Minimize** the card to a single line to get your draft back in full view.

    Generate again to produce a new take — the card is replaced each time, so download anything you want to keep.
  </Step>
</Steps>

***

### Speech markers

Markers are tags the speech model reads as **instructions**, not as words. Type `@` in your draft to open the marker menu at your cursor, then pick one.

<Frame>
  <img alt="The marker menu open at the cursor, offering Laughs and Breath" />
</Frame>

| Marker     | Inserts    | What it does                              |
| ---------- | ---------- | ----------------------------------------- |
| **Laughs** | `[laughs]` | A laugh, where the line lands lightly.    |
| **Breath** | `[breath]` | An audible breath before what comes next. |

<Warning>
  Only the markers listed above are recognised. Any other bracketed tag you type — including one that looks like it should work — is **read out loud, brackets and all**. For a beat in the middle of a sentence, use punctuation, or a `[breath]` mid-clause.
</Warning>

***

### Speaking to a man or a woman

Hebrew writes the same sentence differently depending on who is being addressed: the second person is inflected, so one written line is two different spoken ones.

When you select a Hebrew voice, a **Speaking to** control appears under your draft. Set it to the gender of **the person being spoken to**.

<Note>
  This is the **listener**, not the speaker. The voice's own gender is a property of the voice and is never something you set here. A female voice addressing a man is an ordinary call.
</Note>

The control appears for Hebrew voices only, because it is the only supported language where this changes the delivery.

***

### The voice library

The voice picker is where you browse, filter and manage the voices available to your account.

<Frame>
  <img alt="The voice picker open on the Explore tab, with search, filters and a list of voices" />
</Frame>

It has two tabs:

<CardGroup>
  <Card title="Explore" icon="compass">
    Every voice available to you, for **choosing**: the NLPearl voices, your own clones, and voices other accounts have published.
  </Card>

  <Card title="My voices" icon="star">
    Your account's own list, for **managing**. This is the list your Pearls can pick from.
  </Card>
</CardGroup>

A voice reaches **My voices** in one of two ways: you clone it, or you add it from Explore.

#### Searching and filtering

Search by **name, accent or tag**, and narrow the list with the filters:

* **Language**
* **Accent** — appears once you've picked a language, and only for languages that have accent variants.
* **Gender**

#### Reading a row

Each row shows the language flag, a gender mark, the voice's name, and its language, accent and tags. Some rows also carry a label:

| Label     | Meaning                                                                            |
| --------- | ---------------------------------------------------------------------------------- |
| `private` | Only your account can use it. Every voice you clone starts out private.            |
| `public`  | One of your voices that you've published to the shared library.                    |
| `shared`  | Published by another account, rather than one of your own.                         |
| `yours`   | One of your own clones (shown in Explore, where the rest of the list isn't yours). |

Click the **play** button on a row to hear the voice without leaving the picker. A voice you cloned plays back the same line you auditioned when you created it, so what you hear here is what you approved.

<Note>
  Playing a voice doesn't generate a new take — the clip is rendered once and reused, so every play after the first is instant.
</Note>

#### Managing a voice

The **⋯** button on a row opens its menu:

<Frame>
  <img alt="The menu on a voice row, with Copy voice ID and Add to my voices" />
</Frame>

| Action                 | What it does                                                                                                                        |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Copy voice ID**      | Copies the voice's identifier.                                                                                                      |
| **Publish to library** | Publishes the voice to the shared library. Offered only on your own private voices — see [Publishing a voice](#publishing-a-voice). |
| **Add to my voices**   | Adds the voice to your account's list, so your Pearls can use it.                                                                   |
| **Delete voice**       | Removes the voice from your account's list.                                                                                         |

<Warning>
  **Delete voice** removes the voice from *your list* — it does not destroy the voice. The voice stays in the library and other accounts keep it. What changes is that your Pearls can no longer be set to it, and **any agent already using it loses its voice**.
</Warning>

***

### Cloning a voice

You can build a voice from a short recording of someone speaking, then use it like any other voice on the platform.

Open the voice picker and click **Clone a voice**.

<Steps>
  <Step title="Provide one recording">
    Drag an audio file anywhere onto the popup, click **Browse files**, or click **Record audio** to record straight from your microphone.

    <Frame>
      <img alt="The first step of Clone a voice, asking for one recording" />
    </Frame>

    |               |                          |
    | ------------- | ------------------------ |
    | **Length**    | 5 to 60 seconds          |
    | **File size** | Up to 20 MB              |
    | **Formats**   | WAV, MP3, M4A, OGG, WEBM |
    | **How many**  | One                      |

    <Note>
      A voice is built from **a single recording**. Dropping a second file replaces the first rather than adding to it.
    </Note>

    For the best result, use **clear, continuous speech with no background noise** — one person talking, no music, no overlapping voices.
  </Step>

  <Step title="Describe the voice">
    | Field        | Required |                                                                                                                         |
    | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
    | **Name**     | Yes      | How the voice appears in your library. Up to 25 characters.                                                             |
    | **Language** | Yes      | The language the speaker is speaking. The voice is built for it — generating in another language won't sound like them. |
    | **Accent**   | No       | Available for English and Spanish.                                                                                      |
    | **Gender**   | No       | Used only to filter the library. It changes nothing about how the voice sounds.                                         |
    | **Tags**     | No       | Up to 3, to make the voice easier to find — for example `warm`, `support`, `news`.                                      |

    <Frame>
      <img alt="The second step of Clone a voice, with the name, language, accent, gender and tags fields" />
    </Frame>
  </Step>

  <Step title="Confirm you have permission">
    You must confirm that the voice in the recording is your own, or that you hold documented written permission from the person whose voice it is, before the voice can be created.

    <Warning>
      Cloning someone's voice without their explicit, documented permission is not permitted. The confirmation is a legal attestation, not a formality.
    </Warning>
  </Step>

  <Step title="Hear it before you keep it">
    Click **Hear this voice** to audition the clone. It reads a short line back to you, so you know what you're keeping before anything is saved.

    <Frame>
      <img alt="The audition, playing a line back in the cloned voice before saving" />
    </Frame>

    If your recording contained little actual speech, the audition tells you how much it measured: the clone still works, but more audio makes a closer match. This is the last moment you can go back and record a longer take.

    <Note>
      Auditioning stores nothing. Closing the popup at this point leaves no voice behind.
    </Note>
  </Step>

  <Step title="Save">
    Click **Save to my voices**. The file uploads, the voice is built — this takes a few seconds — and it appears in **My voices** right away, ready to select on the main screen.
  </Step>
</Steps>

<Note>
  If the recording is refused, the message tells you how much usable speech was actually measured. That's the difference between *try again* and *record a longer take*.
</Note>

***

### Publishing a voice

Publishing puts one of your voices into the **shared library**, where every account on the platform can use it.

<Warning>
  **Publishing cannot be undone.** Once a voice is published, it stays in the shared library and you cannot withdraw it. Publish only voices you are certain you want to share, and only if the permission you hold for that voice covers it.
</Warning>

Publishing is offered from the voice's row menu in the picker, and only while the voice is still private. Once published, the option is gone.

***

### Using your voices in a Pearl

The voices in **My voices** are the ones your Pearls can be set to.

<Steps>
  <Step title="Add the voice to your list">
    Clone it, or add it from **Explore**.
  </Step>

  <Step title="Open your Pearl's settings">
    Go to **Pearl Settings → Agent Names, Languages & Voices**.
  </Step>

  <Step title="Pick it for an agent">
    Open the agent's **Voice** dropdown and select it. For the languages Voice Studio supports, the dropdown also offers **Open Voice Studio** at the bottom of the list, which opens the studio in a new tab so you can clone or audition a voice without losing your place in the form.

    <Frame>
      <img alt="An agent's voice dropdown in Pearl Settings, with Open Voice Studio at the bottom of the list" />
    </Frame>
  </Step>
</Steps>

<Note>
  A voice cloned in one browser tab appears in the other tabs you have open, without reloading the platform.
</Note>

See [Voices and Languages](/pages/languages) for how agents, languages and voices work together in a Pearl.

***

### Supported languages

Voice Studio generates speech in the following languages:

| Language    | Accents                                                |
| ----------- | ------------------------------------------------------ |
| **English** | American, British, Australian, Canadian, Irish, Indian |
| **Spanish** | Castilian, Mexican, Argentinian, Colombian, Venezuelan |
| **French**  | —                                                      |
| **German**  | —                                                      |
| **Italian** | —                                                      |
| **Hebrew**  | —                                                      |

<Note>
  This is the list of languages the speech model currently serves, which is narrower than the full set of languages a Pearl can speak. See [Voices and Languages](/pages/languages) for everything the platform supports.
</Note>

<Info>
  Your library may look empty the first time you open it. Only voices the speech model can currently use are listed — clone one from a recording to get started.
</Info>

***

<CardGroup>
  <Card title="Voices and Languages" icon="language" href="/pages/languages">
    Configure agents, languages and voices for a Pearl.
  </Card>

  <Card title="Pearl Settings" icon="user-gear" href="/pages/agent_customization">
    Everything you can configure on a Pearl, including its agents.
  </Card>
</CardGroup>


# Webhooks
Source: https://developers.nlpearl.ai/pages/webhooks

Understand the webhook payloads sent by NLPearl.AI for lead and call events in real time.

<div>
  <Frame>
    <div>
      <img alt="Webhooks documentation light mode" />
    </div>
  </Frame>
</div>

<div>
  <Frame>
    <div>
      <img alt="Webhooks documentation dark mode" />
    </div>
  </Frame>
</div>

***

## 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.

<CardGroup>
  <Card title="Inbound Pearl" icon="phone-arrow-down-left">
    Access to the **Call Webhook** only.
  </Card>

  <Card title="Outbound Pearl" icon="phone-arrow-up-right">
    Access to both the **Call Webhook** and the **Lead Webhook**.
  </Card>
</CardGroup>

<Info>
  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.
</Info>

<Tip>
  Use webhooks only when an **external tool needs event notifications**. For actual automations tied to how a call ended, rely on **[Post-Call Actions](/pages/postcall)** instead.
</Tip>

***

## Webhook Types

<CardGroup>
  <Card title="Call Webhook" icon="phone" href="#call-webhook-payload">
    Triggered at the start and end of every call. Available for both Inbound and Outbound Pearls.
  </Card>

  <Card title="Lead Webhook" icon="user" href="#lead-webhook-payload">
    Triggered every time a lead changes status. Available for Outbound Pearls only.
  </Card>
</CardGroup>

***

## Webhook Version

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

<Tabs>
  <Tab title="V2 (Latest)">
    <Note>
      In V2, all JSON payload keys use **camelCase** (e.g. `pearlId`, `phoneNumber`, `collectedData`).
    </Note>

    ***

    ## 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](#conversation-statuses) below.                   |
    | `status`             | `int (enum)`     | The overall technical status of the call. See [Call Statuses](#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](#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](#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](#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.                                |

    <Note>
      The definition of **Success** and **NotSuccessful** is configured at the Pearl level. Refer to the [Create a Pearl](/pages/create_pearl#pearl-name) page for more details.
    </Note>

    ### 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

    ```json theme={null}
    {
      "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](#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.                             |

    <Note>
      The definition of **Success** and **NotSuccessful** is set at the Pearl level. Refer to the [Create a Pearl](/pages/create_pearl#pearl-name) page for details.
    </Note>

    ### Example Payload

    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="V1">
    <Warning>
      **V1 is a legacy version.** We recommend migrating to V2 for access to additional fields like `collectedData` on leads and a more consistent structure.
    </Warning>

    <Note>
      In V1, all JSON payload keys use **PascalCase** (e.g. `PearlId`, `PhoneNumber`, `CollectedInfo`).
    </Note>

    ***

    ## 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](#conversation-statuses-v1) below.                   |
    | `Status`             | `int (enum)`     | The overall technical status of the call. See [Call Statuses](#call-statuses-v1) 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](#transcript-message-v1) below. |
    | `Summary`            | `string`         | A concise AI-generated summary of the conversation.                                                             |
    | `CollectedInfo`      | `object[]`       | Structured data points collected during the call. See [Collected Info](#collected-info-v1) 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](#sentiment-values-v1) below.        |
    | `LeadId`             | `string`         | The unique identifier of the associated lead, if applicable. Otherwise `null`.                                  |

    <Note>
      V1 includes an additional `RelatedId` field referencing the inbound or outbound entity. This field does not exist in V2.
    </Note>

    ### 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

    ```json theme={null}
    {
      "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](#lead-statuses-v1) 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.           |

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

    ### 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

    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>
</Tabs>

***

## 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.

<Steps>
  <Step title="Open Your Campaign Settings">
    Navigate to the Pearl or outbound campaign you want to configure and open its settings panel.
  </Step>

  <Step title="Locate the Webhook Section">
    Scroll to the **Webhooks** section in the configuration form.

    <div>
      <Frame>
        <div>
          <img alt="Webhook settings on light mode" />
        </div>
      </Frame>
    </div>

    <div>
      <Frame>
        <div>
          <img alt="Webhook settings on dark mode" />
        </div>
      </Frame>
    </div>
  </Step>

  <Step title="Turn Webhooks On">
    Toggle the **Webhooks** setting to **On**. Webhooks are off by default, and the URL fields only appear once it's enabled.
  </Step>

  <Step title="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.

    <Info>
      * **Call Webhook** - available for **Inbound** and **Outbound** Pearls.
      * **Lead Webhook** - available for **Outbound** Pearls only.
    </Info>
  </Step>

  <Step title="Authenticate Your Webhooks (Optional)">
    For each webhook (Call and Lead), you can attach a **Credential** so NLPearl.AI authenticates its requests to your endpoint:

    1. Enable the **Credentials** toggle under the webhook URL.
    2. 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.

    <Tip>
      Credentials work the same way as in the [API Node](/pages/api_action#credentials-authentication). A token created here can be reused across your webhooks.
    </Tip>
  </Step>
</Steps>

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

***

<CardGroup>
  <Card title="Outbound Campaigns" icon="phone-arrow-up-right" href="/pages/outbound">
    Learn how to create and configure outbound campaigns, including webhook setup.
  </Card>

  <Card title="API Reference – Get Calls" icon="code" href="/api-reference/v2/call/get-call">
    Explore the full call object structure returned by the API.
  </Card>
</CardGroup>