PUT — Update Chat / Lead Data

Create or update a lead's profile data in BotPenguin. As soon as a user opens the bot, a UUID is generated for that session — pass it along with the bot and customer IDs to create or update the lead's

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 [e-mail] 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:

<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

{
  "uuid": "7e88d192-9b20-4035-9b68-d4ac3d58a34f",
  "botId": "638d99eeee9e558f1247ae03",
  "customerId": "5fed38e56fb193dcc6c933f5",
  "agentId": "631aa793bcfa100487d13d0d",
  "name": "John Doe",
  "email": "[e-mail]",
  "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

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": "[e-mail]",
    "phone": "9876543210",
    "dialCode": "+91",
    "status": "OPEN",
    "tags": ["lead"],
    "attributes": [{ "key": "plan", "value": "pro" }]
  }'

---

Response

Success — 200 OK

{
  "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" %}

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

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

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

{
  "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" %}

{
  "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 [e-mail]