API Reference — Wahero

Wahero REST API

The Wahero API lets you send WhatsApp messages, manage contacts, handle groups, and receive real-time events — all through a simple REST interface with JSON payloads.

REST API

Standard HTTP verbs, JSON request & response

API Key Auth

Simple header-based authentication

Webhooks

Real-time push events to your endpoint

Base URLhttps://api.wahero.id

Authentication

All API requests must include your API key in the X-Api-Key header. Generate and manage your keys from the dashboard.

http

X-Api-Key: YOUR_API_KEY
Content-Type: application/json

Never expose your API key in client-side code or public repositories. Store it as an environment variable and rotate immediately if compromised.

API Scopes

Parameter	Type	Required	Description
`messages.send`	scope	—	Send text, bulk, media, reply, reaction, poll, location, contact card, link preview
`messages.read`	scope	—	Read message status, list chats, chat messages, profile pictures
`contacts.read`	scope	—	List contacts and validate numbers
`instances.read`	scope	—	View instance list and connection status
`agent.chat`	scope	—	Chat with AI agent, read knowledge base (Q&A, products, URLs, files)
`agent.manage`	scope	—	Manage knowledge base, teach agent from conversations

Quick Start

Send your first message in under 2 minutes. Get your API key, find your instance ID in the dashboard, and run the example below.

curl

curl -X POST https://api.wahero.id/api/v1/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "628123456789",
    "message": "Hello from Wahero!"
  }'

Response200

{
  "success": true,
  "data": {
    "messageId": "BADID_abc123xyz",
    "status": "sent",
    "timestamp": "2026-03-20T10:30:00.000Z"
  }
}

Rate Limits

Limits are enforced per API key. Exceeding the limit returns 429 Too Many Requests.

Plan	Requests / 15 min
Free	100
Pro	1,000
Enterprise	Custom

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1742468400

API Reference

Messages

Send single, bulk, or media messages to any WhatsApp number via your connected instances.

Send Message

Send a text message to a single WhatsApp number.

POSThttps://api.wahero.id/api/v1/messages/send

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance to send from
`phone`	string	Required	Recipient in international format (e.g. 628123456789)
`message`	string	Required	Text content

curl

curl -X POST https://api.wahero.id/api/v1/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "628123456789",
    "message": "Hello from Wahero!"
  }'

Response200

{
  "success": true,
  "data": {
    "messageId": "BADID_abc123xyz",
    "status": "sent",
    "timestamp": "2026-03-20T10:30:00.000Z"
  }
}

Send Bulk Messages

Send up to 100 personalised messages in one request.

POSThttps://api.wahero.id/api/v1/messages/bulk

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`messages`	array	Required	Array of message objects (max 100)
`messages[].phone`	string	Required	Recipient number
`messages[].message`	string	Required	Message text for this recipient

curl

curl -X POST https://api.wahero.id/api/v1/messages/bulk \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "messages": [
      { "phone": "628111000001", "message": "Hi Alice!" },
      { "phone": "628111000002", "message": "Hi Bob!" }
    ]
  }'

Response200

{
  "success": true,
  "data": {
    "sent": 2,
    "failed": 0,
    "results": [
      { "phone": "628111000001", "messageId": "BADID_xxx", "status": "sent" },
      { "phone": "628111000002", "messageId": "BADID_yyy", "status": "sent" }
    ]
  }
}

Send Media

Send an image, video, audio, or document via a publicly accessible HTTPS URL.

POSThttps://api.wahero.id/api/v1/messages/media

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`phone`	string	Required	Recipient number
`mediaUrl`	string	Required	Publicly accessible HTTPS URL of the file
`mediaType`	string	Required	"image" \| "video" \| "audio" \| "document"
`caption`	string	Optional	Caption text (image/video only)
`filename`	string	Optional	Custom filename for the media (useful for documents)

curl

curl -X POST https://api.wahero.id/api/v1/messages/media \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "628123456789",
    "mediaUrl": "https://example.com/image.jpg",
    "mediaType": "image",
    "caption": "Check this out!"
  }'

Response200

{
  "success": true,
  "data": {
    "messageId": "BADID_media456",
    "status": "sent",
    "mediaType": "image"
  }
}

Get Message

Retrieve full details of a previously sent or received message.

GEThttps://api.wahero.id/api/v1/messages/:messageId

Path

Parameter	Type	Required	Description
`messageId`	string	Required	ID returned when the message was sent

Query

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the instance that sent the message

Response200

{
  "success": true,
  "data": {
    "messageId": "BADID_abc123xyz",
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "chatId": "628123456789@c.us",
    "type": "chat",
    "fromMe": true,
    "status": "read",
    "timestamp": "2026-03-20T10:30:00.000Z"
  }
}

Message Status

Check the delivery status of a previously sent message.

GEThttps://api.wahero.id/api/v1/messages/:messageId/status

Path

Parameter	Type	Required	Description
`messageId`	string	Required	ID returned when the message was sent

Query

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the instance that sent the message

Response200

{
  "success": true,
  "data": {
    "messageId": "BADID_abc123xyz",
    "status": "read",
    "sentAt": "2026-03-20T10:30:00.000Z",
    "deliveredAt": "2026-03-20T10:30:03.000Z",
    "readAt": "2026-03-20T10:32:15.000Z"
  }
}

API Reference

Groups

List WhatsApp groups, send messages, and retrieve group members.

List Groups

Returns all groups the instance belongs to.

GEThttps://api.wahero.id/api/v1/groups

Query

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance

Response200

{
  "success": true,
  "data": [
    {
      "id": "120363012345678901@g.us",
      "name": "Team Wahero",
      "participantsCount": 12,
      "isAdmin": true
    }
  ]
}

Send to Group

Send a text message to a WhatsApp group.

POSThttps://api.wahero.id/api/v1/groups/:groupId/message

Path

Parameter	Type	Required	Description
`groupId`	string	Required	WhatsApp group ID (e.g. 120363012345678901@g.us)

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`message`	string	Required	Text to send

Response200

{
  "success": true,
  "data": { "messageId": "BADID_grp789", "status": "sent" }
}

Group Members

Get the participants list for a specific group.

GEThttps://api.wahero.id/api/v1/groups/:groupId/members

Path

Parameter	Type	Required	Description
`groupId`	string	Required	WhatsApp group ID

Query

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance

Response200

{
  "success": true,
  "data": {
    "groupId": "120363012345678901@g.us",
    "participants": [
      { "id": "628123456789@c.us", "isAdmin": true, "isSuperAdmin": false },
      { "id": "628987654321@c.us", "isAdmin": false, "isSuperAdmin": false }
    ],
    "total": 2
  }
}

API Reference

Contacts

Access contacts synced from WhatsApp and validate numbers before sending.

List Contacts

Returns paginated contacts from the instance.

GEThttps://api.wahero.id/api/v1/contacts

Query

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`limit`	integer	Optional	Max contacts to return, max 100 (default: 100)
`offset`	integer	Optional	Number of contacts to skip for pagination (default: 0)

Response200

{
  "success": true,
  "data": [
    { "phone": "628123456789", "name": "Alice", "isMyContact": true }
  ],
  "pagination": { "total": 142, "limit": 100, "offset": 0, "hasMore": true }
}

Contact Detail

Get details for a specific contact.

GEThttps://api.wahero.id/api/v1/contacts/:phone

Path

Parameter	Type	Required	Description
`phone`	string	Required	Phone number without + (e.g. 628123456789)

Query

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the instance

Response200

{
  "success": true,
  "data": {
    "phone": "628123456789",
    "name": "Alice",
    "about": "Busy",
    "isOnWhatsApp": true,
    "profilePicUrl": "https://..."
  }
}

Check Number

Verify whether a phone number is registered on WhatsApp.

POSThttps://api.wahero.id/api/v1/contacts/check

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the instance
`phone`	string	Required	Number to validate

Response200

{
  "success": true,
  "data": {
    "phone": "628123456789",
    "isOnWhatsApp": true,
    "chatId": "628123456789@c.us"
  }
}

API Reference

Instances

An instance is a connected WhatsApp number. Use the instanceId returned here in all messaging and contact endpoints.

List Instances

Returns all WhatsApp instances for your account.

GEThttps://api.wahero.id/api/v1/instances

Response200

{
  "success": true,
  "data": [
    {
      "instanceId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Customer Support",
      "status": "WORKING",
      "phone": "628123456789"
    }
  ]
}

Instance Status

Check the live connection state of a specific instance.

GEThttps://api.wahero.id/api/v1/instances/:instanceId/status

Path

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the instance

Response200

{
  "success": true,
  "data": {
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "WORKING",
    "lastSeen": "2026-03-20T10:30:00.000Z"
  }
}

Status value	Meaning
WORKING	Connected and ready to send messages
SCAN_QR_CODE	Awaiting QR scan to authenticate
STARTING	Instance is initializing
STOPPED	Instance is offline

v2 API

Messages Advanced

Advanced messaging capabilities: replies, reactions, polls, location, contact cards, and link previews. Requires messages.send scope.

Reply to Message

Reply to a specific message by quoting it.

POSThttps://api.wahero.id/api/v2/messages/reply

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`phone`	string	Required	Recipient number
`message`	string	Required	Reply text
`quotedMessageId`	string	Required	ID of the message to quote/reply to

curl

curl -X POST https://api.wahero.id/api/v2/messages/reply \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "628123456789",
    "message": "Thanks for your message!",
    "quotedMessageId": "BAE5abc123"
  }'

Response200

{
  "success": true,
  "data": { "messageId": "BAE5reply789", "status": "sent" }
}

Send Reaction

React to a message with an emoji.

PUThttps://api.wahero.id/api/v2/messages/reaction

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`phone`	string	Required	Recipient number
`messageId`	string	Required	Message ID to react to
`emoji`	string	Required	Emoji character (e.g. 👍 ❤️ 😂 🔥). Empty string to remove reaction.

bash

curl -X PUT https://api.wahero.id/api/v2/messages/reaction \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"550e8400-...","phone":"628123456789","messageId":"BAE5abc123","emoji":"👍"}'

Response200

{ "success": true, "data": { "reacted": true } }

Forward Message

Forward an existing message to another contact.

POSThttps://api.wahero.id/api/v2/messages/forward

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`messageId`	string	Required	Message ID to forward
`toPhone`	string	Required	Target phone number

bash

curl -X POST https://api.wahero.id/api/v2/messages/forward \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"550e8400-...","messageId":"BAE5abc123","toPhone":"628987654321"}'

Send Location

Send GPS coordinates as a location pin.

POSThttps://api.wahero.id/api/v2/messages/location

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`phone`	string	Required	Recipient number
`latitude`	number	Required	Latitude (−90 to 90)
`longitude`	number	Required	Longitude (−180 to 180)
`name`	string	Optional	Location name
`address`	string	Optional	Street address

bash

curl -X POST https://api.wahero.id/api/v2/messages/location \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "628123456789",
    "latitude": -6.2088,
    "longitude": 106.8456,
    "name": "Jakarta Office",
    "address": "Jl. Sudirman No.1, Jakarta"
  }'

Response200

{ "success": true, "data": { "messageId": "BAE5loc456", "status": "sent" } }

Send Contact Card

Share a contact as a vCard message.

POSThttps://api.wahero.id/api/v2/messages/contact

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`phone`	string	Required	Recipient number
`contactPhone`	string	Required	Phone number of the contact to share
`contactName`	string	Required	Display name of the contact

bash

curl -X POST https://api.wahero.id/api/v2/messages/contact \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"550e8400-...","phone":"628123456789","contactPhone":"628987654321","contactName":"John Doe"}'

Poll & Vote

Create polls and submit votes programmatically.

POSThttps://api.wahero.id/api/v2/messages/poll

Create Poll — Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`phone`	string	Required	Recipient number
`question`	string	Required	Poll question
`options`	array	Required	Array of option strings (2–12 items)
`multipleAnswers`	boolean	Optional	Allow multiple selections (default: false)

bash

curl -X POST https://api.wahero.id/api/v2/messages/poll \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "628123456789",
    "question": "Your favourite colour?",
    "options": ["Red", "Blue", "Green"],
    "multipleAnswers": false
  }'

Response200

{ "success": true, "data": { "messageId": "BAE5poll789", "status": "sent" } }

Vote on Poll

POSThttps://api.wahero.id/api/v2/messages/poll/vote

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`messageId`	string	Required	Poll message ID
`selectedOptions`	array	Required	Array of selected option indices (0-based)

Link Preview

Send a message with a rich link preview card.

POSThttps://api.wahero.id/api/v2/messages/link-preview

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`phone`	string	Required	Recipient number
`text`	string	Required	Message text containing the URL
`url`	string	Required	URL to generate preview for
`title`	string	Optional	Preview card title
`description`	string	Optional	Preview card description

bash

curl -X POST https://api.wahero.id/api/v2/messages/link-preview \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"550e8400-...","phone":"628123456789","text":"Check this out!","url":"https://wahero.id"}'

v2 API

Chats

List chats, retrieve message history, and manage chat states. Requires messages.read scope for reads, messages.send for actions.

List Chats

Returns paginated chats for the instance.

GEThttps://api.wahero.id/api/v2/chats

Query

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`limit`	integer	Optional	Results per page (default: 50)
`offset`	integer	Optional	Pagination offset (default: 0)

curl

curl -G https://api.wahero.id/api/v2/chats \
  -H "X-Api-Key: YOUR_API_KEY" \
  --data-urlencode "instanceId=550e8400-e29b-41d4-a716-446655440000" \
  --data-urlencode "limit=50"

Response200

{
  "success": true,
  "data": [
    {
      "id": "628123456789@c.us",
      "name": "Alice",
      "lastMessage": { "body": "Hello!", "timestamp": 1742468400 },
      "unreadCount": 2,
      "isGroup": false
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 124 }
}

Chat Messages

Retrieve message history for a specific chat.

GEThttps://api.wahero.id/api/v2/chats/:chatId/messages

Path

Parameter	Type	Required	Description
`chatId`	string	Required	Chat ID (e.g. 628123456789@c.us)

Query

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`limit`	integer	Optional	Number of messages (default: 100)

bash

curl -G https://api.wahero.id/api/v2/chats/628123456789%40c.us/messages \
  -H "X-Api-Key: YOUR_API_KEY" \
  --data-urlencode "instanceId=550e8400-e29b-41d4-a716-446655440000" \
  --data-urlencode "limit=50"

Response200

{
  "success": true,
  "data": [
    { "id": "BAE5abc", "body": "Hello!", "fromMe": false, "timestamp": 1742468400 },
    { "id": "BAE5def", "body": "Hi there!", "fromMe": true,  "timestamp": 1742468450 }
  ]
}

Chat Actions

All chat management endpoints. All POST/DELETE endpoints require messages.send scope and a body of { instanceId, chatId } unless noted.

Method	Path	Description
POST	/api/v2/chats/mark-read	Mark chat as read
POST	/api/v2/chats/archive	Archive chat
POST	/api/v2/chats/unarchive	Unarchive chat
POST	/api/v2/chats/mute	Mute chat (optional: duration ms)
POST	/api/v2/chats/unmute	Unmute chat
POST	/api/v2/chats/pin	Pin chat to top
POST	/api/v2/chats/unpin	Unpin chat
POST	/api/v2/chats/typing	Show/hide typing indicator (isTyping: bool)
GET	/api/v2/chats/:chatId/profile-picture	Get profile picture URL (query: instanceId)
DELETE	/api/v2/chats/:chatId	Delete chat locally (query: instanceId)

bash

# Example: archive a chat
curl -X POST https://api.wahero.id/api/v2/chats/archive \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"550e8400-e29b-41d4-a716-446655440000","chatId":"628123456789@c.us"}'

Response200

{ "success": true, "data": { "archived": true } }

v2 API

AI Agent

Interact with your AI agent and manage its knowledge base. Chat endpoints require agent.chat scope; management endpoints require agent.manage.

Chat with Agent

Send a message to the AI agent and receive an automated response. The agent uses the instance's knowledge base and conversation history to reply.

POSThttps://api.wahero.id/api/v2/agent/chat

Body

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`phone`	string	Required	User WhatsApp number
`message`	string	Required	User message text
`agentId`	string	Optional	Specific agent ID (defaults to instance agent)

curl

curl -X POST https://api.wahero.id/api/v2/agent/chat \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "628123456789",
    "message": "Berapa harga produk X?"
  }'

Response200

{
  "success": true,
  "data": {
    "reply": "Harga produk X adalah Rp 100.000. Ada yang bisa saya bantu lagi?",
    "agentId": "agent_abc123",
    "confidence": 0.95
  }
}

Learn & Context

Teach the agent from a real conversation, check conversation statistics, retrieve config, or reset context for a user.

POSThttps://api.wahero.id/api/v2/agent/learn

Learn from Conversation — Body (scope: agent.manage)

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`phone`	string	Required	User WhatsApp number
`question`	string	Required	User question to learn from
`correctAnswer`	string	Required	Correct answer to save to knowledge base
`agentId`	string	Optional	Specific agent ID

bash

curl -X POST https://api.wahero.id/api/v2/agent/learn \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "628123456789",
    "question": "Apa jam operasional?",
    "correctAnswer": "Senin-Jumat 09:00-17:00 WIB"
  }'

Response200

{ "success": true, "data": { "learned": true } }

Method	Path	Description	Scope
GET	/api/v2/agent/stats	Conversation statistics; query: instanceId, agentId	agent.chat
GET	/api/v2/agent/config	Agent configuration; query: instanceId, agentId	agent.chat
DELETE	/api/v2/agent/context	Clear conversation context for a user; query: instanceId, phone, agentId	agent.manage

Q&A Knowledge Base

Add question–answer pairs that the agent uses to respond to customers.

POSThttps://api.wahero.id/api/v2/agent/kb/qna

Add Q&A — Body (scope: agent.manage)

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`question`	string	Required	Question text
`answer`	string	Required	Answer text
`category`	string	Optional	Category tag (default: general)
`agentId`	string	Optional	Specific agent ID

bash

curl -X POST https://api.wahero.id/api/v2/agent/kb/qna \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "question": "Jam operasional?",
    "answer": "Senin-Jumat 09:00-17:00 WIB",
    "category": "information"
  }'

Response200

{ "success": true, "data": { "id": "qna_abc123", "question": "Jam operasional?", "answer": "Senin-Jumat 09:00-17:00 WIB" } }

Method	Path	Description
POST	/api/v2/agent/kb/qna	Add Q&A entry (scope: agent.manage)
GET	/api/v2/agent/kb/qna	List Q&A entries; query: instanceId, category, limit, agentId (scope: agent.chat)
DEL	/api/v2/agent/kb/qna/:id	Delete Q&A entry; query: instanceId (scope: agent.manage)

Products

Manage a product catalogue that the agent can reference when answering price and stock questions.

POSThttps://api.wahero.id/api/v2/agent/kb/products

Add Product — Body (scope: agent.manage)

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`name`	string	Required	Product name
`description`	string	Required	Product description
`price`	number	Required	Price in smallest currency unit (e.g. IDR)
`category`	string	Optional	Product category
`stock`	number	Optional	Available stock
`sku`	string	Optional	Stock-keeping unit code
`agentId`	string	Optional	Specific agent ID

bash

curl -X POST https://api.wahero.id/api/v2/agent/kb/products \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Sepatu Sport X",
    "description": "Sepatu olahraga premium anti-slip",
    "price": 350000,
    "category": "footwear",
    "stock": 25,
    "sku": "SX-001"
  }'

Response200

{ "success": true, "data": { "id": "prod_abc123", "name": "Sepatu Sport X", "price": 350000 } }

Method	Path	Description
POST	/api/v2/agent/kb/products	Add product (scope: agent.manage)
GET	/api/v2/agent/kb/products	List products; query: instanceId, category, limit, agentId (scope: agent.chat)
DEL	/api/v2/agent/kb/products/:id	Delete product; query: instanceId (scope: agent.manage)

URLs

Register URLs for the agent to scrape and learn from. Useful for onboarding FAQ pages, product catalogues, or company info pages.

POSThttps://api.wahero.id/api/v2/agent/kb/urls

Add URL — Body (scope: agent.manage)

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`url`	string	Required	URL to scrape and index
`category`	string	Optional	Category tag (default: general)
`agentId`	string	Optional	Specific agent ID

bash

curl -X POST https://api.wahero.id/api/v2/agent/kb/urls \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"550e8400-...","url":"https://example.com/faq","category":"support"}'

Method	Path	Description
POST	/api/v2/agent/kb/urls	Add URL to scrape (scope: agent.manage)
GET	/api/v2/agent/kb/urls	List URLs; query: instanceId, agentId (scope: agent.chat)
DEL	/api/v2/agent/kb/urls/:id	Delete URL; query: instanceId (scope: agent.manage)

Files

Store text content for the agent to learn from. Send the file's text content as a string — useful for FAQ documents, SOPs, or knowledge articles.

POSThttps://api.wahero.id/api/v2/agent/kb/files

Upload File — Body (scope: agent.manage)

Parameter	Type	Required	Description
`instanceId`	string	Required	UUID of the WhatsApp instance
`fileName`	string	Required	Display name of the file (e.g. faq.txt)
`content`	string	Required	Text content of the file
`fileType`	string	Optional	File type hint: "text" or "pdf" (default: text)
`agentId`	string	Optional	Specific agent ID

bash

curl -X POST https://api.wahero.id/api/v2/agent/kb/files \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "fileName": "faq-produk.txt",
    "content": "Jam operasional: Senin-Jumat 09:00-17:00 WIB\nHubungi: cs@example.com",
    "fileType": "text"
  }'

Response200

{ "success": true, "data": { "_id": "file_abc123", "fileName": "faq-produk.txt", "fileSize": 72, "processingStatus": "completed" } }

Method	Path	Description
POST	/api/v2/agent/kb/files	Upload file (multipart/form-data, scope: agent.manage)
GET	/api/v2/agent/kb/files	List uploaded files; query: instanceId, agentId (scope: agent.chat)
DEL	/api/v2/agent/kb/files/:id	Delete file; query: instanceId (scope: agent.manage)

Reference

Error Codes

All errors share a consistent JSON shape. Check the HTTP status code and the message field.

json

{
  "success": false,
  "message": "Instance not found",
  "error": "INSTANCE_NOT_FOUND"
}

Status	Name	When it occurs
400	Bad Request	Missing or invalid request parameters
401	Unauthorized	API key is absent or invalid
403	Forbidden	API key lacks the required scope
404	Not Found	Instance, contact, or message not found
422	Unprocessable Entity	Phone format invalid or instance disconnected
429	Too Many Requests	Rate limit exceeded — retry after X-RateLimit-Reset
500	Internal Server Error	Unexpected server-side failure

Reference

Webhooks

Wahero sends HTTP POST requests to your registered webhook URL when events occur. Configure it in the dashboard.

Payload structure

json

{
  "event":     "message",
  "session":   "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1742468400,
  "payload": {
    "from":      "628123456789@c.us",
    "body":      "Hello!",
    "type":      "chat",
    "messageId": "BAE5abc123"
  }
}

Events

Event	Description
`message`	New incoming message received
`message.ack`	Message delivery status updated (sent/delivered/read)
`session.status`	Instance connection status changed
`qrcode.updated`	New QR code generated for authentication
`call`	Incoming call received or rejected

Signature Verification

Every webhook request includes an X-Wahero-Signature header — an HMAC-SHA256 of the raw body using your webhook secret. Always verify this before processing events.

Ready to build?

Create a free account and get your API key in minutes.

Get API Key — Free Full Documentation