Contacts & Chats APIs

The Contacts & Chats APIs allow you to programmatically manage contacts, retrieve chat and lead data, update user statuses, and modify chat records from any external system or integration.

Before You Begin

• Generate your API token from More → API Tokens in the Customer Panel

• Base URL: https://api.v7.botpenguin.com

• All requests must include the following headers:

Header	Value
Authorization	Bearer YOUR_API_TOKEN
authtype	Key
Content-Type	application/json

Available APIs

Method	API	Endpoint	Description
GET	Segments / Groups	/inbox/segments	Retrieve all segments and groups configured for your account
GET	Chats / Leads Listing	/inbox/direct/chats	Fetch paginated chat and lead records for a specific bot
POST	Add WhatsApp Contact	/inbox/users/import	Import one or more contacts into your account
POST	Get User Inbox	/inbox/users	Retrieve filtered and paginated contact records from your inbox
PUT	Update User Status	/inbox/users/status-update	Update the status of one or more contacts by User ID
PUT	Update Chat / Lead Data	/inbox/direct/lead	Update profile, tags, attributes, and status of a specific chat or lead

FAQs

What is the difference between a segment and a group?

Segments and groups refer to the same entity in this API. The endpoint /inbox/segments returns objects with a segmentName field — these are the same records you see listed under Inbox → Groups in the Customer Panel. The terms are used interchangeably across the platform.

The GET — Chats / Leads Listing uses a different auth header. Why?

All six endpoints in this section use the same authentication method:

Authorization: Bearer YOUR_API_TOKEN

with authtype: Key.

Refer to the Before You Begin section above for the exact headers to pass.

What is the difference between GET — Chats / Leads Listing and POST — Get User Inbox?

These two endpoints serve different purposes:

GET — Chats / Leads Listing (/inbox/direct/chats) is scoped to a specific bot. It requires a botId and customerId and returns records filtered by type — either lead or non-lead.

POST — Get User Inbox (/inbox/users) operates at the account level. It accepts a rich filter body (tags, segments, bots, agents, date ranges, status, and more) and returns all matching contacts across your account with full profile data.

Use the GET endpoint when you need a quick, bot-specific pull. Use the POST endpoint when you need advanced filtering across your entire contact base.

Can I import contacts who are not on WhatsApp?

Yes. Despite the display name Add WhatsApp Contact, the /inbox/users/import endpoint imports contacts into your general contact base. It is not limited to WhatsApp.

You can import any contact by providing a name, email, phone number, tags, and custom attributes.

What does the applicableFilters field do in POST — Get User Inbox?

applicableFilters is an array that tells the API which filters to actually evaluate.

Simply including a filter field in the body is not enough — you must also add its key to applicableFilters for it to take effect.

For example, if you want to filter by userInteracted, your body must include both:

"userInteracted": true,
"applicableFilters": ["userInteracted"]

Support

If everything is correct and you are still unable to move forward, write to us at [e-mail]. We will respond back within 48 business hours.