> 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.md).

# Contacts & Chats APIs

### 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

<details>

<summary><strong>What is the difference between a segment and a group?</strong></summary>

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.

</details>

<details>

<summary><strong>The GET — Chats / Leads Listing uses a different auth header. Why?</strong></summary>

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.

</details>

<details>

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

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.

</details>

<details>

<summary><strong>Can I import contacts who are not on WhatsApp?</strong></summary>

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.

</details>

<details>

<summary><strong>What does the applicableFilters field do in POST — Get User Inbox?</strong></summary>

`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:

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

</details>

### Support

If everything is correct and you are still unable to move forward, write to us at <support@botpenguin.com>. We will respond back within 48 business hours.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.botpenguin.com/api-documentation/contacts-and-chats-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.