POST https://${chatbotUrl}/message
Headers
| Name | Value |
|---|---|
| Content-Type | application/json |
Body
Depending on the type of conversation the body of the message webhook can be either| Name | Type | Description |
|---|---|---|
lastMessage | last-message | The message of the customer that triggered the chatbot |
conversation | conversation | Data about the conversation between the customer and the restaurant |
location | location | Data about the restaurant if mode is "conversation" |
businessOrganization | Business Organization | Data about the organization and the affilited restaurants if mode is "businessOrganization" |
customer | customer | Data about the customer |
orderDraft | order-draft | Data about the current order draft being processed in the conversation |
orders | order[] | Data about the previous orders of the customer |
mode | "location" | "businessOrganization" | Mode of the conversation. Can be either location or business organization |
Message Webhook Processing
The Message Webhook endpoint (POST /message) is the primary entry point for customer conversations. Every time a customer sends a message via WhatsApp, it flows through this endpoint to LeClerk for processing.
What Happens When a Customer Sends a Message
When a customer types “I’d like to order pizza” or “What are your hours?”, here’s the journey their message takes:- WhatsApp receives the message
- Nexus Backend processes it and gathers context
- LeClerk receives a rich payload with everything needed to respond intelligently
- ChatAgent crafts a personalized response
- Customer receives a helpful reply
The Message Payload
LeClerk doesn’t just receive the raw text—it gets a comprehensive payload with context:Customer Information
- Identity: Customer ID, name, phone number, language preferences
- History: Previous orders, favorite items, dietary restrictions
- Memory: Any notes the chatbot has saved about this customer’s preferences
Conversation Context
- Current Conversation: Full message history for this session
- Mode: Whether this is a single location or multi-location organization
- Platform: WhatsApp, with specific conversation ID
Location & Restaurant Data
- Restaurant Info: Hours, contact details, service types (delivery/pickup)
- Menu: Current catalog with prices, availability, and options
- Settings: Payment methods, delivery zones, special promotions
Current Orders
- Active Drafts: Any orders the customer is currently building
- Recent Orders: Order history for quick reordering
- Payment Status: Saved payment methods and preferences
Processing Flow
Message Types LeClerk Handles
1. Menu Inquiries
- “What pizzas do you have?”
- “Do you have gluten-free options?”
- “What’s in the Margherita?”
2. Ordering Requests
- “I want a large pepperoni pizza”
- “Add a Coke to my order”
- “I’ll take the lunch special”
3. Service Questions
- “Do you deliver to [address]?”
- “What are your hours?”
- “How much is delivery?”
4. Order Management
- “Cancel my order”
- “Change my address”
- “When will my food arrive?”
5. Account & History
- “What did I order last time?”
- “Save this as my usual order”
- “Update my payment method”
Location vs Organization Mode
Location Mode
When a customer is talking to a specific restaurant location:- All menu queries target that location’s catalog
- Orders are placed for that specific restaurant
- Address validation checks that location’s delivery zone
- Store hours and contact info are location-specific
Organization Mode
When a customer contacts a restaurant chain:- First step is usually address validation to find the nearest location
- Once location is determined, behavior switches to location-specific mode
- Customers can switch between locations during the conversation
Authentication & Security
Every message request includes:- Bearer Token: Validates the request comes from trusted Nexus backend
- Customer Verification: Ensures the conversation belongs to the stated customer
- Rate Limiting: Prevents abuse and ensures fair usage
Error Handling
When something goes wrong:Validation Errors
- Invalid customer ID → Ask customer to restart conversation
- Malformed payload → Log error, request retry from Nexus
- Authentication failure → Return 401, trigger security alerts
Processing Errors
- LLM API failure → Fallback to simple canned responses
- Tool call failure → Graceful degradation with apology
- Menu data unavailable → Inform customer and suggest callback
Recovery Patterns
- Always try to keep the conversation going
- Provide clear error messages when possible
- Escalate to human support when automated recovery fails