Bring Your Own Agent - Wassist Docs

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

The flow is simple:

A customer sends a message on WhatsApp
Wassist receives it and calls your webhook with the message details (tool call)
Your agent processes the message however you want
Your agent responds to the webhook with the response (tool response)
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.

Dashboard
API

Go to Agents and click Create Agent
Select Bring Your Own Agent as the creation method
Configure your webhook URL (where Wassist will send incoming messages)
Save and deploy

See Create BYOA Agent for more information. The following is an example request:

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:

{
  "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:

Webhook Response
Reply Callback

Send the response to the webhook with the response (tool response) For example:

{
  "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:

{
  "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.

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

Conversations API

Retrieve full conversation history for context.

Example Implementation

Here’s a complete example using Python and Flask:

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

Respond Quickly

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

Conversations API

Learn how to fetch and manage conversation history.

Message Types

Explore all supported message formats.

Introduction

​When to Use BYOA

​How It Works

​Setup

​Step 1: Create a Wassist Agent

​Step 2: Implement Your Webhook

​Step 3: Handle the Response

​Step 4: Test Your Integration

​Rich Content Responses

​Accessing Conversation History

Conversations API

​Example Implementation

​Best Practices

​What Wassist Handles For You

​Next Steps

Conversations API

Message Types

When to Use BYOA

How It Works

Setup

Step 1: Create a Wassist Agent

Step 2: Implement Your Webhook

Step 3: Handle the Response

Step 4: Test Your Integration

Rich Content Responses

Accessing Conversation History

Example Implementation

Best Practices

What Wassist Handles For You

Next Steps