> For the complete documentation index, see [llms.txt](https://help.botpenguin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.botpenguin.com/api-documentation/contacts-and-chats-apis/put-update-chat-lead-data.md).

# PUT — Update Chat / Lead Data

### Overview

| Property          | Details                                           |
| ----------------- | ------------------------------------------------- |
| **Method**        | `PUT`                                             |
| **Endpoint**      | `https://api.v7.botpenguin.com/inbox/direct/lead` |
| **Base URL**      | `https://api.v7.botpenguin.com`                   |
| **API Version**   | v7                                                |
| **Auth Required** | Yes — `x-bp-token`                                |
| **Content-Type**  | `application/json`                                |

***

### Authentication

| Header       | Required | Value                     |
| ------------ | -------- | ------------------------- |
| `x-bp-token` | ✅ Yes    | Your BotPenguin API Token |

> 🔑 **Where to get your token:** Contact <support@botpenguin.com> to obtain your `x-bp-token`.

***

### Prerequisites

Before calling this API, ensure you have the following:

1. **UUID** — Generated automatically when a user opens the bot. Retrieve it from the browser's local session storage.
2. **Bot ID & Customer ID** — Available in two places:

From the chatbot page URL:

```
https://page.botpenguin.com/{BotId}/{CustomerId}
```

From the chatbot embed script:

```html
<script id="BotPenguin-messenger-widget" src="https://cdn.botpenguin.com/botpenguin.js" defer>
  BotId,CustomerId
</script>
```

The first value after `defer>` is the `BotId`, the second is the `CustomerId`.

***

### Request

#### Headers

| Header         | Required | Value                     |
| -------------- | -------- | ------------------------- |
| `x-bp-token`   | ✅ Yes    | Your BotPenguin API Token |
| `Content-Type` | ✅ Yes    | `application/json`        |

***

#### Request Body

```json
{
  "uuid": "7e88d192-9b20-4035-9b68-d4ac3d58a34f",
  "botId": "638d99eeee9e558f1247ae03",
  "customerId": "5fed38e56fb193dcc6c933f5",
  "agentId": "631aa793bcfa100487d13d0d",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "9876543210",
  "dialCode": "+91",
  "notes": [
    { "title": "Follow up", "description": "Called on Monday, needs callback." }
  ],
  "status": "OPEN",
  "picture": "https://example.com/avatar.jpg",
  "tags": ["lead", "demo"],
  "attributes": [
    { "key": "plan", "value": "pro" }
  ]
}
```

**Body Fields**

| Field        | Type     | Required | Description                                                                                             |
| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `uuid`       | `string` | ✅ Yes    | Unique session ID of the chat user. Generated when the user opens the bot.                              |
| `botId`      | `string` | ✅ Yes    | Unique ID of the bot.                                                                                   |
| `customerId` | `string` | ✅ Yes    | Unique ID of the customer account.                                                                      |
| `agentId`    | `string` | ❌ No     | ID of the agent to assign to this chat.                                                                 |
| `name`       | `string` | ❌ No     | Full name of the lead.                                                                                  |
| `email`      | `string` | ❌ No     | Email address of the lead.                                                                              |
| `phone`      | `string` | ❌ No     | Phone number of the lead.                                                                               |
| `dialCode`   | `string` | ❌ No     | Country dial code including `+` sign. Example: `+91`.                                                   |
| `notes`      | `array`  | ❌ No     | Additional notes for the chat. Each entry must contain `title` (string) and `description` (string).     |
| `status`     | `string` | ❌ No     | Conversation status. Accepted values: `OPEN`, `INPROGRESS`, `REVIEW`, `ONHOLD`, `DEPENDANCY`, `CLOSED`. |
| `picture`    | `string` | ❌ No     | Valid HTTP URL of the lead's profile picture.                                                           |
| `tags`       | `array`  | ❌ No     | Labels to assign to the chat. Array of strings.                                                         |
| `attributes` | `array`  | ❌ No     | Custom key-value data. Each entry must contain `key` (string) and `value` (string).                     |

***

#### Example Request

```bash
curl 'https://api.v7.botpenguin.com/inbox/direct/lead' \
  -X PUT \
  -H 'x-bp-token: YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "uuid": "7e88d192-9b20-4035-9b68-d4ac3d58a34f",
    "botId": "638d99eeee9e558f1247ae03",
    "customerId": "5fed38e56fb193dcc6c933f5",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "9876543210",
    "dialCode": "+91",
    "status": "OPEN",
    "tags": ["lead"],
    "attributes": [{ "key": "plan", "value": "pro" }]
  }'
```

***

### Response

#### Success — `200 OK`

```json
{
  "success": true,
  "message": "ok",
  "code": 200
}
```

**Response Fields**

| Field     | Type      | Description                                             |
| --------- | --------- | ------------------------------------------------------- |
| `success` | `boolean` | `true` if the lead was created or updated successfully. |
| `message` | `string`  | Status message. Value: `"ok"` on success.               |
| `code`    | `number`  | HTTP status code echo. `200` on success.                |

***

### HTTP Status Codes

{% tabs %} {% tab title="200 OK" %}

```json
{
  "success": true,
  "message": "ok",
  "code": 200
}
```

Request was successful. Lead created or updated. {% endtab %}

{% tab title="400 Bad Request" %}

```json
{
  "success": false,
  "message": "Bad request / invalid parameters",
  "code": 400
}
```

Missing required fields or invalid values. Check `uuid`, `botId`, and `customerId`. {% endtab %}

{% tab title="401 Unauthorized" %}

```json
{
  "success": false,
  "message": "Unauthorized request",
  "code": 401
}
```

`x-bp-token` is missing, invalid, or expired. {% endtab %} {% endtabs %}

***

### Rate Limits

This endpoint is limited to **100 requests per minute** per token, across all plans. Exceeding this returns `429 Too Many Requests`. Use the `Retry-After` response header (in seconds) to schedule your retry.

***

*For questions or issues, contact* [*support@botpenguin.com*](mailto:support@botpenguin.com)