# BotPenguin MCP MCP

> BotPenguin manages your live chat and chatbot conversations through natural language commands. Use this MCP to list contacts, deep-dive into full chat history, send messages, and even trigger verification SMS codes for lead qualification.

## Overview
- **Category:** customer-support
- **Price:** Free
- **Tags:** chatbot-builder, lead-generation, whatsapp-automation, conversational-marketing, contact-management, customer-engagement

## Description

Need to manage customer leads without jumping between five different dashboards? This connector lets you handle entire support workflows using just your agent's conversational ability. You can pull lists of all existing contacts or search for details on a single person. If a user needs help, you retrieve the full message history and use that context to figure out what went wrong. Need to talk to a human? List available team agents. And if a lead needs verification before moving to sales, your agent can trigger an OTP SMS right from the conversation flow. It’s all about making sure every interaction, whether support or lead-gen, is fully managed and documented. Connecting this through Vinkius gives you access to these tools without ever leaving your AI client.

## Tools

### get_chat_history
Retrieves all past messages from a specific chat session ID.

### get_contact
Fetches all available information for one particular contact record.

### list_agents
Provides a directory of human operators and agents configured in the system.

### list_chats
Gives you a list of all currently active chat sessions happening right now.

### list_contacts
Lists all contacts and leads managed by the chatbot system.

### list_tags
Shows every tag or label you can assign to a contact for better segmentation.

### send_message
Sends a custom message directly into an existing, active chat conversation.

### send_otp
Sends a one-time password SMS to verify a user's provided phone number.

## Prompt Examples

**Prompt:** 
```
List the most recent contacts in BotPenguin.
```

**Response:** 
```
I've retrieved your contacts. You have 3 recent leads: 'John Doe' (john@example.com), 'Jane Smith' (+15550199), and 'Alice Brown'.
```

**Prompt:** 
```
Show the chat history for chat session chat_123.
```

**Response:** 
```
Retrieving the history... The user asked for 'Pricing plans', the bot sent the 'Pricing Menu', and the user requested to speak to a human.
```

**Prompt:** 
```
Send an OTP SMS to +1555998877.
```

**Response:** 
```
OTP SMS successfully triggered for +1555998877. The user should receive their verification code momentarily.
```

## Capabilities

### Manage Lead Records
List all recorded contacts or fetch the specific details for any lead by searching their name.

### Review Chat Conversations
View entire message threads, whether they are active now or happened months ago, to understand the full context of a conversation.

### Automate Messaging
Send messages directly into an ongoing chat session to guide the user or escalate information programmatically.

### Verify User Identity
Programmatically trigger a one-time password (OTP) SMS to verify a user's phone number.

### Map Support Team Structure
Get a list of all human agents and the configured tags, ensuring leads go to the right person every time.

## Use Cases

### Onboarding a New Lead
A sales rep needs to know everything about Jane Doe. They ask their agent to run `get_contact` and `list_tags`. The agent pulls her details, shows the tags (like 'High Value'), and tells the rep where she stands in the funnel.

### Handling a Support Escalation
A user complains about a billing error. The support manager asks their agent to use `list_chats` to find the relevant session, then run `get_chat_history` on that ID so they can see the initial complaint and what steps were already taken.

### Verifying Contact Information
A marketing campaign captured a new phone number. To validate it before adding them to a list, the agent triggers `send_otp`. The user gets the code via SMS, and the system verifies the account.

### Targeted Follow-Up
A chat session closed but needs one last piece of info. Instead of leaving a note for someone else to follow up on, the agent uses `send_message` to send a quick, direct question into the now-closed conversation thread.

## Benefits

- Never miss context again. Use `get_chat_history` to pull full message threads, letting you know exactly what was said weeks ago when reviewing a lead today.
- Speed up qualification. Instead of manually checking CRMs, use `list_contacts` and then call `get_contact` to gather all necessary details on demand.
- Automate the handoff. When your agent detects an issue, it can run `send_otp` to verify the user's phone number instantly, moving them closer to a sale.
- Keep leads organized. Running `list_tags` and then using `get_contact` lets you segment users based on labels without manual data entry.
- Control the conversation flow. You can use `send_message` to send targeted instructions or follow-ups directly into an active chat, keeping the user engaged.

## How It Works

The bottom line is, you give your AI client permission to use these tools so that complex chat management happens with a simple request.

1. Subscribe to this MCP and input your BotPenguin API token.
2. Your AI client connects and authenticates with the platform's APIs.
3. You prompt your agent: 'List all leads tagged 'High Priority'.' The agent executes the tool call, retrieves the data, and presents it back to you.

## Frequently Asked Questions

**How do I find out what tags are available in BotPenguin MCP?**
Run the `list_tags` tool. This simply shows every configured tag label, letting you know how your leads are currently being segmented.

**Can I use get_contact to find a lead's chat history?**
No. The `get_chat_history` tool requires an active chat session ID. You must first run `list_chats` or be provided the specific conversation ID.

**What is the purpose of send_otp in BotPenguin MCP?**
The `send_otp` tool sends a one-time password SMS to verify a phone number. This is crucial for confirming that a lead actually owns the contact information you have.

**Does list_agents tell me which agents are available 24/7?**
`list_agents` shows all configured human operators in the system. It confirms who *can* handle chats, but it doesn't guarantee their real-time availability.

**What are the best practices for bulk messaging when I use send_message?**
The MCP handles API rate limiting automatically, so you don't need to worry about hitting hard limits. If your agent sends too many messages too fast, it will receive a specific error code. It's recommended to batch message sends rather than sending them one by one for reliable bulk outreach.

**Can I filter the leads when calling list_contacts?**
Yes, you can pass optional filters to narrow down your search results effectively. You can typically refine the contact list by criteria like date range or specific lead status. This helps your agent target only the most relevant contacts.

**Does get_chat_history retrieve media content?**
Yes, the history function pulls more than just text; it includes metadata for attached files and images. Your agent can process rich content alongside the conversation transcript to understand the full context of a lead's interaction.

**How do I determine if a chat session is active using list_chats?**
The output from list_chats provides the current status for every listed session. You can filter results by 'active' or 'ended' status directly in your agent workflow. This helps you manage which conversations need immediate human attention.

**Can I search for a specific lead or contact by name?**
Yes! Use the `list_contacts` tool and provide the `search_text` parameter with the name, email, or details you are looking for. The agent will return the matching profiles.

**How do I review the chat history of a conversation?**
First, use `list_chats` to find the active or historical session. Then, use `get_chat_history` with the Chat ID to retrieve the full log of messages.

**Can I send an OTP SMS to a user?**
Yes. Use the `send_otp` action and provide the user's phone number (with the country code). BotPenguin will handle the integration to send the verification code.