> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wassist.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Bring Your Own Agent
> Connect your existing AI agent to WhatsApp through Wassist's infrastructure
Bring Your Own Agent (BYOA) mode lets you use your own AI agent while Wassist handles all the WhatsApp complexity. You get full control over the conversation logic, while we manage typing indicators, message formatting, read receipts, and the entire WhatsApp Business API integration.
## When to Use BYOA
This approach is ideal when you:
* Already have an AI agent built with your preferred framework (LangChain, CrewAI, custom, etc.)
* Want complete control over conversation flow and business logic
* Need to integrate with existing systems that your agent already connects to
* Don't want to deal with WhatsApp's messaging quirks and delivery mechanics
With BYOA, you focus entirely on your agent's intelligence. Wassist handles the WhatsApp side—typing indicators, message types, read receipts, delivery status, and conversational flow.
## How It Works
```mermaid theme={null}
sequenceDiagram
participant User as WhatsApp Customer
participant W as Wassist "Agent"
participant Agent as Your Agent
User->>W: Sends message
W->>Agent: Webhook with message (tool call)
Agent->>Agent: Process with your own Agent
Agent->>W: Webhook Response (tool response)
W->>W: Run Wassist loop
W->>User: Deliver message
Agent->>W: Send content to reply_callback
W->>User: Deliver message
```
The flow is simple:
1. A customer sends a message on WhatsApp
2. Wassist receives it and calls your webhook with the message details (tool call)
3. Your agent processes the message however you want
4. Your agent responds to the webhook with the response (tool response)
5. Wassist formats and delivers the response to WhatsApp (message delivered)
If your processing takes too long, you can respond to the webhook with a intermediate message to keep the engaged, and use the reply\_callback to send more messages later.
reply\_callback is a url available for 24 hours you can use to send more messages to the customer.
## Setup
### Step 1: Create a Wassist Agent
Even in BYOA mode, you need to create a Wassist agent. This agent acts as a passthrough that routes all messages to your external agent.
1. Go to [Agents](https://wassist.app/agents) and click **Create Agent**
2. Select **Bring Your Own Agent** as the creation method
3. Configure your webhook URL (where Wassist will send incoming messages)
4. Save and deploy
See [Create BYOA Agent](../api-reference/agents/byoa) for more information. The following is an example request:
```bash theme={null}
curl -X POST https://wassist.app/api/v1/agents/byoa/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"webhookUrl": "https://your-server.com/webhook",
}'
```
### Step 2: Implement Your Webhook
Your webhook receives a POST request for each incoming message with the following structure:
```json theme={null}
{
"message": "Hello, I need help with my order",
"image": "https://media.wassist.app/...", // null if no image
"phone_number": "+1234567890",
"reply_callback": "https://wassist.app/api/callback/xyz789"
}
```
| Field | Type | Description |
| ---------------- | -------------- | ------------------------------------------- |
| `message` | string | The text content of the customers's message |
| `image` | string \| null | URL to the image if the customers sent one |
| `phone_number` | string | The customers's WhatsApp phone number |
| `reply_callback` | string | One-time URL to send your response |
### Step 3: Handle the Response
After your agent processes the message, you have two options for responding:
Send the response to the webhook with the response (tool response)
For example:
```json theme={null}
{
"type": "message",
"content": "I found your order #12345. It shipped yesterday and should arrive by Friday."
}
```
Wassist will send this message directly to the WhatsApp customer.
We accept any content in the response, including any json object.
You can also instruct the agent to not reply with the response:
```json theme={null}
{
"content": "No CUSTOMER message reply"
}
```
The reply callback is URL that you can use to send more messages to the custoemr at any future point within 24 hours.
Much like the webhook response, you can send any content to the reply callback, including any json object.
```bash theme={null}
curl -X POST "https://wassist.app/api/callback/xyz789" \
-H "Content-Type: application/json" \
-d '{
"content": "I found your order #12345. It shipped yesterday and should arrive by Friday."
}'
```
### Step 4: Test Your Integration
You can test your integration by sending a message to the Wassist agent and checking the response.
When creating the agent, `connectUrl` will be provided in the agent object.
Visit this url to test your integration in the Wassist sandbox number.
This can also be viewed in the agent's overview page. To see this:
* Go to [Agents](https://wassist.app/agents) and click on the agent you created
* Click on the agent name to view the overview page
* On the left sidebar, click on the "Test Agent" button
## Rich Content Responses
All messages will be formatted specially for WhatsApp. Including:
* Image messages
* Send an image url
* Video messages
* Send a video url
* Audio messages
* Send an audio url
* Document messages
* Send a document url
* Contact cards
* Send a contact name and phone number
* Location messages
* Send a latitude and longitude
## Accessing Conversation History
Your agent can retrieve the full conversation context using the Conversations API:
Retrieve full conversation history for context.
## Example Implementation
Here's a complete example using Python and Flask:
```python theme={null}
from flask import Flask, request, jsonify
import requests
from your_agent import process_message # Your agent implementation
app = Flask(__name__)
@app.route("/webhook", methods=["POST"])
def handle_webhook():
data = request.json
message = data["message"]
customer = data["phone_number"]
# Process with your agent
response = process_message(
message=message,
customer=customer,
)
return jsonify(response)
if __name__ == "__main__":
app.run(port=8000)
```
## Best Practices
WhatsApp customers expect fast responses. Aim to respond to the webhook within 5s.
## What Wassist Handles For You
When you use BYOA, Wassist automatically manages:
| Feature | Description |
| ---------------------- | ------------------------------------------------- |
| **Typing Indicators** | Shows "typing..." while your agent processes |
| **Read Receipts** | Marks messages as read at the right time |
| **Message Formatting** | Converts your responses to proper WhatsApp format |
| **Media Handling** | Uploads and hosts images, documents, audio |
| **Delivery Status** | Tracks sent, delivered, and read status |
| **Rate Limiting** | Respects WhatsApp's messaging limits |
| **Error Recovery** | Retries failed message deliveries |
| **Session Management** | Handles 24-hour messaging windows |
You focus on the intelligence. We focus on WhatsApp.
***
## Next Steps
Learn how to fetch and manage conversation history.
Explore all supported message formats.