# Get Started

Check out the documentation to get the most out of NewLead AI!

## [App](/app-app.newlead.ai)

Create, configure and deploy a bot in seconds.

## [Api](/api-api.newlead.ai)

Maximise the performance by integrating the bot with your business


# App - app.newlead.ai


# Dashboard

https\://app.newlead.ai/Home

Get an overview of the performance of your bots.

* New leads in the last 24 hours
* New leads in the last 30 days


# My Bots

https\://app.newlead.ai/Bot

Create new bots in seconds and start automating your sales & marketing efforts.

At the moment you can connect your bot to the following channels:

* Whatsapp
* Instagram (coming soon)


# Leads

https\://app.newlead.ai/Leads

View all the conversations of your bots in real time.


# API - api.newlead.ai

Our API allows you to automate tasks and integrate the bots into your system.

There are different endpoints:

* [/Bot.](/api-api.newlead.ai/bots) Actions related to bot creation and settings.
* [/Lead.](/api-api.newlead.ai/leads) Get details about the leads integraction with the bots
* [/Messages.](/api-api.newlead.ai/messages) It contains methods to send messages to your leads.
* [/Webhooks.](/api-api.newlead.ai/webhooks) Be notified about important events.

Before you start using the API, you will need to [get an Api Key.](/api-api.newlead.ai/authentication)


# Authentication

You can find your API details under the API section in your NewLead account.

## Endpoint

{% embed url="<https://api.newlead.ai>" %}

## Api Key

You can find your api key here: <https://app.newlead.ai/Api>

All requests to the api must include the following Authorization header:

```json
{ "Authorization" : "Bearer YourApiKey" }
```


# Bots

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Bot/Create**

```json
{
  "name": "string",
  "instructions": "string",
  "voiceId": "string",
  "followUpInstructions": "string",
  "manual": "bool",
  "randomAudios": "bool"
}

//Returns the ID of the newly created bot
```

* Name: Name of the bot.
* Instructions: Text to describe the behaviour of the bot.
* VoiceId: Id of the voice for the bot to use. [How do I find it?](https://docs.newlead.ai/faq#how-do-i-change-the-voice-of-my-bot) You can leave it empty to disable sending voice messages.
* FollowUpInstructions: The bot will attempt to reactivate the conversation if it has been inactive for 20 hours. Leave empty to disable this feature.
* Manual: False for the bot to reply automatically. True for manual conversations.
* RandomAudios: Adds a human touch to conversations by seamlessly integrating random voice messages, making your chats more engaging and lively.

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Bot/Update**

```json
{
  "id": "int", // ID of the bot to update
  "name": "string",
  "instructions": "string",
  "followUpInstructions": "string",
  "voiceId": "string",
  "manual": "bool",
  "randomAudios": "bool"
}

//Returns a bool indicating whether the update was successful or not
```

## <mark style="background-color:blue;">**GET**</mark>**&#x20;Bot/Get**

Returns the list of bots

```json
[{
  "id": "int",
  "name": "string"
}]

```

## <mark style="background-color:blue;">**GET**</mark>**&#x20;Bot/Get/{botId}**

Returns the bot with the specified bot ID

```json
{
  "id": "int",
  "name": "string",
  "instructions": "string",
  "voiceId": "string",
  "followUpInstructions": "string",
  "manual": "bool",
  "randomAudios": "bool",
  "limit": "int?",
  "test": "bool",
  "userId": "string",
}

```

## <mark style="background-color:blue;">**GET**</mark>**&#x20;Bot/Get/{botId}/links**

Returns the bot accounts linked to the specified bot ID

```json
[{
  "id": "int", // This is the BotAccountID
  "botId": "int",
  "name": "string"
}]
```

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Bot/Disconnect/{botId}**

Unlinks the specified bot from any integration

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Bot/Skill/Add**

**Adds a skill to the specified bot**

The request body must contain the skill definition. Samples:

```json
{
  "botId": int,
  "function": {
    "name": "get_weather",
    "description": "Determine weather in my location",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "The city and state e.g. San Francisco, CA"
        },
        "unit": {
          "type": "string",
          "enum": [
            "c",
            "f"
          ]
        }
      },
      "required": [
        "location"
      ]
    }
  }
}
```

```json
{
  "botId": int,
  "function": {
    "name": "get_stock_price",
    "description": "Get the current stock price",
    "parameters": {
      "type": "object",
      "properties": {
        "symbol": {
          "type": "string",
          "description": "The stock symbol"
        }
      },
      "required": [
        "symbol"
      ]
    }
  }
}
```

## <mark style="background-color:blue;">**GET**</mark>**&#x20;Bot/Get/{botId}/skills**

Gets the skills of the specified bot ID

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Bot/Skill/Remove**

**Removed the specified skill from the specified bot.**

The request body must contain the name of the skill to remove. Samples:

<pre class="language-json"><code class="lang-json"><strong>{ 
</strong><strong>"functionName": "string",
</strong><strong>"botId": int 
</strong><strong>}
</strong></code></pre>


# Link bot to channel

Once you have created a bot you can deploy it to Whatsapp and Instagram in seconds.

## Link to Whatsapp

Once a bot has been created, you need to call the following url:

<https://app.newlead.ai/api/link?botId=><mark style="color:purple;">**BOT\_ID&**</mark>\&userId=<mark style="color:purple;">**USER\_ID**</mark>\&successUrl=<mark style="color:purple;">**SUCCESS\_REDIRECT\_URL**</mark>& failureUrl=<mark style="color:purple;">**FAILURE\_REDIRECT\_URL**</mark>

Replacing the below parameters:

* BOT\_ID: Id of the bot to link. You can obtain it after creating a bot [using the Bot/Create request](/api-api.newlead.ai/bots#post-bot-create)
* USER\_ID: The userId associated to the bot. You can get it from [Bot/Get/BOT\_ID](/api-api.newlead.ai/bots#get-bot-get-botid).
* SUCCESS\_REDIRECT\_URL: Url to be redirected to after the bot has been linked successfully.
* FAILURE\_REDIRECT\_URL: URL to be redirected when there was a problem linking the bot

In order to confirm that the bot is linked [you can call /Bot/BOT\_ID/Links](/api-api.newlead.ai/bots#get-bot-get-botid-links).

## Link to Instagram

Coming soon.


# Leads

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Lead/Create**

```json
{
  "botId": "int",
  "name": "string",
  "destination": "string",
  "test": "bool"
}

// Returns ID of the newly created lead.
```

* BotId: ID of the bot associated to the lead.&#x20;
* Name: Name of the lead.&#x20;
* Destination: Identifier of the lead:
  * Whatsapp: Phone number with extension code. Only digits, no blank spaces.
  * Instagram: User handle.
* Test: It is a test lead or a real one.

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Lead/Update/Manual**

```json
{
  "id": "int",
  "manual": "bool",
}

//Returns a bool indicating whether the update was successful or not
```

* Id: ID of the lead to update
* Manual: False for the bot to reply automatically. True for manual conversations. It only applies to the specified lead. If the "manual" setting for the bot is enabled, this setting is ignored at lead level.

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Lead/RemoveTest**

Removes all the test leads associated to the bot

```json
{
  "botId": "int",
}
```

* BotId: Id of the bot

## <mark style="background-color:blue;">**GET**</mark>**&#x20;Lead/Get/{botId}**

Returns the leads that belong to the specified bot ID

```json
[{
  "id": "int",
  "botAccountId": "int",
  "destination": "string",
  "createdOn": "DateTime",
  "updatedOn": "DateTime",
  "unread": "bool",
  "retargeted": "bool",
  "manual": "bool",
  "name": "string",
  "lastMessageReceivedOn": "DateTime?"
}]
```


# Messages

## <mark style="background-color:blue;">**GET**</mark>**&#x20;Get/{leadId}**

Returns the messages for the specified lead ID

```json
[{
  "id": "int",
  "leadId": "int",
  "bot": "bool",
  "type": "string",
  "message": "string",
  "url": "string",
  "createdOn": "DateTime",
  "manual": "bool"
}]
```

* Id: Message identifier
* LeadId: Lead identifier
* Bot: Whether the message was sent by the bot or by the lead.
* Type:
  * "text"
  * "audio"
  * "video"
  * "image:
  * "document"
* Message: Content of the message.
* Url: When type is not "text" it contains the url of the media. Empty when type is "text".
* CreatedOn: Moment when the message was sent.
* Manual: Whether message was sent manually or by the bot.

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Message/Send**

**This request can only be used when the lead has sent a message in the latst 24 hours. If you want to initiate a conversation,** [**Message/SendTemplate**](#post-message-sendtemplate) **must be used instead.**

```json
{
  "leadId": "int",
  "text": "string",
  "type": "MessageType", //int
  "url": "string"
}

//Returns a bool indicating whether the message was successfully sent or not
```

* LeadId: Id of the lead to send the message to.
* Text: Content of the message
* MessageType:&#x20;
  * Text = 1
  * Image = 2
  * Video = 3
  * Document = 4
  * Audio = 5
* Url: When not sending a text message, this field should contain the url of the media to be sent.

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Message/SendTemplate**

**This request should only be used when the lead has not sent any message in the last 24 hours.**

**NOTE: For Whatsapp, this request can take longer than expected since Meta verifies and approves the content of the message before sending it.**

```json
{
  "leadId": "int",
  "text": "string"
}

//Returns a bool indicating whether the message was successfully sent or not
```

* LeadId: Id of the lead to send the message to.
* Text: Content of the message


# Webhooks

Get notified about events related to your bots

## <mark style="background-color:purple;">**POST**</mark>**&#x20;Webhook/UpdateEndpoint**

Updates the URL where NewLead will send all even notifications

```json
"your_webhook_url"
```

You can also [update it directly from your NewLead account](https://app.newlead.ai/Api)

## Events

#### New Message Received

```json
{
  "message": {
    "id": "int",
    "leadId": "int",
    "bot": "bool",
    "type": "string",
    "message": "string",
    "url": "string",
    "createdOn": "DateTime",
    "manual": "bool"
  },
  "botId": "int"
}

```

#### New Lead

```json
{
  "lead": {
    "id": "int",
    "botAccountId": "int",
    "destination": "string",
    "createdOn": "DateTime",
    "updatedOn": "DateTime",
    "unread": "bool",
    "retargeted": "bool",
    "manual": "bool",
    "name": "string",
    "lastMessageReceivedOn": "DateTime?"
  },
  "botId": "int"
}

```


# Give it a try!

Are you ready to start working

Start marking requests right away:

{% embed url="<https://api.newlead.ai/swagger/index.html>" %}

1. [Get your api key](/api-api.newlead.ai/authentication)
2. Enter it into Swagger UI
3. Start making requests!

<figure><img src="https://1831028751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLQ38wrirJEJWBBH7PVbE%2Fuploads%2FqeYRR460jZbK1HJQUz94%2Fimage.png?alt=media&amp;token=54d441da-c18f-4ef5-8dfa-c529488f9737" alt=""><figcaption><p>Click on Authorize</p></figcaption></figure>

<figure><img src="https://1831028751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLQ38wrirJEJWBBH7PVbE%2Fuploads%2FTzydphQWSQRoGd1ymaQu%2Fimage.png?alt=media&amp;token=cb512a85-6304-46d8-8699-406150c3168e" alt=""><figcaption><p>Enter your API Key here</p></figcaption></figure>

<figure><img src="https://1831028751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLQ38wrirJEJWBBH7PVbE%2Fuploads%2FHXJ7lkpznw33llYgRLwa%2Fimage.png?alt=media&amp;token=35e690a0-db9a-4787-9e92-799ebb79acbd" alt=""><figcaption><p>Start making requests!</p></figcaption></figure>


# FAQ

## How do I change the voice of my bot?

NewLead uses [ElevenLabs Voice Library](https://elevenlabs.io/app/voice-lab), and you can choose any of their voices by copying their ID and entering in your bot settings or in the API request.

Note: you need to add the voice to Your Library on ElevenLabs in order to see the ID.

<figure><img src="https://1831028751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLQ38wrirJEJWBBH7PVbE%2Fuploads%2FPLb0Ow1hP5aDuAX9EGCz%2FvoiceId.gif?alt=media&amp;token=80aade74-2730-402e-8ba5-e0f3d1dc6235" alt=""><figcaption></figcaption></figure>